Changeset 5998 for DASISH


Ignore:
Timestamp:
02/20/15 11:02:35 (9 years ago)
Author:
olhsha@mpi.nl
Message:

Javadoc are updated for the interfaces CachedRepresentationDao?.java and DBDispatcher java.

Location:
DASISH/t5.6/backend/annotator-backend/trunk/annotator-backend
Files:
1 added
4 edited

Legend:

Unmodified
Added
Removed

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

    r5989 r5998  
    7070     * @param after the earliest time of creating/last-update of annotations; if null then search "from the beginning of time".
    7171     * @param before the latest time of creating/last-update of annotations; if null then search "till now".
    72      * @return
     72     * @return the list of annotation internal database identifiers that satisfy the criteria defined by the parameters.
    7373     */
    7474    public List<Number> getFilteredAnnotationIDs(Number ownerID, String text, String namespace, String after, String before);

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

    r4941 r5998  
    3636    /**
    3737     *
    38      * @param internalID
    39      * @return the object of the class "CachedRepresentationInfo" with the
    40      * internal id "internalID".
     38     * @param internalID the internal database Id of the cached representation.
     39     * @return the object of the class "CachedRepresentationInfo" with the internal id "internalID".
    4140     */
    4241    public CachedRepresentationInfo getCachedRepresentationInfo(Number internalID);
    … …  
    4544     *
    4645     * @param internalID
    47      * @return the Blob of the cached representation with the internal id
    48      * "internalID".
     46     * @return the Blob of the cached representation with the internal database id "internalID".
    4947     */
    5048    public InputStream getCachedRepresentationBlob(Number internalID);
    … …  
    5250    /*
    5351     * @param targetID
    54      * @return the list of the cached representation's ID-s for the target the internal ID "targetID".
     52     * @return the list of the cached representation's ID-s for the target the internal database ID "targetID".
    5553     */
    5654    public List<Number> getCachedRepresentationsForTarget(Number targetID);
    … …  
    6159    /**
    6260     *
    63      * @param cachedInfo
    64      * @param cachedBlob
    65      * @return the internal ID of the just added "cached", or null if the cached
    66      * representation is not added for some reason.
     61     * @param cachedInfo the metadata of the cached representation (incl.the date of creation and mime-type.
     62     * @param cachedBlob the content of the cached representation, considered as BLOB.
     63     * @return the internal ID of the just added "cached", or throws the exception if adding fails.
     64     * @throws NotInDataBaseException if there is no object with the generated for the new cached representation external id.
     65     * @throws IOException if reading blob fails.
    6766     */
     67   
    6868    public Number addCachedRepresentation(CachedRepresentationInfo cachedInfo, InputStream cachedBlob) throws NotInDataBaseException, IOException;
    6969
    … …  
    7272     */
    7373   
    74     public int updateCachedRepresentationMetadata(Number  internlID, CachedRepresentationInfo cachedInfo);
     74    /**
     75     *
     76     * @param internalID the internal database id of the cached representation.
     77     * @param cachedInfo the new metadata for it.
     78     * @return # of updated rows in the table "cached_representation". Must be 1 if updated, and 0 otherwise.
     79     */
     80    public int updateCachedRepresentationMetadata(Number  internalID, CachedRepresentationInfo cachedInfo);
    7581
    76     public int updateCachedRepresentationBlob(Number  internlID, InputStream cachedBlob) throws IOException;
     82    /**
     83     *
     84     * @param internalID the internal database id of the cached representation.
     85     * @param cachedBlob the new content considered as BLOB.
     86     * @return # of updated rows in the table "cached_representation". Must be 1 if updated, and 0 otherwise.
     87     * @throws IOException if reading BLOB fails.
     88     */
     89    public int updateCachedRepresentationBlob(Number  internalID, InputStream cachedBlob) throws IOException;
    7790
    7891    /**
    … …  
    8194    /**
    8295     *
    83      * @param internalID
     96     * @param internalID the internal database id of the cached representation.
    8497     * @return # deleted rows on the table "cached_representation".
    8598     */

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

    r5850 r5998  
    4646
    4747/**
    48  *
     48 * This class does not implement access to the database directly but dispatch
     49 * the requests to the corresponding dao implementations; each defined in the
     50 * interface method implements a request; if the request addresses more then one
     51 * table in the database then the request is split up in a basic per-table
     52 * requests which are ordered so that there will not be constraint violation;
     53 * e.g when a target is to be deleted then first it is checked if no annotation
     54 * refers to it, and if not it is deleted from "target" table.
     55 *
    4956 * @author olhsha
    5057 *
    5158 */
    5259public interface DBDispatcher {
    53 
     60   
     61    /**
     62     * Sets the server address, e.g. "http://lux16.mpi.nl/ds/webannotator/ ".
     63     * @param relServiceURI
     64     *
     65     */
    5466    void setResourcesPaths(String relServiceURI);
    5567
    … …  
    5769     * GETTERS
    5870     */
    59      
     71     
     72    /**
     73     *
     74     * @param externalID the external UUID of the resource.
     75     * @param resource the type of resource (annotation, principal, cached representation, target, notebook)
     76     * which tell in which table to look for.
     77     * @return the internal database id of the resource.
     78     * @throws NotInDataBaseException
     79     */
    6080    Number getResourceInternalIdentifier(UUID externalID, Resource resource) throws NotInDataBaseException;
    6181
     82    /**
     83     *
     84     * @param resourceID the internal database identifier of the resource,
     85     * @param resource the type of resource (annotation, principal, cached representation, target, notebook)
     86     * which tell in which table to look for.
     87     * @return the external UUID of the resource.
     88     */
    6289    UUID getResourceExternalIdentifier(Number resourceID, Resource resource);
    6390
     91    /**
     92     *
     93     * @param resourceID the internal database identifier of the resource.
     94     * @param resource the type of resource (annotation, principal, cached representation, target, notebook)
     95     * which tell in which table to look for.
     96     * @return the list of permissions (principal, permission) for the resource;
     97     * currently makes sense  only for annotations and notebooks.
     98     */
    6499    PermissionList getPermissions(Number resourceID, Resource resource);
    65100
    66101    /**
    67      *
    68      * @param word
    69      * @param text
    70      * @param access
    71      * @param namespace
    72      * @param after
    73      * @param before
    74      * @return the list of internal id-s of the annotations such that: --
    75      * Targets' links of which contain "link" (as a substring), -- serialized
    76      * bodies of which contain "text", -- current principal has "access" (owner,
    77      * read, write) to them, -- namespace ???, -- owned by "owner", --
    78      * created after time-samp "after and before time-stamp "before".
     102     *
     103     * @param ownerId the internal database identifier of the owner whose annotations must be output;
     104     * any owner is allowed when "null".
     105     * @param link the link which at least one target source of the output annotation(s) must contain;
     106     * no limitations on links when null.
     107     * @param matchMode if the link of a target source must "contain, beginWith,
     108     * endsWith or be exact match of the "link" parameter above.
     109     * @param text that must be in the body of the requested annotations; no limitations when null.
     110     * @param inloggedPrincipalID the internal database id of the inlogged principal.
     111     * @param accessMode the access mode that related the inlogged principal to the requested annotations.
     112     * @param namespace not implemented.
     113     * @param after the lower limit of the last update date for requested annotations (the begin of the time, if null).
     114     * @param before the upper limit of the lust update(now, if null).
     115     * @return the list of the internal database identifiers of the annotations satisfying the criteria defined by the parameters.
     116     * @throws NotInDataBaseException if one of the getters used in the implementation throws this exception.
    79117     */
    80118    List<Number> getFilteredAnnotationIDs(UUID ownerId, String link, MatchMode matchMode, String text, Number inloggedPrincipalID, String  accessMode, String namespace, String after, String before) throws NotInDataBaseException;
    81119
     120    /**
     121     * The method must be used only in debug services by principals with "developer" role.
     122     * @return the AnnotationInfo-s of all the annotations (i.e. the information which is taken only from "annotations" table,
     123     * and junction tables for permissions and targets are not used.
     124     */
    82125    AnnotationInfoList getAllAnnotationInfos();
    83126
    84     /**
    85      *
    86      * @param word
    87      * @param text
    88      * @param access
    89      * @param namespace
    90      * @param owner
    91      * @param after
    92      * @param before
    93      * @return the list of the annotationInfos of the annotations such that: --
    94      * Targets' links of which contain "link" (as a substring), -- serialized
    95      * bodies of which contain "text", -- current principal has "access" (owner,
    96      * read, write) to them, -- namespace ???, -- owned by "owner", --
    97      * created after time-samp "after and before time-stamp "before".
    98      */
     127  /**
     128   *
     129     * @param ownerId the internal database identifier of the owner whose annotations must be output;
     130     * any owner is allowed when "null".
     131     * @param link the link which at least one target source of the output annotation(s) must contain;
     132     * no limitations on links when null.
     133     * @param matchMode if the link of a target source must "contain, beginWith,
     134     * endsWith or be exact match of the "link" parameter above.
     135     * @param text that must be in the body of the requested annotations; no limitations when null.
     136     * @param inloggedPrincipalID the internal database id of the inlogged principal.
     137     * @param accessMode the access mode that related the inlogged principal to the requested annotations.
     138     * @param namespace not implemented.
     139     * @param after the lower limit of the last update date for requested annotations (the begin of the time, if null).
     140     * @param before the upper limit of the lust update(now, if null).
     141     * @return the list of the annotation info's (i.e. the information taken only from the table "annotations", and not from junction tables)
     142     * of the annotations satisfying the criteria defined by the parameters.
     143     * @throws NotInDataBaseException if getFileteredAnnotationIDs throws this exception.
     144   */
    99145    AnnotationInfoList getFilteredAnnotationInfos(UUID ownerId, String link, MatchMode matchMode, String text, Number inloggedPrincipalID, String access, String namespace, String after, String before) throws NotInDataBaseException;
    100146
    … …  
    104150     *
    105151     * @param internalID
    106      * @return CachedRepresentationInfo (i.e. "metadata") for cached
    107      * representation with the internal id "intenalID"
     152     * @return CachedRepresentationInfo (i.e. "metadata") for cached representation with the internal id "intenalID"
    108153     */
    109154    CachedRepresentationInfo getCachedRepresentationInfo(Number internalID);
    … …  
    111156    /**
    112157     *
    113      * @param annotationID
    114      * @return the object Annotation generated from the tables "annotation",
    115      * "annotations_target_Targets", "Target",
    116      * "annotations_principals_accesss".
    117      * @throws SQLException
     158     * @param annotationID an internal database annotation identifier.
     159     * @return the {@link Annotation} for this "annotationID, generated from the tables "annotation", "annotations_targets", "target", "annotations_principals_access".
     160     *
    118161     */
    119162    Annotation getAnnotation(Number annotationID);
    120163
     164    /**
     165     *
     166     * @param annotationID an internal database annotation identifier.
     167     * @return the internal database id of the owner of the annotation.
     168     */
    121169    Number getAnnotationOwnerID(Number annotationID);
    122170
     171    /**
     172     *
     173     * @param annotationID an internal database annotation identifier.
     174     * @return the {@link Principal} object that represents the owner of the annotation with "annotationID".
     175     */
    123176    Principal getAnnotationOwner(Number annotationID);
    124177   
    125178    /**
    126179     *
    127      * @param annotationID
    128      * @return the object TargetList containing all target Targets of the
    129      * annotationID
    130      * @throws SQLException
     180     * @param annotationID an internal database annotation identifier.
     181     * @return the {@link ReferenceList} object containing the references of all targets of the annotationID.
    131182     */
    132183    ReferenceList getAnnotationTargets(Number annotationID);
    … …  
    134185    /**
    135186     *
    136      * @param annotationID
    137      * @return the list of targetURI's for which there is no cached
    138      * representation
     187     * @param annotationID an internal database annotation identifier.
     188     * @return the list of h-references for which there is no cached representation.
    139189     */
    140190    List<String> getTargetsWithNoCachedRepresentation(Number annotationID);
    141191
     192    /**
     193     *
     194     * @param annotationID an internal database annotation identifier.
     195     * @return the list of h-references of the principals which are mentioned in
     196     * the junction table "annotations-permissions" in a pair with "annotationID"
     197     * and for which principal's name and / or principal's e-mail is missing.
     198     */
    142199    List<String> getPrincipalsWithNoInfo(Number annotationID);
    143200
    144201    /**
    145202     *
    146      * @param targetID
    147      * @return the list of the external version ID-s that refers to the same
    148      * source (link) as targetID
     203     * @param targetID an internal database target identifier.
     204     * @return the list of the external  ID-s that refers to the same source (link) as targetID
    149205     */
    150206    ReferenceList getTargetsForTheSameLinkAs(Number targetID);
    … …  
    152208    /**
    153209     *
    154      * @param cachedID
    155      * @return BLOB of the cachedID
     210     * @param cachedID an internal database cached representation identifier.
     211     * @return BLOB of the cached representation.
    156212     */
    157213    InputStream getCachedRepresentationBlob(Number cachedID);
    158214
     215    /**
     216     *
     217     * @param internalID an internal database target identifier.
     218     * @return {@link Taget} object built for "internalID".
     219     */
    159220    Target getTarget(Number internalID);
    160221
    161222    /**
    162223     *
    163      * @param principalID
    164      * @return principal with "principalID"
     224     * @param principalID an internal database principal identifier.
     225     * @return {@link Principal} object built for "principalID".
    165226     */
    166227    Principal getPrincipal(Number principalID) ;
    167228
    168     /**
    169      *
    170      * @param eMail
    171      * @return principal with e-mail "eMail"
     229
     230    /**
     231     *
     232     * @param eMail an email address.
     233     * @return {@link Principal} object with e-mail "eMail".
     234     * @throws NotInDataBaseException if an principal with such eMail is not found.
    172235     */
    173236    Principal getPrincipalByInfo(String eMail) throws NotInDataBaseException;
    174237
     238    /**
     239     *
     240     * @param internalID the databaseinternalId of a principal.
     241     * @return {@link Principal} object with this internalID; will throw runtime
     242     * "array out of bound exception" if a principal is not found due to the attempt
     243     * to access empty array; not crucial since if you already have the internalId
     244     * then the object must exist in the database, but fix it by throwing NotInDataBaseException;
     245     */
    175246    String getPrincipalRemoteID(Number internalID);
    176247
     248    /**
     249     *
     250     * @param remoteID the remote id of a principal.
     251     * @return the internal database id of the principal with "remotedID".
     252     * @throws NotInDataBaseException if a principal with "remoteID" is not found.
     253     */
    177254    Number getPrincipalInternalIDFromRemoteID(String remoteID) throws NotInDataBaseException;
    178255   
     256    /**
     257     *
     258     * @param remoteID the remote id of a principal.
     259     * @return the external UUID  of the principal with "remotedID".
     260     * @throws NotInDataBaseException if a principal with "remoteID" is not found.
     261     */
    179262    UUID getPrincipalExternalIDFromRemoteID(String remoteID) throws NotInDataBaseException;
    180263
    181264    /**
    182265     *
    183      * @param annotationID
    184      * @param principalID
    185      * @return access of the principalID w.r.t. annotationID, or null if the
    186      * access is not given
     266     * @param annotationID the internal database id of an annotation.
     267     * @param principalID the internal database id of a principal.
     268     * @return access of the principalID w.r.t. annotationID, which is a maximal access
     269     * from "public" attribute of the annotation and the value "access" in the row
     270     * (annotationId, principalID, access) of the table "annotations_principals_access".
    187271     */
    188272    Access getAccess(Number annotationID, Number principalID) ;
    189273   
     274    /**
     275     *
     276     * @param annotationID the internal database id of an annotation.
     277     * @return the public-attribute value for "annotationID"
     278     * (NONE if database return empty result; fix it to be "NotInDataBaseException".
     279     */
    190280    Access getPublicAttribute(Number annotationID);
    191281
     282    /**
     283     *
     284     * @param principalID the internal database id of a principal.
     285     * @return user, developer, or admin.
     286     */
    192287    String getTypeOfPrincipalAccount(Number principalID);
    193288   
     289    /**
     290     *
     291     * @return  the {@link Principal} object corresponding to the "first in the list" admin of the database
     292     */
    194293    Principal getDataBaseAdmin() ;
    195294
     295    /**
     296     *
     297     * @param action {@link Access} object defining which action is to be perfomed.
     298     * @param principalID the internal Id of the principal who wants to perform "action".
     299     * @param resourceID the internal id of the resource on which action must be performed.
     300     * @param resource a type of resource (annotation, notebook, cached representation, target,
     301     * principal)
     302     * @return true iff "principalId" is allowed to perform "action" on "resourceID"; false
     303     * otherwise false; currently is implemented only for "annotation" and return "true" on
     304     * all other types of resources.
     305     */
    196306    boolean canDo(Access action, Number principalID, Number resourceID, Resource resource);
    197307
    198308   
    199309    /// notebooks ///
     310    /**
     311     *
     312     * @param prinipalID the internal database id of a principal.
     313     * @param access a {@link Access} object.
     314     * @return {@link NotebookInfoList} object containing the list of all notebooks to which
     315     * "principalID" has "access".
     316     */
    200317    NotebookInfoList getNotebooks(Number prinipalID, Access access);
    201318
     319    /**
     320     *
     321     * @param notebookID the internal database id of a notebook.
     322     * @param principalID the internal database id of a principal.
     323     * @param access an {@link Access} object.
     324     * @return true if "principalID" has "access" to  "notebookID".
     325     */
    202326    boolean hasAccess(Number notebookID, Number principalID, Access access);
    203327
     328    /**
     329     *
     330     * @param principalID the internal database id of a principal.
     331     * @return a {@link ReferenceList} object containing hrefs of notebooks owned
     332     * by "principlaID"
     333     */
    204334    ReferenceList getNotebooksOwnedBy(Number principalID);
    205335
     336    /**
     337     *
     338     * @param notebookID the internal database id of a notebook.
     339     * @param access an {@link Access} object.
     340     * @return a {@link ReferenceList} object containing hrefs of principals
     341     * which have "access" to "notebookID".
     342     */
    206343    ReferenceList getPrincipals(Number notebookID, String access);
    207 
     344/**
     345 *
     346 * @param notebookID the internal database id of a notebook.
     347 * @return a {@link Notebook} object corresponding to the notebook with "notebookID".
     348 */
    208349    Notebook getNotebook(Number notebookID);
    209350
     351    /**
     352     *
     353     * @param notebookID the internal database id of a notebook.
     354     * @return an internal database Id of the owner of the "notebookID".
     355     */
    210356    Number getNotebookOwner(Number notebookID);
    211357
     358    /**
     359     *
     360     * @param notebookID the internal database id of a notebook.
     361     * @param startAnnotation the first index for the list (of annotations).
     362     * @param maximumAnnotations the maximum # of annotations in the output list expected.
     363     * @param orderedBy SQL "orderedBy" string value, must be one of the fields in the table "annotation".
     364     * @param desc direction of ordering.
     365     * @return a {@link ReferenceList} object containing hrefs of annotations for notebookID,
     366     * "orderedBy" in "desc" order, starting from "startAnnotation" and and with "maximum" hrefs.
     367     */
    212368    ReferenceList getAnnotationsForNotebook(Number notebookID, int startAnnotation, int maximumAnnotations, String orderedBy, boolean desc);
    213369
    … …  
    216372     */
    217373   
     374    /**
     375     *
     376     * @param resource a type of resource (annotation,notebook, cached representation, target,  principal).
     377     * @param oldIdentifier the external UUD of the resource.
     378     * @param newIdentifier the new external UUID of the resource.
     379     * @return # of updated rows in the corresponding table. Must be 1 if the resource with oldIdentifier
     380     * gets the external identifier updated by "newIdentifier", and 0 otherwise.
     381     * @throws NotInDataBaseException if the resource with "oldIdentifier" is not found.
     382     */
    218383    boolean updateResourceIdentifier(Resource resource, UUID oldIdentifier, UUID newIdentifier) throws NotInDataBaseException;
    219384   
    220    
     385    /**
     386     *
     387     * @param principalExternalID the external UUD of a principle.
     388     * @param account new type of account for this principle (a role: user, developer, admin).
     389     * @return "true" if the account gets updated, and "false" otherwise.
     390     * @throws NotInDataBaseException if the principal with the external UUD of a principle.
     391     */
    221392    boolean updateAccount(UUID principalExternalID, String account) throws NotInDataBaseException;
    222393
    223     /**
    224      *
    225      * @param annotation
    226      * @return 1 of the annotation if it is updated
     394   
     395    /**
     396     *
     397     * @param annotation an {@link Annotation} object.
     398     * @param remoteUser
     399     * @return # of rows in "annotation" table. "1" if the annotation gets updated, and "0" otherwise.
     400     * @throws NotInDataBaseException if the annotation with the external id given in the annotation object,
     401     * or the remote user are not found in the database.
     402     * @throws ForbiddenException if the "remoteUser" does not have "all" rights for the annotation with the external id,
     403     * given in the "annotation" object.
    227404     */
    228405    int updateAnnotation(Annotation annotation, String remoteUser) throws NotInDataBaseException, ForbiddenException;
    … …  
    230407    /**
    231408     *
    232      * @param principalID
    233      * @param annotationBody
    234      * @return 1 of the annotation if it is updated
     409     * @param internalID the internal database id of an annotation whose body to be updated.
     410     * @param annotationBody an {@link Annotation} object.
     411     * @return # of rows in "annotation" table. "1" if the annotation body gets updated by
     412     * "annotationBody" gets updated, and "0" otherwise.
    235413     */
    236414    int updateAnnotationBody(Number internalID, AnnotationBody annotationBody);
    237415   
     416    /**
     417     *
     418     * @param internalID the internal database id of an annotation whose body to be updated.
     419     * @param newHeader  the header to be placed in the database for "internalID".
     420     * @return # of rows in "annotation" table. "1" if the annotation body gets updated by "newHeader",
     421     * and "0" otherwise.
     422     */
    238423    int updateAnnotationHeadline(Number internalID, String newHeader);
    239424
    240425    /**
    241426     *
    242      * @param annotationID
    243      * @param principalID
    244      * @param access
    245      * @return # rows updated to the table "annotations_principals_accesss"
    246      * Sets the "access" for the "principalID" w.r.t. the annotation with
    247      * "annotationID".
     427     * @param annotationID the internal database id of an annotation.
     428     * @param principalID the internal database id of a principal.
     429     * @param access c
     430     * @return # rows updated to the table "annotations_principals_access. "1" if
     431     * "access" is assigned to the "principlaID" for the "ammotationID".
    248432     */
    249433    int updatePermission(Number annotationID, Number principalID, Access access);
    250434
    251435    /**
    252      *
    253      * @param annotationID
    254      * @param accessList
    255      * @return # of rows updated or added in the table
    256      * annotations_principals_accesss
     436     * 
     437     * @param annotationID the internal database id of an annotation.
     438     * @param accessList  {@link PermissionList} object containing the list  representing (principal, access) pairs.
     439     * @return  # of rows updated or added in the table "annotations_principals_access"  according to "accessList".
     440     * @throws NotInDataBaseException if one of the principals mentioned in the list, is not found.
    257441     */
    258442    int updateOrAddPermissions(Number annotationID, PermissionList permissionList) throws NotInDataBaseException ;
    259443   
     444    /**
     445     *
     446     * @param annotationID the internal database id of an annotation.
     447     * @param publicAttribute  an {@link Access} object.
     448     * @return # of updated rows in "annotation" table; must be 1 if "public" field for
     449     * "annotationID" has been updated by value "publicAttribute".
     450     */
    260451    int updatePublicAttribute(Number annotationID, Access publicAttribute);
    261452   
     453    /**
     454     *
     455     * @param principal a {@link Principal} project.
     456     * @return the internal database id of the updated principal.
     457     * @throws NotInDataBaseException if the principal with the external id declared in "principal"
     458     * is not found.
     459     */
    262460    Number updatePrincipal(Principal principal) throws NotInDataBaseException;
    263461
    264    
    265     int updateTargetCachedFragment(Number targetID, Number cachedID, String fragmentDescriptor) throws NotInDataBaseException;
    266    
     462    /**
     463     *
     464     * @param targetID the internal database id of a target.
     465     * @param cachedID the internal database id of a cached representation.
     466     * @param fragmentDescriptor the fragment string that locates the target in the cached representation.
     467     * @return # of updated rows in the junction table "targets_cached_representations".
     468     */
     469    int updateTargetCachedFragment(Number targetID, Number cachedID, String fragmentDescriptor);
     470   
     471    /**
     472     *
     473     * @param cachedInfo a {@link CachedRepresentationInfo} object representing metadata of a cached representation.
     474     * @return # of updated rows in the table "cached_representation"; must be 1 if the
     475     * row with the external id declared in "cachedInfo" has got updated.
     476     * @throws NotInDataBaseException if the cached representation with the external id declared in the
     477     * "cachedInfo" is nit found.
     478     */
    267479    int updateCachedMetada(CachedRepresentationInfo cachedInfo)  throws NotInDataBaseException;
    268480   
     481    /**
     482     *
     483     * @param internalID the internal database id of a cached representation.
     484     * @param cachedBlob a new BLOB for the cached representation.
     485     * @return # of updated rows in "cached_representations_table"; must be "1" if the row with
     486     * "internalID" got updated.
     487     * @throws IOException if reading BLOB fails.
     488     */
    269489    public int updateCachedBlob(Number internalID, InputStream cachedBlob) throws IOException;
    270490   
    271491   
     492    /**
     493     *
     494     * @param notebookID the internal database id of a notebook.
     495     * @param upToDateNotebookInfo a {@link NotebookInfo} object.
     496     * @return true if the "notebooks" table has got updated, namely the row with "notebookID" updated
     497     * by the corresponding values declared in "upToDateNotebookInfo"; false when no updated happens,
     498     * @throws NotInDataBaseException if the notebook with "internalID" is not found.
     499     */
     500    boolean updateNotebookMetadata(Number notebookID, NotebookInfo upToDateNotebookInfo) throws NotInDataBaseException;
     501
     502    /**
     503     *
     504     * @param notebookID the internal database id of a notebook.
     505     * @param annotationID the internal database id of an annotation.
     506     * @return true if the junction table "notebook_annotation" is updated by adding row with values (notebookID, annotationID).
     507     */
     508    boolean addAnnotationToNotebook(Number notebookID, Number annotationID);
     509
     510    /**
     511     * ADDERS
     512     */
     513 
     514    /**
     515     *
     516     * @param targetID the internal database id of a target.
     517     * @param fragmentDescriptor a string that located the target within the cached representation.
     518     * @param cachedInfo a {@link CachedRepresentationInfo} object representing the metadata of the cached representation.
     519     * @param cachedBlob a BLOB, representing the content of a cached representation.
     520     * @return result[0] = # updated rows in the table "targets_cached_representations" (must be 1 or 0). result[1] = the
     521     * internal ID of the added cached (a new one if "cached" was new for the database).
     522     * @throws NotInDataBaseException when adding a cached representation to the corresponding table fails.
     523     * @throws IOException if reading BLOB fails.
     524     */
     525    Number[] addCachedForTarget(Number targetID, String fragmentDescriptor, CachedRepresentationInfo cachedInfo, InputStream cachedBlob) throws NotInDataBaseException, IOException;
     526
     527    /**
     528     *
     529     * @param annotationID the internal database id of an annotation.
     530     * @param targets list of {@link TargetInfo} objects, where {@link targetInfo} represents
     531     * the most essential metadata of a target; it is supposed to be a list of targets
     532     * for the annotations when annotations is just being added to the database or updated.
     533     * @return a map "temporary targetID |--> target externalID"; its domain is the
     534     * temporary IDs of all the new targets; while adding a new target, a new
     535     * external ID is generated for it and it becomes the value of the map; the
     536     * targetIDs which are already present in the DB are not in the domain. If
     537     * all targets are old, then the map is empty.
     538     * @throws NotInDataBaseException if adding of one of fresh targets fails.
     539     */
     540    Map<String, String> addTargetsForAnnotation(Number annotationID, List<TargetInfo> targets)  throws NotInDataBaseException;
     541
     542    /**
     543     *
     544     * @param ownerID the internal database id of a principal.
     545     * @param annotation an {@link Annotation} object, representing an annotation to be added to the database.
     546     * @return the internal database id of the just added fresh annotation.
     547     * @throws NotInDataBaseException if adding fails.
     548     */
     549    Number addPrincipalsAnnotation(Number ownerID, Annotation annotation) throws NotInDataBaseException;
     550
     551   /**
     552    *
     553    * @param principal a {@link Principal} object representing a principal to be added.
     554    * @param remoteID a remote id of the principal to be added.
     555    * @return the internal database id of the just added principal.
     556    * @throws NotInDataBaseException if adding fails.
     557    * @throws PrincipalExists if the principal with the remoteID already exists in the database.
     558    */
     559    Number addPrincipal(Principal principal, String remoteID) throws NotInDataBaseException, PrincipalExists;
     560
     561    /**
     562     *
     563     * @param username
     564     * @param password
     565     * @param strength
     566     * @param salt
     567     * @return the total of updated rows in the tables related to the Spring authentication; must be
     568     * 2=1+1, where 1 is for the table "users", and 1 is for the table "roles".
     569     */
     570    public int addSpringUser(String username, String password, int strength, String salt);
     571   
     572       /// notebooks ////
     573    /**
     574     *
     575     * @param notebook a {@link Noetbook} object to be added.
     576     * @param ownerID the internal database id of a principal who will be the owner of the notebook.
     577     * @return the internal database id of a new notebook.
     578     * @throws NotInDataBaseException if adding fails.
     579     */
     580    Number createNotebook(Notebook notebook, Number ownerID) throws NotInDataBaseException;
     581
     582    /**
     583     *
     584     * @param notebookID  the internal database id of a notebook.
     585     * @param annotation an {@link Annotation} object representing an annotation to be added.
     586     * @param ownerID the internal database id of the notebook's owner (principal).
     587     * @return true if a new annotation has been added to the database and then it was added  to the notebook.
     588     * @throws NotInDataBaseException if adding annotation to the database fails.
     589     */
     590    boolean createAnnotationInNotebook(Number notebookID, Annotation annotation, Number ownerID) throws NotInDataBaseException;
     591
     592   
     593    /**
     594     * DELETERS
     595     */
     596   
     597    /**
     598     *
     599     * @param annotationID the internal database ID of an annotation.
     600     * @param principalID the internal database ID of a principal.
     601     * @return # number of removed rows in the junction table "annotations_principals_accesses";
     602     * must be 1 if a row with "annotationID" and "principalID" has been removed.
     603     */
     604    int deleteAnnotationPrincipalAccess(Number annotationID, Number principalID);
     605   
     606    /**
     607     *
     608     * @param principalID the internal database id of a principal to be deleted.
     609     * @return # of affected rows in the table "principal; it is 1 if the
     610     * principalID is found and deleted; it is 0 if it is not found or not deleted,
     611     * e.g. because it is in use in the table "annotations_principals_accesses".
     612     */
     613    /**
     614     *
     615     * @param principalID the internal database id of a principal to be deleted.
     616     * @return # of affected rows in the table "principal"; it is 1 if the
     617     * principalID is found and deleted; it is 0 if not deleted.
     618     * @throws PrincipalCannotBeDeleted  if the principal cannot be deleted,
     619     * e.g. because it is in use in the table "annotations_principals_accesses".
     620     */
     621    int deletePrincipal(Number principalID) throws PrincipalCannotBeDeleted;
     622
     623 /**
     624  *
     625  * @param internalID the internal id of a cached representation to be deleted;
     626  * @return # of affected rows in the table "cached_representations"; must be "1" if deleted.
     627  */
     628    int deleteCachedRepresentation(Number internalID);
     629
     630    /**
     631     *
     632     * @param targetID the internal database ID of a target.
     633     * @param cachedID the internal database id of a cached representation.
     634     * @return result[0] = # deleted rows in the table "targets_cached_representations" (1, or 0). result[1] = # deleted rows in
     635     * the table "cached_representation" (should be 0 if the cached representation is in use by some other target).
     636     */
     637    int[] deleteCachedRepresentationOfTarget(Number TargetID, Number cachedID);
     638
     639    /**
     640     *
     641     * @param targetID the internal database ID of a target.
     642     * @return result[0] = # deleted rows in the table "targets_cached_representations". result[1] = # deleted rows in the table "cached_representation".
     643     *
     644     */
     645    int[] deleteAllCachedRepresentationsOfTarget(Number targetID);
     646
     647    /**
     648     *
     649     * @param internalID he internal database ID of a target to be deleted.
     650     * @return # of deleted rows in the table "target"; must be one if "internalID" is deleted.
     651     */
     652    int deleteTarget(Number internalID);
     653   
     654   
     655    /**
     656     *
     657     * @param annotationID the internal database id of an annotation to be deleted.
     658     * @return result[0] = # deleted rows in the table "annotation" (1 or 0);
     659     * result[1] = # deleted rows in the table "annotations_principals_accesses".;
     660     * result[2] = # deleted rows in the table "annotations_targets";
     661     * result[3] = # deleted rows in the table "target".
     662     */
     663    int[] deleteAnnotation(Number annotationID);
     664
    272665    /// notebooks ///
    273     boolean updateNotebookMetadata(Number notebookID, NotebookInfo upToDateNotebookInfo) throws NotInDataBaseException;
    274 
    275     boolean addAnnotationToNotebook(Number notebookID, Number annotationID);
    276 
    277     /**
    278      * ADDERS
    279      */
    280     /**
    281      *
    282      * @param targetID
    283      * @param cachedInfo
    284      * @param cachedBlob
    285      * @return result[0] = # updated rows in the table
    286      * "Targets_cached_representations" (must be 1 or 0). result[1] = the
    287      * internal ID of the added cached (a new one if "cached" was new for the
    288      * Data Base).
    289      */
    290     Number[] addCachedForTarget(Number targetID, String fragmentDescriptor, CachedRepresentationInfo cachedInfo, InputStream cachedBlob) throws NotInDataBaseException, IOException;
    291 
    292     /**
    293      *
    294      * @param annotationID
    295      * @param targets
    296      * @return map temporaryTargetID |--> TargetExternalID. Its domain is the
    297      * temporary IDs of all the new Targets. While adding a new Target a new
    298      * external ID is generated for it and it becomes the value of the map. The
    299      * TargetIDs which are already present in the DB are not in the domain. If
    300      * all Targets are old, then the map is empty.
    301      * @throws SQLException
    302      */
    303     Map<String, String> addTargetsForAnnotation(Number annotationID, List<TargetInfo> targets)  throws NotInDataBaseException;
    304 
    305     /**
    306      *
    307      * @param principalID
    308      * @param annotation
    309      * @return the internalId of the just added "annotation" (or null if it is
    310      * not added) by the owner "principalID". calls "addTargetsForAnnotation"
    311      * @throws SQLException
    312      */
    313     Number addPrincipalsAnnotation(Number ownerID, Annotation annotation) throws NotInDataBaseException;
    314 
    315     /**
    316      *
    317      * @param principal
    318      * @param remoteID is got from the server
    319      * @return the internal Id of the just added "principal", or null if it was not
    320      * added for some reason (already exists)
    321      * @throws SQLException
    322      */
    323     Number addPrincipal(Principal principal, String remoteID) throws NotInDataBaseException, PrincipalExists;
    324 
    325     public int addSpringUser(String username, String password, int strength, String salt);
    326    
    327        /// notebooks ////
    328     Number createNotebook(Notebook notebook, Number ownerID) throws NotInDataBaseException;
    329 
    330     boolean createAnnotationInNotebook(Number notebookID, Annotation annotation, Number ownerID) throws NotInDataBaseException;
    331 
    332    
    333     /**
    334      * DELETERS
    335      */
    336    
    337     int deleteAnnotationPrincipalAccess(Number annotationID, Number principalID);
    338    
    339     /**
    340      *
    341      * @param principalID
    342      * @return # of affected rows in the table "principal". It is 1 if the
    343      * principalId is found and deleted; it is 0 if it is not found or not deleted,
    344      * e.g. because it is in use in the table
    345      * "annotationsPreincipalsAccesss"
    346      */
    347     int deletePrincipal(Number principalID) throws PrincipalCannotBeDeleted;
    348 
    349    
    350     int deleteCachedRepresentation(Number internalID);
    351 
    352     /**
    353      *
    354      * @param TargetID
    355      * @param cachedID
    356      * @return result[0] = # deleted rows in the table
    357      * "Targets_cached_representations" (1, or 0). result[1] = # deleted rows in
    358      * the table "cached_representation" (should be 0 if the cached
    359      * representation is in use by some other Target???).
    360      */
    361     int[] deleteCachedRepresentationOfTarget(Number TargetID, Number cachedID);
    362 
    363     /**
    364      *
    365      * @param targetID
    366      * @return result[0] = # deleted rows in the table
    367      * "targets_cached_representations". result[1] = # deleted rows in the table
    368      * "cached_representation".
    369      *
    370      */
    371     int[] deleteAllCachedRepresentationsOfTarget(Number targetID);
    372 
    373     int deleteTarget(Number internalID);
    374    
    375    
    376     /**
    377      *
    378      * @param annotationID
    379      * @return result[0] = # deleted rows in the table "annotation" (1 or 0).
    380      * result[1] = # deleted rows in the table
    381      * "annotations_principals_accesss". result[2] = # deleted rows in the
    382      * table "annotations_target_Targets". result[3] = # deleted rows in the
    383      * table "Target".
    384      * @throws SQLException
    385      */
    386     int[] deleteAnnotation(Number annotationID);
    387 
    388     /// notebooks ///
     666    /**
     667     *
     668     * @param notebookID the internal database id of a notebook to be deleted.
     669     * @return true if the notebook with "notebookID" has been deleted.
     670     */
    389671    boolean deleteNotebook(Number notebookID);
    390672
    391673    //////// HELPERS for resources /////
     674    /**
     675     *
     676     * @param annotationID the internal database id of an annotation.
     677     * @return a {@link ResponseBody} object containing an annotation and a list of actions to do;
     678     * for instance if it is a just added annotation, the result object contains this annotation
     679     * and list of targets for which cached representations are missing.
     680     */
    392681    ResponseBody makeAnnotationResponseEnvelope(Number annotationID);
    393682
     683    /**
     684     *
     685     * @param notebookID the internal database id of an annotation.
     686     * @return a {@link ResponseBody} object containing a notebook and a list of actions to do;
     687     * actions are not specified yet.
     688     *
     689     */
    394690    ResponseBody makeNotebookResponseEnvelope(Number notebookID);
    395691
     692    /**
     693     *
     694     * @param resourceID the internal database id of a resource.
     695     * @param resource a {@link Resource} object, specifying the type of the resource:
     696     * annotation, principal, notebook, target, cached_representation.
     697     * @return a {@link ResponseBody} object containing the list of (principal, permission) for this resource;
     698     * if information about a principal (e.g. an e-mail) is missing then the corresponding action
     699     * is added to the list of actions.
     700     */
    396701    ResponseBody makeAccessResponseEnvelope(Number resourceID, Resource resource);
    397702   
     703    /**
     704     *
     705     * @param fullName a string representing a full name of a principal.
     706     * @return the external Id of the (first) principal with with full name.
     707     * @throws NotInDataBaseException if such principal is not found.
     708     */
    398709    UUID getPrincipalExternalIdFromName(String fullName) throws NotInDataBaseException;
    399710   
     711    /**
     712     *
     713     * @param headline a string representing the headline of an annotation.
     714     * @return  the list of UUID's of all the annotations with this headline.
     715     */
    400716    List<UUID> getAnnotationExternalIdsFromHeadline(String headline);
    401717   
     718    /**
     719     *
     720     * @param headline a string representing the headline of an annotation.
     721     * @return the list of internal database id-s of all the annotations with this headline.
     722     */
    402723    List<Number> getAnnotationInternalIDsFromHeadline(String headline);
    403724}

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

    r5850 r5998  
    412412    }
    413413
    414     // TODO unit test
     414   
    415415    @Override
    416416    public CachedRepresentationInfo getCachedRepresentationInfo(Number internalID) {
    … …  
    418418    }
    419419
    420     //TODO unit test
     420   
    421421    @Override
    422422    public InputStream getCachedRepresentationBlob(Number cachedID) {
    … …  
    799799
    800800    @Override
    801     public int updateTargetCachedFragment(Number targetID, Number cachedID, String fragmentDescriptor) throws NotInDataBaseException {
     801    public int updateTargetCachedFragment(Number targetID, Number cachedID, String fragmentDescriptor){
    802802        return targetDao.updateTargetCachedRepresentationFragment(targetID, cachedID, fragmentDescriptor);
    803803    }
Note: See TracChangeset for help on using the changeset viewer.