Subversion Repositories XServices

/*

 *   Copyright 2010 Brian Rosenberger (Brutex Network)

 *

 *   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 net.brutex.xservices.ws;

import java.util.List;

import javax.jws.WebMethod;

import javax.jws.WebParam;

import javax.jws.WebService;

import javax.xml.bind.annotation.XmlElement;

import org.apache.cxf.annotations.WSDLDocumentation;

import org.apache.cxf.annotations.WSDLDocumentationCollection;

import net.brutex.xservices.types.ArchiveResource;

import net.brutex.xservices.types.AttachmentType;

import net.brutex.xservices.types.FileResource;

import net.brutex.xservices.types.FileSetResource;

import net.brutex.xservices.types.ReplacePattern;

import net.brutex.xservices.types.ReturnCode;

import net.brutex.xservices.util.BrutexNamespaces;

import net.brutex.xservices.util.XServicesDocumentation;

/**

 * File related web service operations.

 *

 * @author Brian Rosenberger

 * @since 0.3.0

 *

 */

@WebService(targetNamespace = BrutexNamespaces.WS_XSERVICES)

@WSDLDocumentationCollection(

    {

    	@WSDLDocumentation(value = BrutexNamespaces.BRUTEX_COPYRIGHT, placement = WSDLDocumentation.Placement.TOP)

    }

)

public interface FileService {

	final String OPERATION_BASENAME ="basename";

	final String OPERATION_DOWNLOADFILE ="downloadFile";

	final String OPERATION_UPLOADFILE ="uploadFile";

	final String OPERATION_COPY ="copy";

	final String OPERATION_COPYFILE ="copyFile";

	final String OPERATION_LOADRESOURCE = "loadResource";

	final String OPERATION_LOADRESOURCEFROMARCHIVE = "loadResourceFromArchive";

	final String OPERATION_ECHOTOFILE = "echoToFile";

	final String OPERATION_CHANGEOWNER = "changeOwner";

	final String OPERATION_CHANGEMODE = "changeMode";

	final String OPERATION_CHANGEGROUP = "changeGroup";

	final String OPERATION_REPLACEINFILE = "replaceInFile";

	final String OPERATION_REPLACEINFILE2 = "replaceInFile2";

	final String OPERATION_REPLACEINFILEREGEX = "replaceInFileRegEx";

	final String PARAM_FILE = "file";

	final String PARAM_ENCODING = "encoding";

	final String PARAM_OVERRIDE = "override";

	/**

	 * @param filename

	 * @param suffix

	 * @return The base name of the given file excluding the suffix.

	 */

	@WSDLDocumentation(value = "The base name of the given file excluding the suffix.")

	@WebMethod(operationName = OPERATION_BASENAME)

	public abstract String basename(

			@WebParam(name = PARAM_FILE) @XmlElement(required=true) String filename,

			@WebParam(name = "suffix") String suffix);

	/**

	 * @param res

	 * @return The file itself (MTOM attachment or inline base64) including some file metadata.

	 * @throws XServicesFault

	 */

	@WSDLDocumentation(XServicesDocumentation.SERVICE_OPERATION_DOWNLOADFILE)

	@WebMethod(operationName = OPERATION_DOWNLOADFILE)

	public abstract AttachmentType downloadFile(

			@WebParam(name = FileResource.XML_NAME) FileResource res) throws XServicesFault;

	/**

	 * @param file

	 * @return The file name of the file that has been uploaded.

	 * @throws XServicesFault

	 */

	@WSDLDocumentation(XServicesDocumentation.SERVICE_OPERATION_UPLOADFILE)

	@WebMethod(operationName = OPERATION_UPLOADFILE)

	public abstract String uploadFile(

			@WebParam(name = PARAM_FILE) AttachmentType file) throws XServicesFault;

	/**

	 * @param src

	 * @param todir

	 * @param plm

	 * @param overwrite

	 * @param encoding

	 * @return

	 * @throws XServicesFault

	 */

	@WSDLDocumentation(value = XServicesDocumentation.SERVICE_OPERATION_COPY)

	@WebMethod(operationName = OPERATION_COPY)

	public abstract ReturnCode copy(

			@WebParam(name =  FileSetResource.XML_NAME) @XmlElement(required=true) FileSetResource src,

			@WebParam(name = "todir") @XmlElement(required=true) String todir,

			@WebParam(name = "preservelastmodified") boolean plm,

			@WebParam(name = PARAM_OVERRIDE) boolean overwrite,

			@WebParam(name = PARAM_ENCODING) String encoding) throws XServicesFault;

	/**

	 * @param fromFile

	 * @param tofile

	 * @param overwrite

	 * @return

	 * @throws XServicesFault

	 */

	@WSDLDocumentation(value = XServicesDocumentation.SERVICE_OPERATION_COPYFILE)

	@WebMethod(operationName = OPERATION_COPYFILE)

	public abstract ReturnCode copyFile(

			@WebParam(name = "fromFile") @XmlElement(required=true) String fromFile,

			@WebParam(name = "toFile") @XmlElement(required=true) String tofile,

			@WebParam(name = PARAM_OVERRIDE) boolean overwrite) throws XServicesFault;

