/**
 * Copyright © 2008-2009 DRIVER PROJECT (ICM UW)
 *
 * 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.resultset.api;

import java.util.List;

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

import eu.dnetlib.resultset.impl.Array1;
import eu.dnetlib.resultset.impl.CreatePullRSType;
import eu.dnetlib.resultset.impl.CreatePushRSType;
import eu.dnetlib.resultset.impl.GetResultType;
import eu.dnetlib.resultset.impl.IndexResultSetFaultMessage;
import eu.dnetlib.resultset.impl.PreparePullRSType;
import eu.dnetlib.resultset.impl.StartPullRSType;

/**
 * ResultSet interface used by index service.
 * @author Marek Horst
 * @version 0.01
 *
 */
@WebService(targetNamespace = "http://api.resultset.dnetlib.eu")
//@SOAPBinding(style = SOAPBinding.Style.RPC, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.BARE)
public interface IResultSet {
	
	/**
	 * Identifies service and version.
	 * @return service and version identifier
	 */
	@WebMethod(operationName="identify", action="identify")
	public String identify();
	
    /**
     * Returns result from RS for given range and request mode.
     * Result is String[] type.
     * @param rsId
     * @param fromPosition
     * @param toPosition
     * @param requestMode
     * @throws IndexResultSetFaultMessage
     * @return result from RS for given range and request mode.
     */
	@WebMethod(operationName = "simpleGetResult", action = "simpleGetResult")
    public String[] simpleGetResult(
            @WebParam(name = "rsId") String rsId,
            @WebParam(name = "fromPosition") int fromPosition,
            @WebParam(name = "toPosition") int toPosition,
            @WebParam(name = "requestMode") String requestMode)
		throws IndexResultSetFaultMessage;
	
    /**
     * Populates ResultSet with data provided in elements.
     * @param rsId
     * @param listRecords
     * @throws IndexResultSetFaultMessage
     * @return rsId
     */
    @WebMethod(operationName = "populateRS", action = "populateRS")
    public String populateRS(
        @WebParam(name = "rsId") String rsId,
        @WebParam(name = "elements") List<String> listRecords)
    	throws IndexResultSetFaultMessage;
    
    /**
     * Returns ResultSet status for given rsId.
     * @param rsId
     * @throws IndexResultSetFaultMessage
     * @return ResultSet status for given rsId
     */
    @WebMethod(operationName = "getRSStatus", action = "getRSStatus")
    public String getRSStatus(
        @WebParam(name = "rsId") String rsId)
    	throws IndexResultSetFaultMessage;
    
    /**
     * Returns ResultSet property value  for given rsId.
     * @param rsId
     * @param name
     * @throws IndexResultSetFaultMessage
     * @return ResultSet status for given rsId
     */
    @WebMethod(operationName = "getProperty", action = "getProperty")
    public String getProperty(
        @WebParam(name = "rsId") String rsId,
        @WebParam(name = "name") String name)
    	throws IndexResultSetFaultMessage;
    
    /**
     * Creates Push ResultSet. 
     * Returns ResultSet EPR.
     * @param expiryTime
     * @param createPushRS_type
     * @throws IndexResultSetFaultMessage
     * @return ResultSet EPR
     */
    @WebMethod(operationName = "createPushRS", action = "createPushRS")
    public W3CEndpointReference createPushRS(
        @WebParam(name = "expiryTime") int expiryTime,
        @WebParam(name = "createPushRS_type") CreatePushRSType createPushRS_type)
		throws IndexResultSetFaultMessage;
    
    /**
     * Deletes ResultSet of given rsId.
     * @param rsId
     * @throws IndexResultSetFaultMessage
     * @return true if ResultSet succesfully deleted.
     */
    @WebMethod(operationName = "deleteRS", action = "deleteRS")
    public boolean deleteRS(
        @WebParam(name = "rsId") String rsId)
		throws IndexResultSetFaultMessage;
    
    /**
     * Refreshes expiration time for given ResultSet id.
     * @param rsId
     * @param expiryTime
     * @throws IndexResultSetFaultMessage
     * @return true if succesfully refreshed.
     */
    @WebMethod(operationName = "refreshExpiryTime", action = "refreshExpiryTime")
    public boolean refreshExpiryTime(
        @WebParam(name = "rsId") String rsId,
        @WebParam(name = "expiryTime") int expiryTime)
		throws IndexResultSetFaultMessage;
    
    /**
     * Closes ResultSet of given rsId.
     * @param rsId
     * @throws IndexResultSetFaultMessage
     * @return rsId
     */
    @WebMethod(operationName = "closeRS", action = "closeRS")
    public void closeRS(
        @WebParam(name = "rsId") String rsId)
		throws IndexResultSetFaultMessage;

