/**
 * The contents of this file are subject to the license and copyright
 * detailed in the LICENSE and NOTICE files at the root of the source
 * tree and available online at
 *
 * http://www.dspace.org/license/
 */
package org.purl.sword.client;

import org.purl.sword.base.DepositResponse;
import org.purl.sword.base.ServiceDocument;

/**
 * Interface for any SWORD client implementation. 
 */
public interface SWORDClient 
{
	/**
	 * Set the server that is to be contacted on the next access. 
	 * 
	 * @param server The name of the server, e.g. www.aber.ac.uk
	 * @param port   The port number, e.g. 80. 
	 */
	public void setServer( String server, int port );
	
	/**
	 * Set the user credentials that are to be used for subsequent accesses. 
	 * 
	 * @param username The username. 
	 * @param password The password. 
	 */
	public void setCredentials( String username, String password );

	/**
    * Clear the credentials settings on the client.
    */
	public void clearCredentials();

	/**
	 * Set the proxy that is to be used for subsequent accesses. 
	 * 
	 * @param host The host name, e.g. cache.host.com. 
	 * @param port The port, e.g. 8080. 
	 */
	public void setProxy( String host, int port );
		
	/**
	 * Get the status result returned from the most recent network test. 
	 * 
	 * @return An the status code and message.  
	 */
	public Status getStatus( );
	
	/**
	 * Get a service document, specified in the URL. 
	 * 
	 * @param url The URL to connect to. 
	 * @return A ServiceDocument that contains the Service details that were 
	 *         obained from the specified URL. 
	 *         
	 * @throws SWORDClientException If there is an error accessing the 
	 *                              URL. 
	 */
	public ServiceDocument getServiceDocument( String url ) throws SWORDClientException;
	
	/**
	 * Get a service document, specified in the URL. The document is accessed on
	 * behalf of the specified user. 
	 * 
	 * @param url        The URL to connect to. 
	 * @param onBehalfOf The username for the onBehalfOf access. 
	 * @return A ServiceDocument that contains the Service details that were 
    *         obained from the specified URL. 
    *         
	 * @throws SWORDClientException If there is an error accessing the 
    *                              URL.
	 */
	public ServiceDocument getServiceDocument(String url, String onBehalfOf ) throws SWORDClientException;
	
	/**
	 * Post a file to the specified destination URL. 
	 * 
	 * @param message    The message that defines the requirements for the operation. 
	 * 
	 * @return A DespoitResponse if the response is successful. If there was an error, 
	 *         <code>null</code> should be returned. 
	 *         
	 * @throws SWORDClientException If there is an error accessing the URL. 
	 */
	public DepositResponse postFile( PostMessage message ) throws SWORDClientException;
}
