# HG changeset patch # User Sascha L. Teichmann # Date 1268304839 0 # Node ID 55eefe63a777d6e6a9d919b9b9fb4c82d07765d5 # Parent 48d1a9a082c2d2d6d0bbde62551e800cbf78cbb1 Repaired the javadoc stuff for almost all artifact interfaces. artifacts/trunk@760 c6561f87-3c4e-4783-a992-168aeb5c3f6f diff -r 48d1a9a082c2 -r 55eefe63a777 ChangeLog --- a/ChangeLog Sun Feb 21 23:05:32 2010 +0000 +++ b/ChangeLog Thu Mar 11 10:53:59 2010 +0000 @@ -1,3 +1,18 @@ +2010-03-11 Sascha L. Teichmann + + * artifacts/src/main/java/de/intevation/artifacts/ArtifactNamespaceContext.java, + artifacts/src/main/java/de/intevation/artifacts/CallContext.java, + artifacts/src/main/java/de/intevation/artifacts/Service.java, + artifacts/src/main/java/de/intevation/artifacts/ArtifactDatabaseException.java, + artifacts/src/main/java/de/intevation/artifacts/CallMeta.java, + artifacts/src/main/java/de/intevation/artifacts/ArtifactFactory.java, + artifacts/src/main/java/de/intevation/artifacts/ArtifactSerializer.java, + artifacts/src/main/java/de/intevation/artifacts/ServiceFactory.java, + artifacts/src/main/java/de/intevation/artifacts/ArtifactContextFactory.java, + artifacts/src/main/java/de/intevation/artifacts/Artifact.java, + artifacts/src/main/java/de/intevation/artifacts/PreferredLocale.java: + Repaired the javadoc stuff. + 2010-02-21 Sascha L. Teichmann * artifact-database/src/main/java/de/intevation/artifactdatabase/ProxyArtifact.java, diff -r 48d1a9a082c2 -r 55eefe63a777 artifacts/src/main/java/de/intevation/artifacts/Artifact.java --- a/artifacts/src/main/java/de/intevation/artifacts/Artifact.java Sun Feb 21 23:05:32 2010 +0000 +++ b/artifacts/src/main/java/de/intevation/artifacts/Artifact.java Thu Mar 11 10:53:59 2010 +0000 @@ -17,17 +17,17 @@ * of this artifact. *
  • {@link #hash() hash()}: Returns a hash value over the internal state * of this artifact.
    • - *
  • {@link #describe(Object)}: Returns a description of this artifact.
    • - *
  • {@link #advance(Document, Object) advance()}: Advances this artifact + *
  • {@link #describe(Document, CallContext)}: Returns a description of this artifact.
    • + *
  • {@link #advance(Document, CallContext) advance()}: Advances this artifact * to the next internal state
    • - *
  • {@link #feed(Document, Object) feed()}: Feed new data into this artifact.
    • + *
  • {@link #feed(Document, CallContext) feed()}: Feed new data into this artifact.
    • *
  • {@link #out(Document, OutputStream, CallContext) out()}: Produces output for this artifact.
    • * * * There are two more methods involved with the life cycle of the are: *
      - *
    1. {@link #setup(String, ArtifactFactory, Object) setup()}: Called after created by the - * factory.
      2. + *
    2. {@link #setup(String, ArtifactFactory, Object, Document) setup()}: + * Called after created by the factory.
      3. *
    3. {@link #endOfLife(Object) endOfLife()}: Called when the artifact * is going to be removed from * system. Useful to clean up.
      4. @@ -53,6 +53,7 @@ /** * A description used to build a interface to interact with this artifact. + * @param data General input data. Useful to produces specific descriptions. * @param context The global context of the runtime system. * @return An XML representation of the current state of the artifact. */ @@ -77,7 +78,9 @@ /** * Produce output from this artifact. * @param format Specifies the format of the output. + * @param out Stream to write the result data to. * @param context The global context of the runtime system. + * @throws IOException Thrown if an I/O occurs. */ void out( Document format, @@ -91,14 +94,14 @@ * @param identifier The identifier from artifact database * @param factory The factory which created this artifact. * @param context The global context of the runtime system. - * @param data The data which can be use to setup an Artifact with + * @param data The data which can be use to setup an artifact with * more details. */ public void setup( String identifier, ArtifactFactory factory, Object context, - Document data); + Document data); /** * Called from artifact database when an artifact is diff -r 48d1a9a082c2 -r 55eefe63a777 artifacts/src/main/java/de/intevation/artifacts/ArtifactContextFactory.java --- a/artifacts/src/main/java/de/intevation/artifacts/ArtifactContextFactory.java Sun Feb 21 23:05:32 2010 +0000 +++ b/artifacts/src/main/java/de/intevation/artifacts/ArtifactContextFactory.java Thu Mar 11 10:53:59 2010 +0000 @@ -13,7 +13,7 @@ * Creates a global context given a configuration in the artifact data base. * @param config the configuration. * @return The global context. - * {@link de.intevation.artifacts.ArtifactFactory#createArtifact(String, Object) createArtifact()} + * {@link de.intevation.artifacts.ArtifactFactory#createArtifact(String, Object, Document) createArtifact()} * {@link de.intevation.artifacts.Artifact Artifact} */ Object createArtifactContext(Document config); diff -r 48d1a9a082c2 -r 55eefe63a777 artifacts/src/main/java/de/intevation/artifacts/ArtifactDatabaseException.java --- a/artifacts/src/main/java/de/intevation/artifacts/ArtifactDatabaseException.java Sun Feb 21 23:05:32 2010 +0000 +++ b/artifacts/src/main/java/de/intevation/artifacts/ArtifactDatabaseException.java Thu Mar 11 10:53:59 2010 +0000 @@ -1,14 +1,22 @@ package de.intevation.artifacts; /** + * The standard exception if something goes wrong inside the artifact database. * @author Sascha L. Teichmann */ public class ArtifactDatabaseException extends Exception { + /** + * The default constructor. + */ public ArtifactDatabaseException() { } + /** + * Constructor with a string message. + * @param msg + */ public ArtifactDatabaseException(String msg) { super(msg); } diff -r 48d1a9a082c2 -r 55eefe63a777 artifacts/src/main/java/de/intevation/artifacts/ArtifactFactory.java --- a/artifacts/src/main/java/de/intevation/artifacts/ArtifactFactory.java Sun Feb 21 23:05:32 2010 +0000 +++ b/artifacts/src/main/java/de/intevation/artifacts/ArtifactFactory.java Thu Mar 11 10:53:59 2010 +0000 @@ -49,10 +49,14 @@ * artifact is created. * @param artifact The artifact to be rated. * @param context The global context. - * return time to live in ms. null means eternal. + * @return time to live in ms. null means eternal. */ Long timeToLiveUntouched(Artifact artifact, Object context); + /** + * Returns the serializer used to store the artifacts. + * @return The Serializer + */ ArtifactSerializer getSerializer(); } // vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8: diff -r 48d1a9a082c2 -r 55eefe63a777 artifacts/src/main/java/de/intevation/artifacts/ArtifactNamespaceContext.java --- a/artifacts/src/main/java/de/intevation/artifacts/ArtifactNamespaceContext.java Sun Feb 21 23:05:32 2010 +0000 +++ b/artifacts/src/main/java/de/intevation/artifacts/ArtifactNamespaceContext.java Thu Mar 11 10:53:59 2010 +0000 @@ -7,6 +7,7 @@ import java.util.Iterator; /** + * The namespace used in artifact documents. * @author Sascha L. Teichmann */ public class ArtifactNamespaceContext @@ -22,12 +23,24 @@ */ public final static String NAMESPACE_PREFIX = "art"; + /** + * Final instance to be easily used to avoid creation + * of instances. + */ public static final ArtifactNamespaceContext INSTANCE = new ArtifactNamespaceContext(); + /** + * The default constructor. + */ public ArtifactNamespaceContext() { } + /** + * @see javax.xml.namespace.NamespaceContext#getNamespaceURI(String) + * @param prefix The prefix + * @return The corresponing URI + */ public String getNamespaceURI(String prefix) { if (prefix == null) { @@ -45,12 +58,24 @@ return XMLConstants.NULL_NS_URI; } + /** + * @see javax.xml.namespace.NamespaceContext#getPrefix(String) + * @param uri The URI + * @return nothing. + * @throws java.lang.UnsupportedOperationException + */ public String getPrefix(String uri) { throw new UnsupportedOperationException(); } + /** + * @see javax.xml.namespace.NamespaceContext#getPrefixes(java.lang.String) + * @param uri The URI + * @return nothing + * @throws java.lang.UnsupportedOperationException + */ public Iterator getPrefixes(String uri) { throw new UnsupportedOperationException(); } } -// 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 48d1a9a082c2 -r 55eefe63a777 artifacts/src/main/java/de/intevation/artifacts/ArtifactSerializer.java --- a/artifacts/src/main/java/de/intevation/artifacts/ArtifactSerializer.java Sun Feb 21 23:05:32 2010 +0000 +++ b/artifacts/src/main/java/de/intevation/artifacts/ArtifactSerializer.java Thu Mar 11 10:53:59 2010 +0000 @@ -7,7 +7,18 @@ */ public interface ArtifactSerializer { + /** + * Restores an artifact from an array of bytes. + * @param bytes the persistent representation of the artifact. + * @return The de-serialized artifact or null if there was an error. + */ Artifact fromBytes(byte [] bytes); + /** + * Brings an artifact to a persistent form in form of a byte array. + * @param artifact The artifact to be serialized. + * @return the byte array representation of the artifact or null + * if there was an error. + */ byte [] toBytes(Artifact artifact); } // vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8: diff -r 48d1a9a082c2 -r 55eefe63a777 artifacts/src/main/java/de/intevation/artifacts/CallContext.java --- a/artifacts/src/main/java/de/intevation/artifacts/CallContext.java Sun Feb 21 23:05:32 2010 +0000 +++ b/artifacts/src/main/java/de/intevation/artifacts/CallContext.java Thu Mar 11 10:53:59 2010 +0000 @@ -1,26 +1,87 @@ package de.intevation.artifacts; +/** + * Instances of this interface are given to feed(), advance(), describe() + * and out() to enable the artifact to communicate with the runtime system. + * @author Sascha L. Teichmann + */ public interface CallContext { + /** + * Constant to signal that nothing should be done + * with the artifact after method return. + */ int NOTHING = 0; + /** + * Constant to signal that the database timestamp + * should be updated after method return. + */ int TOUCH = 1; + /** + * Constant to signal that the artifact should be stored + * after method return. + */ int STORE = 2; + /** + * Constant to signal that the artifact fork a backgroud thread + * and should be hold in memory till it signals that it has + * finished its operation. + */ int BACKGROUND = 3; // int DELETE = 4; // int FOREVER = 5; + /** + * This method may be called from feed(), describe(), advance() + * and out to signal what should happend with artefact after + * the current method call returns. + * @param action Valid values are NOTHING, TOUCH, STORE, BACKGROUND. + */ void afterCall(int action); + /** + * When send to background with a afterCall(BACKGROUND) this + * method is to be called from the background thread to signal + * that the background operation has ended. + * @param action Same semantics as in afterCall. + */ void afterBackground(int action); + /** + * Access to the global context of the runtime system. + * @return The global context. + */ Object globalContext(); + /** + * Access to the artifact database itself. + * @return The database. + */ ArtifactDatabase getDatabase(); + /** + * The meta data of the current call. Used to transport + * language preferences of the callee e.g. + * @return The meta information of this call. + */ CallMeta getMeta(); + /** + * Each call context has a clipboard. + * getContextValue is used to fetch data from this board. + * @param key Key of the requested item. + * @return The value stored for the secified value, null if + * no item with this key exists. + */ Object getContextValue(Object key); + /** + * Each call context has a clipboard. + * putContextValue is used to store a key/value pair onto this board. + * @param key The key of the pair + * @param value The value of the pair. + * @return The formerly stored value under the given key. + */ Object putContextValue(Object key, Object value); } // vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8: diff -r 48d1a9a082c2 -r 55eefe63a777 artifacts/src/main/java/de/intevation/artifacts/CallMeta.java --- a/artifacts/src/main/java/de/intevation/artifacts/CallMeta.java Sun Feb 21 23:05:32 2010 +0000 +++ b/artifacts/src/main/java/de/intevation/artifacts/CallMeta.java Thu Mar 11 10:53:59 2010 +0000 @@ -9,8 +9,18 @@ */ public interface CallMeta { + /** + * Returns a list of the languages the calling client is willing to accept. + * @return the list. + */ PreferredLocale [] getLanguages(); + /** + * Intersects the list of preferred client languages with a server + * given list and returns the one which is best fitting. + * @param locales The list of languages the server provides. + * @return The best fitting language. + */ Locale getPreferredLocale(Locale [] locales); } -// 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 48d1a9a082c2 -r 55eefe63a777 artifacts/src/main/java/de/intevation/artifacts/PreferredLocale.java --- a/artifacts/src/main/java/de/intevation/artifacts/PreferredLocale.java Sun Feb 21 23:05:32 2010 +0000 +++ b/artifacts/src/main/java/de/intevation/artifacts/PreferredLocale.java Thu Mar 11 10:53:59 2010 +0000 @@ -9,7 +9,15 @@ */ public interface PreferredLocale { + /** + * Returns the locale of the pair. + * @return The locale. + */ Locale getLocale(); + /** + * Returns the quality of the pair. + * @return the quality + */ float getQuality(); } // vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8: diff -r 48d1a9a082c2 -r 55eefe63a777 artifacts/src/main/java/de/intevation/artifacts/Service.java --- a/artifacts/src/main/java/de/intevation/artifacts/Service.java Sun Feb 21 23:05:32 2010 +0000 +++ b/artifacts/src/main/java/de/intevation/artifacts/Service.java Thu Mar 11 10:53:59 2010 +0000 @@ -5,13 +5,28 @@ import org.w3c.dom.Document; /** + * The idea is to process some input XML document to produce an output + * XML document. * @author Sascha L. Teichmann */ public interface Service extends Serializable { + /** + * Processes some input XML document + * @param data The input data + * @param globalContext The global context of the artifact database. + * @param callMeta The call meta contex, e.g. preferred languages. + * @return The result output XML document. + */ Document process(Document data, Object globalContext, CallMeta callMeta); + /** + * Setup the concrete processing service. This is done at startup time + * of the artifact database system. + * @param factory The service factory which created this service. + * @param globalContext The global context of the artifact database. + */ void setup(ServiceFactory factory, Object globalContext); } // vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 : diff -r 48d1a9a082c2 -r 55eefe63a777 artifacts/src/main/java/de/intevation/artifacts/ServiceFactory.java --- a/artifacts/src/main/java/de/intevation/artifacts/ServiceFactory.java Sun Feb 21 23:05:32 2010 +0000 +++ b/artifacts/src/main/java/de/intevation/artifacts/ServiceFactory.java Thu Mar 11 10:53:59 2010 +0000 @@ -4,18 +4,43 @@ import org.w3c.dom.Document; import org.w3c.dom.Node; + /** + * A factory which an XML in/XML out service which reachable through the + * artifact database. * @author Sascha L. Teichmann */ public interface ServiceFactory extends Serializable { + /** + * The name of the service which is created by this factory. + * @return The name of the created service. + */ String getName(); + /** + * The description of the service which is created by this factory. + * @return The description. + */ String getDescription(); + /** + * Creates the service. This is done at startup time of the + * artifact database system. + * @param globalContext The global context of the artifact database. + * @return The created service. + */ Service createService(Object globalContext); + /** + * Configures this factory. This is called before + * #createService(Object). + * @param config The global configuration document of the artifact + * database system. + * @param factoryNode The node inside the configuration document which + * corresponds to this factory. + */ void setup(Document config, Node factoryNode); } // vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 :