Changeset 6004 for DASISH


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

Javadoc are updated for the interfaces NotebookDao?, ResourceDao?, TargetDao? and some helpers.

Location:
DASISH/t5.6/backend/annotator-backend/trunk/annotator-backend/src/main/java/eu/dasish/annotation/backend/dao
Files:
6 edited

Legend:

Unmodified
Added
Removed

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

    r5850 r6004  
    2222
    2323/**
    24  *
     24 * This is a help interface used in wrapper methods for REST requests, see RequestWrappers.java;
     25 * "R" may stay for resource, e.g. Annotation.
    2526 * @author olhsha
    2627 */
    2728public interface ILambda<Map, R> {
    2829   
     30    /**
     31     *
     32     * @param params list of pairs parameter->value, e.g. such map can contain the external Id of a resource, e.g. an annotation.
     33     * @return an instance of "R" corresponding to these parameter values,e.g. an annotation if R is instantiated as "Annotation".
     34     * @throws NotInDataBaseException see various implementations in REST resource classes.
     35     * @throws ForbiddenException see various implementations in REST resource classes.
     36     */
    2937    public R apply(Map params)   throws NotInDataBaseException, ForbiddenException;
    3038   

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

    r5053 r6004  
    2222
    2323/**
    24  *
     24 * This is a help interface used in wrapper methods for REST requests, see RequestWrappers.java;
    2525 * @author olhsha
    2626 */
    2727public interface ILambdaPrincipal<Map, R> {
    2828   
     29    /**
     30     *
     31     * @param params list of pairs parameter -> value.
     32     * @return the object corresponding to the parameter values from the "params".
     33     * @throws NotInDataBaseException see the implementations.
     34     * @throws PrincipalExists  see the implementations
     35     */
    2936    public R apply(Map params)   throws NotInDataBaseException, PrincipalExists;
    3037   

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

    r4834 r6004  
    4343  **/
    4444   
     45    /**
     46     *
     47     * @param notebookID the internal ID of a notebook.
     48     * @return the internal database Id of the owner of the notebook.
     49     */
    4550    Number getOwner(Number notebookID);
    4651   
    4752   
    48    
     53    /**
     54     *
     55     * @param principalID the internal database id of some principal.
     56     * @param acessMode {@link Access} object, representing one of the access modes:
     57     * "all", "write", "read" or "none".
     58     * @return the list of internal database id's of the notebooks for which "principalID" has ""accessMode" access.
     59     */
    4960    List<Number> getNotebookIDs(Number principalID, Access acessMode);
    5061   
    51     // Returns a list of notebook Ids for the notebooks for which the given principal "principalID" is the owner.
     62   /**
     63    * @param principaID the internal database id of some principal.
     64    * @return  the list of internal database id's of the notebooks for which "principalID" is the owner.
     65    */
    5266    List<Number> getNotebookIDsOwnedBy(Number principaID);
    5367   
    … …  
    5670    /**
    5771     *
    58      * @param notebookID
    59      * @return the notebook info for the notebook with notebookID
     72     * @param notebookID the internal database id of a notebook.
     73     * @return the {@link NotebookInfo} object built for the notebook with notebookID upon the corresponding row
     74     * in the "notebook" table.
    6075     */
    6176    NotebookInfo getNotebookInfoWithoutOwner(Number notebookID);
    … …  
    6479    /**
    6580     *
    66      * @param notebookID
    67      * @return notebook metadata for the notebook with notebookID
     81     * @param notebookID the internal database id of a notebook.
     82     * @return the {@link Notebook} object built for the notebook with notebookID upon the corresponding row
     83     * in the "notebook" table.
    6884     */
    6985    Notebook getNotebookWithoutAnnotationsAndAccesssAndOwner(Number notebookID);
    … …  
    8197   
    8298   
    83     /**
    84      *
    85      * @param notebookID
    86      * @return true if updated, false otherwise. Logs the reason if the notebook is not updated.
     99
     100    /**
     101     *
     102     * @param notebookID the internal database id of a notebook.
     103     * @param title a new title for the notebook.
     104     * @param ownerID the internal database id of the owner principal of the notebook.
     105     * @return true if the title "notebookID" is updated to "title", false otherwise.
    87106     */
    88107    boolean updateNotebookMetadata(Number notebookID, String title, Number ownerID);
    89108   
     109   
     110    /**
     111     *
     112     * @param notebookID the internal database id of a notebook.
     113     * @param ownerID the internal database id of a new owner for the notebook.
     114     * @return true if the owner_id is in "notebook" table is updated to "ownerID", false otherwise.
     115     */
    90116    boolean setOwner(Number notebookID, Number ownerID);
    91117   
     118    /**
     119     *
     120     * @param notebookID the internal database id of a notebook.
     121     * @param principalID the internal database id of a principal.
     122     * @param access an {@link Access} object.
     123     * @return true iff the access mode to "notebookID" for "principalID" has been assigned to "access"'s value.
     124     */
    92125    boolean updatePrincipalAccessForNotebook(Number notebookID, Number principalID, Access access);
    93126   
    … …  
    99132     */
    100133   
     134    /**
     135     *
     136     * @param notebook the {@link Notebook} object representing a notebook to be created in the database.
     137     * @param ownerID the internal database id of the owner principal.
     138     * @return the internal id of the created notebook.
     139     * @throws NotInDataBaseException if creation the notebook fails.
     140     */
    101141    public Number createNotebookWithoutAccesssAndAnnotations(Notebook notebook, Number ownerID) throws NotInDataBaseException;
    102142   
     143    /**
     144     *
     145     * @param notebookID the internal database ID of a notebook.
     146     * @param annotationID the internal database ID of an annotation.
     147     * @return  true if the row for the (ntebookID,annotationID) has been added to the junction table
     148     * "notebooks_annotations".
     149     */
    103150    boolean addAnnotationToNotebook(Number notebookID, Number annotationID);
    104151   
     152    /**
     153     *
     154     * @param notebookID the internal database ID of a notebook.
     155     * @param principalID the internal database ID of a principal.
     156     * @param access access an {@link Access} object.
     157     * @return true iff the "access" mode to "notebookID" has been assigned for "principalID"
     158     * in the corresponding junction table.
     159     */
    105160    boolean addAccessToNotebook(Number notebookID, Number principalID, Access access);
    106161   
    … …  
    114169     */
    115170   
     171    /**
     172     *
     173     * @param notebookID the internal database ID of a notebook.
     174     * @param annotationID annotationID the internal database ID of an annotation.
     175     * @return  true iff the row for the (notebookID,annotationID) has been deleted from the junction table
     176     * "notebooks_annotations".
     177     */
    116178    boolean deleteAnnotationFromNotebook(Number notebookID, Number annotationID);
    117179   
     180    /**
     181     *
     182     * @param notebookID the internal database ID of a notebook.
     183     * @return true iff all the rows with "notebookID" have been removed from "notebooks_annotations" table.
     184     */
    118185    boolean deleteAllAnnotationsFromNotebook(Number notebookID);
    119186   
     187    /**
     188     *
     189     * @param notebookID the internal database ID of a notebook.
     190     * @param principalID the internal database ID of a principal.
     191     * @return true iff the row for the pair (notebookID, principlaID) has been removed from the "notebooks_principals_accesses" table.
     192     */
    120193    boolean deleteNotebookPrincipalAccess(Number notebookID, Number principalID);
    121194   
     195    /**
     196     *
     197     * @param notebookID the internal database ID of a notebook.
     198     * @return true iff all the rows with "notebookID" have been removed from from the "notebooks_principals_accesses" table.
     199     */
    122200    boolean deleteAllAccesssForNotebook(Number notebookID);
    123201   
     202    /**
     203     *
     204     * @param notebookID the internal database ID of a notebook.
     205     * @return true iff the notebook with "notebookID" has been removed from the "notebook" table.
     206     */
    124207    boolean deleteNotebook(Number notebookID);
    125208}

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

    r5661 r6004  
    3232public interface PrincipalDao extends ResourceDao{
    3333   
     34   
     35    /**
     36     *
     37     * @param internalID the internal database ID of a principal.
     38     * @return the {@link Principal} object with the internal database id "internalID".
     39     */
    3440     public Principal getPrincipal(Number internalID);
    3541     
     42     /**
     43      *
     44      * @param eMail an e-mail string.
     45      * @return the {@link Principal} object with th e-mail "email".
     46      * @throws NotInDataBaseException, if such a principal is not found.
     47      */
    3648     public Principal getPrincipalByInfo(String  eMail) throws NotInDataBaseException;
    3749     
     50     /**
     51      *
     52      * @return  the internalID of a principal who is the admin of the data base (the first admin in the list of admins).
     53      */
    3854     public Number getDBAdminID();
    3955     
    40      // where is it used?
     56    /**
     57     *
     58     * @param principalID the internal database id of a principal.
     59     * @return true iff "principalID" occurs in one of the junction tables.
     60     */
    4161     public boolean principalIsInUse(Number principalID);
    4262     
    43      // where is it used??
     63     /**
     64      *
     65      * @param remoteID the string representing the remote id of a principal.
     66      * @return true iff a principal with "remoteID" exists in the table "principal".
     67      */
    4468     public boolean principalExists(String remoteID);
    4569     
     70     /**
     71      *
     72      * @param internalID the internal database id of a principal.
     73      * @return the type of a principal account: admin, developer, user.
     74      */
    4675     public String getTypeOfPrincipalAccount(Number internalID);
    4776     
     77     /**
     78      *
     79      * @param internalID the internal database id of a principal.
     80      * @return the string representing the remote id of the principal.
     81      */
    4882     public String getRemoteID(Number internalID);
    4983     
    5084     
     85     /**
     86      *
     87      * @param remoteID the string representing the remote id of a principal.
     88      * @return the interna ld database id of the principal with "remotedID".
     89      * @throws NotInDataBaseException if there is no principal with "remoteID".
     90      */
    5191     public Number getPrincipalInternalIDFromRemoteID(String remoteID) throws NotInDataBaseException;
    5292     
     93     /**
     94      *
     95      * @param remoteID the string representing the remote id of a principal.
     96      * @return the external UUID of the principal with "remotedID".
     97      * @throws NotInDataBaseException  if there is no principal with "remoteID".
     98      */
    5399     public UUID getPrincipalExternalIDFromRemoteID(String remoteID) throws NotInDataBaseException;
    54100     
     101     /**
     102      *
     103      * @param fullName the string representing the full name of a principal.
     104      * @return the external UUID of the principal with "fullName.
     105      * @throws NotInDataBaseException if there is no principal with "fullName".
     106      */
    55107     public UUID getExternalIdFromName(String fullName) throws NotInDataBaseException;
    56108     
     109     /**
     110      *
     111      * @param notebookID the internal database id of a notebook.
     112      * @param access an {@link Access} object.
     113      * @return  the list of internal database ids of the principals which have access "access"-value
     114      * for the "notebookID".
     115      */
    57116     public List<Number> getPrincipalIDsWithAccessForNotebook(Number notebookID, Access access);
    58117     
     118  /**
     119   *
     120   * @param externalID the external UUID of a principal.
     121   * @param account a string representing the type of an account: admin, developer, user.
     122   * @return true, if the account of "externalId" has been updated to "account".
     123   * @throws NotInDataBaseException iff no principal with "externalId" is found.
     124   */
    59125     public boolean updateAccount(UUID externalID, String account) throws NotInDataBaseException;
    60126     
     127     /**
     128      *
     129      * @param principal a {@link Principal} object which must update the principal referred by "externakId" given in this object.
     130      * @return the internal id of a principal which has been updated.
     131      * @throws NotInDataBaseException if principal with the externalId given in the "principal" is not found.
     132      */
    61133     public Number updatePrincipal(Principal principal) throws NotInDataBaseException;
    62134   
     135     /**
     136      *
     137      * @param principal a {@link Principal} object to be added to the database.
     138      * @param remoteID a string representing the remote of of the principal to be added.
     139      * @return the internal id of the just added principal.
     140      * @throws NotInDataBaseException if adding the principal fails.
     141      */
    63142     public Number addPrincipal(Principal principal, String remoteID) throws NotInDataBaseException;
    64143     
     144     /**
     145      *
     146      * @param username the name of a user for spring basic authentication.
     147      * @param password a password of a user for spring authentication.
     148      * @param strength the strength of a password.
     149      * @param salt
     150      * @return a number of added rows in "users" table; must be 1 of the user is added.
     151      */
    65152     public int addSpringUser(String username, String password, int strength, String salt);
    66153     
     154     /**
     155      *
     156      * @param username the name of a user for spring basic authentication.
     157      * @return the amount of rows added o "authorities" tables; "1" if "username" is added with the default "ROLE_USER"; 0 otherwise.
     158      */
    67159     public int addSpringAuthorities(String username);
    68160     
     161     /**
     162      *
     163      * @param intenralID the internal ID of a principal to be deleted,
     164      * @return the amount f deleted rows; "1" if deleted, "0" otherwise.
     165      * @throws PrincipalCannotBeDeleted if the principal is in use, i.e. mentioned in one of the junction tables.
     166      */
    69167     public int deletePrincipal(Number intenralID) throws PrincipalCannotBeDeleted;
    70168     

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

    r5468 r6004  
    2525
    2626/**
    27  *
     27 * This interfaces describes signatures common for all resources: Annotation, Target, Cached Representation, Principal, Notebook;
     28 * the implementation must contain field "resourceTableName" whose value is one of the five names of resource tables:
     29 * "annotation", "target", "cached_representation", "principal", "notebook".
    2830 * @author olhsha
    2931 */
    3032public interface ResourceDao {
    3133
     34    /**
     35     *
     36     * @param relResourcePath a string, representing "[relative-servise-url]/[resource]", e.g. "my-servlet/annotations".
     37     */
    3238    void setResourcePath(String relResourcePath);
    3339
     40    /**
     41     *
     42     * @param externalId the external UUId of a resource.
     43     * @return the internal ID of the resource.
     44     * @throws NotInDataBaseException if the resource with this id is not found.
     45     */
    3446    Number getInternalID(UUID externalId) throws NotInDataBaseException;
    3547
     48    /**
     49     *
     50     * @param internalId the internal ID of the resource.
     51     * @return  the external UUID of the resource.
     52     */
    3653    UUID getExternalID(Number internalId);
    3754
     55    /**
     56     *
     57     * @param oldIdentifier the current external UUId of a resource.
     58     * @param newIdentifier the new external ID of the resource.
     59     * @return true iff the external id of the resource have been updated to the value of "newIDentifier".
     60     */
    3861    boolean updateResourceIdentifier(UUID oldIdentifier, UUID newIdentifier);
    3962 
    4063    /**
    4164     *
    42      * @param internalID
    43      * @return URI string of the resource )of the type set in resourceTableName)
    44      * with internalID
     65     * @param internalID the internal databaseID of the resource.
     66     * @return the hyper-reference string of the resource with "internalID".
    4567     */
    4668    String getHrefFromInternalID(Number internalID);
    4769   
     70    /**
     71     *
     72     * @param href the hyper-reference of a resource.
     73     * @return  the internal ID of the resource with "href".
     74     * @throws NotInDataBaseException if the resource with ""href" is not found in the corresponding database.
     75     */
    4876    Number getInternalIDFromHref(String href)  throws NotInDataBaseException;
    4977
     78    /**
     79     *
     80     * @param resourceID the internal database id of a resource.
     81     * @return mapping "principal internal id" -> "access" for a given "resourceID";
     82     * till now makes sense only for annotations and notebooks.
     83     */
    5084    List<Map<Number, String>> getPermissions(Number resourceID);
    5185
     86    /**
     87     *
     88     * @param resourceID the internal database id of a resource.
     89     * @return the public access mode for "resourceID"; till now makes sense only for annotations and notebooks.
     90     */
    5291    Access getPublicAttribute(Number resourceID);
    5392   

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

    r5385 r6004  
    3737    /**
    3838     *
    39      * @param inernalID
    40      * @return the Target with the intrenal Id "internalID".
     39     * @param inernalID the internal database id of a target.
     40     * @return the {@link Target} object with the intrenal Id "internalID".
    4141     */
    4242    public Target getTarget(Number internalID);
    … …  
    4444    /**
    4545     *
    46      * @param targets
    47      * @return the list of TargetInfo objects corresponding to the Targets with
    48      * the internalIds from the list "Targets".
     46     * @param targets the list of internal database ids of targets.
     47     * @return the list of {@link TargetInfo} objects corresponding to the targets with the internalIds from the list "targets".
    4948     */
    5049    public List<TargetInfo> getTargetInfos(List<Number> targets);
    … …  
    5251    /**
    5352     *
    54      * @param targetID
    55      * @return the list of pairs (cached_representation_id, fragment_descriptor)
    56      * for the target with the internal ID "targetID".
     53     * @param targetID the internal database id of a target.
     54     * @return the list of pairs "cached_representation_id -> fragment_descriptor" for the target with the internal ID "targetID".
    5755     */
    5856    public Map<Number, String> getCachedRepresentationFragmentPairs(Number targetID);
    … …  
    6260    /**
    6361     *
    64      * @param targetID
    65      * @return The link (uri) to the source to which the target refers
     62     * @param targetID the internal database id of a target.
     63     * @return The link (uri) to the source to which the target refers.
    6664     */
    6765    public String getLink(Number targetID);
    … …  
    6967    /**
    7068     *
    71      * @param link
    72      * @return the list of Target ID's which link-fields is exactly "link"
     69     * @param link a string representing a link (uri) to a target source.
     70     * @return the list of internal database target ID's whose link-fields is exactly "link".
    7371     */
    7472    public List<Number> getTargetsForLink(String link);
    7573
     74  /**
     75   *
     76   * @param cachedID the internal database id of a cached representation.
     77   * @return true iff "cachedID" is referred to for some target in "targets_cached_representations" table.
     78   */
    7679    boolean cachedIsInUse(Number cachedID);
    7780
Note: See TracChangeset for help on using the changeset viewer.