--- 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 :