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;
}