Changeset 6009 for DASISH


Ignore:
Timestamp:
02/23/15 10:38:31 (9 years ago)
Author:
olhsha@mpi.nl
Message:

Javadoc are updated for AnnotationResource?.java

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r5850 r6009  
    7070    final private String[] admissibleMatchModes = {"exact", "starts_with", "ends_with", "contains"};
    7171
     72   /**
     73    *
     74    * @param httpServletResponse a {@link HttpServletResponse} object, to be set to "this" object and to be used to send error messages.
     75    */
    7276    public void setHttpServletResponse(HttpServletResponse httpServletResponse) {
    7377        this.httpServletResponse = httpServletResponse;
    7478    }
    75 
     79   
     80    /**
     81     *
     82     * @param httpServletRequest a {@link HttpServletRequest} object, to be set to "this" object and to be used in the unit tests.
     83     */
    7684    public void setHttpServletRequest(HttpServletRequest httpServletRequest) {
    7785        this.httpServletRequest = httpServletRequest;
    7886    }
    7987
     88    /**
     89     *
     90     * @param providers a {@link Providers} object, to be set to "this" object and to be used to force
     91     * validation of the input/output xml files w.r.t. the dasish schema.
     92     */
    8093    public void setProviders(Providers providers) {
    8194        this.providers = providers;
    … …  
    8699   
    87100
     101    /**
     102     *
     103     * @param externalIdentifier the string representing the UUID of an annotation.
     104     * @return the xml-element representing the annotation with "externalIdentifier" built up
     105     * from the "annotation" table and the corresponding junction tables.
     106     * @throws IOException if sending the error fails.
     107     */
    88108    @GET
    89109    @Produces(MediaType.TEXT_XML)
    … …  
    116136    }
    117137
    118     //////////////////////////////////////////////////
     138    /**
     139     *
     140     * @param externalIdentifier the string representing the UUID of an annotation.
     141     * @return the xml element representing the list of h-references of the annotation with "externalIdentifier".
     142     * @throws IOException if sending the error fails.
     143     */
    119144    @GET
    120145    @Produces(MediaType.TEXT_XML)
    … …  
    146171        }
    147172    }
    148 // TODO Unit test
    149 
     173
     174    /**
     175     *
     176     * @param link the link representing one of the target sources of the annotation.
     177     * @param matchMode the relation of the actual target-source link to "link" parameter: "exact", "starts_with", "ends_with", "contains"
     178     * @param text the text fragment that must be present in the annotation body.
     179     * @param access the access mode of the logged in user to the requested annotations.
     180     * @param namespace not implemented.
     181     * @param ownerExternalId the external UUID of the owner of requested annotations.
     182     * @param after the minimal creation/update date of the annotation.
     183     * @param before the maximal creation/update date of the annotation.
     184     * @return the xml-element representing the list of {@link AnnotationInfo} objects representing
     185     * the annotations satisfying the requirements defined by the parameters.
     186     * @throws IOException if sending the error fails.
     187     */
    150188    @GET
    151189    @Produces(MediaType.TEXT_XML)
    … …  
    197235    }
    198236   
     237    /**
     238     *
     239     * @param n # of requested annotations (to which logged in principal has "read" access.
     240     * @return the external UUIDs of some n annotations to which the logged in principal has "read" access,
     241     * if the principal has "admin" or "developer" type of account.
     242     * @throws IOException if sending the error fails.
     243     * @throws NotInDataBaseException if getting annotation fails.
     244     */
    199245    @GET
    200246    @Produces(MediaType.TEXT_PLAIN)
    … …  
    234280   
    235281   
    236 // TODO Unit test   
    237 
     282
     283   /**
     284    *
     285    * @param externalIdentifier the external UUID of an annotation.
     286    * @return the xml-element representing the list of permissions, i.e. pairs (principalId, accessMode),
     287    * built upon the table "annotations_principals_accesses".
     288    * @throws IOException if sending the error fails.
     289    */
    238290    @GET
    239291    @Produces(MediaType.TEXT_XML)
    … …  
    265317        }
    266318    }
    267 ///////////////////////////////////////////////////////
    268 
     319
     320    /**
     321     *
     322     * @param externalIdentifier the external UUID of the annotation to be deleted.
     323     * @return the message if the annotation is deleted or not.
     324     * @throws IOException if sending the error fails.
     325     */
    269326    @DELETE
    270327    @Path("{annotationid: " + BackendConstants.regExpIdentifier + "}")
    … …  
    295352    }
    296353
    297 ///////////////////////////////////////////////////////
     354    /**
     355     *
     356     * @param annotation an {@link Annotation} object,
     357     * @return the {@link ResponseBody} element that contains the xml element representing
     358     * the fresh annotation (with its generated by the method external UUID), and the list
     359     * of action-elements representing the actions the client should care for,
     360     * e.g. add a cached representation for a certain target.
     361     * @throws IOException if sending the error fails.
     362     */
    298363    @POST
    299364    @Consumes(MediaType.APPLICATION_XML)
    … …  
    331396    }
    332397
    333 ///////////////////////////////////////////////////////
    334 // TODO: unit test
     398   /**
     399    *
     400    * @param externalId the external UUID of the annotation to be updated.
     401    * @param annotation the {@link Annotation} object that represent the new annotation that should replace the annotation with "externalId".
     402    * @return the {@link ResponseBody} element that contains the xml element representing
     403     * the updated annotation, and the list of action-elements representing the actions the client should care for,
     404     * e.g. add a cached representation for a certain target.
     405     * @throws IOException if sending the error fails.
     406    */
    335407    @PUT
    336408    @Consumes(MediaType.APPLICATION_XML)
    … …  
    365437    }
    366438
    367     ///////////////////////////////////////////////////////////
     439   
    368440    private class UpdateAnnotation implements ILambda<Map, ResponseBody> {
    369441
    … …  
    377449        }
    378450    }
    379     ///////////////////////////////////////////////////////////////////////////////
    380 
     451   
     452   /**
     453    *
     454    * @param externalIdentifier the external UUID of the annotation whose body must be updated.
     455    * @param annotationBody an {@link AnnotationBody} object representation the new body of the annotation,
     456    * which should replace the old body.
     457    * @return the {@link ResponseBody} element that contains the xml element representing
     458    * the updated annotation, and the list of action-elements representing the actions the client should care for.
     459    * @throws IOException if sending the error fails. 
     460    */
    381461    @PUT
    382462    @Consumes(MediaType.APPLICATION_XML)
    … …  
    415495    }
    416496
     497    /**
     498     *
     499     * @param externalIdentifier the external UUID of the annotation whose headline is to be updated.
     500     * @param newHeadline the string representing the new headline.
     501     * @return the {@link ResponseBody} element that contains the xml element representing
     502     * the updated annotation, and the list of action-elements representing the actions the client should care for.
     503     * @throws IOException if sending the error fails. 
     504     */
    417505    @PUT
    418506    @Consumes(MediaType.TEXT_PLAIN)
    … …  
    451539    }
    452540
    453     //////////////////////////////////////////
    454     //////////////////////////////////////////////
     541   /**
     542    *
     543    * @param annotationDatabaseId the internal database Id of the annotation to be updated.
     544    * @param annotationHeadline the annotation's headline.
     545    * @param access the new value for the public attribute of the annotation.
     546    * @return the message if the database has been updated and how many rows have been updated;
     547    * if "annotationDatabaseId" == null or empty then all the annotations with "annotationHeadline"
     548    * must be updated,
     549    * @throws IOException if sending the error fails.
     550    */
    455551    @POST
    456552    @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
    … …  
    513609    }
    514610
    515     ////////////////////////////////////////////////////
     611    /**
     612     *
     613     * @param annotationExternalId the external UUID of an annotation.
     614     * @param principalExternalId the external UUID of a principal whose access mode to the annotation must be updated.
     615     * @param access the access mode that should assigned to the principal.
     616     * @return the message about the amount of updated rows.
     617     * @throws IOException if sending the error fails.
     618     */
    516619    @PUT
    517620    @Consumes(MediaType.APPLICATION_XML)
    … …  
    531634    }
    532635
    533     //////////////////////////////////////////////
     636    /**
     637     * One of 3 principal-related parameters must be non-null and non-empty; one of 2 annotation related parameters must be non-null and non-empty.
     638     * @param remoteID the remote ID of the principal whose access mode to the annotation (see below) must be updated.
     639     * @param fullName the full name of the principal whose access mode to the annotation must be updated.
     640     * @param principalDatabaseId the internal database identifier of the principal whose access mode to the annotation must be updated.
     641     * @param annotationDatabaseId the internal database id of the annotation for which the access mode must be updated.
     642     * @param annotationHeadline the headline of the annotation for which the access mode must be updated.
     643     * @param access the new access mode.
     644     * @return the message explaining how many rows have been updated.
     645     * @throws IOException  if sending error message fails.
     646     */
    534647    @POST
    535648    @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
    … …  
    613726        }
    614727    }
    615     ///////////////////////////////////////////
    616 
     728   
     729   
     730    /**
     731     *
     732     * @param annotationExternalId the external UUID of an annotation.
     733     * @param permissions a {@link PermissionList} object representing a list of pairs (principal UUID, access mode) of the
     734     * new list of permissions for the annotation.
     735     * @return the {@link ResponseBody} element that contains the xml element representing
     736     * the updated annotation, and the list of action-elements representing the actions the client should care for,
     737     * e.g. add the e-mail of a certain principal.
     738     * @throws IOException if sending the error fails.
     739     */
    617740    @PUT
    618741    @Consumes(MediaType.APPLICATION_XML)
    … …  
    652775    }
    653776
    654     ////////////////////////////////////////////////////////////
     777    /**
     778     *
     779     * @param annotationId the external UUID of the annotation.
     780     * @param principalId the external UUID of a principal whose access mode must be deleted.
     781     * @return the amount of updated/removed rows in the database.
     782     * @throws IOException if sending the error fails.
     783     */
    655784    @DELETE
    656785    @Produces(MediaType.TEXT_PLAIN)
Note: See TracChangeset for help on using the changeset viewer.