Changeset 6024

Timestamp:

02/23/15 16:28:19 (9 years ago)

Author:

olhsha@mpi.nl

Message:

Javadocs are updated for PrincipalResource? and AnnotationResource?, + very minor correction for retrieval of annotations for notebooks.

Location:

DASISH/t5.6/backend/annotator-backend/trunk/annotator-backend/src/main/java/eu/dasish/annotation/backend/rest

Files:

• AnnotationResource.java (modified) (2 diffs)
• PrincipalResource.java (modified) (12 diffs)

DASISH/t5.6/backend/annotator-backend/trunk/annotator-backend/src/main/java/eu/dasish/annotation/backend/rest/AnnotationResource.java

@@ -72 +72 @@
    /**
     * 
-    * @param httpServletResponse a {@link HttpServletResponse} object, to be set to "this" object and to be used to send error messages.
+    * @param httpServletResponse a {@link HttpServletResponse} object, setting us used in unit tests.
     */
     public void setHttpServletResponse(HttpServletResponse httpServletResponse) {
@@ -80 +80 @@
     /**
      * 
-     * @param httpServletRequest a {@link HttpServletRequest} object, to be set to "this" object and to be used in the unit tests.
+     * @param httpServletRequest a {@link HttpServletRequest} object, setting is used in the unit tests.
      */
     public void setHttpServletRequest(HttpServletRequest httpServletRequest) {

DASISH/t5.6/backend/annotator-backend/trunk/annotator-backend/src/main/java/eu/dasish/annotation/backend/rest/PrincipalResource.java

@@ -63 +63 @@
     int shaStrength = 512;
 
+    
+    /**
+     * 
+     * @param request a {@link HttpServletRequest} object; set object is used in unit tests.
+     */
     public void setHttpRequest(HttpServletRequest request) {
         this.httpServletRequest = request;
@@ -70 +75 @@
     }
 
+    /**
+     * 
+     * @param externalIdentifier the external UUID of a principal.
+     * @return the {@link Principal} element representing the principal object with the "externalIdentifier".
+     * @throws IOException is sending the error fails.
+     */
     @GET
     @Produces(MediaType.TEXT_XML)
@@ -98 +109 @@
     }
 
-    /////////////////////////////////
+    /**
+     * 
+     * @return a message containing the fill name and the e-mail of the admin.
+     * @throws IOException if sending the error in the call of "this.getPrincipalID()".
+     */
     @GET
     @Produces(MediaType.TEXT_PLAIN)
@@ -111 +126 @@
     }
 
-    /////////////////////////////////////////
+   /**
+    * 
+    * @param email a string representing the e-mail of a principal.
+    * @return a {@link Principal} representing the principal with the "email", 
+    * if such a principal is found; otherwise "SC_NOT_FOUND" error is sent.
+    * @throws IOException if sending the error fails.
+    */
     @GET
     @Produces(MediaType.TEXT_XML)
@@ -139 +160 @@
     }
 
-    ////////////////////////////////////////
+ 
+    /**
+     * 
+     * @param externalIdentifier the external UUID of a principal.
+     * @return a {@link CurrentPrincipalInfo} element containing "true" if the principal 
+     * with externalIdentifier is logged-in in this session; 
+     * withe the current implementation does not make that much sense for me,
+     * because the logged-in user knows his/her externalIDdentifier and knows that the other UUIDs
+     * will be "not logged in", and therefore "false" is expected,
+     * @throws IOException if sending the error fails.
+     */
     @GET
     @Produces(MediaType.TEXT_XML)
@@ -223 +254 @@
 //
 //    }
-    /////////////////////////////////////
+    /**
+     * 
+     * @param name the name of the principal to be registered as a basic-authentication user.
+     * @param remoteId the  remote id of the principal to be registered.
+     * @param password the password selected by the principal to be registered.
+     * @param email an email of the principal to be registered.
+     * @return a @Link Principal} element representing the just registered principal.
+     * @throws IOException if sending the error fails.
+     */
     @POST
     @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
@@ -267 +306 @@
     }
 
-    ///////////////////////////////////////////////
+    /**
+     * 
+     * @param name the name of the principal to be registered
+     * @param remoteId the remote shibboleth id.
+     * @param email the email.
+     * @return a @Link Principal} element representing the just registered principal.
+     * @throws IOException if sending the error fails.
+     */
     @POST
     @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
@@ -304 +350 @@
     }
 
-    ///////////////////////////////////////////////////
+    /**
+     * It is of a good convenience method limiting proliferation of user profiles, however
+     * the method is currently not used till security issues will be discussed with the LAT 
+     * system administrators.
+     * @param remoteId a shibboleth remote id, which will be set as a basic-authentication remote id as well.
+     * @param password a shibboleth password which will be set as a basic-authentication password.
+     * @return a message about amount of records; which must be 2 if everything goes well: 
+     * 1 record for the principal, another for the authorities table
+     * @throws IOException if sending the error fails.
+     */
     @POST
     @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
@@ -320 +375 @@
         }
     }
-
+    
+    /**
+     * 
+     * @param principal a {@link Principal} object representing new information (name, e-mail) about the principal 
+     * with the eternal UUID given in the object,
+     * @return a @Link Principal} element representing the just updated principal.
+     * @throws IOException if sending the error message fails.
+     */
     @PUT
     @Consumes(MediaType.APPLICATION_XML)
@@ -351 +413 @@
     /////////////////////////////////
 
-    // logged in user can update his/her account
-    // or account can be updated by the admin in a separate request, see above
+    /**
+     * 
+     * @param name a new full name.
+     * @param email a new email
+     * @return a @Link Principal} element representing the just updated principal.
+     * @throws IOException if sending the error fails.
+     * @throws NotInDataBaseException if the in-logged principal is not found in the database
+     * or updated fails.
+     */
     @POST
     @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
@@ -389 +458 @@
     }
 
-    //////////////////////////////////////
+   /**
+    * 
+    * @param externalId the external UUID of a principal.
+    * @param accountType an account type: "user", "developer", "admin".
+    * @return a message telling if and how the account is updated; this action can be performed only by admin.
+    * @throws IOException 
+    */
     @PUT
     @Produces(MediaType.TEXT_PLAIN)
@@ -421 +496 @@
     }
 
+    /**
+     * 
+     * @param externalIdentifier the external UUID of a principal to be deleted.
+     * @return a message informing if deletion has been successful; see "error" messages if deletion 
+     * has not taken place.
+     * @throws IOException if sending error messages fails.
+     */
     @DELETE
     @Path("{principalId}")