/*
 *   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 com.sun.xml.internal.ws.api.model.wsdl.WSDLDescriptorKind;

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;
/**
 * @author Brian Rosenberger
 *
 */
@WebService(targetNamespace = BrutexNamespaces.WS_XSERVICES)
@WSDLDocumentationCollection(
    {
    	@WSDLDocumentation(value = BrutexNamespaces.BRUTEX_COPYRIGHT, placement = WSDLDocumentation.Placement.TOP)
    }
)
public interface FileService {

	/**
	 * @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 = "basename")
	public abstract String basename(
			@WebParam(name = "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.
	 */
	@WSDLDocumentation(XServicesDocumentation.SERVICE_OPERATION_DOWNLOADFILE)
	@WebMethod(operationName = "downloadFile")
	public abstract AttachmentType downloadFile(
			@WebParam(name = "file") FileResource res);
	
	/**
	 * @param file
	 * @return The file name of the file that has been uploaded.
	 */
	@WSDLDocumentation(XServicesDocumentation.SERVICE_OPERATION_UPLOADFILE)
	@WebMethod(operationName = "uploadFile")
	public abstract String uploadFile(
			@WebParam(name = "file") AttachmentType file);
			
	/**
	 * @param src
	 * @param todir
	 * @param plm
	 * @param overwrite
	 * @param encoding
	 * @return 
	 * @throws XServicesFault
	 */
	@WSDLDocumentation(value = XServicesDocumentation.SERVICE_OPERATION_COPY)
	@WebMethod(operationName = "copy")
	public abstract ReturnCode copy(
			@WebParam(name = "fileset") @XmlElement(required=true) FileSetResource src,
			@WebParam(name = "todir") @XmlElement(required=true) String todir,
			@WebParam(name = "preservelastmodified") boolean plm,
			@WebParam(name = "overwrite") boolean overwrite,
			@WebParam(name = "encoding") String encoding) throws XServicesFault;
	
	/**
	 * @param fromFile
	 * @param tofile
	 * @param overwrite
	 * @return
	 * @throws XServicesFault
	 */
	@WSDLDocumentation(value = XServicesDocumentation.SERVICE_OPERATION_COPYFILE)
	@WebMethod(operationName = "copyFile")
	public abstract ReturnCode copyFile(
			@WebParam(name = "fromFile") @XmlElement(required=true) String fromFile,
			@WebParam(name = "toFile") @XmlElement(required=true) String tofile,
			@WebParam(name = "overwrite") boolean overwrite) throws XServicesFault;

	/**
	 * @param res
	 * @param encoding
	 * @return content of the resource
	 */
	@WSDLDocumentation(value = XServicesDocumentation.SERVICE_OPERATION_LOADRESOURCE)
	@WebMethod(operationName = "loadResource")
	public abstract String loadRes(
			@WebParam(name = "resource") FileResource res,
			@WebParam(name = "encoding") String encoding);

	/**
	 * @param res
	 * @param encoding
	 * @return content of the resource
	 */
	@WSDLDocumentation(value = XServicesDocumentation.SERVICE_OPERATION_LOADRESOURCEFROMARCHIVE)
	@WebMethod(operationName = "loadResourceFromArchive")
	public abstract String loadResFromArchive(
			@WebParam(name = "archiveresource") ArchiveResource res,
			@WebParam(name = "encoding") String encoding);

	/**
	 * @param message
	 * @param file
	 * @param encoding
	 * @param append
	 * @return
	 */
	@WSDLDocumentation(value = XServicesDocumentation.SERVICE_OPERATION_ECHOTOFILE)
	@WebMethod(operationName = "echoToFile")
	public abstract ReturnCode echo2file(
			@WebParam(name = "message") @XmlElement(required=true) String message,
			@WebParam(name = "file") @XmlElement(required=true) String file,
			@WebParam(name = "encoding") String encoding,
			@WebParam(name = "append") boolean append);

	@WebMethod(operationName = "changeOwner")
	public abstract ReturnCode changeOwner(
			@WebParam(name = "fileset") FileSetResource res,
			@WebParam(name = "owner") @XmlElement(required=true) String owner);

	@WebMethod(operationName = "changeGroup")
	public abstract ReturnCode changeGroup(
			@WebParam(name = "fileset") FileSetResource res,
			@WebParam(name = "group") @XmlElement(required=true) String group);

	@WebMethod(operationName = "changeMode")
	public abstract ReturnCode changeMode(
			@WebParam(name = "fileset") FileSetResource res,
			@WebParam(name = "permissions") @XmlElement(required=true) String perm);
	
	@WebMethod(operationName = "replaceInFile")
	public abstract ReturnCode replaceInFile(
			@WebParam(name = "file") @XmlElement(required=true) FileResource res,
			@WebParam(name = "search") @XmlElement(required=true) String search,
			@WebParam(name = "replace") @XmlElement(required=true) String replace);
	
	@WebMethod(operationName = "replaceInFile2")
	public abstract ReturnCode replaceInFile2(
			@WebParam(name = "file") FileResource res,
			@WebParam(name = "patternList") List<ReplacePattern> patternList);
	
	@WebMethod(operationName = "replaceInFileRegEx")
	public abstract ReturnCode replaceInFileRegEx(
			@WebParam(name = "file") FileResource res,
			@WebParam(name = "search") String search,
			@WebParam(name = "replace") String replace,
			@WebParam(name = "flags") String flags);
}