    /**
     * Returns number of elements for given ResultSet id.
     * @param rsId
     * @throws IndexResultSetFaultMessage
     * @return number of elements for given ResultSet id
     */
    @WebMethod(operationName = "getNumberOfElements", action = "getNumberOfElements")
    public int getNumberOfElements(
        @WebParam(name = "rsId") String rsId)
		throws IndexResultSetFaultMessage;
    
    /**
     * Returns number of elements and ResultSet status for given ResultSet id.
     * @param bdId
     * @throws IndexResultSetFaultMessage
     * @return number of elements and ResultSet status for given ResultSet id
     */
    @WebMethod(operationName = "getNumberOfResults", action = "getNumberOfResults")
    public String getNumberOfResults(
        @WebParam(name = "bdId") String bdId)
		throws IndexResultSetFaultMessage;
    
    /**
     * Returns result from ResultSet for given range, request mode and result type.
     * @param rsId
     * @param fromPosition
     * @param toPosition
     * @param requestMode
     * @param getResult_type
     * @throws IndexResultSetFaultMessage
     * @return result from ResultSet for given range, request mode and result type
     */
    @WebMethod(operationName = "getResult", action = "getResult")
    public List<String> getResult(
        @WebParam(name = "rsId") String rsId,
        @WebParam(name = "fromPosition") int fromPosition,
        @WebParam(name = "toPosition") int toPosition,
        @WebParam(name = "requestMode") String requestMode,
        @WebParam(name = "getResult_type") GetResultType getResult_type)
    	throws IndexResultSetFaultMessage;
    
    /**
     * Removes single result from ResultSet of given rsId and specified position.
     * @param rsId
     * @param position
     * @throws IndexResultSetFaultMessage
     * @return removed Result.
     */
    @WebMethod(operationName = "removeResult", action = "removeResult")
    public String removeResult(
        @WebParam(name = "rsId") String rsId,
        @WebParam(name = "position") int position)
    	throws IndexResultSetFaultMessage;
     
    /**
     * Returns ResultSet as resource.
     * @param rsId
     * @param label
     * @return ResultSet as resource
     * @throws IndexResultSetFaultMessage
     */
    @WebMethod(operationName = "rSasResource", action = "rSasResource")
    public String rSasResource(
        @WebParam(name = "rsId")
        String rsId,
        @WebParam(name = "label")
        String label)
        throws IndexResultSetFaultMessage;
    
    /**
     * Starts PullRS.
     * @param rsId
     * @param bdId
     * @param expiryTime
     * @param startPullRS_type
     * @return rsId
     * @throws IndexResultSetFaultMessage
     */
    @WebMethod(operationName = "startPullRS", action = "startPullRS")
    public String startPullRS(
        @WebParam(name = "rsId")
        String rsId,
        @WebParam(name = "bdId")
        String bdId,
        @WebParam(name = "expiryTime")
        int expiryTime,
        @WebParam(name = "startPullRS_type")
        StartPullRSType startPullRS_type)
        throws IndexResultSetFaultMessage;
    
    /**
     * Creates pull ResultSet.
     * @param dataProviderServiceAddress
     * @param bdId
     * @param initialPageSize
     * @param expiryTime
     * @param createPullRS_type
     * @return PullRS id.
     * @throws IndexResultSetFaultMessage
     */
    @WebMethod(operationName = "createPullRS", action = "createPullRS")
    public W3CEndpointReference createPullRS(
        @WebParam(name = "dataProviderServiceAddress")
        String dataProviderServiceAddress,
        @WebParam(name = "bdId")
        String bdId,
        @WebParam(name = "initialPageSize")
        int initialPageSize,
        @WebParam(name = "expiryTime")
        int expiryTime,
        @WebParam(name = "createPullRS_type")
        CreatePullRSType createPullRS_type)
        throws IndexResultSetFaultMessage;
    
    /**
     * Prepares pull result set.
     * @param dataProviderServiceAddress
     * @param initialPageSize
     * @param expiryTime
     * @param preparePullRS_type
     * @return prepared pull Result Set id.
     * @throws IndexResultSetFaultMessage
     */
    @WebMethod(operationName = "preparePullRS", action = "preparePullRS")
    public String preparePullRS(
        @WebParam(name = "dataProviderServiceAddress")
        String dataProviderServiceAddress,
        @WebParam(name = "initialPageSize")
        int initialPageSize,
        @WebParam(name = "expiryTime")
        int expiryTime,
        @WebParam(name = "preparePullRS_type")
        PreparePullRSType preparePullRS_type)
        throws IndexResultSetFaultMessage
    ;
    
    /**
     * Performs fusion on a result sets which eprs are passed as an array.
     * @param expiryTime
     * @param eprs
     * @return newly created Result Set id.
     * @throws IndexResultSetFaultMessage
     */
    @WebMethod(operationName = "fusion", action = "fusion")
    public String fusion(
        @WebParam(name = "expiryTime")
        int expiryTime,
        @WebParam(name = "eprs")
        Array1 eprs)
        throws IndexResultSetFaultMessage
    ;
}