/**
 * Copyright 2010 JBoss Inc
 *
 * 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 org.eclipse.webdav;

import java.io.IOException;
import java.io.InputStream;
import org.w3c.dom.Document;

/**
 * Represents a WebDAV server API.
 * <p>
 * There is a one-to-one correspondence between the methods
 * in this interface and methods in the HTTP and WebDAV
 * protocols.</p>
 * <p>
 * The methods all return a response object; it is the
 * client's responsibility to <code>close()</code> the response
 * when they are done with it.</p>
 * <p>
 * <b>Note:</b> This class/interface is part of an interim API that is still under 
 * development and expected to change significantly before reaching stability. 
 * It is being made available at this early stage to solicit feedback from pioneering 
 * adopters on the understanding that any code that uses this API will almost 
 * certainly be broken (repeatedly) as the API evolves.
 * </p>
 */
public interface IServer {

	/**
	 * Corresponds to the BASELINE-CONTROL method defined in the WebDAV
	 * Versioning Specification.
	 * The <code>IResponse</code> body is undefined.
	 *
	 * @param locator the location of the collection to put under baseline control.
	 * @param context key-value pairings defined by the user.
	 * @param body the DOM document for the DAV:baseline element.
	 * @return the response from the server; the client
	 *   must send <code>close()</code> to the response when done with it.
	 * @exception IOException if there was a problem sending the request
	 *   or receiving the response.
	 */
	public IResponse baselineControl(ILocator locator, IContext context, Document body) throws IOException;

	/**
	 * Binds the given source locator, to the given destination. An overwrite boolean may
	 * be defined in the user context. Corresponds to the WebDAV method BIND defined 
	 * in the WebDAV Bindings Specification (part of the Advanced Collections Protocol)
	 *
	 * @param source the location of the resource
	 * @param destination the location of the resource's desired parent
	 * @param context key-value pairings as set by the user
	 * @return the response from the server; the client
	 *   must send <code>close()</code> to the response when done with it
	 * @exception IOException if there was a problem sending the request
	 *   or receiving the response
	 */
	public IResponse bind(ILocator source, ILocator destination, IContext context) throws IOException;

	/**
	 * Corresponds to the CHECKIN method defined in the WebDAV
	 * Versioning Specification.
	 * The <code>IResponse</code> body is undefined.
	 *
	 * @param locator the location of the resource to check in.
	 * @param context key-value pairings defined by the user.
	 * @param body DOM document for DAV:checkin.
	 * @return the response from the server; the client
	 *   must send <code>close()</code> to the response when done with it.
	 * @exception IOException if there was a problem sending the request
	 *   or receiving the response.
	 */
	public IResponse checkin(ILocator locator, IContext context, Document body) throws IOException;

	/**
	 * Corresponds to the CHECKOUT method defined in the WebDAV
	 * Versioning Specification.
	 * The <code>IResponse</code> body is undefined.
	 *
	 * @param locator the location of the resource
	 * @param context key-value pairings defined by the user
	 * @param body the XML elements that describe the parameters
	 *	of the checkout in a DAV:checkout element.
	 * @return the response from the server; the client
	 *   must send <code>close()</code> to the response when done with it.
	 * @exception IOException if there was a problem sending the request
	 *   or receiving the response.
	 */
	public IResponse checkout(ILocator locator, IContext context, Document body) throws IOException;

	/**
	 * Copies the resource with the given locator, to the given
	 * destination. Corresponds to the COPY method defined in
	 * the WebDAV Specification.
	 *
	 * @param source the location of the resource
	 * @param destination the desired location of the resource copy
	 * @param context key-value pairings as defined by the user
	 * @param body XML document describing the properties to copy
	 * @return the response from the server; the client
	 *   must send <code>close()</code> to the response when done with it
	 * @exception IOException if there was a problem sending the request
	 *   or receiving the response
	 */
	public IResponse copy(ILocator source, ILocator destination, IContext context, Document body) throws IOException;

	/**
	 * Deletes the resource with the given locator. Corresponds to
	 * the DELETE method defined in the HTTP/1.1 Specfication.
	 *
	 * @param locator the location of the resource
	 * @param context key-value pairings as defined by the user
	 * @return the response from the server; the client
	 *   must send <code>close()</code> to the response when done with it
	 * @exception IOException if there was a problem sending the request
	 *   or receiving the response
	 */
	public IResponse delete(ILocator locator, IContext context) throws IOException;

	/**
	 * Gets the content of the resource with the given locator.
	 * Corresponds to the GET method defined in the HTTP/1.1 specification.
	 * <p>
	 * The input stream in the resulting response body should be closed
	 * by the user.</p>
	 *
	 * @param locator the location of the resource
	 * @param context key-value pairings as defined by the user
	 * @return the response from the server; the client
	 *   must send <code>close()</code> to the response when done with it
	 * @exception IOException if there was a problem sending the request
	 *   or receiving the response
	 */
	public IResponse get(ILocator locator, IContext context) throws IOException;

