package eu.dnetlib.pid.service.rmi;

import java.util.List;

import javax.jws.WebParam;
import javax.jws.WebService;

import org.socialhistoryservices.pid.LocationType;
import org.socialhistoryservices.pid.PidType;

import eu.dnetlib.common.rmi.BaseService;

/**
 * WebService interface acting as bridge from D-Net to the IISG Pid service.
 * <p>
 * Methods reflect those of the IISG PID web service you can find at: https://pid.dev.objectrepository.nl/pid/
 * </p>
 * 
 * @author alessia
 * 
 */
@WebService
public interface PIDBridgeService extends BaseService {

	/**
	 * Updates the binding of the given string pid to the provided resolveURL, localID and location attributes.
	 * <p>
	 * If the pidType.resolveUrl or pidType.locAtt are not supplied they will be un-bound\removed from the pid (if
	 * there). A pidType.localIdentifier cannot be removed, only changed or added.
	 * </p>
	 * 
	 * 
	 * @param pid
	 *            persistent identifier to update
	 * @param resolveURL
	 *            set to null to unbind
	 * @param localID
	 *            TODO: what if it is null?
	 * @param locations
	 *            Collection of LocationType, that is derivatives' URL (href) and typlogies (view).
	 * @return the updated PidType
	 */
	PidType update(
			@WebParam(name = "pid") String pid,
			@WebParam(name = "resolveURL") String resolveURL,
			@WebParam(name = "localID") String localID,
			@WebParam(name = "locations") List<LocationType> locations);

	/**
	 * Updates the binding of the PidType with pid equals to pid.pid with the provided binding.
	 * 
	 * @see {@link eu.consortiumservices.pid.UpdatePidRequestType}
	 * @param pid
	 *            PidType with the requested changes
	 * @return the updated PidType
	 */
	PidType updatePid(@WebParam(name = "pid") PidType pid);

	/**
	 * Deletes all PIDs of the given naming authority.
	 * 
	 * @param namingAuthority
	 * @return the number of deleted PIDs
	 */
	int deletePids(@WebParam(name = "namingAuthority") String namingAuthority);

	void deleteListPids(@WebParam(name = "pidsToRemove") List<PidType> pidsToRemove);

	/**
	 * Performs a reverse lookup of a Pid owned by the given naming authority based on associated attributes.
	 * <p>
	 * Available attributes are the resolveURL and localIdentifier.
	 * </p>
	 * 
	 * @param namingAuthority
	 * @param attributeValue
	 * @return the collection of PIDs having an attribute with the given value
	 */
	List<PidType> getPidByAttribute(@WebParam(name = "namingAuthority") String namingAuthority, @WebParam(name = "attributeValue") String attributeValue);

	/**
	 * Retrieves all known bound attributes that belong to this pid.
	 * 
	 * @param pid
	 *            the string pid
	 * @return a PidType instance representing the string pid
	 */
	PidType getPid(@WebParam(name = "pid") String pid);

	/**
	 * Looks up for a PID owned by the given NA, associated to the localID.
	 * <p>
	 * If there is no such a PID, one will be created. If there is such a PID, then it is rebound to the provided
	 * not-null resolveURL (if the resolveURL is null, then the PID is not rebound).
	 * </p>
	 * 
	 * @param namingAuthority
	 * @param localID
	 * @param resolveURL
	 * @return a PidType instance representing the search/updated/created PID
	 */
	PidType getQuickPid(
			@WebParam(name = "namingAuthority") String namingAuthority,
			@WebParam(name = "localID") String localID,
			@WebParam(name = "resolveURL") String resolveURL);

	/**
	 * Creates a new unbound PID for the given naming authority.
	 * 
	 * @param namingAuthority
	 *            NA asking the PID
	 * @return the newly created PID
	 */
	PidType createPid(@WebParam(name = "namingAuthority") String namingAuthority);

	/**
	 * Checks if the given localID is associated to a PID for the given naming authority
	 * 
	 * @param namingAuthority
	 * @param localID
	 * @return true if there is a PID associated to the given localID for the provided NA
	 */
	boolean isLocalIDBounded(@WebParam(name = "namingAuthority") String namingAuthority, @WebParam(name = "localID") String localID);

	/**
	 * Gets the Pid associated to the given localID in the provided NA
	 * 
	 * @param namingAuthority
	 * @param localID
	 * @return the PID bounded to the localID in the NA or null, if there is no such a binding.
	 */
	PidType reverseLookupByLocalID(@WebParam(name = "namingAuthority") String namingAuthority, @WebParam(name = "localID") String localID);

	/**
	 * Gets the Pid associated to the given resolveURL in the provided NA
	 * 
	 * @param namingAuthority
	 * @param resolveURL
	 * @return the PID bounded to the resolveURL in the NA, or null, if there is no such a binding
	 */
	PidType reverseLookupByResolveURL(@WebParam(name = "namingAuthority") String namingAuthority, @WebParam(name = "resolveURL") String resolveURL);

	PidType upsert(
			@WebParam(name = "namingAuthority") String namingAuthority,
			@WebParam(name = "pid") String pid,
			@WebParam(name = "resolveURL") String resolveURL,
			@WebParam(name = "localID") String localID,
			@WebParam(name = "locations") List<LocationType> locations);
}