Mercurial > lada > lada-server

changeset 628:21a49dc9984d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Code documentation.
author Raimund Renkert <rrenkert@intevation.de>
date Wed, 22 Apr 2015 14:03:53 +0200
parents 9a6d8c174e78
children 3bbfdef05ee1
files src/main/java/de/intevation/lada/rest/MessungService.java src/main/java/de/intevation/lada/rest/ProbeService.java src/main/java/de/intevation/lada/rest/QueryService.java src/main/java/de/intevation/lada/rest/StatusService.java src/main/java/de/intevation/lada/rest/ZusatzwertService.java
diffstat 5 files changed, 401 insertions(+), 42 deletions(-) [+]
line wrap: on
line diff
--- a/src/main/java/de/intevation/lada/rest/MessungService.java	Wed Apr 22 09:18:29 2015 +0200
+++ b/src/main/java/de/intevation/lada/rest/MessungService.java	Wed Apr 22 14:03:53 2015 +0200
@@ -222,7 +222,7 @@
     }
 
     /**
-     * Update an existing messung object.
+     * Update an existing Messung object.
      * <p>
      * The object to update should come as JSON formatted string.
      * <pre>
--- a/src/main/java/de/intevation/lada/rest/ProbeService.java	Wed Apr 22 09:18:29 2015 +0200
+++ b/src/main/java/de/intevation/lada/rest/ProbeService.java	Wed Apr 22 14:03:53 2015 +0200
@@ -1,9 +1,9 @@
 /* Copyright (C) 2013 by Bundesamt fuer Strahlenschutz
  * Software engineering by Intevation GmbH
  *
- * This file is Free Software under the GNU GPL (v>=3) 
- * and comes with ABSOLUTELY NO WARRANTY! Check out 
- * the documentation coming with IMIS-Labordaten-Application for details. 
+ * This file is Free Software under the GNU GPL (v>=3)
+ * and comes with ABSOLUTELY NO WARRANTY! Check out
+ * the documentation coming with IMIS-Labordaten-Application for details.
  */
 package de.intevation.lada.rest;
 
@@ -57,9 +57,53 @@
 import de.intevation.lada.validation.Violation;
 import de.intevation.lada.validation.annotation.ValidationConfig;
 
-
 /**
- * This class produces a RESTful service to interact with probe objects.
+ * REST service for Probe objects.
+ * <p>
+ * The services produce data in the application/json media type.
+ * All HTTP methods use the authorization module to determine if the user is
+ * allowed to perform the requested action.
+ * A typical response holds information about the action performed and the data.
+ * <pre>
+ * <code>
+ * {
+ *  "success": [boolean];
+ *  "message": [string],
+ *  "data":[{
+ *      "id":[number],
+ *      "baId": [string],
+ *      "datenbasisId": [number],
+ *      "letzteAenderung": [timestamp],
+ *      "media": [string],
+ *      "mediaDesk": [string],
+ *      "mittelungsdauer": [number],
+ *      "mstId": [string],
+ *      "netzbetreiberId":[string],
+ *      "probeentnahmeBeginn": [timestamp],
+ *      "probeentnahmeEnde": [timestamp],
+ *      "probenartId": [number],
+ *      "test": [boolean],
+ *      "umwId": [string],
+ *      "hauptprobenNr": [string],
+ *      "erzeugerId": [string],
+ *      "mpKat": [string],
+ *      "mplId": [number],
+ *      "mprId": [number],
+ *      "probeNehmerId": [number],
+ *      "solldatumBeginn": [timestamp],
+ *      "solldatumEnde": [timestamp],
+ *      "treeModified": [timestamp],
+ *      "readonly": [boolean],
+ *      "owner": [boolean],
+ *      "probeIdAlt": [string]
+ *  }],
+ *  "errors": [object],
+ *  "warnings": [object],
+ *  "readonly": [boolean],
+ *  "totalCount": [number]
+ * }
+ * </code>
+ * </pre>
  *
  * @author <a href="mailto:rrenkert@intevation.de">Raimund Renkert</a>
  */
