[Lada-commits] [PATCH] Code documentation
Wald Commits
scm-commit at wald.intevation.org
Wed Apr 22 14:03:57 CEST 2015
# HG changeset patch
# User Raimund Renkert <rrenkert at intevation.de>
# 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.
* <p>
* The object to update should come as JSON formatted string.
* <pre>
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.
+ * <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 at 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.
*/
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.
+ * <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 at 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());
}
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.
+ * <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 at 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.
*/
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.
+ * <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 at 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.
*/
More information about the Lada-commits
mailing list