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