# HG changeset patch # User Sascha L. Teichmann # Date 1269770463 0 # Node ID 730ff077a58c36a1d1935731d1d6dcf1278a61ff # Parent 68285f7bc476d17719db93cfb80870b9f95e35a3 More javadoc, some code formatting. artifacts/trunk@847 c6561f87-3c4e-4783-a992-168aeb5c3f6f diff -r 68285f7bc476 -r 730ff077a58c ChangeLog --- 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 + + * 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 * artifact-database/src/main/java/de/intevation/artifactdatabase/ProxyArtifact.java, diff -r 68285f7bc476 -r 730ff077a58c artifact-database/src/main/java/de/intevation/artifactdatabase/Config.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 Sascha L. Teichmann */ 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 diff -r 68285f7bc476 -r 730ff077a58c artifact-database/src/main/java/de/intevation/artifactdatabase/DBConnection.java --- 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 : diff -r 68285f7bc476 -r 730ff077a58c artifact-database/src/main/java/de/intevation/artifactdatabase/DatabaseCleaner.java --- 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. */ diff -r 68285f7bc476 -r 730ff077a58c artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultArtifact.java --- 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 Sascha L. Teichmann */ 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 : diff -r 68285f7bc476 -r 730ff077a58c artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultArtifactContextFactory.java --- 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 : diff -r 68285f7bc476 -r 730ff077a58c artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultArtifactFactory.java --- 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 : diff -r 68285f7bc476 -r 730ff077a58c artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultCallMeta.java --- 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 : diff -r 68285f7bc476 -r 730ff077a58c artifact-database/src/main/java/de/intevation/artifactdatabase/XMLUtils.java --- 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 Sascha L. Teichmann */ 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 : diff -r 68285f7bc476 -r 730ff077a58c artifact-database/src/main/java/de/intevation/artifactdatabase/rest/CreateResource.java --- 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 : diff -r 68285f7bc476 -r 730ff077a58c artifact-database/src/main/java/de/intevation/artifactdatabase/rest/FactoriesResource.java --- 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 :