Mercurial > dive4elements > framework
changeset 92:73d0ebae81d7
Last bunch of javadoc
artifacts/trunk@848 c6561f87-3c4e-4783-a992-168aeb5c3f6f
| author | Sascha L. Teichmann <sascha.teichmann@intevation.de> |
|---|---|
| date | Sun, 28 Mar 2010 14:16:05 +0000 |
| parents | 730ff077a58c |
| children | e27cf9c84eb8 |
| files | ChangeLog TODO artifact-database/src/main/java/de/intevation/artifactdatabase/ArtifactDatabaseImpl.java artifact-database/src/main/java/de/intevation/artifactdatabase/XMLUtils.java |
| diffstat | 4 files changed, 228 insertions(+), 13 deletions(-) [+] |
line wrap: on
line diff
--- a/ChangeLog Sun Mar 28 10:01:03 2010 +0000 +++ b/ChangeLog Sun Mar 28 14:16:05 2010 +0000 @@ -1,16 +1,24 @@ 2010-03-28 Sascha L. Teichmann <sascha.teichmann@intevation.de> - * 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. + * artifact-database/src/main/java/de/intevation/artifactdatabase/ArtifactDatabaseImpl.java, + artifact-database/src/main/java/de/intevation/artifactdatabase/XMLUtils.java, + TODO: + Last bunch of javadoc. Possible TODO: check for typos and cross reference problems + but the main work should be done with this commit. + +2010-03-28 Sascha L. Teichmann <sascha.teichmann@intevation.de> + + * 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 <sascha.teichmann@intevation.de>
--- a/TODO Sun Mar 28 10:01:03 2010 +0000 +++ b/TODO Sun Mar 28 14:16:05 2010 +0000 @@ -1,3 +1,2 @@ TODO: * Document the XML of the configuration file. - * Adjust JavaDoc.
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/ArtifactDatabaseImpl.java Sun Mar 28 10:01:03 2010 +0000 +++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/ArtifactDatabaseImpl.java Sun Mar 28 14:16:05 2010 +0000 @@ -34,6 +34,10 @@ import org.w3c.dom.Element; /** + * The core implementation of artifact database. This layer exposes + * the needed methods to the artifact runtime system which e.g. may + * expose them via REST. The concrete persistent representation of the + * artifacts is handled by the {@link Backend backend}. * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a> */ public class ArtifactDatabaseImpl @@ -42,59 +46,144 @@ private static Logger logger = Logger.getLogger(ArtifactDatabaseImpl.class); + /** + * Error message issued if a requested artifact factory + * is not registered to this database. + */ public static final String NO_SUCH_FACTORY = "No such factory"; + /** + * Error message issued if a requested artifact is not found + * in this database. + */ public static final String NO_SUCH_ARTIFACT = "No such artifact"; + /** + * Error message issued if one tries to remove a requested artifact + * from the list of artifacts running in background which is + * not in this list. + */ public static final String NOT_IN_BACKGROUND = "Not in background"; + /** + * Error message issued if an artifact wants to translate itself + * into a none valid persistent state. + */ public static final String INVALID_CALL_STATE = "Invalid after call state"; + /** + * Error message issued if the creation of an artifact failed. + */ public static final String CREATION_FAILED = "Creation of artifact failed"; + /** + * Error message if an severe internal error occurred. + */ public static final String INTERNAL_ERROR = "Creation of artifact failed"; + /** + * Error message issued if a requested service is not + * offered by this database. + */ public static final String NO_SUCH_SERVICE = "No such service"; + /** + * Default digest hash to be used while im-/exporting artifacts. + */ public static final String DIGEST_ALGORITHM = "SHA-1"; + /** + * XPath to get the checksum from an XML representation of + * an exported artifact. + */ public static final String XPATH_IMPORT_CHECKSUM = "/art:action/art:data/@checksum"; + /** + * XPath to get the name of the factory which should be + * used to revive an antrifact that is going to be imported. + */ public static final String XPATH_IMPORT_FACTORY = "/art:action/art:data/@factory"; + /** + * XPath to get the base64 encoded data of an artifact + * that is going to be imported. + */ public static final String XPATH_IMPORT_DATA = "/art:action/art:data/text()"; + /** + * Error message issued if the checksum of an + * artifact to be imported has an invalid syntax. + */ public static final String INVALID_CHECKSUM = "Invalid checksum"; + /** + * Error message issued the checksum validation + * of an artifact to be imported fails. + */ public static final String CHECKSUM_MISMATCH = "Mismatching checksum"; + /** + * Error message issued if an artifact to be imported + * does not have any data. + */ public static final String NO_DATA = "No data"; + /** + * Error message issued if the deserialization of + * an artifact to be imported fails. + */ public static final String INVALID_ARTIFACT = "Invalid artifact"; + /** + * Inner class that implements the call context handed + * to the methods calls describe(), feed(), etc. of the artifact. + */ public class CallContextImpl implements CallContext { + /** + * The persistence wrapper around the living artifact + */ protected PersistentArtifact artifact; + /** + * The action to be performed after the artifact calls + * desribe(), feed(), etc. return. + */ protected int action; + /** + * The meta information of the concrete call + * (preferred languages et. al.) + */ protected CallMeta callMeta; + /** + * Map to act like a clipboard when nesting calls + * like a proxy artifact. + */ protected HashMap customValues; + /** + * Constructor to create a call context with a given + * persistent artifact, a default action and meta informations. + * @param artifact The persistent wrapper around a living artifact. + * @param action The action to be performed after the concrete + * artifact call has returned. + * @param callMeta The meta information for this call context. + */ public CallContextImpl( PersistentArtifact artifact, int action, @@ -135,6 +224,10 @@ return artifact.getTTL(); } + /** + * Dispatches and executes the persistence action after + * the return of the concrete artifact call. + */ public void postCall() { switch (action) { case NOTHING: @@ -169,16 +262,40 @@ } } // class CallContextImpl + /** + * This inner class allows the deferral of writing the output + * of the artifact's out() call. + */ public class DeferredOutputImpl implements DeferredOutput { + /** + * The persistence wrapper around a living artifact. + */ protected PersistentArtifact artifact; + /** + * The input document for the artifact's out() call. + */ protected Document format; + /** + * The meta information of the artifact's out() call. + */ protected CallMeta callMeta; + /** + * Default constructor. + */ public DeferredOutputImpl() { } + /** + * Constructor to create a deferred execution unit for + * the artifact's out() call given an artifact, an input document + * an the meta information. + * @param artifact The persistence wrapper around a living artifact. + * @param format The input document for the artifact's out() call. + * @param callMeta The meta information of the artifact's out() call. + */ public DeferredOutputImpl( PersistentArtifact artifact, Document format, @@ -203,26 +320,70 @@ } } // class DeferredOutputImpl + /** + * List of name/description pairs needed for + * {@link #artifactFactoryNamesAndDescriptions() }. + */ protected String [][] factoryNamesAndDescription; + /** + * Map to access artifact factories by there name. + */ protected HashMap name2factory; + /** + * List of name/description pairs needed for + * {@link #serviceNamesAndDescriptions() }. + */ protected String [][] serviceNamesAndDescription; + /** + * Map to access services by there name. + */ protected HashMap name2service; + /** + * Reference to the storage backend. + */ protected Backend backend; + /** + * Reference of the global context of the artifact runtime system. + */ protected Object context; + /** + * The signing secret to be used for ex-/importing artifacts. + */ protected byte [] exportSecret; + /** + * A set of ids of artifact which currently running in background. + * This artifacts should not be removed from the database by the + * database cleaner. + */ protected HashSet backgroundIds; + /** + * Default constructor. + */ public ArtifactDatabaseImpl() { } + /** + * Constructor to create a artifact database with the given + * bootstrap parameters like artifact- and service factories et. al. + * Created this way the artifact database has no backend. + * @param bootstrap The parameters to start this artifact database. + */ public ArtifactDatabaseImpl(FactoryBootstrap bootstrap) { this(bootstrap, null); } + /** + * Constructor to create a artifact database with the a given + * backend and + * bootstrap parameters like artifact- and service factories et. al. + * @param bootstrap The parameters to start this artifact database. + * @param backend The storage backend. + */ public ArtifactDatabaseImpl(FactoryBootstrap bootstrap, Backend backend) { backgroundIds = new HashSet(); @@ -236,6 +397,11 @@ wireWithBackend(backend); } + /** + * Used to extract the artifact factories from the bootstrap + * parameters and building the internal lookup tables. + * @param bootstrap The bootstrap parameters. + */ protected void setupArtifactFactories(FactoryBootstrap bootstrap) { name2factory = new HashMap(); @@ -256,6 +422,12 @@ } } + /** + * Used to extract the service factories from the bootstrap + * parameters, setting up the services and building the internal + * lookup tables. + * @param bootstrap The bootstrap parameters. + */ protected void setupServices(FactoryBootstrap bootstrap) { name2service = new HashMap(); @@ -282,6 +454,12 @@ } + /** + * Wires a storage backend to this artifact database and + * establishes a callback to be able to revive artifacts + * via the serializers of this artifact factories. + * @param backend The backend to be wired with this artifact database. + */ public void wireWithBackend(Backend backend) { if (backend != null) { this.backend = backend; @@ -289,6 +467,13 @@ } } + /** + * Called after an backgrounded artifact signals its + * will to be written back to the backend. + * @param artifact The persistence wrapper around + * the backgrounded artifact. + * @param action The action to be performed. + */ protected void fromBackground(PersistentArtifact artifact, int action) { logger.warn("BACKGROUND processing is not fully implemented, yet!"); switch (action) { @@ -306,12 +491,25 @@ removeIdFromBackground(artifact.getId()); } + /** + * Removes an artifact's database id from the set of backgrounded + * artifacts. The database cleaner is now able to remove it safely + * from the database again. + * @param id The database id of the artifact. + */ protected void removeIdFromBackground(int id) { synchronized (backgroundIds) { backgroundIds.remove(Integer.valueOf(id)); } } + /** + * Adds an artifact's database id to the set of artifacts + * running in backgroound. To be in this set prevents the + * artifact to be removed from the database by the database cleaner. + * @param id The database id of the artifact to be protected + * from being removed from the database. + */ protected void addIdToBackground(int id) { synchronized (backgroundIds) { backgroundIds.add(Integer.valueOf(id)); @@ -324,6 +522,7 @@ synchronized (backgroundIds) { for (int i = 0; i < N; ++i) { Id id = (Id)ids.get(i); + // only delete artifact if its not in background. if (!backgroundIds.contains(Integer.valueOf(id.getId()))) { out.add(id); } @@ -501,6 +700,15 @@ exportSecret); } + /** + * Creates an exteral XML representation of an artifact. + * @param factoryName The name of the factory which is responsible + * for the serialized artifact. + * @param artifact The byte data of the artifact itself. + * @param secret The signing secret. + * @return An XML document containing the external representation + * of the artifact. + */ protected static Document createExportDocument( String factoryName, byte [] artifact,
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/XMLUtils.java Sun Mar 28 10:01:03 2010 +0000 +++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/XMLUtils.java Sun Mar 28 14:16:05 2010 +0000 @@ -216,7 +216,7 @@ } /** - * Evaluates an XPath query on a given objectr and returns the result + * Evaluates an XPath query on a given object 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.