changeset 627:9a6d8c174e78

Code documentation.
author Raimund Renkert <raimund.renkert@intevation.de>
date Wed, 22 Apr 2015 09:18:29 +0200
parents 9e733f44d8b0
children 21a49dc9984d
files src/main/java/de/intevation/lada/lock/LockConfig.java src/main/java/de/intevation/lada/lock/LockType.java src/main/java/de/intevation/lada/lock/ObjectLocker.java src/main/java/de/intevation/lada/lock/TimestampLocker.java src/main/java/de/intevation/lada/rest/KommentarMService.java src/main/java/de/intevation/lada/rest/KommentarPService.java src/main/java/de/intevation/lada/rest/LoginService.java src/main/java/de/intevation/lada/rest/MessungService.java src/main/java/de/intevation/lada/rest/MesswertService.java src/main/java/de/intevation/lada/rest/OrtService.java
diffstat 10 files changed, 639 insertions(+), 63 deletions(-) [+]
line wrap: on
line diff
--- a/src/main/java/de/intevation/lada/lock/LockConfig.java	Mon Apr 20 17:45:22 2015 +0200
+++ b/src/main/java/de/intevation/lada/lock/LockConfig.java	Wed Apr 22 09:18:29 2015 +0200
@@ -1,3 +1,10 @@
+/* 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.
+ */
 package de.intevation.lada.lock;
 
 import java.lang.annotation.ElementType;
@@ -7,6 +14,11 @@
 
 import javax.inject.Qualifier;
 
