changeset 91:730ff077a58c

More javadoc, some code formatting. artifacts/trunk@847 c6561f87-3c4e-4783-a992-168aeb5c3f6f
author Sascha L. Teichmann <sascha.teichmann@intevation.de>
date Sun, 28 Mar 2010 10:01:03 +0000
parents 68285f7bc476
children 73d0ebae81d7
files ChangeLog artifact-database/src/main/java/de/intevation/artifactdatabase/Config.java artifact-database/src/main/java/de/intevation/artifactdatabase/DBConnection.java artifact-database/src/main/java/de/intevation/artifactdatabase/DatabaseCleaner.java artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultArtifact.java artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultArtifactContextFactory.java artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultArtifactFactory.java artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultCallMeta.java artifact-database/src/main/java/de/intevation/artifactdatabase/XMLUtils.java artifact-database/src/main/java/de/intevation/artifactdatabase/rest/CreateResource.java artifact-database/src/main/java/de/intevation/artifactdatabase/rest/FactoriesResource.java
diffstat 11 files changed, 264 insertions(+), 17 deletions(-) [+]
line wrap: on
line diff
--- a/ChangeLog	Fri Mar 26 17:59:50 2010 +0000
+++ b/ChangeLog	Sun Mar 28 10:01:03 2010 +0000
@@ -1,3 +1,17 @@
+2010-03-28	Sascha L. Teichmann	<sascha.teichmann@intevation.de>
+
+    * artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultArtifactContextFactory.java,
+      artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultArtifact.java,
+      artifact-database/src/main/java/de/intevation/artifactdatabase/DBConnection.java,
+      artifact-database/src/main/java/de/intevation/artifactdatabase/Config.java,
+      artifact-database/src/main/java/de/intevation/artifactdatabase/XMLUtils.java,
+      artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultCallMeta.java,
+      artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultArtifactFactory.java,
+      artifact-database/src/main/java/de/intevation/artifactdatabase/rest/FactoriesResource.java,
+      artifact-database/src/main/java/de/intevation/artifactdatabase/rest/CreateResource.java,
+      artifact-database/src/main/java/de/intevation/artifactdatabase/DatabaseCleaner.java:
+      More javadoc, some code formatting.
+
 2010-03-26	Sascha L. Teichmann	<sascha.teichmann@intevation.de>
 
 	* artifact-database/src/main/java/de/intevation/artifactdatabase/ProxyArtifact.java,
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/Config.java	Fri Mar 26 17:59:50 2010 +0000
+++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/Config.java	Sun Mar 28 10:01:03 2010 +0000
@@ -19,27 +19,51 @@
 import org.apache.log4j.Logger;
 
 /**
+ * The central access to the configuration of the artifact database.
+ * This class provides some static methods to access the central
+ * configuration XML file via XPath.
+ *
  * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
  */
 public final class Config
 {
     private static Logger logger = Logger.getLogger(Config.class);
 
+    /**
+     * System property name where to find the configuration directory.
+     */
     public static final String CONFIG_DIR = "artifact.database.dir";
 
+    /**
+     * Default path to the configuration directory if none
+     * was specified by the CONFIG_DIR system property.
+     */
     public static final File CONFIG_DIR_DEFAULT =
         new File(new File(System.getProperty("user.home",
             System.getProperty("user.dir", "."))), ".artifactdb");
 
+    /**
+     * Name of the central configuration XML file.
+     */
     public static final String CONFIG_FILE  = "conf.xml";
 
-    public static final String CONFIG_DIR_PLACEHOLDER = "${artifacts.config.dir}";
+    /**
+     * Name of the configuration filename alias to be use
+     * within the configuration. This alias is replaced by
+     * the real path.
+     */
+    public static final String CONFIG_DIR_PLACEHOLDER =
+        "${artifacts.config.dir}";
 
     private static Document config;
 
     private Config() {
     }
 
+    /**
+     * Singleton access to the central XML configuration document.
+     * @return The central XML configuration document.
+     */
     public static synchronized final Document getConfig() {
         if (config == null) {
             config = loadConfig();
@@ -47,6 +71,12 @@
         return config;
     }
 
+    /**
+     * Returns the path to the configuartion directory. If a path
+     * was specified via the CONFIG_DIR system property this one
+     * is used. Else it falls back to default configuration path.
+     * @return The path to the configuartion directory.
+     */
     public static File getConfigDirectory() {
         String configDirString = System.getProperty(CONFIG_DIR);
 
@@ -62,6 +92,13 @@
         return configDir;
     }
 
+    /**
+     * Replaces the CONFIG_DIR_PLACEHOLDER alias with the real path
+     * of the configuration directory.
+     * @param path The path containing the CONFIG_DIR_PLACEHOLDER placeholder.
+     * @return The path where the CONFIG_DIR_PLACEHOLDER placeholders are
+     * replaced by the real path name.
+     */
     public static String replaceConfigDir(String path) {
         String configDir = getConfigDirectory().getAbsolutePath();
         return path.replace(CONFIG_DIR_PLACEHOLDER, configDir);
@@ -80,7 +117,8 @@
         }
 
         try {
-            DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
+            DocumentBuilderFactory factory =
+                DocumentBuilderFactory.newInstance();
             factory.setValidating(false); // XXX: This may change in future.
             return factory.newDocumentBuilder().parse(file);
         }
@@ -97,28 +135,75 @@
         return null;
     }
 
+    /**
+     * Convenience method to search within a given document tree via XPath.
+     * See {@link XMLUtils#xpath(Object, String, QName) } for details.
+     * @param root The object which is used as the root of the tree to
+     * be searched in.
+     * @param query The XPath query.
+     * @param returnType The type of the result.
+     * @return The result of type 'returnTyp' or null if something went
+     * wrong during XPath evaluation.
+     */
     public static final Object getXPath(
         Object root, String query, QName returnType
     ) {
         return XMLUtils.xpath(root, query, returnType);
     }
 
+    /**
+     * Convenience method to search within the central configuration via XPath.
+     * See {@link XMLUtils#xpath(Object, String, QName) } for details.
+     * @param query The XPath query.
+     * @param returnType The type of the result.
+     * @return The result of type 'returnTyp' or null if something went
+     * wrong during XPath evaluation.
+     */
     public static final Object getXPath(String query, QName returnType) {
         return XMLUtils.xpath(getConfig(), query, returnType);
     }
 
+    /**
+     * Convenience method to search for a node list within the central
+     * configuation document via XPath.
+     * @param query The XPath query.
+     * @return The queried node list or null if something went
+     * wrong during XPath evaluation.
+     */
     public static final NodeList getNodeSetXPath(String query) {
         return (NodeList)getXPath(query, XPathConstants.NODESET);
     }
 
+    /**
+     * Convenience method to search for a node within the central
+     * configuation document via XPath.
+     * @param query The XPath query.
+     * @return The queried node or null if something went
+     * wrong during XPath evaluation.
+     */
     public static final Node getNodeXPath(String query) {
         return (Node)getXPath(query, XPathConstants.NODE);
     }
 
+    /**
+     * Convenience method to search for a string within the central
+     * configuation document via XPath.
+     * @param xpath The XPath query.
+     * @return The queried string or null if something went
+     * wrong during XPath evaluation.
+     */
     public static final String getStringXPath(String xpath) {
         return getStringXPath(xpath, null);
     }
 
+    /**
+     * Convenience method to search for a string within the central
+     * configuation document via XPath.
+     * @param query The XPath query.
+     * @param def The string to be returned if the search has no results.
+     * @return The queried string or the default value if something went
+     * wrong during XPath evaluation.
+     */
     public static final String getStringXPath(String query, String def) {
         String s = (String)getXPath(query, XPathConstants.STRING);
         return s == null || s.length() == 0
@@ -126,18 +211,51 @@
             : s;
     }
 
+    /**
+     * Convenience method to search for a node list within a given tree
+     * via XPath.
+     * @param root The root of the tree to be searched in.
+     * @param query The XPath query.
+     * @return The queried node list or null if something went
+     * wrong during XPath evaluation.
+     */
     public static final NodeList getNodeSetXPath(Object root, String query) {
         return (NodeList)getXPath(root, query, XPathConstants.NODESET);
     }
 
+    /**
+     * Convenience method to search for a node within a given tree
+     * via XPath.
+     * @param root The root of the tree to be searched in.
+     * @param query The XPath query.
+     * @return The queried node or null if something went
+     * wrong during XPath evaluation.
+     */
     public static final Node getNodeXPath(Object root, String query) {
         return (Node)getXPath(root, query, XPathConstants.NODE);
     }
 
+    /**
+     * Convenience method to search for a string within a given tree
+     * via XPath.
+     * @param root The root of the tree to be searched in.
+     * @param xpath The XPath query.
+     * @return The queried string or null if something went
+     * wrong during XPath evaluation.
+     */
     public static final String getStringXPath(Object root, String xpath) {
         return getStringXPath(root, xpath, null);
     }
 
+    /**
+     * Convenience method to search for a string within a given tree
+     * via XPath.
+     * @param root The root of the tree to be searched in.
+     * @param query xpath The XPath query.
+     * @param def The string to be returned if the search has no results.
+     * @return The queried string or the default value if something went
+     * wrong during XPath evaluation.
+     */
     public static final String getStringXPath(
         Object root, String query, String def
     ) {
@@ -147,4 +265,4 @@
             : s;
     }
 }
-// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8:
+// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 :
\ No newline at end of file
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/DBConnection.java	Fri Mar 26 17:59:50 2010 +0000
+++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/DBConnection.java	Sun Mar 28 10:01:03 2010 +0000
@@ -134,4 +134,4 @@
         return dataSource;
     }
 }
-//  vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8:
+//  vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 :
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/DatabaseCleaner.java	Fri Mar 26 17:59:50 2010 +0000
+++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/DatabaseCleaner.java	Sun Mar 28 10:01:03 2010 +0000
@@ -116,7 +116,7 @@
 
     /**
      * Constructor to create a cleaner with a given global context
-     * and an given reviver.
+     * and a given reviver.
      * @param context The global context of the artifact database
      * @param reviver The reviver to awake artifact one last time.
      */
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultArtifact.java	Fri Mar 26 17:59:50 2010 +0000
+++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultArtifact.java	Sun Mar 28 10:01:03 2010 +0000
@@ -1,17 +1,18 @@
 package de.intevation.artifactdatabase;
 
+import de.intevation.artifacts.Artifact;
+import de.intevation.artifacts.ArtifactFactory;
+import de.intevation.artifacts.CallContext;
+
 import java.io.IOException;
 import java.io.OutputStream;
 
 import org.apache.log4j.Logger;
