Mercurial > dive4elements > framework
changeset 87:0f48188a6e02
Added some javadoc to the artifactdatabase module. Not done yet.
artifacts/trunk@839 c6561f87-3c4e-4783-a992-168aeb5c3f6f
line wrap: on
line diff
--- 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,
--- 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();
--- 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();
--- 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() { }
--- 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() { }
--- 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 :
--- 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; }
--- 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 :
--- 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());
--- /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>
--- /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>