# HG changeset patch # User Sascha L. Teichmann # Date 1269615911 0 # Node ID 69c84cf7c5d7fbe00a2406114a6f5d8f17a5d7ed # Parent 0f48188a6e0210b3e1e9cb0a01fc42d4b0174400 Added javadoc to the REST package of the artifact database (complete). artifacts/trunk@840 c6561f87-3c4e-4783-a992-168aeb5c3f6f diff -r 0f48188a6e02 -r 69c84cf7c5d7 ChangeLog --- a/ChangeLog Fri Mar 26 11:40:28 2010 +0000 +++ b/ChangeLog Fri Mar 26 15:05:11 2010 +0000 @@ -1,3 +1,20 @@ +2010-03-26 Sascha L. Teichmann + + * artifact-database/src/main/java/de/intevation/artifactdatabase/rest/BaseResource.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/Standalone.java, + artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ExportResource.java, + artifact-database/src/main/java/de/intevation/artifactdatabase/rest/OutRepresentation.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/rest/ArtifactOutResource.java, + artifact-database/src/main/java/de/intevation/artifactdatabase/rest/RestApp.java: + Added javadoc to the REST package (complete). TODO: Add javadoc to the remaining classes + of the 'artifactdatabase'. + 2010-03-26 Sascha L. Teichmann * artifact-database/src/main/java/de/intevation/artifactdatabase/SQL.java, @@ -13,6 +30,7 @@ * 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 * artifact-database/src/main/java/de/intevation/artifactdatabase/ProxyArtifact.java, diff -r 0f48188a6e02 -r 69c84cf7c5d7 artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ArtifactOutResource.java --- a/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ArtifactOutResource.java Fri Mar 26 11:40:28 2010 +0000 +++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ArtifactOutResource.java Fri Mar 26 15:05:11 2010 +0000 @@ -25,20 +25,31 @@ import java.io.IOException; /** + * Resource to serve the out()-outputs of artifacts. * @author Sascha L. Teichmann */ public class ArtifactOutResource extends BaseResource { + /** + * server URL where to find the resource. + */ public static final String PATH = "/artifact/{uuid}/{type}"; + /** + * XPath to figure out the MIME type of the requested result. + */ public static final String XPATH_MIME_TYPE = "/art:action/art:out/art:mime-type/@value"; + /** + * Default result MIME type: octet stream + */ public static final MediaType DEFAULT_MIME_TYPE = MediaType.APPLICATION_OCTET_STREAM; private static Logger logger = Logger.getLogger(ArtifactOutResource.class); + @Override protected Representation innerPost(Representation requestRepr) throws ResourceException { @@ -95,4 +106,4 @@ } } } -// 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 0f48188a6e02 -r 69c84cf7c5d7 artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ArtifactResource.java --- a/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ArtifactResource.java Fri Mar 26 11:40:28 2010 +0000 +++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ArtifactResource.java Fri Mar 26 15:05:11 2010 +0000 @@ -26,6 +26,13 @@ import de.intevation.artifactdatabase.XMLUtils; /** + * Resource to expose the core artifact methods + * (describe, feed and advance) via REST. + * + *
    + *
  • describe() is modelled via GET.
    • + *
  • advance() and feed() are modelled via POST.
    • + *
