/**
 * Copyright 2008-2009 DRIVER PROJECT (ICM UW)
 * Original author: Marek Horst
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package eu.dnetlib.data.index;


import java.util.Collection;

import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
import javax.xml.ws.wsaddressing.W3CEndpointReference;

import eu.dnetlib.common.ws.dataprov.IDataProviderExt;
import eu.dnetlib.data.index.ws.nh.INotificationHandler;

/**
 * Main Driver Index Service interface. 
 * @author <a href="mailto:marek.imialek at uni-bielefeld.de">Marek Imialek</a>
 *
 */
@WebService
@SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, 
		parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)
public interface IIndexService extends INotificationHandler, IDataProviderExt {

	/**
	 * Method returns current service version.
	 * @return service version identifier
	 */
	@WebMethod(operationName="identify", action="identify")
	public String identify();
	
	/**
	 * The basic index searching method returning list of records passing given criteria.
	 * Method double-checks whether the selected
       Index Data Structures contain records conforming to mdFormat and layout, then generates a bulk data reference bdId
       and based on bdId, creates a pull-mode ResultSet. As a response, method returns End Point Reference for pull-mode
       ResultSet where the results are stored. Note that in order to query all indices available from the Index Servicei,
       method can take string 'all' as first parameter or the list of comma-separated index identifiers. In this case
       the method may identify among all Index Data Structures available only those conforming to mdFormat and layout.
	 * @param ixId index data structure identifier or the list of comma separated identifiers or 'all' phrase  
	 * @param query CQL query format
	 * @param mdFormatId meta-data format name, for example oai_dc
	 * @param layoutId layout name
	 * @throws IndexServiceException
	 * @return ResultSet (EPR) containing result records 
	 */
	@WebMethod(operationName="indexLookup", action="indexLookup")
	public W3CEndpointReference indexLookup(
			@WebParam(name="id") String ixId, 
			@WebParam(name="query") String query, 
			@WebParam(name="mdformat") String mdFormatId,
			@WebParam(name="layout") String layoutId)
		throws IndexServiceException;
	
	/**
	 * Method returns basic index statistics as for example
       number of indexed documents, index size or last modification date for selected Index Data Structure.
	 * @param ixId index data structure identifier
	 * @throws IndexServiceException
	 * @return XML containing basic index statistics
	 */
	@WebMethod(operationName="getIndexStatistics", action="getIndexStatistics")
	public String getIndexStatistics(
			@WebParam(name="index") String ixId)
		throws IndexServiceException;
	
	/**
	 * Basic browsing functionality
       returning list of terms and their number for specified query and defined field. Note that in order to query all
       indices available from the Index Service the method can take string 'all' as first parameter or
       the list of comma-separated indexIdentifiers. In this case the method may identify among all Index Data
       Structures available only those conforming to mdFormat and layout.
	 * @param query CQL query format
	 * @param ixId index data structure identifier or the list of comma separated identifiers or 'all' phrase 
	 * @throws IndexServiceException
	 * @return XML containing browsing statistics
	 */
	@WebMethod(operationName="getBrowsingStatistics", action="getBrowsingStatistics")
	public W3CEndpointReference getBrowsingStatistics(
			@WebParam(name="query") String query, 
			@WebParam(name="index") String ixId,
			@WebParam(name="mdformat") String mdFormatId,
			@WebParam(name="layout") String layoutId)
		throws IndexServiceException;
	
	/**
	 * Method returns list of registered Store Data Structure identifiers.
	 * @return List of index identifiers
	 */
	@WebMethod(operationName="getListOfIndices", action="getListOfIndices")
	public String[] getListOfIndices();
	
	/**
	 * Method returns list of registered Store Data Structure identifiers as
       comma-separated string.
	 * @return comma separated list index identifiers
	 */
	@WebMethod(operationName="getListOfIndicesCSV", action="getListOfIndicesCSV")
	public String getListOfIndicesCSV();
	
