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