	/**

	 * @param res

	 * @param encoding

	 * @return content of the resource

	 * @throws XServicesFault

	 */

	@WSDLDocumentation(value = XServicesDocumentation.SERVICE_OPERATION_LOADRESOURCE)

	@WebMethod(operationName = OPERATION_LOADRESOURCE)

	public abstract String loadRes(

			@WebParam(name = FileResource.XML_NAME) FileResource res,

			@WebParam(name = PARAM_ENCODING) String encoding) throws XServicesFault;

	/**

	 * @param res

	 * @param encoding

	 * @return content of the resource

	 * @throws XServicesFault

	 */

	@WSDLDocumentation(value = XServicesDocumentation.SERVICE_OPERATION_LOADRESOURCEFROMARCHIVE)

	@WebMethod(operationName = OPERATION_LOADRESOURCEFROMARCHIVE)

	public abstract String loadResFromArchive(

			@WebParam(name = "archiveresource") ArchiveResource res,

			@WebParam(name = PARAM_ENCODING) String encoding) throws XServicesFault;

	/**

	 * @param message

	 * @param file

	 * @param encoding

	 * @param append

	 * @return

	 * @throws XServicesFault

	 */

	@WSDLDocumentation(value = XServicesDocumentation.SERVICE_OPERATION_ECHOTOFILE)

	@WebMethod(operationName = OPERATION_ECHOTOFILE)

	public abstract ReturnCode echo2file(

			@WebParam(name = "message") @XmlElement(required=true) String message,

			@WebParam(name = PARAM_FILE) @XmlElement(required=true) String file,

			@WebParam(name = PARAM_ENCODING) String encoding,

			@WebParam(name = "append") boolean append) throws XServicesFault;

	/**

	 * Changes the owner of a file or all files inside specified directories.

	 * Right now it has effect only under Unix/ Linux as it is implemented through

	 * the 'chown' command.

	 *

	 * @param res Collection of files/ directories

	 * @param owner Identifier of the new owner

	 * @return

	 */

	@WebMethod(operationName = OPERATION_CHANGEOWNER)

	public abstract ReturnCode changeOwner(

			@WebParam(name =  FileSetResource.XML_NAME) FileSetResource res,

			@WebParam(name = "owner") @XmlElement(required=true) String owner);

	/**

	 * Changes the group owner of a file or all files inside specified directories.

	 * Right now it has effect only under Unix/ Linux as it is implemented through

	 * the 'chgrp' command.

	 *

	 * @param res Collection of files/ directories

	 * @param group Identifier of the new group owner

	 * @return

	 */

	@WebMethod(operationName = OPERATION_CHANGEGROUP)

	public abstract ReturnCode changeGroup(

			@WebParam(name =  FileSetResource.XML_NAME) FileSetResource res,

			@WebParam(name = "group") @XmlElement(required=true) String group);

	/**

	 * @param res

	 * @param perm

	 * @return

	 */

	@WebMethod(operationName = OPERATION_CHANGEMODE)

	public abstract ReturnCode changeMode(

			@WebParam(name = FileSetResource.XML_NAME) FileSetResource res,

			@WebParam(name = "permissions") @XmlElement(required=true) String perm);

	/**

	 * @param res

	 * @param search

	 * @param replace

	 * @return

	 * @throws XServicesFault

	 */

	@WSDLDocumentation(value = XServicesDocumentation.SERVICE_OPERATION_REPLACEINFILE)

	@WebMethod(operationName = OPERATION_REPLACEINFILE)

	public abstract ReturnCode replaceInFile(

			@WebParam(name = FileResource.XML_NAME) @XmlElement(required=true) FileResource res,

			@WebParam(name = "search") @XmlElement(required=true) String search,

			@WebParam(name = "replace") @XmlElement(required=true) String replace) throws XServicesFault;

	/**

	 * @param res

	 * @param patternList

	 * @return

	 * @throws XServicesFault

	 */

	@WSDLDocumentation(value = XServicesDocumentation.SERVICE_OPERATION_REPLACEINFILE2)

	@WebMethod(operationName = OPERATION_REPLACEINFILE2)

	public abstract ReturnCode replaceInFile2(

			@WebParam(name = FileResource.XML_NAME) FileResource res,

			@WebParam(name = "patternList") List<ReplacePattern> patternList) throws XServicesFault;

	/**

	 * @param res

	 * @param search

	 * @param replace

	 * @param flags

	 * @return

	 * @throws XServicesFault

	 */

	@WSDLDocumentation(value = XServicesDocumentation.SERVICE_OPERATION_REPLACEINFILEREGEX)

	@WebMethod(operationName = OPERATION_REPLACEINFILEREGEX)

	public abstract ReturnCode replaceInFileRegEx(

			@WebParam(name = FileResource.XML_NAME) FileResource res,

			@WebParam(name = "search") String search,

			@WebParam(name = "replace") String replace,

			@WebParam(name = "flags") String flags) throws XServicesFault;

}