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