+/**
+ * Annotation to configure data object locker.
+ *
+ * @author <a href="mailto:rrenkert@intevation.de">Raimund Renkert</a>
+ */
 @Qualifier
 @Retention(RetentionPolicy.RUNTIME)
 @Target({
--- a/src/main/java/de/intevation/lada/lock/LockType.java	Mon Apr 20 17:45:22 2015 +0200
+++ b/src/main/java/de/intevation/lada/lock/LockType.java	Wed Apr 22 09:18:29 2015 +0200
@@ -1,5 +1,17 @@
+/* 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.
+ */
 package de.intevation.lada.lock;
 
+/**
+ * Enumeration for data object lock type.
+ *
+ * @author <a href="mailto:rrenkert@intevation.de">Raimund Renkert</a>
+ */
 public enum LockType {
     NONE, TIMESTAMP
 }
--- a/src/main/java/de/intevation/lada/lock/ObjectLocker.java	Mon Apr 20 17:45:22 2015 +0200
+++ b/src/main/java/de/intevation/lada/lock/ObjectLocker.java	Wed Apr 22 09:18:29 2015 +0200
@@ -1,5 +1,17 @@
+/* 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.
+ */
 package de.intevation.lada.lock;
 
+/**
+ * Interface for data object locker.
+ *
+ * @author <a href="mailto:rrenkert@intevation.de">Raimund Renkert</a>
+ */
 public interface ObjectLocker {
     boolean isLocked(Object o);
 }
--- a/src/main/java/de/intevation/lada/lock/TimestampLocker.java	Mon Apr 20 17:45:22 2015 +0200
+++ b/src/main/java/de/intevation/lada/lock/TimestampLocker.java	Wed Apr 22 09:18:29 2015 +0200
@@ -1,3 +1,10 @@
+/* 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.
+ */
 package de.intevation.lada.lock;
 
 import java.lang.reflect.InvocationTargetException;
@@ -15,16 +22,33 @@
 import de.intevation.lada.util.data.RepositoryType;
 import de.intevation.lada.util.rest.Response;
 
+/**
+ * Data object locker using a timestamp to lock data access.
+ *
+ * @author <a href="mailto:rrenkert@intevation.de">Raimund Renkert</a>
+ */
 @LockConfig(type=LockType.TIMESTAMP)
 public class TimestampLocker implements ObjectLocker {
 
+    /**
+     * The logger used in this class.
+     */
     @Inject
     private Logger logger;
 
+    /**
+     * The repository used to read data.
+     */
     @Inject
     @RepositoryConfig(type=RepositoryType.RO)
     Repository repository;
 
+    /**
+     * Test whether a data object is locked or not.
+     *
+     * @param o The object to test.
+     * @return True if the object is locked else false.
+     */
     @Override
     public boolean isLocked(Object o) {
         if (o instanceof LProbe) {
@@ -75,6 +99,13 @@
         return false;
     }
 
+    /**
+     * Test whether an object is newer tha the given timestamp.
+     *
+     * @param o     The object to test.
+     * @param t     The timestamp.
+     * @return True if the object is newer.
+     */
     private boolean isNewer(Object o, Timestamp t) {
         Method m;
         try {
--- a/src/main/java/de/intevation/lada/rest/KommentarMService.java	Mon Apr 20 17:45:22 2015 +0200
+++ b/src/main/java/de/intevation/lada/rest/KommentarMService.java	Wed Apr 22 09:18:29 2015 +0200
@@ -34,24 +34,64 @@
 import de.intevation.lada.util.rest.RequestMethod;
 import de.intevation.lada.util.rest.Response;
 
+/**
+ * REST service for KommentarM 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":[{
+ *      "messungsId": [number],
+ *      "datum": [timestamp],
+ *      "erzeuger": [string],
+ *      "id": [number],
+ *      "text": [string],
+ *      "owner": [boolean],
+ *      "readonly": [boolean]
+ *  }],
+ *  "errors": [object],
+ *  "warnings": [object],
+ *  "readonly": [boolean],
+ *  "totalCount": [number]
+ * }
+ * </code>
+ * </pre>
+ *
+ * @author <a href="mailto:rrenkert@intevation.de">Raimund Renkert</a>
+ */
 @Path("mkommentar")
 @RequestScoped
 public class KommentarMService {
 
-    /* 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;
 
     /**
-     * Get all messung objects.
+     * Get all KommentarM objects.
+     * <p>
+     * The requested objects can be filtered using a URL parameter named
+     * messungsId.
+     * <p>
+     * Example: http://example.com/mkommentar?messungsId=[ID]
      *
-     * @return Response object containing all messung objects.
+     * @return Response object containing all (filtered) KommentarM objects.
      */
     @GET
     @Path("/")
@@ -78,9 +118,13 @@
     }
 
     /**
-     * Get an object by id.
+     * Get a single KommentarM object by id.
+     * <p>
+     * The id is appended to the URL as a path parameter.
+     * <p>
+     * Example: http://example.com/mkommentar/{id}
      *
-     * @return Response object containing a single kommentarP.
+     * @return Response object containing a single KommentarM.
      */
     @GET
     @Path("/{id}")
@@ -99,6 +143,24 @@
             LKommentarM.class);
     }
 
+    /**
+     * Create a KommentarM object.
+     * <p>
+     * The new object is embedded in the post data as JSON formatted string.
+     * <p>
+     * <pre>
+     * <code>
+     * {
+     *  messungsId: [number],
+     *  erzeuger: [string],
+     *  text: [string],
+     *  datum: [date]
+     *  owner: [boolean],
+     * }
+     * </code>
+     * </pre>
+     * @return A response object containing the created KommentarM.
+     */
     @POST
     @Path("/")
     @Produces(MediaType.APPLICATION_JSON)
@@ -123,9 +185,23 @@
     }
 
     /**
-     * Update an existing object.
+     * Update an existing KommentarM object.
+     * <p>
+     * The object to update should come as JSON formatted string.
+     * <pre>
+     * <code>
+     * {
+     *  "id": [number],
+     *  "owner": [boolean],
+     *  "messungsId": [number],
+     *  "erzeuger": [string],
+     *  "text": [string],
+     *  "datum": [date]
+     * }
+     * </code>
+     * </pre>
      *
-     * @return Response object containing the updated probe object.
+     * @return Response object containing the updated KommentarM object.
      */
     @PUT
     @Path("/{id}")
@@ -150,7 +226,11 @@
     }
 
     /**
-     * Delete an existing object by id.
+     * Delete an existing KommentarM object by id.
+     * <p>
+     * The id is appended to the URL as a path parameter.
+     * <p>
+     * Example: http://example.com/mkommentar/{id}
      *
      * @return Response object.
      */
--- a/src/main/java/de/intevation/lada/rest/KommentarPService.java	Mon Apr 20 17:45:22 2015 +0200
+++ b/src/main/java/de/intevation/lada/rest/KommentarPService.java	Wed Apr 22 09:18:29 2015 +0200
@@ -36,28 +36,70 @@
 import de.intevation.lada.util.rest.RequestMethod;
 import de.intevation.lada.util.rest.Response;
 
+/**
+ * REST service to operate on KommentarP 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":[{
+ *      "datum": [timestamp],
+ *      "erzeuger": [string],
+ *      "id": [number],
+ *      "text": [string],
+ *      "probeId": [number],
+ *      "owner": [boolean],
+ *      "readonly": [boolean]
+ *  }],
+ *  "errors": [object],
+ *  "warnings": [object],
+ *  "readonly": [boolean],
+ *  "totalCount": [number]
+ * }
+ * </code>
+ * </pre>
+ *
+ * @author <a href="mailto:rrenkert@intevation.de">Raimund Renkert</a>
+ */
 @Path("pkommentar")
 @RequestScoped
 public class KommentarPService {
 
-    /* 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;
 
     /**
-     * Get all messung objects.
+     * Get all KommentarP objects.
+     * <p>
+     * The requested objects can be filtered using a URL parameter named
+     * probeId.
+     * <p>
+     * Example: http://example.com/pkommentar?probeId=[ID]
      *
-     * @return Response object containing all messung objects.
+     * @return Response object containing all KommentarP objects.
      */
     @GET
     @Path("/")
@@ -84,9 +126,13 @@
     }
 
     /**
-     * Get a kommentarP object by id.
+     * Get a single KommentarP object by id.
+     * <p>
+     * The id is appended to the URL as a path parameter.
+     * <p>
+     * Example: http://example.com/pkommentar/{id}
      *
-     * @return Response object containing a single kommentarP.
+     * @return Response object containing a single KommentarP.
      */
     @GET
     @Path("/{id}")
@@ -102,6 +148,25 @@
             LKommentarP.class);
     }
 
