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