cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/IIdentifiableEntityService.java

   1 // $Id$
   2 /**
   3 * Copyright (C) 2007 EDIT
   4 * European Distributed Institute of Taxonomy
   5 * http://www.e-taxonomy.eu
   6 *
   7 * The contents of this file are subject to the Mozilla Public License Version 1.1
   8 * See LICENSE.TXT at the top of this package for the full license terms.
   9 */
  10
  11 package eu.etaxonomy.cdm.api.service;
  12
  13 import java.util.List;
  14
  15 import org.hibernate.criterion.Criterion;
  16
  17 import eu.etaxonomy.cdm.api.service.config.IIdentifiableEntityServiceConfigurator;
  18 import eu.etaxonomy.cdm.api.service.dto.FindByIdentifierDTO;
  19 import eu.etaxonomy.cdm.api.service.pager.Pager;
  20 import eu.etaxonomy.cdm.common.monitor.IProgressMonitor;
  21 import eu.etaxonomy.cdm.model.common.DefinedTerm;
  22 import eu.etaxonomy.cdm.model.common.ISourceable;
  23 import eu.etaxonomy.cdm.model.common.IdentifiableEntity;
  24 import eu.etaxonomy.cdm.model.common.IdentifiableSource;
  25 import eu.etaxonomy.cdm.model.common.LSID;
  26 import eu.etaxonomy.cdm.model.media.Rights;
  27 import eu.etaxonomy.cdm.persistence.dao.initializer.IBeanInitializer;
  28 import eu.etaxonomy.cdm.persistence.dto.UuidAndTitleCache;
  29 import eu.etaxonomy.cdm.persistence.query.MatchMode;
  30 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  31 import eu.etaxonomy.cdm.strategy.cache.common.IIdentifiableEntityCacheStrategy;
  32 import eu.etaxonomy.cdm.strategy.match.IMatchStrategy;
  33 import eu.etaxonomy.cdm.strategy.match.IMatchable;
  34 import eu.etaxonomy.cdm.strategy.merge.IMergable;
  35 import eu.etaxonomy.cdm.strategy.merge.IMergeStrategy;
  36
  37 public interface IIdentifiableEntityService<T extends IdentifiableEntity> extends IAnnotatableService<T> {
  38
  39     /**
  40      * (Re-)generate the title caches for all objects of this concrete IdentifiableEntity class.
  41      * Uses default values.
  42      * @see #updateTitleCache(Class, Integer, IIdentifiableEntityCacheStrategy, IProgressMonitor)
  43      */
  44     public void updateTitleCache();
  45
  46     /**
  47      * (Re-)generate the title caches for all objects of this concrete IdentifiableEntity class
  48      *
  49      * @param clazz class of objects to be updated
  50      * @param stepSize number of objects loaded per step. If <code>null</code> use default.
  51      * @param cacheStrategy cachestrategy used for title cache. If <code>null</code> use default.
  52      * @param monitor progress monitor. If <code>null</code> use default.
  53      */
  54     public void updateTitleCache(Class<? extends T> clazz, Integer stepSize, IIdentifiableEntityCacheStrategy<T> cacheStrategy, IProgressMonitor monitor);
  55
  56     /**
  57      * Finds an object with a given LSID. If the object does not currently exist in the current view, then
  58      * the most recent prior version of the object will be returned, or null if an object with this identifier
  59      * has never existed
  60      *
  61      * @param lsid
  62      * @return an object of type T or null of the object has never existed
  63      */
  64     public T find(LSID lsid);
  65
  66     /**
  67      * Replaces all *ToMany and *ToOne references to an object (x) with another object of the same type (y)
  68      *
  69      * Ignores ManyToAny and OneToAny relationships as these are typically involved with bidirectional
  70      * parent-child relations
  71      *
  72      * @param x
  73      * @param y
  74      * @return the replacing object (y)
  75      */
  76     public T replace(T x, T y);
  77
  78     /**
  79      * Return a Pager of sources belonging to this object
  80      *
  81      * @param t The identifiable entity
  82      * @param pageSize The maximum number of sources returned (can be null for all sources)
  83      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
  84      * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
  85      * @return a Pager of OriginalSource entities
  86      */
  87     public Pager<IdentifiableSource> getSources(T t, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
  88
  89     /**
  90      * Return a Pager of rights belonging to this object
  91      *
  92      * @param t The identifiable entity
  93      * @param pageSize The maximum number of rights returned (can be null for all rights)
  94      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
  95      * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
  96      * @return a Pager of Rights entities
  97      */
  98     public Pager<Rights> getRights(T t, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
  99
 100     /**
 101      * Return a list of all uuids mapped to titleCache in the convenient <code>UuidAndTitleCache</code> object.
 102      * Retrieving this list is considered to be significantly faster than initializing the fully fledged buiseness
 103      * objects. To be used in cases where you want to present large amount of data and provide details after
 104      * a selection has been made.
 105      *
 106      * @return a list of <code>UuidAndTitleCache</code> instances
 107      */
 108     public List<UuidAndTitleCache<T>> getUuidAndTitleCache();
 109
 110     /**
 111      * Return a Pager of objects matching the given query string, optionally filtered by class, optionally with a particular MatchMode
 112      *
 113      * @param clazz filter by class - can be null to include all instances of type T
 114      * @param queryString the query string to filter by
 115      * @param matchmode use a particular type of matching (can be null - defaults to exact matching)
 116      * @param criteria additional criteria to filter by
 117      * @param pageSize The maximum number of objects returned (can be null for all objects)
 118      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 119      * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
 120      * @param orderHints
 121      *            Supports path like <code>orderHints.propertyNames</code> which
 122      *            include *-to-one properties like createdBy.username or
 123      *            authorTeam.persistentTitleCache
 124      * @return a paged list of instances of type T matching the queryString
 125      */
 126     public Pager<T> findByTitle(Class<? extends T> clazz, String queryString,MatchMode matchmode, List<Criterion> criteria, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 127
 128
 129     /**
 130      * Return a Pager of objects matching the given query string, optionally filtered by class,
 131      * optionally with a particular MatchMode
 132      *
 133      * @return a paged list of instances of type T matching the queryString
 134      */
 135     public Pager<T> findByTitle(IIdentifiableEntityServiceConfigurator<T> configurator);
 136
 137
 138     /**
 139      * Return an Integer of how many objects matching the given query string, optionally filtered by class, optionally with a particular MatchMode
 140      *
 141      * @param clazz filter by class - can be null to include all instances of type T
 142      * @param queryString the query string to filter by
 143      * @param matchmode use a particular type of matching (can be null - defaults to exact matching)
 144      * @param criteria additional criteria to filter by
 145      *
 146      * @return
 147      */
 148     public Integer countByTitle(Class<? extends T> clazz, String queryString,MatchMode matchmode, List<Criterion> criteria);
 149
 150     /**
 151      * Return an Integer of how many objects matching the given query string, optionally filtered by class, optionally with a particular MatchMode
 152      *
 153      * @param configurator an {@link IIdentifiableEntityServiceConfigurator} object
 154      *
 155      * @return
 156      */
 157     public Integer countByTitle(IIdentifiableEntityServiceConfigurator<T> configurator);
 158
 159
 160     /**
 161      * Return a List of objects matching the given query string, optionally filtered by class, optionally with a particular MatchMode
 162      *
 163      * @param clazz filter by class - can be null to include all instances of type T
 164      * @param queryString the query string to filter by
 165      * @param matchmode use a particular type of matching (can be null - defaults to exact matching)
 166      * @param criteria additional criteria to filter by
 167      * @param pageSize The maximum number of objects returned (can be null for all objects)
 168      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 169      * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
 170      * @param orderHints
 171      *            Supports path like <code>orderHints.propertyNames</code> which
 172      *            include *-to-one properties like createdBy.username or
 173      *            authorTeam.persistentTitleCache
 174      * @return a list of instances of type T matching the queryString
 175      */
 176     public List<T> listByTitle(Class<? extends T> clazz, String queryString,MatchMode matchmode, List<Criterion> criteria, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 177
 178     /**
 179      * Return a List of objects matching the given query string, optionally filtered by class, optionally with a particular MatchMode
 180      *
 181      * @param clazz filter by class - can be null to include all instances of type T
 182      * @param queryString the query string to filter by
 183      * @param matchmode use a particular type of matching (can be null - defaults to exact matching)
 184      * @param criteria additional criteria to filter by
 185      * @param pageSize The maximum number of objects returned (can be null for all objects)
 186      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 187      * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
 188      * @param orderHints
 189      *            Supports path like <code>orderHints.propertyNames</code> which
 190      *            include *-to-one properties like createdBy.username or
 191      *            authorTeam.persistentTitleCache
 192      * @return a list of instances of type T matching the queryString
 193      */
 194     public List<T> listByReferenceTitle(Class<? extends T> clazz, String queryString,MatchMode matchmode, List<Criterion> criteria, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 195
 196     /**
 197      * Returns a Paged List of IdentifiableEntity instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
 198      *
 199      * @param clazz filter the results by class (or pass null to return all IdentifiableEntity instances)
 200      * @param queryString
 201      * @param pageSize The maximum number of identifiable entities returned (can be null for all matching identifiable entities)
 202      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 203      * @param orderHints
 204      *            Supports path like <code>orderHints.propertyNames</code> which
 205      *            include *-to-one properties like createdBy.username or
 206      *            authorTeam.persistentTitleCache
 207      * @param propertyPaths properties to be initialized
 208      * @return a Pager IdentifiableEntity instances
 209      * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
 210      */
 211     public Pager<T> search(Class<? extends T> clazz, String queryString, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 212
 213
 214     /**
 215      * This method tries to deduplicate all objects of a certain class by first trying to find matchabel objects and
 216      * merging them in a second step. For performance reasons implementing classes must not guarantee that ALL
 217      * matching object pairs are found but only a subset. But it must guarantee that only matching objects are merged.
 218      *<BR> Matching is defined by the given matching strategy or if no matching strategy is given the default matching
 219      *strategy is used.
 220      *<BR>Clazz must implement {@link IMatchable} and {@link IMergable} otherwise no deduplication is performed.
 221      *<BR>The current implementation in IdentifiableServiceBase tries to match and merge all objects with an identical non
 222      *empty titleCache.
 223      * @param clazz
 224      * @param matchStrategy
 225      * @param mergeStrategy
 226      * @return the number of merges performed during deduplication
 227      */
 228     public int deduplicate(Class<? extends T> clazz, IMatchStrategy matchStrategy, IMergeStrategy mergeStrategy);
 229
 230
 231     /**
 232      * Return a Pager of objects with distinct titleCache strings filtered by the given query string, optionally filtered by class, optionally with a particular MatchMode
 233      * @param clazz
 234      * @param queryString
 235      * @param pageSize
 236      * @param pageNumber
 237      * @param orderHints
 238      * @param matchMode
 239      * @return
 240      */
 241     public Pager<T> findTitleCache(Class<? extends T> clazz, String queryString, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, MatchMode matchMode);
 242
 243
 244     /**
 245      * Returns an Sourceable object according the
 246      * @param clazz
 247      * @param idInSource
 248      * @param idNamespace
 249      * @return
 250      */
 251     //TODO shouldn't we move this to CommonService or to a new SourceService ?
 252     //TODO should this return a List ?
 253     public ISourceable getSourcedObjectByIdInSource(Class clazz, String idInSource, String idNamespace);
 254
 255     /**
 256      * Returns a Pager for {@link FindByIdentifierDTO DTOs} that hold the identifier including type, title and uuid
 257      * and the according CDM Object information (uuid, title and the object itself (optional)).
 258      *
 259      * all {@link IdentifiableEntity identifiable entities} which have the according
 260      * identifier attached
 261      * @param clazz the identifiable entity subclass, may be null
 262      * @param identifier the identifier as {@link String}
 263      * @param identifierType the identifier type, maybe null
 264      * @param matchmode
 265      * @param includeCdmEntity if true the CDM entity is also returned (this may slow down performance for large datasets)
 266      * @param pageSize
 267      * @param pageNumber
 268      * @param propertyPaths
 269      * @return
 270      */
 271     public <S extends T> Pager<FindByIdentifierDTO<S>> findByIdentifier(Class<S> clazz, String identifier, DefinedTerm identifierType, MatchMode matchmode, boolean includeCdmEntity, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 272
 273 }