Mercurial > dive4elements > framework
changeset 89:d348fe1fd822
More javadoc (fixes small glitches, too).
artifacts/trunk@845 c6561f87-3c4e-4783-a992-168aeb5c3f6f
line wrap: on
line diff
--- a/ChangeLog Fri Mar 26 15:05:11 2010 +0000 +++ b/ChangeLog Fri Mar 26 16:16:32 2010 +0000 @@ -1,3 +1,21 @@ +2010-03-26 Sascha L. Teichmann <sascha.teichmann@intevation.de> + + * artifact-database/src/main/java/de/intevation/artifactdatabase/ProxyArtifact.java, + artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultPreferredLocale.java, + artifact-database/src/main/java/de/intevation/artifactdatabase/DBConnection.java, + artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultService.java, + artifact-database/src/main/java/de/intevation/artifactdatabase/FactoryBootstrap.java, + artifact-database/src/main/java/de/intevation/artifactdatabase/Id.java, + artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ImportResource.java, + artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ArtifactResource.java, + artifact-database/src/main/java/de/intevation/artifactdatabase/rest/FactoriesResource.java, + artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ServiceResource.java, + artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ExportResource.java, + artifact-database/src/main/java/de/intevation/artifactdatabase/rest/CreateResource.java, + artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ServicesResource.java, + artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultServiceFactory.java: + More javadoc (fixes small glitches, too). + 2010-03-26 Sascha L. Teichmann <sascha.teichmann@intevation.de> * artifact-database/src/main/java/de/intevation/artifactdatabase/rest/BaseResource.java,
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/DBConnection.java Fri Mar 26 15:05:11 2010 +0000 +++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/DBConnection.java Fri Mar 26 16:16:32 2010 +0000 @@ -75,7 +75,7 @@ * 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 + * @return The default URL. */ public static final String getDefaultURL() { File configDir = Config.getConfigDirectory();
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultPreferredLocale.java Fri Mar 26 15:05:11 2010 +0000 +++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultPreferredLocale.java Fri Mar 26 16:16:32 2010 +0000 @@ -5,17 +5,35 @@ import java.util.Locale; /** + * Models a pair of Locale and quality (0.0-1.0) to be used to + * find best matching locale between server offerings and clients requests. + * * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a> */ public class DefaultPreferredLocale implements PreferredLocale { + /** + * The locale of this tuple pair. + */ protected Locale locale; + /** + * The quality of this tuple pair between 0.0 and 1.0. + */ protected float quality; + /** + * Default constructor + */ public DefaultPreferredLocale() { } + /** + * Constructor to build a pair of given a locale speficied by + * string 'lang' and an given 'quality'. + * @param lang The name of the locale. + * @param quality The quality of the locale. + */ public DefaultPreferredLocale(String lang, float quality) { locale = new Locale(lang); this.quality = quality; @@ -29,4 +47,4 @@ return quality; } } -// 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/DefaultService.java Fri Mar 26 15:05:11 2010 +0000 +++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultService.java Fri Mar 26 16:16:32 2010 +0000 @@ -8,12 +8,22 @@ import org.w3c.dom.Document; +/** + * Trivial implementation of an artifact database service. Useful to + * be subclassed. + * + * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a> + */ public class DefaultService implements Service { private static Logger logger = Logger.getLogger(DefaultService.class); - public Document process(Document data, Object globalContext, CallMeta callMeta) { + public Document process( + Document data, + Object globalContext, + CallMeta callMeta + ) { if (logger.isDebugEnabled()) { logger.debug("Service.process"); }
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultServiceFactory.java Fri Mar 26 15:05:11 2010 +0000 +++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultServiceFactory.java Fri Mar 26 16:16:32 2010 +0000 @@ -9,6 +9,12 @@ import org.apache.log4j.Logger; /** + * Trivial implementation of the ServiceFactory interface. + * Name and an description are configured by the given Node given to + * #setup(Document, Node) via the 'name' and 'description' attributes. + * The name of the class that provides the concrete serice is configured + * by the 'service' attribute. + * * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a> */ public class DefaultServiceFactory @@ -17,22 +23,50 @@ private static Logger logger = Logger.getLogger(DefaultServiceFactory.class); + /** + * XPath to access the name of the service. + */ public static final String XPATH_NAME = "@name"; + /** + * XPath to access the description of the service. + */ public static final String XPATH_DESCRIPTION = "@description"; + /** + * XPath to access the class name of the service to be build by + * this factory. + */ public static final String XPATH_SERVICE = "@service"; + /** + * Default description if no description is given in configuration. + */ public static final String DEFAULT_DESCRIPTION = "No description available"; + /** + * Loaded service class if no class name is given in the configuration. + */ public static final String DEFAULT_SERVICE = "de.intevation.artifactdatabase.DefaultService"; + /** + * The name of the service factory. + */ protected String name; + /** + * The description of the service factory. + */ protected String description; + /** + * The loaded class used to build the concrete service. + */ protected Class serviceClass; + /** + * Default constructor. + */ public DefaultServiceFactory() { }
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/FactoryBootstrap.java Fri Mar 26 15:05:11 2010 +0000 +++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/FactoryBootstrap.java Fri Mar 26 16:16:32 2010 +0000 @@ -20,33 +20,75 @@ { private static Logger logger = Logger.getLogger(FactoryBootstrap.class); + /** + * XPath to figure out the class name of the context factory from + * the global configuration. + */ public static final String CONTEXT_FACTORY = "/artifact-database/factories/context-factory/text()"; + /** + * The name of the default context factory. + */ public static final String DEFAULT_CONTEXT_FACTORY = "de.intevation.artifactdatabase.DefaultArtifactContextFactory"; + /** + * XPath to figure out the names of the artifact factories from + * the global configuration to be exposed by the artifact database. + */ public static final String ARTIFACT_FACTORIES = "/artifact-database/factories/artifact-factories/artifact-factory"; + /** + * XPath to figure out the names of the service factories from + * the global configuration to build the services offered by the + * artifact database. + */ public static final String SERVICE_FACTORIES = "/artifact-database/factories/service-factories/service-factory"; + /** + * XPath to figure out the secret used to sign the artifact exports + * made by the artfifact database server. + */ public static final String EXPORT_SECRET = "/artifact-database/export-secret/text()"; - public static final String DEFAULT_EXORT_SECRET = + /** + * Default export signing secret. + * <strong>PLEASE CHANGE THE SECRET VIA THE XPATH EXPORT_SECRET + * IN THE CONFIGURATION.</strong>. + */ + public static final String DEFAULT_EXPORT_SECRET = "!!!CHANGE ME! I'M NO SECRET!!!"; + /** + * Reference to the global context build by the global context factory. + */ protected Object context; + /** + * List of the artifact factories to be exposed by the + * artifact database. + */ protected ArtifactFactory [] artifactFactories; + /** + * List of service factories which creates services that are + * exposed by the artifact database. + */ protected ServiceFactory [] serviceFactories; + /** + * byte array holding the export signing secret. + */ protected byte [] exportSecret; + /** + * Default constructor + */ public FactoryBootstrap() { } @@ -83,6 +125,10 @@ context = factory.createArtifactContext(Config.getConfig()); } + /** + * Scans the global configuration to load the configured + * artifact factories and sets them up. + */ protected void loadArtifactFactories() { logger.info("loading artifact factories"); @@ -122,7 +168,8 @@ if (factory != null) { factory.setup(config, nodes.item(i)); loadedFactories.add(factory); - logger.info("Registering '" + factory.getName() + "' as artifact factory."); + logger.info("Registering '" + + factory.getName() + "' as artifact factory."); } } @@ -130,6 +177,10 @@ new ArtifactFactory[loadedFactories.size()]); } + /** + * Scans the global configuration for the configured service factories + * and sets them up. + */ protected void loadServiceFactories() { logger.info("loading service factories"); @@ -177,17 +228,25 @@ new ServiceFactory[loadedFactories.size()]); } + /** + * Fetches the export signing secret from the global configuration. + * If none is found if defaults to the DEFAULT_EXORT_SECRET which + * is insecure. + */ protected void setupExportSecret() { String secret = Config.getStringXPath(EXPORT_SECRET); if (secret == null) { logger.warn("NO EXPORT SECRET SET! USING INSECURE DEFAULT!"); - secret = DEFAULT_EXORT_SECRET; + secret = DEFAULT_EXPORT_SECRET; } exportSecret = StringUtils.getUTF8Bytes(secret); } + /** + * Loads all the dynamic classes configured by the global configuration. + */ public void boot() { setupExportSecret(); buildContext(); @@ -195,18 +254,35 @@ loadServiceFactories(); } + /** + * Returns the list of ready to use artifact factories. + * @return The list of artifact factories. + */ public ArtifactFactory [] getArtifactFactories() { return artifactFactories; } + /** + * Returns the ready to use service factories. + * @return The list of service factories. + */ public ServiceFactory [] getServiceFactories() { return serviceFactories; } + /** + * Returns the global context created by the global context factory. + * @return The global context. + */ public Object getContext() { return context; } + /** + * Returns the signing secret to be used when ex- and importing + * artifacts from and into the artifact database. + * @return the byte array containg the signing secret. + */ public byte [] getExportSecret() { return exportSecret; }
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/Id.java Fri Mar 26 15:05:11 2010 +0000 +++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/Id.java Fri Mar 26 16:16:32 2010 +0000 @@ -3,25 +3,54 @@ import java.util.List; /** + * Class to model the concept of an 'id' in terms of unique integer as + * used in databases. Subclasses of this class are able to be processed + * by this id. + * * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a> */ public class Id { + /** + * Interface to filter a list of ids. + */ public interface Filter { + /** + * A list of ids is processed in a functional way to be + * free from some ids by the implementing code. The resulting + * list maybe short or equal sized to the original one. The + * original list is not modified. + * @param ids The list of input ids. + * @return A list of processed ids. + */ List filterIds(List ids); } + /** + * The backing int of the id. + */ protected int id; + /** + * Default constructor: id = 0 + */ public Id() { } + /** + * Constructor to create an id with a given value. + * @param id The id value + */ public Id(int id) { this.id = id; } + /** + * Returns the id value. + * @return The value of the id. + */ public int getId() { return id; } } -// 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/ProxyArtifact.java Fri Mar 26 15:05:11 2010 +0000 +++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/ProxyArtifact.java Fri Mar 26 16:16:32 2010 +0000 @@ -11,32 +11,69 @@ import java.io.OutputStream; /** + * The proxy artifact is a wrapper around another artifact. It simply forwards + * the interface calls to this underlaying artifact. + * The reason for using proxy artifacts is enable the workflow to exchange + * artifacts at any time by something else without losing the concrete + * artifact. From the outside it always looks like there is only one + * distinct artifact.<br> + * + * An inner artifact is able to replace itself by indirectly hand over + * the replacement via the call context to the proxy artifact.<br> + * To do so the proxied artifact has to call + * <code>callContext.getContextValue(EPLACE_PROXY, replacement);</code>. + * After the current call (describe, feed, advance and out) of the proxied + * artifact is finished the proxy artifact replaces the former proxied artifact + * with the replacement. + * * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a> */ public class ProxyArtifact extends DefaultArtifact { + /** + * Key to signal that the proxied artifact should be replaced. + */ public static final Object REPLACE_PROXY = new Object(); private static Logger logger = Logger.getLogger(ProxyArtifact.class); + /** + * The proxied artifact. + */ protected Artifact proxied; + /** + * Default constructor. + */ public ProxyArtifact() { } + /** + * Constructor to create a new proxy artifact around a given artifact. + * @param proxied The artifact to be proxied. + */ public ProxyArtifact(Artifact proxied) { this.proxied = proxied; } + /** + * The currently proxied artifact. + * @return The proxied artifact. + */ public Artifact getProxied() { return proxied; } + /** + * Explicitly set the proxied artifacts. + * @param proxied + */ public void setProxied(Artifact proxied) { this.proxied = proxied; } + @Override public void setIdentifier(String identifier) { this.identifier = identifier; @@ -44,6 +81,11 @@ proxied.setIdentifier(identifier); } + /** + * Method to check if the current proxied artifact should be replaced + * by a new one coming from the call context. + * @param callContext + */ protected void checkReplacement(CallContext callContext) { Object replacement = callContext.getContextValue(REPLACE_PROXY); if (replacement instanceof Artifact) { @@ -51,12 +93,14 @@ } } + @Override public String hash() { return proxied != null ? proxied.hash() : super.hash(); } + @Override public Document describe(Document data, CallContext context) { try { return proxied != null @@ -68,6 +112,7 @@ } } + @Override public Document advance(Document target, CallContext context) { try { return proxied != null @@ -79,6 +124,7 @@ } } + @Override public Document feed(Document target, CallContext context) { try { return proxied != null @@ -90,6 +136,7 @@ } } + @Override public void out( Document format, OutputStream out, @@ -110,6 +157,7 @@ } } + @Override public void endOfLife(Object context) { if (proxied != null) { proxied.endOfLife(context); @@ -119,6 +167,7 @@ } } + @Override public void cleanup(Object context) { if (proxied != null) proxied.cleanup(context); @@ -126,4 +175,4 @@ super.cleanup(context); } } -// 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/ArtifactResource.java Fri Mar 26 15:05:11 2010 +0000 +++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ArtifactResource.java Fri Mar 26 16:16:32 2010 +0000 @@ -118,7 +118,7 @@ * @param source The input document to further parameterize the * operation. * @param db The artifact database where to find the artifact. - * @return + * @return The representation produced by the performed action. */ protected Representation dispatch( String identifier,
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/CreateResource.java Fri Mar 26 15:05:11 2010 +0000 +++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/CreateResource.java Fri Mar 26 16:16:32 2010 +0000 @@ -47,6 +47,7 @@ */ public static final String NO_ARTIFACT_CREATED = "No artifact created"; + @Override protected Representation innerPost(Representation requestRepr) throws ResourceException {
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ExportResource.java Fri Mar 26 15:05:11 2010 +0000 +++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ExportResource.java Fri Mar 26 16:16:32 2010 +0000 @@ -33,6 +33,7 @@ */ public static final String PATH = "/export/{uuid}"; + @Override protected Representation innerGet() throws ResourceException {
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/FactoriesResource.java Fri Mar 26 15:05:11 2010 +0000 +++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/FactoriesResource.java Fri Mar 26 16:16:32 2010 +0000 @@ -33,6 +33,7 @@ */ public static final String PATH = "/factories"; + @Override protected Representation innerGet() throws ResourceException {
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ImportResource.java Fri Mar 26 15:05:11 2010 +0000 +++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ImportResource.java Fri Mar 26 16:16:32 2010 +0000 @@ -35,6 +35,7 @@ */ public static final String PATH = "/import"; + @Override protected Representation innerPost(Representation requestRepr) { Document inputDocument = null;
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ServiceResource.java Fri Mar 26 15:05:11 2010 +0000 +++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ServiceResource.java Fri Mar 26 16:16:32 2010 +0000 @@ -40,6 +40,7 @@ */ public static final String NO_SUCH_ACTION_MESSAGE = "no such service"; + @Override protected Representation innerPost(Representation requestRepr) { Document inputDocument = null;
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ServicesResource.java Fri Mar 26 15:05:11 2010 +0000 +++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ServicesResource.java Fri Mar 26 16:16:32 2010 +0000 @@ -35,6 +35,7 @@ */ public static final String PATH = "/services"; + @Override protected Representation innerGet() throws ResourceException {