# HG changeset patch
# User Sascha L. Teichmann <sascha.teichmann@intevation.de>
# Date 1269603628 0
# Node ID 0f48188a6e0210b3e1e9cb0a01fc42d4b0174400
# Parent  b2e0cb83631c364f5be55fabea04f92245cc8615
Added some javadoc to the artifactdatabase module. Not done yet.


artifacts/trunk@839 c6561f87-3c4e-4783-a992-168aeb5c3f6f

diff -r b2e0cb83631c -r 0f48188a6e02 ChangeLog
--- a/ChangeLog	Fri Mar 26 10:04:34 2010 +0000
+++ b/ChangeLog	Fri Mar 26 11:40:28 2010 +0000
@@ -1,3 +1,18 @@
+2010-03-26	Sascha L. Teichmann	<sascha.teichmann@intevation.de>
+
+	* artifact-database/src/main/java/de/intevation/artifactdatabase/SQL.java,
+	  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/App.java,
+	  artifact-database/src/main/java/de/intevation/artifactdatabase/StringUtils.java,
+	  artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultCallMeta.java,
+	  artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultArtifactSerializer.java:
+	  Added javadoc.
+
+	* artifact-database/src/main/java/de/intevation/artifactdatabase/package.html,
+	  artifact-database/src/main/java/de/intevation/artifactdatabase/rest/package.html: New.
+	  Package descriptions.
 2010-03-26	Sascha L. Teichmann	<sascha.teichmann@intevation.de>
 
 	* artifact-database/src/main/java/de/intevation/artifactdatabase/ProxyArtifact.java,
diff -r b2e0cb83631c -r 0f48188a6e02 artifact-database/src/main/java/de/intevation/artifactdatabase/App.java
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/App.java	Fri Mar 26 10:04:34 2010 +0000
+++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/App.java	Fri Mar 26 11:40:28 2010 +0000
@@ -18,9 +18,16 @@
  */
 public class App
 {
+    /**
+     * The logging is done via Log4j. To configure the logging
+     * a file 'log4j.properties' is search in the configuration directory.
+     */
     public static final String LOG4J_PROPERTIES =
         "log4j.properties";
 
+    /**
+     * Trys to load the Log4j configuration from ${config.dir}/log4j.properties.
+     */
     public static final void configureLogging() {
         File configDir = Config.getConfigDirectory();
         File propFile = new File(configDir, LOG4J_PROPERTIES);
@@ -36,6 +43,10 @@
         }
     }
 
