cdmlib-persistence/src/main/java/eu/etaxonomy/cdm/persistence/dao/common/IIdentifiableDao.java

   1 /**
   2 * Copyright (C) 2007 EDIT
   3 * European Distributed Institute of Taxonomy
   4 * http://www.e-taxonomy.eu
   5 *
   6 * The contents of this file are subject to the Mozilla Public License Version 1.1
   7 * See LICENSE.TXT at the top of this package for the full license terms.
   8 */
   9
  10 package eu.etaxonomy.cdm.persistence.dao.common;
  11
  12 import java.util.List;
  13 import java.util.UUID;
  14
  15 import org.hibernate.criterion.Criterion;
  16
  17 import eu.etaxonomy.cdm.model.common.IdentifiableEntity;
  18 import eu.etaxonomy.cdm.model.common.IdentifiableSource;
  19 import eu.etaxonomy.cdm.model.common.LSID;
  20 import eu.etaxonomy.cdm.model.common.MarkerType;
  21 import eu.etaxonomy.cdm.model.media.Rights;
  22 import eu.etaxonomy.cdm.model.term.DefinedTerm;
  23 import eu.etaxonomy.cdm.persistence.dao.initializer.IBeanInitializer;
  24 import eu.etaxonomy.cdm.persistence.dto.UuidAndTitleCache;
  25 import eu.etaxonomy.cdm.persistence.query.MatchMode;
  26 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  27
  28 public interface IIdentifiableDao <T extends IdentifiableEntity>
  29         extends IAnnotatableDao<T>, ITitledDao<T>, ISearchableDao<T>{
  30
  31         /**
  32          * Return an object by LSID. NOTE: Because of the fact that LSIDs are supposed to
  33          * be globally resolvable, this method behaves in a different way to other methods
  34          *
  35          * In short, it attempts to find an object of type T in the current view using the LSID passed. If the LSID passed has a
  36          * revision part, then this will be used in the query, but if not, then it is expected that the request is for the 'current'
  37          * version of the object and the revision part will not be used as a matching criteria in the query.
  38          *
  39          * If the object does not appear in the current view (i.e. it has been deleted), then this method will search the history
  40          * tables for a match, again using the revision if it exists, but ignoring it if not.
  41          *
  42          *  @param lsid a LifeScience Identifier identifying the desired object
  43          */
  44         public T find(LSID lsid);
  45
  46         /**
  47          * Return a count of the sources for this identifiable entity
  48          *
  49          * @param identifiableEntity The identifiable entity
  50          * @return a count of OriginalSource instances
  51          */
  52         public long countSources(T identifiableEntity);
  53
  54         /**
  55          * Return a List of the sources for this identifiable entity
  56          *
  57          * @param identifiableEntity The identifiable entity
  58          * @param pageSize The maximum number of sources returned (can be null for all sources)
  59          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
  60          * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
  61          * @return a List of OriginalSource instances
  62          */
  63         public List<IdentifiableSource> getSources(T identifiableEntity, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
  64
  65         /**
  66          * Return a count of the rights for this identifiable entity
  67          *
  68          * @param identifiableEntity The identifiable entity
  69          * @return a count of Rights instances
  70          */
  71     public long countRights(T identifiableEntity);
  72
  73
  74         /**
  75          * Return a List of the rights for this identifiable entity
  76          *
  77          * @param identifiableEntity The identifiable entity
  78          * @param pageSize The maximum number of rights returned (can be null for all rights)
  79          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
  80          * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
  81          * @return a List of Rights instances
  82          */
  83         public List<Rights> getRights(T identifiableEntity, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
  84
  85         // TODO Migrated from IOriginalSourceDao
  86         public List<T> findOriginalSourceByIdInSource(String idInSource, String idNamespace);
  87
  88
  89
  90     /**
  91      * Returns the titleCache for a given object defined by uuid.
  92      * @param uuid the uuid of the requested object.
  93      * @param refresh if false the value as stored in the DB is returned,
  94      *      otherwise it is recomputed by loading the object and calling the formatter.
  95      * @return the titleCache of the requested object
  96      */
  97     public String getTitleCache(UUID uuid, boolean refresh);
  98
  99     /**
 100     * Return a List of objects matching the given query string, optionally filtered by class, optionally with a particular MatchMode
 101     *
 102     * @param clazz filter by class - can be null to include all instances of type T
 103     * @param queryString the query string to filter by
 104     * @param matchmode use a particular type of matching (can be null - defaults to exact matching)
 105     * @param criteria extra restrictions to apply
 106     * @param pageSize The maximum number of rights returned (can be null for all rights)
 107     * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 108     * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
 109     * @param orderHints
 110     *            Supports path like <code>orderHints.propertyNames</code> which
 111     *            include *-to-one properties like createdBy.username or
 112     *            authorTeam.persistentTitleCache
 113     * @return a List of instances of type T matching the queryString
 114     */
 115    public <S extends T> List<S> findByTitle(Class<S> clazz, String queryString,MatchMode matchmode, List<Criterion> criteria, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 116
 117
 118          /**
 119          * Return a List of objects matching the given query string, optionally filtered by class, optionally with a particular MatchMode
 120          *
 121          * @param clazz filter by class - can be null to include all instances of type T
 122          * @param queryString the query string to filter by
 123          * @param matchmode use a particular type of matching (can be null - defaults to exact matching)
 124      * @param restrictions a <code>List</code> of additional {@link Restriction}s to filter by
 125          * @param pageSize The maximum number of rights returned (can be null for all rights)
 126          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 127          * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
 128          * @param orderHints
 129          *            Supports path like <code>orderHints.propertyNames</code> which
 130          *            include *-to-one properties like createdBy.username or
 131          *            authorTeam.persistentTitleCache
 132          * @return a List of instances of type T matching the queryString
 133          */
 134         public <S extends T> List<S> findByTitleWithRestrictions(Class<S> clazz, String queryString,MatchMode matchmode, List<Restriction<?>> restrictions, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 135
 136
 137
 138         /**
 139          * TODO
 140          * @param clazz
 141          * @param queryString
 142          * @param pageSize
 143          * @param pageNumber
 144          * @param orderHints
 145          * @param matchMode
 146          * @return
 147          */
 148         public List<String> findTitleCache(Class<? extends T> clazz, String queryString, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, MatchMode matchMode);
 149     /**
 150     * Return a List of objects matching the given query string, optionally filtered by class, optionally with a particular MatchMode
 151     *
 152     * @param clazz filter by class - can be null to include all instances of type T
 153     * @param queryString the query string to filter by
 154     * @param matchmode use a particular type of matching (can be null - defaults to exact matching)
 155     * @param criteria extra restrictions to apply
 156     * @param pageSize The maximum number of rights returned (can be null for all rights)
 157     * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 158     * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
 159     * @param orderHints
 160     *            Supports path like <code>orderHints.propertyNames</code> which
 161     *            include *-to-one properties like createdBy.username or
 162     *            authorTeam.persistentTitleCache
 163     * @return a List of instances of type T matching the queryString
 164     */
 165    public <S extends T> List<S> findByReferenceTitle(Class<S> clazz, String queryString,MatchMode matchmode, List<Criterion> criteria, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 166
 167          /**
 168          * Return a List of objects matching the given query string, optionally filtered by class, optionally with a particular MatchMode
 169          *
 170          * @param clazz filter by class - can be null to include all instances of type T
 171          * @param queryString the query string to filter by
 172          * @param matchmode use a particular type of matching (can be null - defaults to exact matching)
 173      * @param restrictions a <code>List</code> of additional {@link Restriction}s to filter by
 174          * @param pageSize The maximum number of rights returned (can be null for all rights)
 175          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 176          * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
 177          * @param orderHints
 178          *            Supports path like <code>orderHints.propertyNames</code> which
 179          *            include *-to-one properties like createdBy.username or
 180          *            authorTeam.persistentTitleCache
 181          * @return a List of instances of type T matching the queryString
 182          */
 183         public <S extends T> List<S> findByReferenceTitleWithRestrictions(Class<S> clazz, String queryString,MatchMode matchmode, List<Restriction<?>> restrictions, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 184
 185         /**
 186      * Return a count of objects matching the given query string in the titleCache, optionally filtered by class, optionally with a particular MatchMode
 187      *
 188      * @param clazz filter by class - can be null to include all instances of type T
 189      * @param queryString the query string to filter by
 190      * @param matchmode use a particular type of matching (can be null - defaults to exact matching)
 191      * @param criteria extra restrictions to apply
 192      * @return a count of instances of type T matching the queryString
 193      */
 194     public long countByTitle(Class<? extends T> clazz, String queryString, MatchMode matchmode, List<Criterion> criteria);
 195
 196         /**
 197          * Return a count of objects matching the given query string in the titleCache, optionally filtered by class, optionally with a particular MatchMode
 198          *
 199          * @param clazz filter by class - can be null to include all instances of type T
 200          * @param queryString the query string to filter by
 201          * @param matchmode use a particular type of matching (can be null - defaults to exact matching)
 202      * @param restrictions a <code>List</code> of additional {@link Restriction}s to filter by
 203          * @return a count of instances of type T matching the queryString
 204          */
 205         public long countByTitleWithRestrictions(Class<? extends T> clazz, String queryString, MatchMode matchmode,  List<Restriction<?>> restrictions);
 206
 207         /**
 208      * Return a count of objects matching the given query string in the title, optionally filtered by class, optionally with a particular MatchMode
 209      *
 210      * @param clazz filter by class - can be null to include all instances of type T
 211      * @param queryString the query string to filter by
 212      * @param matchmode use a particular type of matching (can be null - defaults to exact matching)
 213      * @param criteria extra restrictions to apply
 214      * @return a count of instances of type T matching the queryString
 215      */
 216     public long countByReferenceTitle(Class<? extends T> clazz, String queryString, MatchMode matchmode, List<Criterion> criteria);
 217
 218         /**
 219          * Return a count of objects matching the given query string in the title, optionally filtered by class, optionally with a particular MatchMode
 220          *
 221          * @param clazz filter by class - can be null to include all instances of type T
 222          * @param queryString the query string to filter by
 223          * @param matchmode use a particular type of matching (can be null - defaults to exact matching)
 224      * @param restrictions a <code>List</code> of additional {@link Restriction}s to filter by
 225          * @return a count of instances of type T matching the queryString
 226          */
 227         public long countByReferenceTitleWithRestrictions(Class<? extends T> clazz, String queryString, MatchMode matchmode, List<Restriction<?>> restrictions);
 228
 229         /**
 230          * Return a count of distinct titleCache Strings for a given {@link IdentifiableEntity}, optionally filtered by class, optionally with a particular MatchMode
 231          *
 232          * @param clazz filter by class - can be null to include all instances of type T
 233          * @param queryString the query string to filter by
 234          * @param matchmode use a particular type of matching (can be null - defaults to exact matching)
 235          * @return a count of instances of type T matching the queryString
 236          */
 237         public abstract Long countTitleCache(Class<? extends T> clazz, String queryString, MatchMode matchMode);
 238
 239
 240         /**
 241          * Return a count of entities having an {@link Identifier} that matches the given parameters.
 242          * @param clazz the entities class
 243          * @param identifier the identifier string
 244          * @param identifierType the identifier type
 245          * @param matchmode
 246          * @see #findByIdentifier
 247          * @return
 248          */
 249         public <S extends T> long countByIdentifier(Class<S> clazz, String identifier, DefinedTerm identifierType, MatchMode matchmode);
 250
 251     /**
 252      * Returns a tuple including the identifier type, the identifier string,
 253      * and if includeEntity is <code>false</code> the CDM entities uuid, and titleCache,
 254      * otherwise the CDM entity itself
 255      * @param clazz the identifiable entity subclass, may be null
 256      * @param identifier the identifier as {@link String}
 257      * @param identifierType the identifier type, maybe null
 258      * @param matchmode
 259      * @param includeCdmEntity
 260      * @param pageSize
 261      * @param pageNumber
 262      * @param propertyPaths
 263      * @see #countByIdentifier(Class, String, DefinedTerm, MatchMode)
 264      * @return
 265      */
 266     public <S extends T> List<Object[]> findByIdentifier(Class<S> clazz, String identifier, DefinedTerm identifierType, MatchMode matchmode, boolean includeCdmEntity, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 267
 268     /**
 269      * @param clazz
 270      * @param markerType
 271      * @param markerValue
 272      * @param includeEntity
 273      * @param pageSize
 274      * @param pageNumber
 275      * @param propertyPaths
 276      * @return
 277      */
 278     public <S extends T> long countByMarker(Class<S> clazz, MarkerType markerType, Boolean markerValue);
 279
 280     /**
 281      * @param clazz
 282      * @param markerType
 283      * @param markerValue
 284      * @param includeEntity
 285      * @param pageSize
 286      * @param pageNumber
 287      * @param propertyPaths
 288      * @return
 289      */
 290     public <S extends T> List<Object[]> findByMarker(Class<S> clazz, MarkerType markerType, Boolean markerValue, boolean includeEntity,
 291             Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 292
 293     /**
 294      * Return a list of all uuids mapped to titleCache in the convenient <code>UuidAndTitleCache</code> object.
 295      * Retrieving this list is considered to be significantly faster than initializing the fully fledged buiseness
 296      * objects. To be used in cases where you want to present large amount of data and provide details after
 297      * a selection has been made.
 298      *
 299      * @return a list of <code>UuidAndTitleCache</code> instances
 300      * @see #getUuidAndTitleCache(Class, Integer, String)
 301      */
 302     public List<UuidAndTitleCache<T>> getUuidAndTitleCache(Integer limit, String pattern);
 303
 304     /**
 305      * Like {@link #getUuidAndTitleCache(Integer, String)} but searching only on a subclass
 306      * of the type handled by the DAO.
 307      *
 308      * @param clazz the (sub)class
 309      * @param limit max number of results
 310      * @param pattern search pattern
 311
 312      * @see #getUuidAndTitleCache(Integer, String)
 313      */
 314     public <S extends T> List<UuidAndTitleCache<S>> getUuidAndTitleCache(Class<S> clazz, Integer limit, String pattern);
 315
 316
 317     /**
 318      * Return a list of all uuids mapped to titleCache in the convenient <code>UuidAndTitleCache</code> object.
 319      * Retrieving this list is considered to be significantly faster than initializing the fully fledged buiseness
 320      * objects. To be used in cases where you want to present large amount of data and provide details after
 321      * a selection has been made.
 322      *
 323      * @return a list of <code>UuidAndTitleCache</code> instances
 324      */
 325     public List<UuidAndTitleCache<T>> getUuidAndTitleCache();
 326
 327     /**
 328      *
 329      * Like {@link #getUuidAndTitleCache(Integer, String)} but searching only for elements with a marker of markertype
 330      * matching the given parameter
 331      * @param limit
 332      * @param pattern
 333      * @param markerType
 334      * @return
 335      */
 336     List<UuidAndTitleCache<T>> getUuidAndTitleCacheByMarker(Integer limit, String pattern, MarkerType markerType);
 337
 338 }