@@ -67,32 +111,58 @@
 @RequestScoped
 public class ProbeService {
 
-    /* The logger used in this class.*/
+    /**
+     * The logger used in this class.
+     */
     @Inject
     private Logger logger;
 
-    /* The data repository granting read/write access.*/
+    /**
+     * The data repository granting read/write access.
+     */
     @Inject
     @RepositoryConfig(type=RepositoryType.RW)
     private Repository defaultRepo;
 
-    /* The authorization module.*/
+    /**
+     * The authorization module.
+     */
     @Inject
     @AuthorizationConfig(type=AuthorizationType.OPEN_ID)
     private Authorization authorization;
 
+    /**
+     * The object lock mechanism.
+     */
     @Inject
     @LockConfig(type=LockType.TIMESTAMP)
     private ObjectLocker lock;
 
+    /**
+     * The validator used for Rpobe objects.
+     */
     @Inject
     @ValidationConfig(type="Probe")
     private Validator validator;
 
     /**
-     * Get all probe objects.
+     * Get all Probe objects.
+     * <p>
+     * The requested objects can be filtered using the following URL
+     * parameters:<br>
+     *  * qid: The id of the query.<br>
+     *  * page: The page to display in a paginated result grid.<br>
+     *  * start: The first Probe item.<br>
+     *  * limit: The count of Probe items.<br>
+     *  * sort: Sort the result ascending(ASC) or descenting (DESC).<br>
+     *  <br>
+     *  The response data contains a stripped set of Probe objects. The returned fields
+     *  are defined in the query used in the request.
+     * <p>
+     * Example:
+     * http://example.com/probe?qid=[ID]&page=[PAGE]&start=[START]&limit=[LIMIT]&sort=[{"property":"probeId","direction":"ASC"}]
      *
-     * @return Response object containing all probe objects.
+     * @return Response object containing all Probe objects.
      */
     @SuppressWarnings("unchecked")
     @GET
@@ -164,9 +234,13 @@
     }
 
     /**
-     * Get a probe object by id.
+     * Get a single Probe object by id.
+     * <p>
+     * The id is appended to the URL as a path parameter.
+     * <p>
+     * Example: http://example.com/probe/{id}
      *
-     * @return Response object containing a single probe.
+     * @return Response object containing a single Probe.
      */
     @GET
     @Path("/{id}")
@@ -186,7 +260,39 @@
     }
 
     /**
-     * Create a new probe object.
+     * Create a new Probe object.
+     * <p>
+     * The new object is embedded in the post data as JSON formatted string.
+     * <p>
+     * <pre>
+     * <code>
+     * {
+     *  "probeIdAlt": [string],
+     *  "hauptprobenNr": [string],
+     *  "test": [boolean],
+     *  "netzbetreiberId": [string],
+     *  "mstId": [string],
+     *  "datenbasisId": [number],
+     *  "baId": [string],
+     *  "probenartId": [number],
+     *  "mediaDesk": [string],
+     *  "media": [string],
+     *  "umwId": [string],
+     *  "mittelungsdauer": [number],
+     *  "erzeugerId":[string],
+     *  "probeNehmerId": [number],
+     *  "mpKat": [string],
+     *  "mplId": [number],
+     *  "mprId": [number],
+     *  "treeModified":null,
+     *  "probeentnahmeBeginn": [date],
+     *  "probeentnahmeEnde": [date],
+     *  "letzteAenderung": [date],
+     *  "solldatumBeginn": [date],
+     *  "solldatumEnde": [date]
+     * }
+     * </code>
+     * </pre>
      *
      * @return Response object containing the new probe object.
      */
@@ -233,9 +339,41 @@
     }
 
     /**
-     * Update an existing probe object.
+     * Update an existing Probe object.
+     * <p>
+     * The object to update should come as JSON formatted string.
+     * <pre>
+     * <code>
+     * {
+     *  "id": [number],
+     *  "probeIdAlt": [string],
+     *  "hauptprobenNr": [string],
+     *  "test": [boolean],
+     *  "netzbetreiberId": [string],
+     *  "mstId": [string],
+     *  "datenbasisId": [number],
+     *  "baId": [string],
+     *  "probenartId": [number],
+     *  "mediaDesk": [string],
+     *  "media": [string],
+     *  "umwId": [string],
+     *  "mittelungsdauer": [number],
+     *  "erzeugerId": [number],
+     *  "probeNehmerId": [number],
+     *  "mpKat": [string],
+     *  "mplId": [number],
+     *  "mprId": [number],
+     *  "treeModified": [timestamp],
+     *  "probeentnahmeBeginn": [date],
+     *  "probeentnahmeEnde": [date],
+     *  "letzteAenderung": [date],
+     *  "solldatumBeginn": [date],
+     *  "solldatumEnde":[date]
+     * }
+     * </code>
+     * </pre>
      *
-     * @return Response object containing the updated probe object.
+     * @return Response object containing the updated Probe object.
      */
     @PUT
     @Path("/{id}")