	/**
	 * Returns the message headers from a message send to the server.
	 * Corresponds to the HEAD method defined in the HTTP/1.1 specification.
	 *
	 * @param locator the location of the resource
	 * @param context key-value pairings as defined by the user
	 * @return the response from the server; the client
	 *   must send <code>close()</code> to the response when done with it
	 * @exception IOException if there was a problem sending the request
	 *   or receiving the response
	 */
	public IResponse head(ILocator locator, IContext context) throws IOException;

	/**
	 * Corresponds to the LABEL method defined in the WebDAV
	 * Versioning Specification.
	 * The <code>IResponse</code> body is undefined.
	 *
	 * @param locator the location of the resource
	 * @param context key-value pairings defined by the user
	 * @param body DOM document for DAV:label element
	 * @return the response from the server; the client
	 *   must send <code>close()</code> to the response when done with it
	 * @exception IOException if there was a problem sending the request
	 *   or receiving the response
	 */
	public IResponse label(ILocator locator, IContext context, Document body) throws IOException;

	/**
	 * Locks the resource with the given locator. Use the information
	 * contained in the context and DAV:lockinfo element. Corresponds
	 * to the LOCK method defined in the WebDAV specification.
	 *
	 * @param locator the location of the resource
	 * @param context key-value pairings defined by the user
	 * @param body XML document containing lock information
	 * @return the response from the server; the client
	 *   must send <code>close()</code> to the response when done with it
	 * @exception IOException if there was a problem sending the request
	 *   or receiving the response
	 */
	public IResponse lock(ILocator locator, IContext context, Document body) throws IOException;

	/**
	 * Corresponds to the MERGE method defined in the WebDAV
	 * Versioning Specification.
	 *
	 * @param locator the location of the resource
	 * @param context key-value pairings defined by the user
	 * @param body XML document containing MERGE parameters
	 * @return the response from the server; the client
	 *   must send <code>close()</code> to the response when done with it
	 * @exception IOException if there was a problem sending the request
	 *   or receiving the response
	 */
	public IResponse merge(ILocator locator, IContext context, Document body) throws IOException;

	/**
	 * Creates an activity as specified by the given locator.
	 * Corresponds to the MKACTIVITY method as defined by the
	 * Delta-V Versioning Specification.
	 *
	 * @param locator the location of the new resource.
	 * @param context key-value pairings defined by the user.
	 * @param element an undefined XML body document.
	 * @return the response from the server; the client
	 *   must send <code>close()</code> to the response when done with it
	 * @exception IOException if there was a problem sending the request
	 *   or receiving the response.
	 */
	public IResponse mkactivity(ILocator locator, IContext context, Document element) throws IOException;

	/**
	 * Creates the collection specified by the given locator.
	 * Corresponds to the MKCOL method as defined by the WebDAV specification.
	 *
	 * @param locator the location of the resource
	 * @param context key-value pairings defined by the user
	 * @param element XML document containing properties
	 * @return the response from the server; the client
	 *   must send <code>close()</code> to the response when done with it
	 * @exception IOException if there was a problem sending the request
	 *   or receiving the response
	 */
	public IResponse mkcol(ILocator locator, IContext context, Document element) throws IOException;

	/**
	 * Creates a workspace as specified by the given locator. Corresponds to the
	 * MKWORKSPACE method as defined by the Delta-V Versioning Specification.
	 *
	 * @param locator the location of the new resource.
	 * @param context key-value pairings defined by the user.
	 * @param element an undefined XML body document.
	 * @return the response from the server; the client
	 *   must send <code>close()</code> to the response when done with it
	 * @exception IOException if there was a problem sending the request
	 *   or receiving the response.
	 */
	public IResponse mkworkspace(ILocator locator, IContext context, Document element) throws IOException;

	/**
	 * Moves the resource with the given source locator, to the
	 * specified destination. Corresponds to the MOVE method as
	 * defined by the WebDAV specification.
	 *
	 * @param source the location of the resource
	 * @param destination the desired location for the resource
	 * @param context key-value pairing defined by the user
	 * @param body XML document specifying the properties to move
	 * @return the response from the server; the client
	 *   must send <code>close()</code> to the response when done with it
	 * @exception IOException if there was a problem sending the request
	 *   or receiving the response
	 */
	public IResponse move(ILocator source, ILocator destination, IContext context, Document body) throws IOException;

	/**
	 * Performs an options call to the server. Answers a list of
	 * characteristics of the target resource.
	 * <p>
	 * Corresponds to the OPTIONS method as defined by the HTTP/1.1
	 * Specification.</p>
	 * <p>
	 * If the resource URL (in the locator) is "*", the server's
	 * general capabilities are queried.</p>
	 *
	 * @param locator the location of the resource
	 * @param context key-value pairings defined by the user
	 * @return the response from the server; the client
	 *   must send <code>close()</code> to the response when done with it
	 * @exception IOException if there was a problem sending the request
	 *   or receiving the response
	 */
	public IResponse options(ILocator locator, IContext context) throws IOException;