	/**
	 * Method removes documents indicated by
       record identifiers from specified index.
	 * @param ixId index data structure identifier
	 * @param recordIds list of records identifiers to be removed
	 * @throws IndexServiceException the Index Service exception
	 */
	@WebMethod(operationName="deleteRecords", action="deleteRecords")
	public void deleteRecords(
			@WebParam(name="ixId") String ixId,
			@WebParam(name="recordIds") Collection<String> recordIds)
	throws IndexServiceException;
	
	/**
	 * Method creates a new Index Data Structure capable of indexing meta-data and 
	 * full-texts conforming to the MDFormat definition identified by formatName 
	 * and interpreted through the layout layoutName. The method registers a new Index
	 * Data Structure Profile to the Information Service.
	 * 
	 * @param format meta-data format name
	 * @param layout layout name
	 * @param interpretationName interpretation name, one meta-data 
	 * format can be interpreted differently by different communities
	 * @return Method return new Index Data Structure identifier.
	 * 
	 * @throws IndexServiceException the index service exception
	 */
	@WebMethod(operationName="createIndex", action="createIndex")
	public String createIndex(
			@WebParam(name="format") String format,
			@WebParam(name="layout") String layout,
			@WebParam(name="interpretationName") String interpretationName)
	throws IndexServiceException;
	

	/**
	 * Method feeds Index Data Structure
       identified by indexIdentifier with records contained into the ResultSet according to feeding type. The feeding type
       can be incremental, i.e. appending the records to the existing ones, or refresh, replace the existing records
       with the one in the ResultSet. The records in such ResultSet must obey to the Index Record schema. The merge flag
       parameter is used for full-text indexing and decide if the full-text should be merged with the proper meta-data
       already hold in Index Data Structure.
	 * 
	 * @param ixId feeded index data structure identifier
	 * @param feedingType feeding type that can be INCREMENTAL or REFRESH
	 * @param resultSetEPRBase64Enc ResultSet EPRr base64 encoded
	 * @param merge full-text feeding functionality deciding if the full-texts should be merged with the current meta-data 
	 * @param feedWithFulltext true if feeding with full-texts
	 * 
	 * @return true, if feeding successful
	 * 
	 * @throws IndexServiceException the Index Service exception
	 */
	@WebMethod(operationName="feedIndex", action="feedIndex")
	public boolean feedIndex(
			@WebParam(name="ixId") String ixId,
			@WebParam(name="feedingType") String feedingType,
			@WebParam(name="resultSetEPRBase64Enc") String resultSetEPRBase64Enc,
			@WebParam(name="merge") boolean merge,
			@WebParam(name="feedWithFulltext") boolean feedWithFulltext)
	throws IndexServiceException;
	
	/**
	 * Method removes Index Data Structure indicated by indexIdentifier and 
	 * causes the removal of the relative profile from the Information Service.<
	 * @param ixId index data structure to be removed
	 * 
	 * @return true, if deletion was successful
	 * 
	 * @throws IndexServiceException the Index Service exception
	 */
	@WebMethod(operationName="deleteIndex", action="deleteIndex")
	public boolean deleteIndex(
			@WebParam(name="ixId") String ixId)
	throws IndexServiceException;
	
	/**
	 *  Method removes from selected index all documents containing 
	 *  specified value in particular field.
	 * 
	 * @param ixId index data structure identifier
	 * @param field searched field
	 * @param value value searched in field
	 * 
	 * @throws IndexServiceException the Index Service exception
	 */
	public void deleteDocumentsByTerm(String ixId, String field, String value) 
		throws IndexServiceException;
	
	
	/**
	 * Function restores all records marked for deletion. This operation is
     * possible only if the index was not optimized because index optimization removes all records marked for deletion.
	 * 
	 * @param ixId index data structure identifier
	 * 
	 * @throws IndexServiceException the Index Service exception
	 */
	public void undeleteAll(String ixId) throws IndexServiceException;
}