@@ -278,7 +416,11 @@
     }
 
     /**
-     * Delete an existing probe object by id.
+     * Delete an existing Probe object by id.
+     * <p>
+     * The id is appended to the URL as a path parameter.
+     * <p>
+     * Example: http://example.com/probe/{id}
      *
      * @return Response object.
      */
--- a/src/main/java/de/intevation/lada/rest/QueryService.java	Wed Apr 22 09:18:29 2015 +0200
+++ b/src/main/java/de/intevation/lada/rest/QueryService.java	Wed Apr 22 14:03:53 2015 +0200
@@ -18,6 +18,33 @@
 
 /**
  * REST-Service for preconfigured queries.
+ * <p>
+ * The services produce data in the application/json media type.
+ * All HTTP methods use the authorization module to determine if the user is
+ * allowed to perform the requested action.
+ * A typical response holds information about the action performed and the data.
+ * <pre>
+ * <code>
+ * {
+ *  "success": [boolean];
+ *  "message": [string],
+ *  "data":[{
+ *      "id": [string],
+ *      "name": [string],
+ *      "description": [string],
+ *      "sql": [string],
+ *      "filters": [array],
+ *      "results": [array]
+ *  }],
+ *  "errors": [object],
+ *  "warnings": [object],
+ *  "readonly": [boolean],
+ *  "totalCount": [number]
+ * }
+ * </code>
+ * </pre>
+ *
+ * @author <a href="mailto:rrenkert@intevation.de">Raimund Renkert</a>
  */
 @Path("/query")
 @RequestScoped
@@ -27,7 +54,7 @@
      * Request all configured queries.
      */
     @GET
-    @Produces("text/json")
+    @Produces("application/json")
     public Response get() {
         return new Response(true, 200, QueryTools.getConfig());
     }
--- a/src/main/java/de/intevation/lada/rest/StatusService.java	Wed Apr 22 09:18:29 2015 +0200
+++ b/src/main/java/de/intevation/lada/rest/StatusService.java	Wed Apr 22 14:03:53 2015 +0200
@@ -1,9 +1,9 @@
 /* Copyright (C) 2013 by Bundesamt fuer Strahlenschutz
  * Software engineering by Intevation GmbH
  *
- * This file is Free Software under the GNU GPL (v>=3) 
- * and comes with ABSOLUTELY NO WARRANTY! Check out 
- * the documentation coming with IMIS-Labordaten-Application for details. 
+ * This file is Free Software under the GNU GPL (v>=3)
+ * and comes with ABSOLUTELY NO WARRANTY! Check out
+ * the documentation coming with IMIS-Labordaten-Application for details.
  */
 package de.intevation.lada.rest;
 
@@ -37,28 +37,74 @@
 import de.intevation.lada.util.rest.RequestMethod;
 import de.intevation.lada.util.rest.Response;
 
+/**
+ * REST service for Status objects.
+ * <p>
+ * The services produce data in the application/json media type.
+ * All HTTP methods use the authorization module to determine if the user is
+ * allowed to perform the requested action.
+ * A typical response holds information about the action performed and the data.
+ * <pre>
+ * <code>
+ * {
+ *  "success": [boolean];
+ *  "message": [string],
+ *  "data":[{
+ *      "id": [number],
+ *      "erzeuger": [string],
+ *      "messungsId": [number],
+ *      "status": [number],
+ *      "owner": [boolean],
+ *      "readonly": [boolean],
+ *      "treeModified": [timestamp],
+ *      "parentModified": [timestamp],
+ *      "sdatum": [timestamp],
+ *      "skommentar": [string]
+ *  }],
+ *  "errors": [object],
+ *  "warnings": [object],
+ *  "readonly": [boolean],
+ *  "totalCount": [number]
+ * }
+ * </code>
+ * </pre>
+ *
+ * @author <a href="mailto:rrenkert@intevation.de">Raimund Renkert</a>
+ */
 @Path("status")
 @RequestScoped
 public class StatusService {
 
-    /* The data repository granting read/write access.*/
+    /**
+     * The data repository granting read/write access.
+     */
     @Inject
     @RepositoryConfig(type=RepositoryType.RW)
     private Repository defaultRepo;
 
+    /**
+     * The object lock mechanism.
+     */
     @Inject
     @LockConfig(type=LockType.TIMESTAMP)
     private ObjectLocker lock;
 
-    /* The authorization module.*/
+    /**
+     * The authorization module.
+     */
     @Inject
     @AuthorizationConfig(type=AuthorizationType.OPEN_ID)
     private Authorization authorization;
 
     /**
-     * Get all objects.
+     * Get all Status objects.
+     * <p>
+     * The requested objects can be filtered using a URL parameter named
+     * probeId.
+     * <p>
+     * Example: http://example.com/status?messungsId=[ID]
      *
-     * @return Response object containing all messung objects.
+     * @return Response object containing all Status objects.
      */
     @GET
     @Path("/")
@@ -85,9 +131,13 @@
     }
 
     /**
-     * Get an object by id.
+     * Get a single Status object by id.
+     * <p>
+     * The id is appended to the URL as a path parameter.
+     * <p>
+     * Example: http://example.com/status/{id}
      *
-     * @return Response object containing a single messung.
+     * @return Response object containing a single Status.
      */
     @GET
     @Path("/{id}")