* @author Sascha L. Teichmann */ public class ArtifactResource @@ -33,19 +40,47 @@ { private static Logger logger = Logger.getLogger(ArtifactResource.class); + /** + * XPath to figure out the type of action (feed, advance) via the + * incoming POST request. + */ public static final String XPATH_ACTION = "/art:action/art:type/@name"; + /** + * server URL where to reach the resource. + */ public static final String PATH = "/artifact/{uuid}"; + /** + * Error message if no action was given. + */ public static final String NO_ACTION_MESSAGE = "no action given"; + + /** + * Error message if a unknown action was given. + */ public static final String NO_SUCH_ACTION_MESSAGE = "no such action"; + /** + * Error message if the requested artifact was not found in + * the artifact database. + */ public static final String NO_ARTIFACT_FOUND = "Artifact not found"; + /** + * Action name 'advance'. + */ public static final String ADVANCE = "advance"; + /** + * Action name 'feed'. + */ public static final String FEED = "feed"; + /** + * Action name 'describe'. + */ public static final String DESCRIBE = "describe"; + @Override protected Representation innerGet() throws ResourceException { @@ -74,6 +109,17 @@ } } + /** + * Method to figure out which POST action (feed or advance) was + * triggered and perform this operation on the artifact specified + * by 'identifier' and found in the artifact database 'db' + * @param identifier The identifier of the artifact. + * @param action The action to be performed. + * @param source The input document to further parameterize the + * operation. + * @param db The artifact database where to find the artifact. + * @return + */ protected Representation dispatch( String identifier, String action, @@ -107,6 +153,7 @@ return new DomRepresentation(MediaType.APPLICATION_XML, out); } + @Override protected Representation innerPost(Representation requestRepr) { Document inputDocument = null; @@ -144,4 +191,4 @@ return dispatch(identifier, action, inputDocument, db); } } -// 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 0f48188a6e02 -r 69c84cf7c5d7 artifact-database/src/main/java/de/intevation/artifactdatabase/rest/BaseResource.java --- a/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/BaseResource.java Fri Mar 26 11:40:28 2010 +0000 +++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/BaseResource.java Fri Mar 26 15:05:11 2010 +0000 @@ -21,6 +21,8 @@ import de.intevation.artifactdatabase.DefaultPreferredLocale; /** + * Base class for the resources of REST interface of the artifact database. + * Primarily used to unify the logging. * @author Sascha L. Teichmann */ public class BaseResource @@ -28,9 +30,24 @@ { private static Logger logger = Logger.getLogger(BaseResource.class); + /** + * Default constructor. + */ public BaseResource() { } + /** + * Overrides the post method of ServerResource to handle some + * exceptions and to the required logging. + * The call bridges to #innerPost(Representation) which + * should be overwitten by the subclasses to do the real + * request processing. + * @param requestRepr The incoming represention of the HTTP request. + * @return The representation produced by #innerPost(Representation). + * @throws ResourceException Thrown if something went wrong during + * request processing. + */ + @Override protected Representation post(Representation requestRepr) throws ResourceException { @@ -46,12 +63,30 @@ } } + /** + * Trivial implementation of innerPost() which is called by + * #post(Representation) which simply calls super.post(Representation). + * This should be overwritten by subclasses which need POST support. + * @param requestRepr The incoming representation of the request. + * @return The representation produced by super.post(Representation). + * @throws ResourceException Thrown if something went wrong during + * request processing. + */ protected Representation innerPost(Representation requestRepr) throws ResourceException { return super.post(requestRepr); } + /** + * Wrapper around get() of the super class to handle some exceptions + * and do the corresponing logging. The call is bridged to #innerGet() + * which should be overwritten by subclasses. + * @return The representation produced by #innerGet() + * @throws ResourceException Thrown if something went wrong during + * request processing. + */ + @Override protected Representation get() throws ResourceException { @@ -67,12 +102,25 @@ } } + /** + * Trivial implementaion of innerGet() which simply calls + * super.get() to produce some output representation. This method + * should be overwritten by subclasses which need GET support. + * @return The representation produced by super.get(). + * @throws ResourceException Thrown if something went wrong during + * request processing. + */ protected Representation innerGet() throws ResourceException { return super.get(); } + /** + * Returns meta information (preferred languages et. al.) + * of the current HTTP request. + * @return the meta information + */ protected CallMeta getCallMeta() { ClientInfo clientInfo = getClientInfo(); @@ -92,4 +140,4 @@ return new DefaultCallMeta(languages); } } -// 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 0f48188a6e02 -r 69c84cf7c5d7 artifact-database/src/main/java/de/intevation/artifactdatabase/rest/CreateResource.java --- a/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/CreateResource.java Fri Mar 26 11:40:28 2010 +0000 +++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/CreateResource.java Fri Mar 26 15:05:11 2010 +0000 @@ -18,6 +18,7 @@ import de.intevation.artifacts.ArtifactNamespaceContext; /** + * Resource to create a new artifact within artifact database. * @author Sascha L. Teichmann */ public class CreateResource @@ -25,12 +26,25 @@ { private static Logger logger = Logger.getLogger(CreateResource.class); + /** + * server URL where to reach the resource. + */ public static final String PATH = "/create"; + /** + * XPATH to figure out the name of the factory which should be used + * to create the new artifact. + */ public static final String XPATH_FACTORY = "/art:action/art:factory/@name"; + /** + * Error message if no factory was given. + */ public static final String NO_FACTORY_MESSAGE = "No factory given"; + /** + * Error message if no artifact was created. + */ public static final String NO_ARTIFACT_CREATED = "No artifact created"; protected Representation innerPost(Representation requestRepr) diff -r 0f48188a6e02 -r 69c84cf7c5d7 artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ExportResource.java --- a/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ExportResource.java Fri Mar 26 11:40:28 2010 +0000 +++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ExportResource.java Fri Mar 26 15:05:11 2010 +0000 @@ -18,6 +18,9 @@ import org.restlet.resource.ResourceException; /** + * Resource to produce an external XML representation of a given + * artifact to be import by ImportResource later on. + * * @author Sascha L. Teichmann */ public class ExportResource @@ -25,6 +28,9 @@ { private static Logger logger = Logger.getLogger(ExportResource.class); + /** + * server URL where to reach the resource. + */ public static final String PATH = "/export/{uuid}"; protected Representation innerGet() diff -r 0f48188a6e02 -r 69c84cf7c5d7 artifact-database/src/main/java/de/intevation/artifactdatabase/rest/FactoriesResource.java --- a/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/FactoriesResource.java Fri Mar 26 11:40:28 2010 +0000 +++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/FactoriesResource.java Fri Mar 26 15:05:11 2010 +0000 @@ -20,6 +20,7 @@ import org.apache.log4j.Logger; /** + * Resource to list the available factories. * @author Sascha L. Teichmann */ public class FactoriesResource @@ -27,6 +28,9 @@ { private static Logger logger = Logger.getLogger(FactoriesResource.class); + /** + * server URL where to reach the resource. + */ public static final String PATH = "/factories"; protected Representation innerGet() diff -r 0f48188a6e02 -r 69c84cf7c5d7 artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ImportResource.java --- a/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ImportResource.java Fri Mar 26 11:40:28 2010 +0000 +++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ImportResource.java Fri Mar 26 15:05:11 2010 +0000 @@ -20,6 +20,9 @@ import org.w3c.dom.Document; /** + * Resource to import an XML document containg an artifact produced by + * the ExportResource. + * * @author Sascha L. Teichmann */ public class ImportResource @@ -27,6 +30,9 @@ { private static Logger logger = Logger.getLogger(ImportResource.class); + /** + * server URL where to reach the resource. + */ public static final String PATH = "/import"; protected Representation innerPost(Representation requestRepr) { diff -r 0f48188a6e02 -r 69c84cf7c5d7 artifact-database/src/main/java/de/intevation/artifactdatabase/rest/OutRepresentation.java --- a/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/OutRepresentation.java Fri Mar 26 11:40:28 2010 +0000 +++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/OutRepresentation.java Fri Mar 26 15:05:11 2010 +0000 @@ -10,20 +10,38 @@ import java.io.OutputStream; /** + * Special representation to serve the out()-outputs + * via DeferredOutput efficently . * @author Sascha L. Teichmann */ public class OutRepresentation extends OutputRepresentation { + /** + * The deferred output fetched from ArtifactDatabase.out(). + */ protected DeferredOutput out; + /** + * Constructor to create representation with a given MIME type and + * a deferred output. + * @param mediaType The MIME type of this representation. + * @param out The deferred output from the ArtifactDatabase.out() call. + */ public OutRepresentation(MediaType mediaType, DeferredOutput out) { super(mediaType); this.out = out; } + /** + * Overwrites the write(OutputStream) of OutRepresentation to serve + * the data from the deferred output. + * @param output the stream where to write the data into. + * @throws IOException Thrown if an exception occurred while writing + * the data to the output stream. + */ public void write(OutputStream output) throws IOException { out.write(output); } } -// 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 0f48188a6e02 -r 69c84cf7c5d7 artifact-database/src/main/java/de/intevation/artifactdatabase/rest/RestApp.java --- a/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/RestApp.java Fri Mar 26 11:40:28 2010 +0000 +++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/RestApp.java Fri Mar 26 15:05:11 2010 +0000 @@ -11,21 +11,43 @@ import org.restlet.routing.Router; /** + * This is the core REST application that binds the serveral resources + * used to manage the artifact database to the HTTP server provided + * by the Restlet framework. * * @author Sascha L. Teichmann */ public class RestApp extends Application { + /** + * The central artifact database instance to work with. + */ protected ArtifactDatabase database; + /** + * Default constructor + */ public RestApp() { } + /** + * Constructor to create REST appliction bound to a specific + * artifact database. + * + * @param database The artifact database to be used. + */ public RestApp(ArtifactDatabase database) { this.database = database; } + /** + * Overwrites the createRoot() method of Application to + * build the resource tree to form the exposed server URLs. + * + * @return The root of the URL tree exposed by the HTTP server. + */ + @Override public Restlet createRoot() { Context context = getContext(); diff -r 0f48188a6e02 -r 69c84cf7c5d7 artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ServiceResource.java --- a/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ServiceResource.java Fri Mar 26 11:40:28 2010 +0000 +++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ServiceResource.java Fri Mar 26 15:05:11 2010 +0000 @@ -20,6 +20,8 @@ import java.io.IOException; /** + * Resource to process incoming XML documents with a given service. + * * @author Sascha L. Teichmann */ public class ServiceResource @@ -27,8 +29,15 @@ { private static Logger logger = Logger.getLogger(ServiceResource.class); + /** + * server URL where to reach the resource. + */ public static final String PATH = "/service/{service}"; + /** + * Error message if no corresponing service is provided by + * the artifact database. + */ public static final String NO_SUCH_ACTION_MESSAGE = "no such service"; protected Representation innerPost(Representation requestRepr) { diff -r 0f48188a6e02 -r 69c84cf7c5d7 artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ServicesResource.java --- a/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ServicesResource.java Fri Mar 26 11:40:28 2010 +0000 +++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ServicesResource.java Fri Mar 26 15:05:11 2010 +0000 @@ -21,6 +21,8 @@ import org.w3c.dom.Element; /** + * Resource to list the available service offered by the artifact database. + * * @author Sascha L. Teichmann */ public class ServicesResource @@ -28,6 +30,9 @@ { private static Logger logger = Logger.getLogger(ServicesResource.class); + /** + * server URL where to reach the resource. + */ public static final String PATH = "/services"; protected Representation innerGet() diff -r 0f48188a6e02 -r 69c84cf7c5d7 artifact-database/src/main/java/de/intevation/artifactdatabase/rest/Standalone.java --- a/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/Standalone.java Fri Mar 26 11:40:28 2010 +0000 +++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/Standalone.java Fri Mar 26 15:05:11 2010 +0000 @@ -8,25 +8,48 @@ import de.intevation.artifactdatabase.Config; -import de.intevation.artifactdatabase.rest.RestApp; - import org.apache.log4j.Logger; /** + * Starts an HTTP server bound to a RestApp. + * The server (binding interface and port) is configure via the + * global configuration. + * * @author Sascha L. Teichmann */ public class Standalone { private static Logger logger = Logger.getLogger(Standalone.class); + /** + * XPath to figure out the port where to listen from the + * global configuration. + */ public static final String REST_PORT = "/artifact-database/rest-server/port/text()"; + /** + * XPath to figure out from global configuration + * which network interface to use to bind the HTTP server. + */ public static final String LISTEN_INTERFACE = "/artifact-database/rest-server/listen/text()"; + /** + * The default port of the HTTP server: 8181 + */ public static final int DEFAULT_PORT = 8181; + /** + * Builds a RestApp wrapped around the given artifact database, + * and bind this application to HTTP server. The HTTP server + * is configured by the global configuration. If no port is + * given by the configuration the default port is used. If + * no interface is given the HTTP server is reachable from + * all interfaces. + * @param db The artifact database to be exposed via the + * REST application. + */ public static void startAsServer(ArtifactDatabase db) { String portString = Config.getStringXPath(REST_PORT); String listenString = Config.getStringXPath(LISTEN_INTERFACE); @@ -71,4 +94,4 @@ } } } -// 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 : \ No newline at end of file