Changeset 5989 for DASISH


Ignore:
Timestamp:
02/17/15 17:38:30 (9 years ago)
Author:
olhsha@mpi.nl
Message:

Javadoc are updated for the interface.

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

    r5838 r5989  
    4141     */
    4242   
     43    /**
     44     *
     45     * @param headline the headline of an annotation.
     46     * @return the list of uuid-s of the annotations with this headline; may be empty.
     47     */
    4348    public List<UUID> getExternalIdFromHeadline(String headline);
    4449   
     50    /**
     51     *
     52     * @param headline the headline of an annotation.
     53     * @return the list of internal (database) identifiers of the annotations with this headline; may be empty.
     54     */
    4555    public List<Number>  getInternalIDsFromHeadline(String headline);
    4656    /**
    4757     *
    48      * @param annotationID
    49      * @return the pair (annotation, owner_id) with empty list of Targets.
    50      *
    51      * (Constructing a complete Annotation object using  "getAnnotationWithoutTargets" and "retrieveTargetIDs" is done in "DaoDispatchter".)
    52      *
     58     * @param annotationID the internal (database) identifier of an annotation.
     59     * @return the {@link Annotation} object whose fields are filled in partially,
     60     * only with the information accessible from the table "annotation".
     61     * Constructing a complete {@link Annotation} object is done in the implementation of {@link DBDispatchter}.)
    5362     */
    5463    public Annotation getAnnotationWithoutTargetsAndPemissionList(Number annotationID);
    5564   
    56      
     65    /**
     66     *
     67     * @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.
     69     * @param namespace (search on the parameter is not implemented).
     70     * @param after the earliest time of creating/last-update of annotations; if null then search "from the beginning of time".
     71     * @param before the latest time of creating/last-update of annotations; if null then search "till now".
     72     * @return
     73     */
    5774    public List<Number> getFilteredAnnotationIDs(Number ownerID, String text, String namespace, String after, String before);
    5875     
     76    /**
     77     *
     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;
     90     * for instance on "write" the method should output annotations
     91     * whose "public" value is "write" or "all".
     92     */
     93    public List<Number> getAnnotationIDsPublicAtLeast(Access access);
     94   
     95   
    5996 
    60     public List<Number> getAnnotationIDsPermissionAtLeast(Number principalID, Access acess);
    61    
    62    
    63     public List<Number> getAnnotationIDsPublicAtLeast(Access access);
    64    
    65    
    66     /*
    67      * Use inly in the debugging mode to acces all the existing annotations.
     97    /**
     98     *
     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.
    68101     */
    69102    public List<Number> getAllAnnotationIDs();
    70103   
     104    /**
     105     *
     106     * @param annotationIDs the list of internal annotationIDs.
     107     * @param offset the offset parameter for SELECT SQL request.
     108     * @param limit the limit parameter for SELECT SQL request.
     109     * @param orderedBy criterion of ordering according to the SQL syntax (by some field).
     110     * @param desc direction of ordering according to the SQL syntax.
     111     * @return the SELECT response on the given parameters: i.e. the list of annotationID's starting from offset and to limit,
     112     * if the database rows are ordered according to "orderedBy" and "desc".
     113     */
    71114    public List<Number> sublistOrderedAnnotationIDs(List<Number> annotationIDs, int offset, int limit, String orderedBy, String desc);
    72115   
    73        /**
    74      * unit test is missing
     116     /**
    75117     * @param annotationIDs
    76      * @return annotationInfo  for the annotation with the internal annotationID.
     118     * @return annotationInfo for the annotation with the internal annotationID:
     119     * 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.
    77121     *
    78122     */
    … …  
    82126     *
    83127     * @param annotationIDs
    84      * @return list of reTarget references where an i-th reference is constructed from the external identifier of the annotation with the i-th internal identifier from the list.
     128     * @return list of target references where the i-th reference is constructed from the external
     129     * identifier of the annotation with the i-th internal identifier from the list.
    85130     */
    86131    public List<String> getAnnotationREFs(List<Number> annotationIDs);
    87132   
    88133 
    89    
     134    /**
     135     *
     136     * @param annotationID
     137     * @return the internal database ID of the owner of the annotation.
     138     */
    90139    public Number  getOwner(Number annotationID);
    91140   
    … …  
    94143     * @param annotationID
    95144     * @param principalID
    96      * @return access of the principalID w.r.t. annotationID, or null if the access is not given
     145     * @return access of the principalID w.r.t. annotationID, or Access.NONE if the access is not given.
    97146     */
    98147    public Access  getAccess(Number annotationID, Number principalID);
    99148   
     149    /**
     150     *
     151     * @param annotationID
     152     * @param principalID
     153     * @return true if there is triple (annotationID, principalID, access) for some access
     154     * in the corresponding junction table; false otherwise.
     155     */
    100156    public boolean  hasExplicitAccess(Number annotationID, Number principalID);
    101157   
    102    
     158    /**
     159     *
     160     * @param annotationID
     161     * @return the value of the "public" field for annotationID; can be one of ACCESS values.
     162     */
    103163    public Access getPublicAttribute(Number annotationID);
    104164   
    105165   
    106    
     166    /**
     167     *
     168     * @param notebookID
     169     * @return the list of annotationIDs of the annotations from the notebook with notebookID.
     170     */
    107171    public List<Number> getAnnotations(Number notebookID);
    108172   
    109    
     173    /**
     174     *
     175     * @param targetID
     176     * @return true if at least one annotation refers to this target; false otherwise.
     177     */
    110178    public boolean targetIsInUse(Number targetID);
    111     /**
    112      *
    113      * @param annotationID
    114      * @return true if "annotationID" is mentioned in at least one of the joint tables:
    115      * "annotations_targets", "annotations_principals_accesss", "notebook_annotations".
    116      * Otherwise return "false".
    117      */
    118     //public boolean annotationIsInUse(Number annotationID);
    119    
     179 
    120180    /**
    121181     * ADDERS
    … …  
    126186     * @param annotationID
    127187     * @param targetID
    128      * @return # updated rows in the joint table "annotations_target_Targets".
    129      * @throws SQLException
    130      * Connects the annotation to its target Target by adding the pair (annotationID, TargetID) to the joint table.
     188     * @return # updated rows in the joint table "annotations_targets".
     189     * Connects the annotation to its target by adding the pair (annotationID, targetID)
     190     * to the junction table.
    131191     */
    132192    public int addAnnotationTarget(Number annotationID, Number targetID);
    … …  
    138198     * @param principalID
    139199     * @param access
    140      * @return # rows added to the table "annotations_principals_accesss"
     200     * @return # rows added to the table "annotations_principals_access".
    141201     * Sets the "access" for the "principalID" w.r.t. the annotation with "annotationID".
    142202     */
    … …  
    144204   
    145205   
    146  
    147      /**
    148      *
    149      * @param annotation: the object to be added to the table "annotation".
    150      * @return  the internal ID of the added annotation, if it is added, or null otherwise.
    151      **/
    152    
     206 
     207    /**
     208     *
     209     * @param annotationthe the object to be added to the table "annotation".
     210     * @param newOwnerID the ownerID,
     211     * @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.
     213     */
    153214    public Number addAnnotation(Annotation annotation, Number newOwnerID)  throws NotInDataBaseException;
    154215 
    … …  
    156217    /////// UPDATERS //////////////////
    157218   
    158    
     219   /**
     220    *
     221    * @param annotationID the internal database ID of the annotation to be updated.
     222    * @param text the new body text.
     223    * @param mimeType the new mime type.
     224    * @param isXml if the new body is a text body or an xml.
     225    * @return # of updated rows in the table "annotation".
     226    */
    159227    public int updateAnnotationBody(Number annotationID, String text, String mimeType, Boolean isXml);
    160228   
     229    /**
     230     *
     231     * @param annotationID the internal database ID of the annotation to be updated.
     232     * @param text the new headline.
     233     * @return # of updated rows in the table "annotation".
     234     */
    161235    public int updateAnnotationHeadline(Number annotationID, String text);
    162236   
    … …  
    166240     *
    167241     * @param annotation
    168      * @return # of updated rows in "annotation" table after updating the annotation. Should return 1 if update  happens
    169      * @throws SQLException
     242     * @return # of updated rows in "annotation" table after updating the annotation. Should return 1 if update  happens.
     243     */
     244    /**
     245     *
     246     * @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.
     249     * @return # of updated rows in "annotation" table after this FULL updating the annotation. Should return 1 if update  happens.
    170250     */
    171251    public int updateAnnotation(Annotation annotation, Number annotationID, Number ownerID);
    … …  
    177257     * @param principalID
    178258     * @param access
    179      * @return # rows updated to the table "annotations_principals_accesss"
     259     * @return # rows updated to the table "annotations_principals_access".
    180260     * Sets the "access" for the "principalID" w.r.t. the annotation with "annotationID".
    181261     */
    182262    public int updatePermission(Number annotationID, Number principalID, Access access);
    183263   
    184    
     264    /**
     265     *
     266     * @param annotationID the internal database ID of the annotation to be updated.
     267     * @param access access level.
     268     * @return # of updated rows in "annotation". should be "1" if updated and "0" otherwise.
     269     */
    185270    public int updatePublicAccess(Number annotationID, Access access);
    186271   
    … …  
    212297    *
    213298    * @param annotationID
    214     * @return # removed rows in the table "annotations_principals_accesss".
    215     * @throws SQLException
     299    * @return # removed rows in the table "annotations_principals_access".
    216300    */
    217301    public int deletePermissions(Number annotationID);
    218302   
     303    /**
     304     *
     305     * @param annotationID
     306     * @param principalID
     307     * @return # removed rows in the table "annotations_principals_access".
     308     * Should be "1" is removed and "0" otherwise.
     309     */
    219310    public int deletePermission(Number annotationID, Number principalID);
    220311   
     312    /**
     313     *
     314     * @param annotationID
     315     * @return # removed rows in the table "notebookds_annotations".
     316     */
    221317    public int deleteAnnotationFromAllNotebooks(Number annotationID);
    222318   
    … …  
    225321     */
    226322   
     323    /**
     324     *
     325     * @param annotationBody
     326     * @return two string components of the annotationBody: the text/xml content and the mime type.
     327     */
    227328    public String[] retrieveBodyComponents(AnnotationBody annotationBody);
    228329
Note: See TracChangeset for help on using the changeset viewer.