@@ -103,6 +153,28 @@
             LStatus.class);
     }
 
+    /**
+     * Create a Status object.
+     * <p>
+     * The new object is embedded in the post data as JSON formatted string.
+     * <p>
+     * <pre>
+     * <code>
+     * {
+     *  "owner": [boolean],
+     *  "messungsId": [number],
+     *  "erzeuger": [string],
+     *  "status": [number],
+     *  "skommentar": [string],
+     *  "treeModified":null,
+     *  "parentModified":null,
+     *  "sdatum": [date]
+     * }
+     * </code>
+     * </pre>
+     *
+     * @return A response object containing the created Status.
+     */
     @POST
     @Path("/")
     @Produces(MediaType.APPLICATION_JSON)
@@ -127,9 +199,26 @@
     }
 
     /**
-     * Update an existing object.
+     * Update an existing Status object.
+     * <p>
+     * The object to update should come as JSON formatted string.
+     * <pre>
+     * <code>
+     * {
+     *  "id": [number],
+     *  "owner": [boolean],
+     *  "messungsId": [number],
+     *  "erzeuger": [string],
+     *  "status": [number],
+     *  "skommentar": [string],
+     *  "treeModified": [timestamp],
+     *  "parentModified": [timestamp],
+     *  "sdatum": [date]
+     * }
+     * </code>
+     * </pre>
      *
-     * @return Response object containing the updated probe object.
+     * @return Response object containing the updated Status object.
      */
     @PUT
     @Path("/{id}")
@@ -161,7 +250,11 @@
     }
 
     /**
-     * Delete an existing object by id.
+     * Delete an existing Status object by id.
+     * <p>
+     * The id is appended to the URL as a path parameter.
+     * <p>
+     * Example: http://example.com/status/{id}
      *
      * @return Response object.
      */
--- a/src/main/java/de/intevation/lada/rest/ZusatzwertService.java	Wed Apr 22 09:18:29 2015 +0200
+++ b/src/main/java/de/intevation/lada/rest/ZusatzwertService.java	Wed Apr 22 14:03:53 2015 +0200
@@ -1,9 +1,9 @@
 /* Copyright (C) 2013 by Bundesamt fuer Strahlenschutz
  * Software engineering by Intevation GmbH
  *
- * This file is Free Software under the GNU GPL (v>=3) 
- * and comes with ABSOLUTELY NO WARRANTY! Check out 
- * the documentation coming with IMIS-Labordaten-Application for details. 
+ * This file is Free Software under the GNU GPL (v>=3)
+ * and comes with ABSOLUTELY NO WARRANTY! Check out
+ * the documentation coming with IMIS-Labordaten-Application for details.
  */
 package de.intevation.lada.rest;
 
@@ -40,28 +40,76 @@
 import de.intevation.lada.util.rest.RequestMethod;
 import de.intevation.lada.util.rest.Response;
 