	/**
	 * Corresponds to the POST method as defined by the HTTP/1.1
	 * specification.
	 * <p>
	 * The given input stream will be closed by the server after
	 * the contents have been consumed.</p>
	 *
	 * @param locator the location of the resource
	 * @param context key-value pairings defined by the user
	 * @param input the input stream containing the resource data
	 * @return the response from the server; the client
	 *   must send <code>close()</code> to the response when done with it
	 * @exception IOException if there was a problem sending the request
	 *   or receiving the response
	 */
	public IResponse post(ILocator locator, IContext context, InputStream input) throws IOException;

	/**
	 * Performs a property find on the server. Corresponds to the
	 * PROPFIND method as defined by the WebDAV specification.
	 *
	 * @param locator the location of the resource
	 * @param context key-value pairings defined by the user
	 * @param body XML document as defined by the spec
	 * @return the response from the server; the client
	 *   must send <code>close()</code> to the response when done with it
	 * @exception IOException if there was a problem sending the request
	 *   or receiving the response
	 */
	public IResponse propfind(ILocator locator, IContext context, Document body) throws IOException;

	/**
	 * Performs a property patch call on the server. Corresponds to the
	 * PROPPATCH method as defined by the WebDAV specification.
	 *
	 * @param locator the location of the resource
	 * @param context key-value pairings defined by the user
	 * @param body XML document as defined by the spec
	 * @return the response from the server; the client
	 *   must send <code>close()</code> to the response when done with it
	 * @exception IOException if there was a problem sending the request
	 *   or receiving the response
	 */
	public IResponse proppatch(ILocator locator, IContext context, Document body) throws IOException;

	/**
	 * Puts the given contents onto the server into the specified
	 * location. Corresponds to the PUT method as defined by the
	 * HTTP/1.1 specification.
	 * <p>
	 * The given input stream will be closed by the server after the
	 * contents have been consumed.</p>
	 *
	 * @param locator the location of the resource
	 * @param context key-value pairings defined by the user
	 * @param input the input stream containing the resource data
	 * @return the response from the server; the client
	 *   must send <code>close()</code> to the response when done with it
	 * @exception IOException if there was a problem sending the request
	 *   or receiving the response
	 */
	public IResponse put(ILocator locator, IContext context, InputStream input) throws IOException;

	/**
	 * Corresponds to the REPORT method defined in the WebDAV
	 * Versioning Specification.
	 *
	 * @param locator the location of the resource
	 * @param context key-value pairings defined by the user
	 * @param body XML document containing REPORT parameters
	 * @return the response from the server; the client
	 *   must send <code>close()</code> to the response when done with it
	 * @exception IOException if there was a problem sending the request
	 *   or receiving the response
	 */
	public IResponse report(ILocator locator, IContext context, Document body) throws IOException;

	/**
	 * Does a trace call to the server. Corresponds to the TRACE method
	 * as defined by the HTTP/1.1 specification.
	 * <p>
	 * The input stream in the response body should be closed by the user.</p>
	 *
	 * @param locator the location of the resource
	 * @param context key-value pairings defined by the user
	 * @return the response from the server; the client
	 *   must send <code>close()</code> to the response when done with it
	 * @exception IOException if there was a problem sending the request
	 *   or receiving the response
	 */
	public IResponse trace(ILocator locator, IContext context) throws IOException;

	/**
	 * Corresponds to the UNCHECKOUT method defined in the WebDAV
	 * Versioning Specification.
	 *
	 * @param locator the location of the resource
	 * @param context key-value pairings defined by the user
	 * @return the response from the server; the client
	 *   must send <code>close()</code> to the response when done with it
	 * @exception IOException if there was a problem sending the request
	 *   or receiving the response
	 */
	public IResponse uncheckout(ILocator locator, IContext context) throws IOException;

	/**
	 * Unlocks the resource with the given locator. Corresponds to the
	 * UNLOCK method as defined by the WebDAV specification.
	 *
	 * @param locator the location of the resource
	 * @param context key-value pairings defined by the user
	 * @return the response from the server; the client
	 *   must send <code>close()</code> to the response when done with it
	 * @exception IOException if there was a problem sending the request
	 *   or receiving the response
	 */
	public IResponse unlock(ILocator locator, IContext context) throws IOException;

	/**
	 * Performs an update call on the server. Corresponds to the
	 * UPDATE method as defined by the Delta-V specification.
	 *
	 * @param locator the location of the version-controlled resource.
	 * @param context key-value pairings defined by the client.
	 * @param body DAV:update XML document as defined by the spec.
	 * @return the response from the server; the client
	 *   must send <code>close()</code> to the response when done with it
	 * @exception IOException if there was a problem sending the request
	 *   or receiving the response
	 */
	public IResponse update(ILocator locator, IContext context, Document body) throws IOException;

	/**
	 * Corresponds to the VERSION-CONTROL method defined in the WebDAV
	 * Versioning Specification.
	 *
	 * @param locator the location of the versionable resource.
	 * @param context key-value pairings defined by the user.
	 * @param body the request body elements as a DOM document.
	 * @return the response from the server; the client
	 *   must send <code>close()</code> to the response when done with it
	 * @exception IOException if there was a problem sending the request
	 *   or receiving the response
	 */
	public IResponse versionControl(ILocator locator, IContext context, Document body) throws IOException;
}
