Changeset 3476


Ignore:
Timestamp:
08/26/13 09:55:49 (11 years ago)
Author:
olhsha
Message:

compleeteng javadoc comments for dispatcher' signatures

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

Legend:

Unmodified
Added
Removed

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

    r3475 r3476  
    3737   
    3838   
    39     ////////////// GETTERS //////////////////////////
     39    /**
     40     * GETTERS
     41     */
    4042   
    4143    /**
    … …  
    117119    public boolean annotationIsInUse(Number annotationID);
    118120   
    119     ///////////// ADDERS /////////////////////
     121    /**
     122     * ADDERS
     123     */
    120124   
    121125    /**
    … …  
    161165   
    162166   
    163     //////////// DELETERS ///////////////////////
     167   /**
     168    * DELETERS
     169    */
    164170   
    165171    /**

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

    r3475 r3476  
    2727   
    2828   
    29  
     29    /** GETTERS
     30     *
     31     */
    3032 
    3133    /**
    … …  
    3739   
    3840 
     41    /**
     42     * ADDERS
     43     */
     44   
    3945     /**
    4046     *
    … …  
    4450    public Number addCachedRepresentationInfo(CachedRepresentationInfo cached);
    4551   
    46    
     52   /**
     53    * DELETERS
     54    */
    4755    /**
    4856     *

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

    r3461 r3476  
    3131 *
    3232 * @author olhsha
    33  */
     33 *
     34 * Resource  and the corresponding Dao's are, so to say, "lavelled".  Notebook has level 5, Annotation has level 4, Source has level 3, Version has level 2 and CachedRepresentation has level 1. Users are not subject to this hierarchy.
     35 * The hierarchy is based on the way the schemas  for the resources are designed: to describe resource of the level X we need resource X-1.
     36 *
     37 * DaoDispathcer class contains "getters", "adders" and "deleters".
     38 *
     39 * An <adder> has two parameters: <resource<X>ID> and <resource<X-1>Object>. It return numbers of updated rows.
     40 *
     41 * A <deleter> has one parameter: <resource<X>ID>. First, it checks if <resource<X>ID> is in use by calling <X>isInUse of the corresponding Dao..
     42 * If "yes" the nothing happens. Otherwise  the deletion proceeds.
     43 * Second, delete<X> is called from the corresponding Dao.
     44 * Third, delete<X-1> are recursively called for all the related sub-resources of the level X-1. E.g., after deleting an annotation itself all the sources (which are not used by other annotations) must be deleted as well.
     45 **/
     46
     47/**
     48 *
     49 * Comments on Dao-classes.
     50 *
     51 * -- Each Dao-class contains "isInUse(internalID") method. It return "true" if the resource  with ID occurs at least in one of the joint tables. Used in "delete(internalID)" methods.
     52 *
     53 * -- If the resource with "internalID" is asked to be deleted, the deletion methods will first call "isInUse(internalID)". If it returns 'true" nothing will happen. Otherwise deletion is happen.
     54 *
     55 * -- every "add(object)" method return the added object new internalID or null if the DB has not been updated for some reason.
     56 *
     57 **/
     58
     59
    3460public interface DaoDispatcher{
    3561   
    3662    public void setServiceURI(String serviceURI);
    37 
    38     /////////////// ADDERS  /////////////////////////////////
    39     Number[] addCachedForVersion(Number versionID, CachedRepresentationInfo cached);
    40 
    41     Number[] addSiblingVersionForSource(Number sourceID, Version version) throws SQLException;
    42 
    43     Map<String, String> addSourcesForAnnotation(Number annotationID, List<NewOrExistingSourceInfo> sources) throws SQLException;
    44 
    45     Number addUsersAnnotation(Annotation annotation, Number userID) throws SQLException;
    46 
    47     int[] deleteAllCachedOfVersion(Number versionID);
    48 
    49     int[] deleteAllVersionsOfSource(Number sourceID) throws SQLException;
    50 
    51     int[] deleteAnnotation(Number annotationID) throws SQLException;
    52 
    53     ////////////// DELETERS //////////////////
    54     int[] deleteCachedOfVersion(Number versionID, Number cachedID);
    55 
    56     Annotation getAnnotation(Number annotationID) throws SQLException;
    57 
     63   
     64   
     65    /**
     66     * GETTERS
     67     */
     68   
     69    /**
     70     *
     71     * @param UUID
     72     * @return the internal identifier of the annotations with "externalID", or null if no such annotation.
     73     */
     74    Number getAnnotationInternalIdentifier(UUID externalID);
     75   
     76    /**
     77     *
     78     * @param annotationID
     79     * @return the externalID of the annotation with "internalID" or null if there is no such annotation.
     80     */
    5881    UUID getAnnotationExternalIdentifier(Number annotationID);
    5982
    60     ///////////// GETTERS //////////////////////////
    61     Number getAnnotationInternalIdentifier(UUID UUID);
    62 
    63     ////////////////////////////////////////////////////////////////////////
     83
     84   /**
     85    *
     86    * @param link
     87    * @param text
     88    * @param access
     89    * @param namespace
     90    * @param owner
     91    * @param after
     92    * @param before
     93    * @return the list of internal id-s of the annotations such that:
     94    * -- sources' links of which contain "link" (as a substring),
     95    * -- serialized bodies of which contain "text",
     96    * -- current user has "access" (owner, reader, writer)  to them,
     97    * -- namespace ???,
     98    * -- owned by "owner",
     99    * -- created after time-samp "after and before time-stamp "before".
     100    */
    64101    List<Number> getFilteredAnnotationIDs(String link, String text, String access, String namespace, UUID
    65102            owner, Timestamp after, Timestamp before);
    66103
     104    /**
     105     *
     106     * @param userID
     107     * @return the external identifier of the user "userID", or null if no such user.
     108     */
    67109    UUID getUserExternalIdentifier(Number userID);
    68110
    69     Number getUserInternalIdentifier(UUID UUID);
     111    /**
     112     *
     113     * @param externalID
     114     * @return the internal identifier of the user with "externalID", or null if there is no such user.
     115     */
     116    Number getUserInternalIdentifier(UUID externalID);
     117   
     118    /**
     119     *
     120     * @param annotationID
     121     * @return the object Annotation generated from the tables "annotation", "annotations_target_sources", "source", "annotations_principals_permissions".
     122     * @throws SQLException
     123     */
     124    Annotation getAnnotation(Number annotationID) throws SQLException;
     125
     126   
     127   /**
     128    * ADDERS
     129    */
     130    /**
     131     *
     132     * @param versionID
     133     * @param cached
     134     * @return result[0] = # updated rows in the table "versions_cached_representations" (must be 1 or 0).
     135     * result[1] = the internal ID of the added cached (a new one if "cached" was new for the Data Base).
     136     */
     137    Number[] addCachedForVersion(Number versionID, CachedRepresentationInfo cached);
     138   
     139   
     140
     141    /**
     142     *
     143     * @param sourceID
     144     * @param version
     145     * @return result[0] = added rows in the table "sources_versions" (1, or 0)
     146     * result[1] = the internal id of the added "version" ( a new one if the version was new for the DB
     147     * @throws SQLException
     148     */
     149   
     150    Number[] addSiblingVersionForSource(Number sourceID, Version version) throws SQLException;
     151
     152   
     153    /**
     154     *
     155     * @param annotationID
     156     * @param sources
     157     * @return map temporarySourceID |--> sourceExternalID. Its domain is the temporary IDs of all the new sources. While adding a new source a new external ID is generated for it and it becomes the value of the map. The sourceIDs which are already present in the DB are not in the domain. If all sources are old, then the map is empty.
     158     * @throws SQLException
     159     */
     160    Map<String, String> addSourcesForAnnotation(Number annotationID, List<NewOrExistingSourceInfo> sources) throws SQLException;
     161
     162    /**
     163     *
     164     * @param annotation
     165     * @param userID
     166     * @return the internalId of the just added "annotation" (or null if it is not added) by the owner "userID".
     167     * calls "addSourcesForAnnotation"
     168     * @throws SQLException
     169     */
     170    Number addUsersAnnotation(Annotation annotation, Number userID) throws SQLException;
     171
     172    /**
     173     * DELETERS
     174     */
     175   
     176    /**
     177     *
     178     * @param versionID
     179     * @param cachedID
     180     * @return result[0] = # deleted rows in the table "versions_cached_representations" (1, or 0).
     181     * result[1] = # deleted rows in the table "cached_representation" (should be 0 if the cached representation is in use by some other version).
     182     */
     183    int[] deleteCachedOfVersion(Number versionID, Number cachedID);
     184
     185
     186
     187   
     188    /**
     189     *
     190     * @param versionID
     191     * @return result[0] = # deleted tows in the table "version".
     192     * result[1] =  # deleted rows in the table "versions_cached_representations".
     193     * result[2] = # deleted rows in the table "cached_representation".
     194     * If the version "versionId" is in use (occurs in at least one of the joint tables) then nothing happes in the DB and all the three values result[0], result[1] and result[2] are zeros.
     195     */
     196   
     197    int[] deleteAllCachedOfVersion(Number versionID);
     198
     199   
     200   /**
     201    *
     202    * @param sourceID
     203    * @return result[0] = # deleted rows in the table "source" ( 0 is the source is in use).
     204    * result[1] = # deleted rows in the table "sources_versions".
     205    * result[2] = # deleted rows in the table source.
     206    * @throws SQLException
     207    */
     208    int[] deleteAllVersionsOfSource(Number sourceID) throws SQLException;
     209
     210    /**
     211     *
     212     * @param annotationID
     213     * @return result[0] = # deleted rows in the table "annotation" (1 or 0).
     214     * result[1] = # deleted rows in the table "annotations_principals_permissions".
     215     * result[2] = # deleted rows in the table "annotations_target_sources".
     216     * result[3] = # deleted rows in the table "source".
     217     * @throws SQLException
     218     */
     219    int[] deleteAnnotation(Number annotationID) throws SQLException;
     220
     221   
    70222   
    71223}

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

    r3475 r3476  
    3737
    3838   
    39     ////////// GETTERS /////////////////////
     39    /**
     40     *
     41     * GETTERS
     42     *
     43     */
    4044    // Returns a list of notebook-info for the notebooks accessible to the current user.
    4145    List<NotebookInfo> getNotebookInfos(UUID userID);
    … …  
    7478   
    7579   
    76     ////////////  ADDERS ///////////////////////////
     80    /**
     81     *
     82     *  ADDERS
     83     */
    7784   
    7885    // Creates a new notebook and returns the _nid_ of the created Notebook
    … …  
    8491   
    8592   
    86     ///////////// DELETERS ///////////////
     93   /**
     94    *
     95    * DELETE
     96    *
     97    */
    8798   
    8899    // Delete _nid_. Annotations stay, they just lose connection to _nid_.<br>

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

    r3461 r3476  
    7878
    7979    @Override
    80     public Number getAnnotationInternalIdentifier(UUID UUID) {
    81         return annotationDao.getInternalID(UUID);
     80    public Number getAnnotationInternalIdentifier(UUID externalID) {
     81        return annotationDao.getInternalID(externalID);
    8282    }
    8383
    … …  
    8888
    8989    @Override
    90     public Number getUserInternalIdentifier(UUID UUID) {
    91         return userDao.getInternalID(UUID);
     90    public Number getUserInternalIdentifier(UUID externalID) {
     91        return userDao.getInternalID(externalID);
    9292    }
    9393
Note: See TracChangeset for help on using the changeset viewer.