+    /**
+     * Starts the artifact database.
+     * @param args The commandline arguments. Unused.
+     */
     public static void main(String[] args) {
 
         configureLogging();
diff -r b2e0cb83631c -r 0f48188a6e02 artifact-database/src/main/java/de/intevation/artifactdatabase/DBConnection.java
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/DBConnection.java	Fri Mar 26 10:04:34 2010 +0000
+++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/DBConnection.java	Fri Mar 26 11:40:28 2010 +0000
@@ -11,35 +11,72 @@
 import org.apache.log4j.Logger;
 
 /**
- *  @author Sascha L. Teichmann
+ * This class encapsulate the creation and pooling of database connections used
+ * by the artifact database. The credential to open the database connections
+ * are taken from the global configuratiion.
+ * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
  */
 public class DBConnection
 {
     private static Logger logger = Logger.getLogger(DBConnection.class);
 
+    /**
+     * XPath to access the database driver within the global configuration.
+     */
     public static final String DB_DRIVER =
         "/artifact-database/database/driver/text()";
+    /**
+     * XPath to access the database URL within the global configuration.
+     */
     public static final String DB_URL =
         "/artifact-database/database/url/text()";
+    /**
+     * XPath to access the database use within the global configuration.
+     */
     public static final String DB_USER =
         "/artifact-database/database/user/text()";
+    /**
+     * XPath to access the database password within the global configuration.
+     */
     public static final String DB_PASSWORD =
         "/artifact-database/database/password/text()";
 
+    /**
+     * The default database driver: H2
+     */
     public static final String DEFAULT_DRIVER =
         "org.h2.Driver";
 
+    /**
+     * The default database name: artifacts.db
+     */
     public static final String DEFAULT_DATABASE_FILE =
         "artifacts.db";
 
+    /**
+     * The default database URL: This is created once by #getDefaultURL()
+     */
     public static final String DEFAULT_URL = getDefaultURL();
 
+    /**
+     * The default database user: ""
+     */
     public static final String DEFAULT_USER     = "";
+
+    /**
+     * The default database password: ""
+     */
     public static final String DEFAULT_PASSWORD = "";
 
     private DBConnection() {
     }
 
+    /**
+     * Constructs the default databse URL. It concats the
+     * config directory and the #DEFAULT_DATABASE_FILE
+     * to the string with is needed to access H2 databases.
+     * @return
+     */
     public static final String getDefaultURL() {
         File configDir = Config.getConfigDirectory();
         File databaseFile = new File(configDir, DEFAULT_DATABASE_FILE);
@@ -50,6 +87,7 @@
 
     private static final void addShutdownHook() {
         Runtime.getRuntime().addShutdownHook(new Thread() {
+            @Override
             public void run() {
                 if (dataSource != null) {
                     try {
@@ -63,6 +101,10 @@
         });
     }
 
+    /**
+     * Static method to fetch a database connection.
+     * @return a DataSource to access the database connection.
+     */
     public static synchronized DataSource getDataSource() {
         if (dataSource == null) {
             dataSource = new BasicDataSource();
diff -r b2e0cb83631c -r 0f48188a6e02 artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultArtifact.java
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultArtifact.java	Fri Mar 26 10:04:34 2010 +0000
+++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultArtifact.java	Fri Mar 26 11:40:28 2010 +0000
@@ -11,6 +11,7 @@
 import de.intevation.artifacts.CallContext;
 
 /**
+ * Trivial implementation of an artifact. Useful to subclass.
  * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
  */
 public class DefaultArtifact
@@ -18,8 +19,14 @@
 {
     private static Logger logger = Logger.getLogger(DefaultArtifact.class);
 
+    /**
+     * The identifier of the artifact.
+     */
     protected String identifier;
 
+    /**
+     * Default constructor.
+     */
     public DefaultArtifact() {
     }
 
diff -r b2e0cb83631c -r 0f48188a6e02 artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultArtifactContextFactory.java
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultArtifactContextFactory.java	Fri Mar 26 10:04:34 2010 +0000
+++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultArtifactContextFactory.java	Fri Mar 26 11:40:28 2010 +0000
@@ -13,6 +13,9 @@
 public class DefaultArtifactContextFactory
 implements   ArtifactContextFactory
 {
+    /**
+     * Default constructor.
+     */
     public DefaultArtifactContextFactory() {
     }
 
diff -r b2e0cb83631c -r 0f48188a6e02 artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultArtifactSerializer.java
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultArtifactSerializer.java	Fri Mar 26 10:04:34 2010 +0000
+++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultArtifactSerializer.java	Fri Mar 26 11:40:28 2010 +0000
@@ -17,6 +17,10 @@
 import org.apache.log4j.Logger;
 
 /**
+ * Default implementation of the ArtifactSerializer interface.
+ * It uses serialized Java objects which are gzipped and
+ * turned into bytes.
+ *
  * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
  */
 public class DefaultArtifactSerializer
@@ -25,9 +29,15 @@
     private static Logger logger =
         Logger.getLogger(DefaultArtifactSerializer.class);
 
+    /**
+     * Static instance to avoid repeated creation of Serializers.
+     */
     public static final ArtifactSerializer INSTANCE =
         new DefaultArtifactSerializer();
 
+    /**
+     * Default constructor.
+     */
     public DefaultArtifactSerializer() {
     }
 
@@ -83,16 +93,32 @@
         }
     }
 
+    /**
+     * Wraps an input stream into an object input stream. You may
+     * overwrite this to get a more specialized deserializer.
+     * @param is The raw input stream
+     * @return An instance of a subclass of ObjectInputStream.
+     * @throws IOException Thrown if something went wrong during
+     * creation of the object input stream.
+     */
     protected ObjectInputStream getObjectInputStream(InputStream is)
     throws    IOException
     {
         return new ObjectInputStream(is);
     }
 
+    /**
+     * Wraps an output stream into an object output stream. You may
+     * overwrite this to get a more specialized serializer.
+     * @param os the raw output stream.
+     * @return An instance of a subclass of ObjectOutputStream.
+     * @throws IOException Thrown if something went wrong during
+     * creation of the object output stream.
+     */
     protected ObjectOutputStream getObjectOutputStream(OutputStream os)
     throws    IOException
     {
         return new ObjectOutputStream(os);
     }
 }
-// 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 b2e0cb83631c -r 0f48188a6e02 artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultCallMeta.java
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultCallMeta.java	Fri Mar 26 10:04:34 2010 +0000
+++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultCallMeta.java	Fri Mar 26 11:40:28 2010 +0000
@@ -6,16 +6,30 @@
 import de.intevation.artifacts.PreferredLocale;
 
 /**
+ * Default implementation of CallMeta. It provides a list of
+ * preferred langauages and implements an intersection mechanism
+ * to figure out the best matching language given a list of server
+ * provided languages.
  * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
  */
 public class DefaultCallMeta
 implements   CallMeta
 {
+    /**
+     * The list of preferred languages.
+     */
     protected PreferredLocale [] languages;
 
+    /**
+     * Default constructor.
+     */
     public DefaultCallMeta() {
     }
 
+    /**
+     * Creates new DefaultCallMeta with a given list of languages.
+     * @param languages The list of preferred languages.
+     */
     public DefaultCallMeta(PreferredLocale [] languages) {
         this.languages = languages;
     }
diff -r b2e0cb83631c -r 0f48188a6e02 artifact-database/src/main/java/de/intevation/artifactdatabase/SQL.java
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/SQL.java	Fri Mar 26 10:04:34 2010 +0000
+++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/SQL.java	Fri Mar 26 11:40:28 2010 +0000
@@ -8,6 +8,10 @@
 import org.apache.log4j.Logger;
 
 /**
+ * Singleton to provide SQL statement strings as key/value pairs.
+ * This mechanism is used to encapsulate database specific SQL
+ * dialects.
+ *
  * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
  */
 public final class SQL
@@ -19,6 +23,20 @@
 
     private static Properties statements;
 
+    /**
+     * Returns key/value pairs of SQL statements for the used database
+     * backend.
+     * The concrete set of SQL statements is determined by the
+     * used JDBC database driver which is configured in conf.xml.
+     * The class name of the driver is transformed by replacing
+     * all '.' with '_' and lower case the resulting string.
+     * The transformed string is used to load a properties file
+     * in '/sql/' which should contain the statements.
+     * Example:<br>
+     * <code>org.postgresql.Driver</code> results in loading of
+     * <code>/sql/org-postgresql-driver.properties</code>.
+     * @return The key/value pairs of SQL statements.
+     */
     public static final synchronized Properties getStatements() {
         if (statements == null) {
             statements = loadStatements();
@@ -61,8 +79,14 @@
         return properties;
     }
 
+    /**
+     * Returns a particular SQL statement for a given key.
+     * @param key The key of the statement.
+     * @return The corresponing SQL statement or null if none
+     * is found.
+     */
     public static final String get(String key) {
         return getStatements().getProperty(key);
     }
 }
-// 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 b2e0cb83631c -r 0f48188a6e02 artifact-database/src/main/java/de/intevation/artifactdatabase/StringUtils.java
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/StringUtils.java	Fri Mar 26 10:04:34 2010 +0000
+++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/StringUtils.java	Fri Mar 26 11:40:28 2010 +0000
@@ -11,16 +11,27 @@
 import org.apache.log4j.Logger;
 
 /**
+ * Commonly used string functions.
+ *
  * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
  */
 public final class StringUtils
 {
     private static Logger logger = Logger.getLogger(StringUtils.class);
 
+    /**
+     * Generated a random UUIDv4 in form of a string.
+     * @return the UUID
+     */
     public static final String newUUID() {
         return UUID.randomUUID().toString();
     }
 
+    /**
+     * Checks if a given string is a valid UUID.
+     * @param uuid The string to test.
+     * @return true if the string is a valid UUID else false.
+     */
     public static final boolean checkUUID(String uuid) {
         try {
             UUID.fromString(uuid);
@@ -32,6 +43,11 @@
         return true;
     }
 
+    /**
+     * Returns the UTF-8 byte array representation of a given string.
+     * @param s The string to be transformed.
+     * @return The byte array representation.
+     */
     public static final byte [] getUTF8Bytes(String s) {
         try {
             return s.getBytes("UTF-8");
@@ -42,6 +58,13 @@
         }
     }
 
+    /**
+     * Tries to convert a Base64 encoded string into the
+     * corresponing byte array.
+     * @param s The Base64 encoded string
+     * @return The byte array representation or null if
+     * an decoding error occurs.
+     */
     public static final byte [] decodeHex(String s) {
         try {
             return Hex.decodeHex(s.toCharArray());
diff -r b2e0cb83631c -r 0f48188a6e02 artifact-database/src/main/java/de/intevation/artifactdatabase/package.html
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/package.html	Fri Mar 26 11:40:28 2010 +0000
@@ -0,0 +1,10 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<html>
+<head>
+</head>
+<body>
+The reference implementation of an artifact database. It starts
+an HTTP server and publishes the interface of the artifact database
+via REST.
+</body>
+</html>
diff -r b2e0cb83631c -r 0f48188a6e02 artifact-database/src/main/java/de/intevation/artifactdatabase/rest/package.html
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/package.html	Fri Mar 26 11:40:28 2010 +0000
@@ -0,0 +1,6 @@
+</head>
+<body>
+The REST interface of the artfifact database.  This package contains classes
+that offer the URL resources to manage the artifacts via REST.
+</body>
+</html>