changeset 78:55eefe63a777

Repaired the javadoc stuff for almost all artifact interfaces. artifacts/trunk@760 c6561f87-3c4e-4783-a992-168aeb5c3f6f
author Sascha L. Teichmann <sascha.teichmann@intevation.de>
date Thu, 11 Mar 2010 10:53:59 +0000 (2010-03-11)
parents 48d1a9a082c2
children f69e5b87f05f
files ChangeLog artifacts/src/main/java/de/intevation/artifacts/Artifact.java artifacts/src/main/java/de/intevation/artifacts/ArtifactContextFactory.java artifacts/src/main/java/de/intevation/artifacts/ArtifactDatabaseException.java artifacts/src/main/java/de/intevation/artifacts/ArtifactFactory.java artifacts/src/main/java/de/intevation/artifacts/ArtifactNamespaceContext.java artifacts/src/main/java/de/intevation/artifacts/ArtifactSerializer.java artifacts/src/main/java/de/intevation/artifacts/CallContext.java artifacts/src/main/java/de/intevation/artifacts/CallMeta.java artifacts/src/main/java/de/intevation/artifacts/PreferredLocale.java artifacts/src/main/java/de/intevation/artifacts/Service.java artifacts/src/main/java/de/intevation/artifacts/ServiceFactory.java
diffstat 12 files changed, 196 insertions(+), 11 deletions(-) [+]
line wrap: on
line diff
--- 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	<sascha.teichmann@intevation.de>
+
+	* 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	<sascha.teichmann@intevation.de>
 
 	* artifact-database/src/main/java/de/intevation/artifactdatabase/ProxyArtifact.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.</li>
  *   <li>{@link #hash() hash()}: Returns a hash value over the internal state
  *        of this artifact.</li>
- *   <li>{@link #describe(Object)}: Returns a description of this artifact.</li>
- *   <li>{@link #advance(Document, Object) advance()}: Advances this artifact
+ *   <li>{@link #describe(Document, CallContext)}: Returns a description of this artifact.</li>
+ *   <li>{@link #advance(Document, CallContext) advance()}: Advances this artifact
  *       to the next internal state</li>
- *   <li>{@link #feed(Document, Object) feed()}: Feed new data into this artifact.</li>
+ *   <li>{@link #feed(Document, CallContext) feed()}: Feed new data into this artifact.</li>
  *   <li>{@link #out(Document, OutputStream, CallContext) out()}: Produces output for this artifact.</li>
  * </ol>
  *
  * There are two more methods involved with the life cycle of the are:
  * <ol>
- *   <li>{@link #setup(String, ArtifactFactory, Object) setup()}: Called after created by the
- *                                               factory.</li>
+ *   <li>{@link #setup(String, ArtifactFactory, Object, Document) setup()}: 
+ *   Called after created by the factory.</li>
  *   <li>{@link #endOfLife(Object) endOfLife()}: Called when the artifact
  *                                               is going to be removed from
  *                                               system. Useful to clean up.</li>
@@ -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
--- 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);
--- 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 <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
  */
 public class ArtifactDatabaseException
 extends      Exception
 {
+    /**
+     * The default constructor.
+     */
     public ArtifactDatabaseException() {
     }
 
+    /**
+     * Constructor with a string message.
+     * @param msg
+     */
     public ArtifactDatabaseException(String msg) {
         super(msg);
     }
--- 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:
--- 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 <a href="mailto:sascha.teichmann@intevation">Sascha L. Teichmann</a>
  */
 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 :
--- 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:
--- 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 <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
+ */
 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:
--- 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 :
--- 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:
--- 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 <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
  */
 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 :
--- 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 <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
  */
 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 :

http://dive4elements.wald.intevation.org