+/**
+ * REST service for Zusatzwert objects.
+ * <p>
+ * The services produce data in the application/json media type.
+ * All HTTP methods use the authorization module to determine if the user is
+ * allowed to perform the requested action.
+ * A typical response holds information about the action performed and the data.
+ * <pre>
+ * <code>
+ * {
+ *  "success": [boolean];
+ *  "message": [string],
+ *  "data":[{
+ *      "id": [number],
+ *      "letzteAenderung": [timestamp],
+ *      "messfehler": [number],
+ *      "messwertPzs": [number],
+ *      "nwgZuMesswert": [number],
+ *      "probeId": [number],
+ *      "pzsId": [string],
+ *      "owner": [boolean],
+ *      "readonly": [boolean],
+ *      "treeModified": [timestamp],
+ *      "parentModified": [timestamp]
+ *  }],
+ *  "errors": [object],
+ *  "warnings": [object],
+ *  "readonly": [boolean],
+ *  "totalCount": [number]
+ * }
+ * </code>
+ * </pre>
+ *
+ * @author <a href="mailto:rrenkert@intevation.de">Raimund Renkert</a>
+ */
 @Path("zusatzwert")
 @RequestScoped
 public class ZusatzwertService {
 
-    /* The data repository granting read/write access.*/
+    /**
+     * The data repository granting read/write access.
+     */
     @Inject
     @RepositoryConfig(type=RepositoryType.RW)
     private Repository defaultRepo;
 
+    /**
+     * The object lock mechanism.
+     */
     @Inject
     @LockConfig(type=LockType.TIMESTAMP)
     private ObjectLocker lock;
 
-    /* The authorization module.*/
+    /**
+     * The authorization module.
+     */
     @Inject
     @AuthorizationConfig(type=AuthorizationType.OPEN_ID)
     private Authorization authorization;
 
     /**
-     * Get all objects.
+     * Get all Zusatzwert objects.
+     * <p>
+     * The requested objects can be filtered using a URL parameter named
+     * probeId.
+     * <p>
+     * Example: http://example.com/zusatzwert?probeId=[ID]
      *
-     * @return Response object containing all messung objects.
+     *
+     * @return Response object containing all Zusatzwert objects.
      */
     @GET
     @Path("/")
@@ -88,9 +136,13 @@
     }
 
     /**
-     * Get an object by id.
+     * Get a Zusatzwert object by id.
+     * <p>
+     * The id is appended to the URL as a path parameter.
+     * <p>
+     * Example: http://example.com/zusatzwert/{id}
      *
-     * @return Response object containing a single messung.
+     * @return Response object containing a single Zusatzwert.
      */
     @GET
     @Path("/{id}")
@@ -106,6 +158,29 @@
             LZusatzWert.class);
     }
 
+    /**
+     * Create a Zusatzwert object.
+     * <p>
+     * The new object is embedded in the post data as JSON formatted string.
+     * <p>
+     * <pre>
+     * <code>
+     * {
+     *  "owner": [boolean],
+     *  "probeId": [number],
+     *  "pzsId": [string],
+     *  "nwgZuMesswert": [number],
+     *  "messwertPzs": [number],
+     *  "messfehler": [number],
+     *  "treeModified": null,
+     *  "parentModified": null,
+     *  "letzteAenderung": [date]
+     * }
+     * </code>
+     * </pre>
+     *
+     * @return A response object containing the created Zusatzwert.
+     */
     @POST
     @Path("/")
     @Produces(MediaType.APPLICATION_JSON)
@@ -130,9 +205,27 @@
     }
 
     /**
-     * Update an existing object.
+     * Update an existing Zusatzwert object.
+     * <p>
+     * The object to update should come as JSON formatted string.
+     * <pre>
+     * <code>
+     * {
+     *  "id": [number],
+     *  "owner": [boolean],
+     *  "probeId": [number],
+     *  "pzsId": [string],
+     *  "nwgZuMesswert": [number],
+     *  "messwertPzs": [number],
+     *  "messfehler": [number],
+     *  "treeModified": [timestamp],
+     *  "parentModified": [timestamp],
+     *  "letzteAenderung": [date]
+     * }
+     * </code>
+     * </pre>
      *
-     * @return Response object containing the updated probe object.
+     * @return Response object containing the updated Zusatzwert object.
      */
     @PUT
     @Path("/{id}")
@@ -165,7 +258,11 @@
     }
 
     /**
-     * Delete an existing object by id.
+     * Delete an existing Zusatzwert object by id.
+     * <p>
+     * The id is appended to the URL as a path parameter.
+     * <p>
+     * Example: http://example.com/zusatzwert/{id}
      *
      * @return Response object.
      */
This site is hosted by Intevation GmbH (Datenschutzerklärung und Impressum | Privacy Policy and Imprint)