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