# HG changeset patch # User Raimund Renkert # Date 1429704233 -7200 # Node ID 21a49dc9984ddd0b367f4a3f9c03a3de6762e1e1 # Parent 9a6d8c174e787dff9bb18b3753d2daea0f35d2d6 Code documentation. diff -r 9a6d8c174e78 -r 21a49dc9984d src/main/java/de/intevation/lada/rest/MessungService.java --- 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. *

* The object to update should come as JSON formatted string. *

diff -r 9a6d8c174e78 -r 21a49dc9984d src/main/java/de/intevation/lada/rest/ProbeService.java
--- 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.
+ * 

+ * 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. + *

+ * 
+ * {
+ *  "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]
+ * }
+ * 
+ * 
* * @author Raimund Renkert */ @@ -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. + *

+ * The requested objects can be filtered using the following URL + * parameters:
+ * * qid: The id of the query.
+ * * page: The page to display in a paginated result grid.
+ * * start: The first Probe item.
+ * * limit: The count of Probe items.
+ * * sort: Sort the result ascending(ASC) or descenting (DESC).
+ *
+ * The response data contains a stripped set of Probe objects. The returned fields + * are defined in the query used in the request. + *

+ * 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. + *

+ * The id is appended to the URL as a path parameter. + *

+ * 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. + *

+ * The new object is embedded in the post data as JSON formatted string. + *

+ *

+     * 
+     * {
+     *  "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]
+     * }
+     * 
+     * 
* * @return Response object containing the new probe object. */ @@ -233,9 +339,41 @@ } /** - * Update an existing probe object. + * Update an existing Probe object. + *

+ * The object to update should come as JSON formatted string. + *

+     * 
+     * {
+     *  "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]
+     * }
+     * 
+     * 
* - * @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. + *

+ * The id is appended to the URL as a path parameter. + *

+ * Example: http://example.com/probe/{id} * * @return Response object. */ diff -r 9a6d8c174e78 -r 21a49dc9984d src/main/java/de/intevation/lada/rest/QueryService.java --- 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. + *

+ * 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. + *

+ * 
+ * {
+ *  "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]
+ * }
+ * 
+ * 
+ * + * @author Raimund Renkert */ @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()); } diff -r 9a6d8c174e78 -r 21a49dc9984d src/main/java/de/intevation/lada/rest/StatusService.java --- 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. + *

+ * 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. + *

+ * 
+ * {
+ *  "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]
+ * }
+ * 
+ * 
+ * + * @author Raimund Renkert + */ @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. + *

+ * The requested objects can be filtered using a URL parameter named + * probeId. + *

+ * 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. + *

+ * The id is appended to the URL as a path parameter. + *

+ * 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. + *

+ * The new object is embedded in the post data as JSON formatted string. + *

+ *

+     * 
+     * {
+     *  "owner": [boolean],
+     *  "messungsId": [number],
+     *  "erzeuger": [string],
+     *  "status": [number],
+     *  "skommentar": [string],
+     *  "treeModified":null,
+     *  "parentModified":null,
+     *  "sdatum": [date]
+     * }
+     * 
+     * 
+ * + * @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. + *

+ * The object to update should come as JSON formatted string. + *

+     * 
+     * {
+     *  "id": [number],
+     *  "owner": [boolean],
+     *  "messungsId": [number],
+     *  "erzeuger": [string],
+     *  "status": [number],
+     *  "skommentar": [string],
+     *  "treeModified": [timestamp],
+     *  "parentModified": [timestamp],
+     *  "sdatum": [date]
+     * }
+     * 
+     * 
* - * @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. + *

+ * The id is appended to the URL as a path parameter. + *

+ * Example: http://example.com/status/{id} * * @return Response object. */ diff -r 9a6d8c174e78 -r 21a49dc9984d src/main/java/de/intevation/lada/rest/ZusatzwertService.java --- 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. + *

+ * 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. + *

+ * 
+ * {
+ *  "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]
+ * }
+ * 
+ * 
+ * + * @author Raimund Renkert + */ @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. + *

+ * The requested objects can be filtered using a URL parameter named + * probeId. + *

+ * 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. + *

+ * The id is appended to the URL as a path parameter. + *

+ * 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. + *

+ * The new object is embedded in the post data as JSON formatted string. + *

+ *

+     * 
+     * {
+     *  "owner": [boolean],
+     *  "probeId": [number],
+     *  "pzsId": [string],
+     *  "nwgZuMesswert": [number],
+     *  "messwertPzs": [number],
+     *  "messfehler": [number],
+     *  "treeModified": null,
+     *  "parentModified": null,
+     *  "letzteAenderung": [date]
+     * }
+     * 
+     * 
+ * + * @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. + *

+ * The object to update should come as JSON formatted string. + *

+     * 
+     * {
+     *  "id": [number],
+     *  "owner": [boolean],
+     *  "probeId": [number],
+     *  "pzsId": [string],
+     *  "nwgZuMesswert": [number],
+     *  "messwertPzs": [number],
+     *  "messfehler": [number],
+     *  "treeModified": [timestamp],
+     *  "parentModified": [timestamp],
+     *  "letzteAenderung": [date]
+     * }
+     * 
+     * 
* - * @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. + *

+ * The id is appended to the URL as a path parameter. + *

+ * Example: http://example.com/zusatzwert/{id} * * @return Response object. */