+    /**
+     * Create a new KommentarP object.
+     * <p>
+     * The new object is embedded in the post data as JSON formatted string.
+     * <p>
+     * <pre>
+     * <code>
+     * {
+     *  "probeId": [number],
+     *  "erzeuger": [string],
+     *  "text": [string],
+     *  "datum": [date],
+     *  "owner": [boolean]
+     * }
+     * </code>
+     * </pre>
+     *
+     * @return Response object containing the new KommentarP.
+     */
     @POST
     @Path("/")
     @Produces(MediaType.APPLICATION_JSON)
@@ -126,9 +191,23 @@
     }
 
     /**
-     * Update an existing messung object.
+     * Update an existing KommentarP object.
+     * <p>
+     * The object to update should come as JSON formatted string.
+     * <pre>
+     * <code>
+     * {
+     *  "id": [number],
+     *  "owner": [boolean],
+     *  "probeId": [number],
+     *  "erzeuger": [string],
+     *  "text": [string],
+     *  "datum": [date]
+     * }
+     * </code>
+     * </pre>
      *
-     * @return Response object containing the updated probe object.
+     * @return Response object containing the updated KommentarP object.
      */
     @PUT
     @Path("/{id}")
@@ -154,7 +233,11 @@
     }
 
     /**
-     * Delete an existing object by id.
+     * Delete an existing KommentarP by id.
+     * <p>
+     * The id is appended to the URL as a path parameter.
+     * <p>
+     * Example: http://example.com/pkommentar/{id}
      *
      * @return Response object.
      */
