Ignore:
Timestamp:
02/24/15 16:08:22 (9 years ago)
Author:
olhsha@mpi.nl
Message:

Javadoc annotations are revised for "eu.daish.annotation.backend" and "eu.daish.annotation.backend.dao" packages.

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r5998 r6042  
    2828
    2929/**
    30  * Created on : Jun 27, 2013, 10:34:13 AM
    31  *
    32  * @author Peter Withers <peter.withers@mpi.nl>
     30 * @author olhsha@mpi.nl
    3331 */
    3432
    … …  
    5755     *
    5856     * @param annotationID the internal (database) identifier of an annotation.
    59      * @return the {@link Annotation} object whose fields are filled in partially,
     57     * @return the {@link Annotation} object whose fields are filled partially,
    6058     * only with the information accessible from the table "annotation".
    61      * Constructing a complete {@link Annotation} object is done in the implementation of {@link DBDispatchter}.)
     59     * Constructing a complete {@link Annotation} object is done in the implementation of {@link DBDispatcher}.
    6260     */
    6361    public Annotation getAnnotationWithoutTargetsAndPemissionList(Number annotationID);
    … …  
    6664     *
    6765     * @param ownerID the owner of annotations we search for; if null then the owner may be any.
    68      * @param text the text fragment which must occur in an annotation-body; if null, the now requirements on the annotation body.
     66     * @param text the text fragment which must occur in an annotation-body; if null, then no requirements on the annotation body.
    6967     * @param namespace (search on the parameter is not implemented).
    7068     * @param after the earliest time of creating/last-update of annotations; if null then search "from the beginning of time".
    7169     * @param before the latest time of creating/last-update of annotations; if null then search "till now".
    72      * @return the list of annotation internal database identifiers that satisfy the criteria defined by the parameters.
     70     * @return the list of the internal database identifiers of the annotations that satisfy the criteria defined by the parameters.
    7371     */
    7472    public List<Number> getFilteredAnnotationIDs(Number ownerID, String text, String namespace, String after, String before);
    … …  
    7674    /**
    7775     *
    78      * @param principalID the internal database ID of a principal (user or, in general, a group).
    79      * @param acess access level (none, read, write, all).
    80      * @return the list of internal (database) annotation identifiers to which "principalID" has access at least "acess".
    81      * For instance, on access==write, the method should output id-s of the annotations to which user has "write" (update bodies),
    82      * or "all" access, according to the junction table "annotations-principals-acesses".
    83      */
    84     public List<Number> getAnnotationIDsPermissionAtLeast(Number principalID, Access acess);
    85    
    86     /**
    87      *
    88      * @param access the value of public assess of an annotation.
    89      * @return The list of internal (database identifiers to which public has at least "access" access;
     76     * @param principalID the internal database ID of a principal (a user or, in general, a group).
     77     * @param access an {@link Access} object representing an access level (none, read, write, all).
     78     * @return the list of the internal (database) identifiers of annotations to which "principalID" has access at least "acess".
     79     * For instance, if access' value is Access.WRITE, the method should output id-s of the annotations to which user has "write" (update bodies),
     80     * or "all" access, according to the junction table "annotations-principals-accesses".
     81     */
     82    public List<Number> getAnnotationIDsPermissionAtLeast(Number principalID, Access access);
     83   
     84    /**
     85     *
     86     * @param access an {@link Access} object representing  the public assess level of an annotation.
     87     * @return The list of the internal database identifiers of annotations for which "public" attribute has at least "access" access;
    9088     * for instance on "write" the method should output annotations
    9189     * whose "public" value is "write" or "all".
    … …  
    9795    /**
    9896     *
    99      * @return the list of the internal (database) annotation IDs of all the annotations;
    100      * used only by the developers and the admin in the debugging mode to access all the existing annotations.
     97     * @return the list of the internal database identifiers of all the annotations, ordered by last-update, with the latest on top;
     98     * used only by developers and the admin in the debugging service to access all the existing annotations.
    10199     */
    102100    public List<Number> getAllAnnotationIDs();
    … …  
    104102    /**
    105103     *
    106      * @param annotationIDs the list of internal annotationIDs.
     104     * @param annotationIDs the list of internal database annotation identifiers.
    107105     * @param offset the offset parameter for SELECT SQL request.
    108106     * @param limit the limit parameter for SELECT SQL request.
    109      * @param orderedBy criterion of ordering according to the SQL syntax (by some field).
     107     * @param orderedBy a criterion of ordering according to the SQL syntax (by some field).
    110108     * @param desc direction of ordering according to the SQL syntax.
    111109     * @return the SELECT response on the given parameters: i.e. the list of annotationID's starting from offset and to limit,
    … …  
    115113   
    116114     /**
    117      * @param annotationIDs
    118      * @return annotationInfo for the annotation with the internal annotationID:
     115     * @param annotationIDs the internal database identifier of an annotation.
     116     * @return an {@link AnnotationInfo} object for the annotation with the internal annotationID:
    119117     * i.e. the information which you can take only from the "annotation" table
    120      * and not the junction tables connecting the annotations to permissions and targets.
     118     * and not from the junction tables connecting the annotations to permissions and targets.
    121119     *
    122120     */
    … …  
    125123    /**
    126124     *
    127      * @param annotationIDs
    128      * @return list of target references where the i-th reference is constructed from the external
     125     * @param annotationIDs the list of the internal database annotation identifiers.
     126     * @return the list of target h-references where the i-th reference is constructed from the external
    129127     * identifier of the annotation with the i-th internal identifier from the list.
    130128     */
    … …  
    134132    /**
    135133     *
    136      * @param annotationID
     134     * @param annotationID the internal database identifier of an annotation.
    137135     * @return the internal database ID of the owner of the annotation.
    138136     */
    … …  
    141139    /**
    142140     *
    143      * @param annotationID
    144      * @param principalID
     141     * @param annotationID the internal database identifier of an annotation.
     142     * @param principalID the internal database identifier of a principal.
    145143     * @return access of the principalID w.r.t. annotationID, or Access.NONE if the access is not given.
    146144     */
    … …  
    149147    /**
    150148     *
    151      * @param annotationID
    152      * @param principalID
     149     * @param annotationID the internal database identifier of an annotation.
     150     * @param principalID the internal database identifier of a principal.
    153151     * @return true if there is triple (annotationID, principalID, access) for some access
    154152     * in the corresponding junction table; false otherwise.
    … …  
    158156    /**
    159157     *
    160      * @param annotationID
     158     * @param annotationID the internal database identifier of an annotation.
    161159     * @return the value of the "public" field for annotationID; can be one of ACCESS values.
    162160     */
    … …  
    166164    /**
    167165     *
    168      * @param notebookID
    169      * @return the list of annotationIDs of the annotations from the notebook with notebookID.
     166     * @param notebookID the internal database identifier of a notebook.
     167     * @return the list of internal database identifiers of the annotations from the notebook with notebookID.
    170168     */
    171169    public List<Number> getAnnotations(Number notebookID);
    … …  
    173171    /**
    174172     *
    175      * @param targetID
    176      * @return true if at least one annotation refers to this target; false otherwise.
     173     * @param targetID the internal database identifier of a target.
     174     * @return true if at least one annotation refers to the target with targetID; false otherwise.
    177175     */
    178176    public boolean targetIsInUse(Number targetID);
    … …  
    184182    /**
    185183     *
    186      * @param annotationID
    187      * @param targetID
    188      * @return # updated rows in the joint table "annotations_targets".
     184     * @param annotationID the internal database identifier of an annotation.
     185     * @param targetID the internal database identifier of a target.
     186     * @return # of updated rows in the junction table "annotations_targets".
    189187     * Connects the annotation to its target by adding the pair (annotationID, targetID)
    190188     * to the junction table.
    … …  
    195193    /**
    196194     *
    197      * @param annotationID
    198      * @param principalID
    199      * @param access
    200      * @return # rows added to the table "annotations_principals_access".
     195     * @param annotationID the internal database identifier of an annotation.
     196     * @param principalID the internal database identifier of a principal.
     197     * @param access the {@link Access} object representing an access level.
     198     * @return # of rows added to the table "annotations_principals_accesses".
    201199     * Sets the "access" for the "principalID" w.r.t. the annotation with "annotationID".
    202200     */
    … …  
    207205    /**
    208206     *
    209      * @param annotationthe the object to be added to the table "annotation".
    210      * @param newOwnerID the ownerID,
     207     * @param annotation the object to be added to the table "annotation".
     208     * @param newOwnerID the ownerID.
    211209     * @return the internal ID of the added annotation, if it is added, or throws NotInDataBaseException otherwise.
    212      * @throws NotInDataBaseException if the request on the internal database annotation ID for the added annotation throws this exception.
     210     * @throws NotInDataBaseException if the request for the internal database annotation ID for the added annotation throws this exception.
    213211     */
    214212    public Number addAnnotation(Annotation annotation, Number newOwnerID)  throws NotInDataBaseException;
    … …  
    222220    * @param text the new body text.
    223221    * @param mimeType the new mime type.
    224     * @param isXml if the new body is a text body or an xml.
     222    * @param isXml true if the new body is an xml, and false if it is a text.
    225223    * @return # of updated rows in the table "annotation".
    226224    */
    … …  
    245243     *
    246244     * @param annotation the new annotation (including targets and permissions).
    247      * @param annotationID the ID of the annotation to be updated.
    248      * @param ownerID the Id of the new owner.
     245     * @param annotationID the internal database ID of the annotation to be updated.
     246     * @param ownerID the internal database Id of the new owner.
    249247     * @return # of updated rows in "annotation" table after this FULL updating the annotation. Should return 1 if update  happens.
    250248     */
    … …  
    254252     /**
    255253     *
    256      * @param annotationID
    257      * @param principalID
    258      * @param access
    259      * @return # rows updated to the table "annotations_principals_access".
     254     * @param annotationID the internal database identifier of an annotation.
     255     * @param principalID the internal database identifier of a principal.
     256     * @param access a {@link Access} object representing an access level.
     257     * @return # of rows updated in the table "annotations_principals_accesses".
    260258     * Sets the "access" for the "principalID" w.r.t. the annotation with "annotationID".
    261259     */
    … …  
    266264     * @param annotationID the internal database ID of the annotation to be updated.
    267265     * @param access access level.
    268      * @return # of updated rows in "annotation". should be "1" if updated and "0" otherwise.
     266     * @return # of updated rows in "annotation". Should be "1" if updated and "0" otherwise.
    269267     */
    270268    public int updatePublicAccess(Number annotationID, Access access);
    … …  
    277275    /**
    278276     *
    279      * @param annotationId
    280      * @return # rows in the table "annotation". It should be "1" if the annotation with "annotationID" is successfully deleted, and "0" otherwise.
    281      */
    282    
    283    
    284    
    285     public int deleteAnnotation(Number annotationId);
    286    
    287     /**
    288      *
    289      * @param annotationId
    290      * @return # removed rows in the table "annotations_target_Targets".
     277     * @param annotationID the internal database identifier of an annotation.
     278     * @return # of deleted rows in the table "annotation". It should be "1" if the annotation with "annotationID" is successfully deleted, and "0" otherwise.
     279     */
     280   
     281   
     282   
     283    public int deleteAnnotation(Number annotationID);
     284   
     285    /**
     286     *
     287     * @param annotationID the internal database identifier of an annotation.
     288     * @return # of removed rows in the table "annotations_targets".
    291289     */
    292290   
    … …  
    296294   /**
    297295    *
    298     * @param annotationID
    299     * @return # removed rows in the table "annotations_principals_access".
     296    * @param annotationID the internal database identifier of an annotation.
     297    * @return # of removed rows in the table "annotations_principals_accesses".
    300298    */
    301299    public int deletePermissions(Number annotationID);
    … …  
    303301    /**
    304302     *
    305      * @param annotationID
    306      * @param principalID
    307      * @return # removed rows in the table "annotations_principals_access".
     303     * @param annotationID the internal database identifier of an annotation.
     304     * @param principalID the internal database identifier of a principal.
     305     * @return # removed rows in the table "annotations_principals_accesses".
    308306     * Should be "1" is removed and "0" otherwise.
    309307     */
    … …  
    312310    /**
    313311     *
    314      * @param annotationID
    315      * @return # removed rows in the table "notebookds_annotations".
     312     * @param annotationID the internal database identifier of an annotation.
     313     * @return # of removed rows in the table "notebookds_annotations".
    316314     */
    317315    public int deleteAnnotationFromAllNotebooks(Number annotationID);
    … …  
    323321    /**
    324322     *
    325      * @param annotationBody
    326      * @return two string components of the annotationBody: the text/xml content and the mime type.
     323     * @param annotationBody a {@link AnnotationBody} object.
     324     * @return two string components of the annotationBody: the text or xml content, and the mime type.
    327325     */
    328326    public String[] retrieveBodyComponents(AnnotationBody annotationBody);
Note: See TracChangeset for help on using the changeset viewer.