Added javadoc information

git-svn-id: https://brutex.net/svn/xservices/trunk@10 e7e49efb-446e-492e-b9ec-fcafc1997a86

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) {

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:<br>
+     * <code>c:/path/to/myfile.txt<br>
+     * /usr/share/file<br>
+     * http://server/path/file.zip</code>
+     */
     @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) {

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",
+@XmlType(name = "FileSetType", namespace = "http://ws.xservices.brutex.net",
-    propOrder={"type", "source", "includes", "excludes", "casesensitive"})
+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="")
+     * Pattern of files to exclude.
-    public String excludes ="";
+     */
-
+    @XmlElement(name = "excludes", required = false, nillable = true, defaultValue = "")
-    @XmlElement(name="casesensitive", required=true, nillable=false, defaultValue="true")
+    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{
+    public enum FileSetType {
-        FILES, ZIP, TAR, GZTAR
-    }
 
+        /**
+         * 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
+    }
 }

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

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;

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<String, String> result = runner.postTask();
-        return "complete";
+        return new ReturnCode(0,"complete","");
     }
 
     @WebMethod(exclude = true)