--- a/src/main/java/de/intevation/lada/rest/LoginService.java	Mon Apr 20 17:45:22 2015 +0200
+++ b/src/main/java/de/intevation/lada/rest/LoginService.java	Wed Apr 22 09:18:29 2015 +0200
@@ -1,9 +1,9 @@
 /* Copyright (C) 2015 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;
 
@@ -23,16 +23,55 @@
 import de.intevation.lada.util.rest.Response;
 
 /**
- * This class serves as a login check service
+ * REST service to get login data for the Lada application.
+ * <p>
+ * This service produces data in the application/json media type.
+ * A typical response holds information about the action performed and the data.
+ * <pre>
+ * <code>
+ * {
+ *  "success": [boolean],
+ *  "message": [string],
+ *  "data":{
+ *      "username": [string],
+ *      "servertime": [timestamp],
+ *      "roles": [string]
+ *  },
+ *  "errors": [object],
+ *  "warnings": [object],
+ *  "readonly": [boolean],
+ *  "totalCount": [number]
+ * }
+ * </code>
+ * </pre>
+ *
+ * @author <a href="mailto:rrenkert@intevation.de">Raimund Renkert</a>
  */
 @Path("login")
 @RequestScoped
 public class LoginService {
 
     /**
-     * Get all probe objects.
+     * Get login data.
+     * <pre>
+     * <code>
+     * {
+     *  "success": [boolean],
+     *  "message": [string],
+     *  "data": {
+     *      "username": [string],
+     *      "servertime": [timestamp],
+     *      "roles": [string]
+     *  },
+     *  "errors": [object],
+     *  "warnings": [object],
+     *  "readonly": [boolean],
+     *  "totalCount": [number]
+     * }
+     * </code>
+     * </pre>
      *
-     * @return Response object containing all probe objects.
+     * @return Response object containing login data.
      */
     @GET
     @Path("/")
@@ -46,7 +85,6 @@
         response.put("username", request.getAttribute("lada.user.name"));
         response.put("roles", request.getAttribute("lada.user.roles"));
         response.put("servertime", new Date().getTime());
-        /* This should probably contain the users name and roles. */
         return new Response(true, 200, response);
     }
 }
--- a/src/main/java/de/intevation/lada/rest/MessungService.java	Mon Apr 20 17:45:22 2015 +0200
+++ b/src/main/java/de/intevation/lada/rest/MessungService.java	Wed Apr 22 09:18:29 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;
 
@@ -42,28 +42,78 @@
 import de.intevation.lada.util.rest.RequestMethod;
 import de.intevation.lada.util.rest.Response;
 
+/**
+ * REST service for Messung 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],
+ *      "fertig": [boolean],
+ *      "letzteAenderung": [timestamp],
+ *      "messdauer": [number],
+ *      "messzeitpunkt": [timestamp],
+ *      "mmtId": [string],
+ *      "probeId": [number],
+ *      "owner": [boolean],
+ *      "readonly": [boolean],
+ *      "nebenprobenNr": [string],
+ *      "geplant": [boolean],
+ *      "treeModified": [timestamp],
+ *      "parentModified": [timestamp],
+ *      "messungsIdAlt": [number]
+ *  }],
+ *  "errors": [object],
+ *  "warnings": [object],
+ *  "readonly": [boolean],
+ *  "totalCount": [number]
+ * }
+ * </code>
+ * </pre>
+ *
+ * @author <a href="mailto:rrenkert@intevation.de">Raimund Renkert</a>
+ */
 @Path("messung")
 @RequestScoped
 public class MessungService {
 
-    /* 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 messung objects.
+     * Get all Messung objects.
+     * <p>
+     * The requested objects can be filtered using a URL parameter named
+     * probeId.
+     * <p>
+     * Example: http://example.com/messung?probeId=[ID]
      *
-     * @return Response object containing all messung objects.
+     * @return Response object containing all Messung objects.
      */
     @GET
     @Path("/")
@@ -90,9 +140,13 @@
     }
 
     /**
-     * Get a messung object by id.
+     * Get a Messung object by id.
+     * <p>
+     * The id is appended to the URL as a path parameter.
+     * <p>
+     * Example: http://example.com/messung/{id}
      *
-     * @return Response object containing a single messung.
+     * @return Response object containing a single Messung.
      */
     @GET
     @Path("/{id}")
@@ -108,6 +162,32 @@
             LMessung.class);
     }
 
+    /**
+     * Create a Messung object.
+     * <p>
+     * The new object is embedded in the post data as JSON formatted string.
+     * <p>
+     * <pre>
+     * <code>
+     * {
+     *  "owner": [boolean],
+     *  "probeId": [number],
+     *  "mmtId": [string],
+     *  "nebenprobenNr": [string],
+     *  "messdauer": [number],
+     *  "fertig": [boolean],
+     *  "geplant": [boolean],
+     *  "messungsIdAlt": [string],
+     *  "treeModified": null,
+     *  "parentModified": null,
+     *  "messzeitpunkt": [date],
+     *  "letzteAenderung": [date]
+     * }
+     * </code>
+     * </pre>
+     *
+     * @return A response object containing the created Messung.
+     */
     @POST
     @Path("/")
     @Produces(MediaType.APPLICATION_JSON)