+
 import org.w3c.dom.Document;
 
-import de.intevation.artifacts.Artifact;
-import de.intevation.artifacts.ArtifactFactory;
-import de.intevation.artifacts.CallContext;
-
 /**
- * Trivial implementation of an artifact. Useful to subclass.
+ * Trivial implementation of an artifact. Useful to be subclassed.
  * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
  */
 public class DefaultArtifact
@@ -103,6 +104,9 @@
     }
 
     public void cleanup(Object context) {
+        if (logger.isDebugEnabled()) {
+            logger.debug("DefaultArtifact.cleanup: " + identifier);
+        }
     }
 }
-// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8:
+// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 :
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultArtifactContextFactory.java	Fri Mar 26 17:59:50 2010 +0000
+++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultArtifactContextFactory.java	Sun Mar 28 10:01:03 2010 +0000
@@ -23,4 +23,4 @@
         return new DefaultArtifactContext(config);
     }
 }
-// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8:
+// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 :
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultArtifactFactory.java	Fri Mar 26 17:59:50 2010 +0000
+++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultArtifactFactory.java	Sun Mar 28 10:01:03 2010 +0000
@@ -155,4 +155,4 @@
         return DefaultArtifactSerializer.INSTANCE;
     }
 }
-// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8:
+// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 :
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultCallMeta.java	Fri Mar 26 17:59:50 2010 +0000
+++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultCallMeta.java	Sun Mar 28 10:01:03 2010 +0000
@@ -70,4 +70,4 @@
             : best;
     }
 }
-// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8:
+// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 :
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/XMLUtils.java	Fri Mar 26 17:59:50 2010 +0000
+++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/XMLUtils.java	Sun Mar 28 10:01:03 2010 +0000
@@ -34,11 +34,19 @@
 import org.xml.sax.SAXException;
 
 /**
+ * Some helper functions to ease work with XML concering namespaces, XPATH
+ * and so on.
  *  @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
  */
 public final class XMLUtils
 {
+    /**
+     * W3C URL of XForms
+     */
     public static final String XFORM_URL    = "http://www.w3.org/2002/xforms";
+    /**
+     * W3C prefix of XForms
+     */
     public static final String XFORM_PREFIX = "xform";
 
     private static Logger logger = Logger.getLogger(XMLUtils.class);
@@ -46,28 +54,71 @@
     private XMLUtils() {
     }
 
+    /**
+     * Helper class to generate elements and attributes with
+     * namespaces.
+     */
     public static class ElementCreator
     {
+        /**
+         * owner document of the elements to be created
+         */
         protected Document document;
+        /**
+         * namespace to be used
+         */
         protected String   ns;
+        /**
+         * prefix to be used
+         */
         protected String   prefix;
 
+        /**
+         * Constructor to create an element/attribute creator
+         * with a given namespace and namespace prefix using a
+         * given owner document.
+         * @param document The owning document
+         * @param ns       The namespace
+         * @param prefix   The namespace prefix
+         */
         public ElementCreator(Document document, String ns, String prefix) {
             this.document = document;
             this.ns       = ns;
             this.prefix   = prefix;
         }
 
+        /**
+         * Creates a new element using the owning document with
+         * the this creators namespace and namespace prefix.
+         * @param name The name of the element
+         * @return     The new element
+         */
         public Element create(String name) {
             Element element = document.createElementNS(ns, name);
             element.setPrefix(prefix);
             return element;
         }
 
+        /**
+         * Adds a new attribute and its value to a given element.
+         * It does not set the namespace prefix.
+         * @param element The element to add the attribute to
+         * @param name    The name of the attribute
+         * @param value   The value of the attribute
+         */
         public void addAttr(Element element, String name, String value) {
             addAttr(element, name, value, false);
         }
 
+        /**
+         * Adds a new attribute and its value to a given element.
+         * If the namespace prefix is used is decided by the 'addPrefix' flag.
+         * @param element The element to add the attribute to
+         * @param name    The name of the attribute
+         * @param value   The value of the attribute
+         * @param addPrefix If true the creators namespace prefix is
+         * set on the attribute.
+         */
         public void addAttr(
             Element element,
             String  name,
@@ -84,6 +135,11 @@
         }
     } // class ElementCreator
 
+    /**
+     * Creates a new XML document
+     * @return the new XML document ot null if something went wrong during
+     * creation.
+     */
     public static final Document newDocument() {
         DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
         factory.setNamespaceAware(true);
@@ -97,6 +153,12 @@
         return null;
     }
 
+    /**
+     * Loads a XML document namespace aware from a file
+     * @param file The file to load.
+     * @return the XML document or null if something went wrong
+     * during loading.
+     */
     public static final Document parseDocument(File file) {
         DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
         factory.setNamespaceAware(true);
@@ -116,10 +178,20 @@
         return null;
     }
 
+    /**
+     * Creates a new XPath without a namespace context.
+     * @return the new XPath.
+     */
     public static final XPath newXPath() {
         return newXPath(null);
     }
 
+    /**
+     * Creates a new XPath with a given namespace context.
+     * @param namespaceContext The namespace context to be used or null
+     * if none should be used.
+     * @return The new XPath
+     */
     public static final XPath newXPath(NamespaceContext namespaceContext) {
         XPathFactory factory = XPathFactory.newInstance();
         XPath        xpath   = factory.newXPath();
@@ -129,10 +201,31 @@
         return xpath;
     }
 
+    /**
+     * Evaluates an XPath query on a given object and returns the result
+     * as a given type. No namespace context is used.
+     * @param root  The object which is used as the root of the tree to
+     * be searched in.
+     * @param query The XPath query
+     * @param returnTyp The type of the result.
+     * @return The result of type 'returnTyp' or null if something
+     * went wrong during XPath evaluation.
+     */
     public static final Object xpath(Object root, String query, QName returnTyp) {
         return xpath(root, query, returnTyp, null);
     }
 
+    /**
+     * Evaluates an XPath query on a given objectr and returns the result
+     * as a string. A given namespace context is used.
+     * @param root  The object which is used as the root of the tree to
+     * be searched in.
+     * @param query The XPath query
+     * @param namespaceContext The namespace context to be used or null
+     * if none should be used.
+     * @return The result of the query or null if something went wrong
+     * during XPath evaluation.
+     */
     public static final String xpathString(
         Object root, String query, NamespaceContext namespaceContext
     ) {
@@ -140,6 +233,18 @@
             root, query, XPathConstants.STRING, namespaceContext);
     }
 
+    /**
+     * Evaluates an XPath query on a given object and returns the result
+     * as a given type. Optionally a namespace context is used.
+     * @param root The object which is used as the root of the tree to
+     * be searched in.
+     * @param query The XPath query
+     * @param returnType The type of the result.
+     * @param namespaceContext The namespace context to be used or null
+     * if none should be used.
+     * @return The result of type 'returnTyp' or null if something
+     * went wrong during XPath evaluation.
+     */
     public static final Object xpath(
         Object           root,
         String           query,
@@ -163,6 +268,12 @@
         return null;
     }
 
+    /**
+     * Streams out an XML document to a given output stream.
+     * @param document The document to be streamed out.
+     * @param out      The output stream to be used.
+     * @return true if operation succeeded else false.
+     */
     public static boolean toStream(Document document, OutputStream out) {
         try {
             Transformer transformer =
@@ -185,4 +296,4 @@
         return false;
     }
 }
-// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8:
+// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 :
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/CreateResource.java	Fri Mar 26 17:59:50 2010 +0000
+++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/CreateResource.java	Sun Mar 28 10:01:03 2010 +0000
@@ -98,4 +98,4 @@
         }
     }
 }
-// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8:
+// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 :
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/FactoriesResource.java	Fri Mar 26 17:59:50 2010 +0000
+++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/FactoriesResource.java	Sun Mar 28 10:01:03 2010 +0000
@@ -73,4 +73,4 @@
             MediaType.APPLICATION_XML, document);
     }
 }
-// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8:
+// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 :

http://dive4elements.wald.intevation.org