From f25e3d4af9c7676ddc59134e9a429497edba9151 Mon Sep 17 00:00:00 2001 From: Brian Rosenberger Date: Sat, 9 Jan 2010 11:51:14 +0000 Subject: [PATCH] Added javadoc information git-svn-id: https://brutex.net/svn/xservices/trunk@10 e7e49efb-446e-492e-b9ec-fcafc1997a86 --- .../xservices/types/ArchiveResource.java | 51 ++++++++++++- .../brutex/xservices/types/FileResource.java | 58 ++++++++++++++- .../xservices/types/FileSetResource.java | 74 ++++++++++++++----- .../xservices/types/ResourceInterface.java | 7 ++ .../brutex/xservices/types/ReturnCode.java | 43 +++++++++-- .../brutex/xservices/ws/ArchiveService.java | 9 ++- 6 files changed, 209 insertions(+), 33 deletions(-) diff --git a/src/java/net/brutex/xservices/types/ArchiveResource.java b/src/java/net/brutex/xservices/types/ArchiveResource.java index 1d0f013..c8a8dbb 100644 --- a/src/java/net/brutex/xservices/types/ArchiveResource.java +++ b/src/java/net/brutex/xservices/types/ArchiveResource.java @@ -20,6 +20,7 @@ import java.io.File; import javax.xml.bind.annotation.XmlElement; import javax.xml.bind.annotation.XmlEnum; import javax.xml.bind.annotation.XmlType; +import net.brutex.xservices.util.BrutexNamespaces; import org.apache.tools.ant.Project; import org.apache.tools.ant.types.Resource; import org.apache.tools.ant.types.resources.TarResource; @@ -28,26 +29,68 @@ import org.apache.tools.tar.TarEntry; import org.apache.tools.zip.ZipEntry; /** - * + * Resource from archive declaration. + * + * Defines a resource within an archive. * @author Brian Rosenberger, bru@brutex.de */ -@XmlType(namespace = "http://ws.xservices.brutex.net") +@XmlType(namespace = BrutexNamespaces.WS_XSERVICES, name="ArchiveResourceType") public class ArchiveResource implements ResourceInterface { + /** + * Archive Type. + */ @XmlElement(defaultValue = "ZIP", nillable = false, required = true) public ArchiveType type = ArchiveType.ZIP; + + /** + * Archive file. + * + * Path and filename of the archive to use. + */ @XmlElement(nillable = false, required = true) public String archive; + + /** + * URI within the archive. + * + * This is usually a filename or a path/filename combination. Relative paths + * are based from the archive root. It depends on how the archive has been + * created wether or not it is possible to use relative paths, absolute + * paths are required otherwise. Uses "/" as separator. + */ @XmlElement(nillable = false, required = true) public String uri; - @XmlEnum(String.class) + /** + * Supported archive types. + */ + @XmlEnum(value=String.class) public enum ArchiveType { - ZIP, TAR, GZTAR + /** + * Zip archive type. + */ + ZIP, + + /** + * Tar archive type, without compression + */ + TAR, + + /** + * Tar archive type, with GZIP compression + */ + GZTAR } + /** + * Get Apache Ant Resource Type. + * + * @param p Ant project + * @return this ArchiveResource as Ant Resource + */ public Resource getAntResource(Project p) { Resource res = null; switch (type) { diff --git a/src/java/net/brutex/xservices/types/FileResource.java b/src/java/net/brutex/xservices/types/FileResource.java index 0248aac..21d888a 100644 --- a/src/java/net/brutex/xservices/types/FileResource.java +++ b/src/java/net/brutex/xservices/types/FileResource.java @@ -20,6 +20,7 @@ import java.io.File; import javax.xml.bind.annotation.XmlElement; import javax.xml.bind.annotation.XmlEnum; import javax.xml.bind.annotation.XmlRootElement; +import net.brutex.xservices.util.BrutexNamespaces; import org.apache.tools.ant.Project; import org.apache.tools.ant.types.Resource; import org.apache.tools.ant.types.resources.BZip2Resource; @@ -27,32 +28,83 @@ import org.apache.tools.ant.types.resources.GZipResource; import org.apache.tools.ant.types.resources.URLResource; /** + * File based resource declaration. * * @author Brian Rosenberger, bru@brutex.de */ -@XmlRootElement(namespace="http://ws.xservices.brutex.net") +@XmlRootElement(namespace=BrutexNamespaces.WS_XSERVICES, name="FileResourceType") public class FileResource implements ResourceInterface { + /** + * File resource type. + */ @XmlElement(defaultValue = "FILE", nillable = false, required = true) public Type type = Type.FILE; + + /** + * URI to file. + * + * Examples:
+ * c:/path/to/myfile.txt
+ * /usr/share/file
+ * http://server/path/file.zip + */ @XmlElement(nillable = false, required = true) public String uri; - @XmlEnum(String.class) + /** + * File resource type. + * + * Defines the wrapper around the source. + */ + @XmlEnum(value=String.class) public enum Type { - FILE, URL, GZIP, BZIP2 + /** + * Plain file from OS accessible file system. + */ + FILE, + + /** + * File from URL (http, https, ftp, ...) + */ + URL, + + /** + * File from file system with on-the-fly GZIP decompression + */ + GZIP, + + /** + * File from file system with on-the-fly BZIP2 decompression + */ + BZIP2 } + /** + * Creates a FileResource. + * + * @param type file resource type + * @param uri file resource uri + */ public FileResource(Type type, String uri) { this.type = type; this.uri = uri; } + /** + * Create an empty FileResource + */ public FileResource() { } + /** + * Get Apache Ant Resource type. + * + * @param p Ant project + * @return This FileResource as Ant Resource + */ public Resource getAntResource(Project p) { Resource res = null; switch (type) { diff --git a/src/java/net/brutex/xservices/types/FileSetResource.java b/src/java/net/brutex/xservices/types/FileSetResource.java index 1223863..cf0a657 100644 --- a/src/java/net/brutex/xservices/types/FileSetResource.java +++ b/src/java/net/brutex/xservices/types/FileSetResource.java @@ -13,7 +13,6 @@ * See the License for the specific language governing permissions and * limitations under the License. */ - package net.brutex.xservices.types; import java.io.File; @@ -27,31 +26,53 @@ import org.apache.tools.ant.types.TarFileSet; import org.apache.tools.ant.types.ZipFileSet; /** + * Set of files from various sources. * * @author Brian Rosenberger, bru@brutex.de */ -@XmlType(name="FileSetType", namespace="http://ws.xservices.brutex.net", - propOrder={"type", "source", "includes", "excludes", "casesensitive"}) +@XmlType(name = "FileSetType", namespace = "http://ws.xservices.brutex.net", +propOrder = {"type", "source", "includes", "excludes", "casesensitive"}) public class FileSetResource { - @XmlElement(name="FileSetType", required=true, nillable=false, defaultValue="FILES") + /** + * Type of FileSet + */ + @XmlElement(name = "FileSetType", required = true, nillable = false, defaultValue = "FILES") public FileSetType type = FileSetType.FILES; - - @XmlElement(name="source", required=true, nillable=false) + /** + * File set source. + * + * Depends on the file set type. This is either an archive file or a + * directory. + */ + @XmlElement(name = "source", required = true, nillable = false) public String source = ""; - - @XmlElement(name="includes", required=true, nillable=false, defaultValue="**/*") + /** + * Pattern of files to include. + * + */ + @XmlElement(name = "includes", required = true, nillable = false, defaultValue = "**/*") public String includes = ""; - - @XmlElement(name="excludes", required=false, nillable=true, defaultValue="") - public String excludes =""; - - @XmlElement(name="casesensitive", required=true, nillable=false, defaultValue="true") + /** + * Pattern of files to exclude. + */ + @XmlElement(name = "excludes", required = false, nillable = true, defaultValue = "") + public String excludes = ""; + /** + * Case sensitivity for include/ exclude patterns. + */ + @XmlElement(name = "casesensitive", required = true, nillable = false, defaultValue = "true") public boolean casesensitive = true; + /** + * Get Ant FileSet for this file set. + * + * @param p Ant project + * @return Ant FileSet for this file set. + */ public FileSet getAntFileSet(Project p) { FileSet set = null; - switch(type) { + switch (type) { case ZIP: ZipFileSet zset = new ZipFileSet(); zset.setSrc(new File(source)); @@ -81,9 +102,28 @@ public class FileSetResource { return set; } + /** + * File set types. + */ @XmlEnum - public enum FileSetType{ - FILES, ZIP, TAR, GZTAR - } + public enum FileSetType { + /** + * Set of files (this is based on a directory, so provide a path only + * as file set source). + */ + FILES, + /** + * Set of files inside a ZIP archive. + */ + ZIP, + /** + * Set of files inside a TAR archive (without compression). + */ + TAR, + /** + * Set of files inside a gzip compressed TAR archive. + */ + GZTAR + } } diff --git a/src/java/net/brutex/xservices/types/ResourceInterface.java b/src/java/net/brutex/xservices/types/ResourceInterface.java index caa5ab0..11f72a1 100644 --- a/src/java/net/brutex/xservices/types/ResourceInterface.java +++ b/src/java/net/brutex/xservices/types/ResourceInterface.java @@ -20,11 +20,18 @@ import org.apache.tools.ant.Project; import org.apache.tools.ant.types.Resource; /** + * Wrapper for Ant Resources. * * @author Brian Rosenberger, bru@brutex.de */ public interface ResourceInterface { + /** + * Get this resource as Ant Resource. + * + * @param p Ant project + * @return this resource as Ant Resource + */ Resource getAntResource(Project p); } diff --git a/src/java/net/brutex/xservices/types/ReturnCode.java b/src/java/net/brutex/xservices/types/ReturnCode.java index ac43298..cb3b398 100644 --- a/src/java/net/brutex/xservices/types/ReturnCode.java +++ b/src/java/net/brutex/xservices/types/ReturnCode.java @@ -18,23 +18,56 @@ package net.brutex.xservices.types; import javax.xml.bind.annotation.XmlElement; import javax.xml.bind.annotation.XmlType; +import net.brutex.xservices.util.BrutexNamespaces; /** * * @author Brian Rosenberger, bru@brutex.de */ -@XmlType(namespace="http://ws.xservices.brutex.net") +@XmlType(namespace=BrutexNamespaces.WS_XSERVICES, name="ReturnCodeType") public class ReturnCode { - @XmlElement(required=true) - public int returnCode; + /** + * Numeric return code. + * + * The numeric return code of the last operation on the underlying operation + * systen (OS). In general the return code indicates the failure or success + * of a command. Which value indicates success is dependent on the OS, most + * linux based systems use "0" for success. + */ + @XmlElement(required=true, nillable=false) + public int returnCode=0; - public String stdOut; - public String stdErr; + /** + * Standard Out as provided by the OS. + * + * The stdOut given by the last operation (if any). + */ + @XmlElement(name="stdOut", nillable=false) + public String stdOut=""; + /** + * The Standard Error as provided by the OS. + * + * The stdErr given by the last operation (if any). The presents of any + * value here ususally indicates that a failure has occured. + */ + @XmlElement(name="stdErr", nillable=false) + public String stdErr=""; + + /** + * Create a new ReturnCode default constructor. + */ public ReturnCode() { } + /** + * Create a new ReturnCode. + * + * @param returnCode return code integer value + * @param stdOut standard out string + * @param stdErr standard error string + */ public ReturnCode(int returnCode, String stdOut, String stdErr) { this.returnCode = returnCode; this.stdOut = stdOut; diff --git a/src/java/net/brutex/xservices/ws/ArchiveService.java b/src/java/net/brutex/xservices/ws/ArchiveService.java index 1562c5d..563459e 100644 --- a/src/java/net/brutex/xservices/ws/ArchiveService.java +++ b/src/java/net/brutex/xservices/ws/ArchiveService.java @@ -25,6 +25,7 @@ import net.brutex.xservices.types.ArchiveResource; import net.brutex.xservices.types.CompressionType; import net.brutex.xservices.types.FileResource; import net.brutex.xservices.types.ResourceInterface; +import net.brutex.xservices.types.ReturnCode; import net.brutex.xservices.util.RunTask; import net.brutex.xservices.util.UnRarTask; import org.apache.tools.ant.taskdefs.BUnzip2; @@ -61,13 +62,13 @@ public class ArchiveService { public static final String WS_PARAM_OVERWRITE= "overwrite"; @WebMethod(operationName = WS_OPERATION_BZIP2, action=WS_OPERATION_BZIP2) - public String bzip2(@WebParam(name = WS_PARAM_SOURCEFILE) FileResource src, + public ReturnCode bzip2(@WebParam(name = WS_PARAM_SOURCEFILE) FileResource src, @WebParam(name = WS_PARAM_DESTFILE) String file) { return bzip(src, new File(file)); } @WebMethod(operationName = WS_OPERATION_BZIP2_ARCHIVE, action=WS_OPERATION_BZIP2_ARCHIVE) - public String bzip2FromArchive(@WebParam(name = WS_PARAM_SOURCEARCHIVE) ArchiveResource src, + public ReturnCode bzip2FromArchive(@WebParam(name = WS_PARAM_SOURCEARCHIVE) ArchiveResource src, @WebParam(name = WS_PARAM_DESTFILE) String file) { return bzip(src, new File(file)); } @@ -184,7 +185,7 @@ public class ArchiveService { } @WebMethod(exclude = true) - private String bzip(ResourceInterface src, File dst) { + private ReturnCode bzip(ResourceInterface src, File dst) { if (dst.exists() && dst.isFile()) { dst.delete(); } @@ -195,7 +196,7 @@ public class ArchiveService { bzip.setDestfile(dst); Map result = runner.postTask(); - return "complete"; + return new ReturnCode(0,"complete",""); } @WebMethod(exclude = true)