@@ -143,8 +223,29 @@
 
     /**
      * Update an existing messung object.
+     * <p>
+     * The object to update should come as JSON formatted string.
+     * <pre>
+     * <code>
+     * {
+     *  "id": [number],
+     *  "owner": [boolean],
+     *  "probeId": [number],
+     *  "mmtId": [string],
+     *  "nebenprobenNr": [string],
+     *  "messdauer": [number],
+     *  "fertig": [boolean],
+     *  "geplant": [boolean],
+     *  "messungsIdAlt": [number],
+     *  "treeModified": [timestamp],
+     *  "parentModified": [timestamp],
+     *  "messzeitpunkt": [date],
+     *  "letzteAenderung": [date]
+     * }
+     * </code>
+     * </pre>
      *
-     * @return Response object containing the updated probe object.
+     * @return Response object containing the updated Messung object.
      */
     @PUT
     @Path("/{id}")
@@ -177,7 +278,11 @@
     }
 
     /**
-     * Delete an existing messung object by id.
+     * Delete an existing Messung object by id.
+     * <p>
+     * The id is appended to the URL as a path parameter.
+     * <p>
+     * Example: http://example.com/messung/{id}
      *
      * @return Response object.
      */
--- a/src/main/java/de/intevation/lada/rest/MesswertService.java	Mon Apr 20 17:45:22 2015 +0200
+++ b/src/main/java/de/intevation/lada/rest/MesswertService.java	Wed Apr 22 09:18:29 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;
 
@@ -42,32 +42,84 @@
 import de.intevation.lada.util.rest.RequestMethod;
 import de.intevation.lada.util.rest.Response;
 
+/**
+ * REST service for Messwert 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],
+ *      "grenzwertueberschreitung": [boolean],
+ *      "letzteAenderung": [timestamp],
+ *      "mehId": [number],
+ *      "messfehler": [number],
+ *      "messgroesseId": [number],
+ *      "messungsId": [number],
+ *      "messwert": [number],
+ *      "messwertNwg": [string],
+ *      "nwgZuMesswert": [number],
+ *      "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("messwert")
 @RequestScoped
 public class MesswertService {
 
-    /* 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 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 messung objects.
+     * Get all Messwert objects.
+     * <p>
+     * The requested objects can be filtered using a URL parameter named
+     * probeId.
+     * <p>
+     * Example: http://example.com/messwert?messungsId=[ID]
      *
-     * @return Response object containing all messung objects.
+     * @return Response object containing all Messwert objects.
      */
     @GET
     @Path("/")
@@ -95,9 +147,13 @@
     }
 
     /**
-     * Get a messung object by id.
+     * Get a Messwert object by id.
+     * <p>
+     * The id is appended to the URL as a path parameter.
+     * <p>
+     * Example: http://example.com/messwert/{id}
      *
-     * @return Response object containing a single messung.
+     * @return Response object containing a single Messwert.
      */
     @GET
     @Path("/{id}")
@@ -113,6 +169,32 @@
             LMesswert.class);
     }
 
+    /**
+     * Create a Messwert object.
+     * <p>
+     * The new object is embedded in the post data as JSON formatted string.
+     * <p>
+     * <pre>
+     * <code>
+     * {
+     *  "owner": [boolean],
+     *  "messungsId": [number],
+     *  "messgroesseId": [number],
+     *  "messwert": [number],
+     *  "messwertNwg": [string],
+     *  "messfehler": [number],
+     *  "nwgZuMesswert": [number],
+     *  "mehId": [number],
+     *  "grenzwertueberschreitung": [boolean],
+     *  "treeModified": null,
+     *  "parentModified": null,
+     *  "letzteAenderung": [date]
+     * }
+     * </code>
+     * </pre>
+     *
+     * @return A response object containing the created Messwert.
+     */
     @POST
     @Path("/")
     @Produces(MediaType.APPLICATION_JSON)
@@ -137,9 +219,30 @@
     }
 
     /**
-     * Update an existing messung object.
+     * Update an existing Messwert object.
+     * <p>
+     * The object to update should come as JSON formatted string.
+     * <pre>
+     * <code>
+     * {
+     *  "id": [number],
+     *  "owner": [boolean],
+     *  "messungsId": [number],
+     *  "messgroesseId": [number],
+     *  "messwert": [number],
+     *  "messwertNwg": [string],
+     *  "messfehler": [number],
+     *  "nwgZuMesswert": [number],
+     *  "mehId": [number],
+     *  "grenzwertueberschreitung": [boolean],
+     *  "treeModified": [timestamp],
+     *  "parentModified": [timestamp],
+     *  "letzteAenderung": [date]
+     * }
+     * </code>
+     * </pre>
      *
-     * @return Response object containing the updated probe object.
+     * @return Response object containing the updated Messwert object.
      */
     @PUT
     @Path("/{id}")
@@ -172,7 +275,11 @@
     }
 
     /**
-     * Delete an existing messung object by id.
+     * Delete an existing Messwert object by id.
+     * <p>
+     * The id is appended to the URL as a path parameter.
+     * <p>
+     * Example: http://example.com/messwert/{id}
      *
      * @return Response object.
      */
--- a/src/main/java/de/intevation/lada/rest/OrtService.java	Mon Apr 20 17:45:22 2015 +0200
+++ b/src/main/java/de/intevation/lada/rest/OrtService.java	Wed Apr 22 09:18:29 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;
 
@@ -42,32 +42,81 @@
 import de.intevation.lada.util.rest.RequestMethod;
 import de.intevation.lada.util.rest.Response;
 
+/**
+ * REST service for Ort 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],
+ *      "ortsTyp": [string],
+ *      "ortszusatztext": [string],
+ *      "probeId": [number],
+ *      "ort": [number],
+ *      "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("ort")
 @RequestScoped
 public class OrtService {
 
-    /* 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 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 Ort objects.
+     * <p>
+     * The requested objects can be filtered using a URL parameter named
+     * probeId.
+     * <p>
+     * Example: http://example.com/ort?probeId=[ID]
      *
-     * @return Response object containing all messung objects.
+     *
+     * @return Response object containing all Ort objects.
      */
     @GET
     @Path("/")
@@ -95,9 +144,13 @@
     }
 
     /**
-     * Get an object by id.
+     * Get a Ort object by id.
+     * <p>
+     * The id is appended to the URL as a path parameter.
+     * <p>
+     * Example: http://example.com/ort/{id}
      *
-     * @return Response object containing a single messung.
+     * @return Response object containing a single Ort.
      */
     @GET
     @Path("/{id}")
@@ -113,6 +166,28 @@
             LOrt.class);
     }
 
+    /**
+     * Create a new Ort object.
+     * <p>
+     * The new object is embedded in the post data as JSON formatted string.
+     * <p>
+     * <pre>
+     * <code>
+     * {
+     *  "owner": [boolean],
+     *  "ort": [number],
+     *  "probeId": [number],
+     *  "ortsTyp": [string],
+     *  "ortszusatztext": [string],
+     *  "treeModified": null,
+     *  "parentModified": null,
+     *  "letzteAenderung": [date]
+     * }
+     * </code>
+     * </pre>
+     *
+     * @return A response object containing the created Ort.
+     */
     @POST
     @Path("/")
     @Produces(MediaType.APPLICATION_JSON)
@@ -136,9 +211,26 @@
     }
 
     /**
-     * Update an existing object.
+     * Update an existing Ort object.
+     * <p>
+     * The object to update should come as JSON formatted string.
+     * <pre>
+     * <code>
+     * {
+     *  "id": [number],
+     *  "owner": [boolean],
+     *  "ort": [number],
+     *  "probeId": [number],
+     *  "ortsTyp": [string],
+     *  "ortszusatztext": [string],
+     *  "treeModified": [timestamp],
+     *  "parentModified": [timestamp],
+     *  "letzteAenderung": [date]
+     * }
+     * </code>
+     * </pre>
      *
-     * @return Response object containing the updated probe object.
+     * @return Response object containing the updated Ort object.
      */
     @PUT
     @Path("/{id}")
@@ -170,7 +262,11 @@
     }
 
     /**
-     * Delete an existing object by id.
+     * Delete an existing Ort object by id.
+     * <p>
+     * The id is appended to the URL as a path parameter.
+     * <p>
+     * Example: http://example.com/orortt/{id}
      *
      * @return Response object.
      */
This site is hosted by Intevation GmbH (Datenschutzerklärung und Impressum | Privacy Policy and Imprint)