3 * Copyright (C) 2007 EDIT
4 * European Distributed Institute of Taxonomy
5 * http://www.e-taxonomy.eu
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.
11 package eu
.etaxonomy
.cdm
.api
.service
;
13 import java
.util
.List
;
15 import org
.hibernate
.criterion
.Criterion
;
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
;
37 public interface IIdentifiableEntityService
<T
extends IdentifiableEntity
> extends IAnnotatableService
<T
> {
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)
44 public void updateTitleCache();
47 * (Re-)generate the title caches for all objects of this concrete IdentifiableEntity class
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.
54 public void updateTitleCache(Class
<?
extends T
> clazz
, Integer stepSize
, IIdentifiableEntityCacheStrategy
<T
> cacheStrategy
, IProgressMonitor monitor
);
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
62 * @return an object of type T or null of the object has never existed
64 public T
find(LSID lsid
);
67 * Replaces all *ToMany and *ToOne references to an object (x) with another object of the same type (y)
69 * Ignores ManyToAny and OneToAny relationships as these are typically involved with bidirectional
70 * parent-child relations
74 * @return the replacing object (y)
76 public T
replace(T x
, T y
);
79 * Return a Pager of sources belonging to this object
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
87 public Pager
<IdentifiableSource
> getSources(T t
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
90 * Return a Pager of rights belonging to this object
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
98 public Pager
<Rights
> getRights(T t
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
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.
106 * @return a list of <code>UuidAndTitleCache</code> instances
108 public List
<UuidAndTitleCache
<T
>> getUuidAndTitleCache();
111 * Return a Pager of objects matching the given query string, optionally filtered by class, optionally with a particular MatchMode
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)}
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
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
);
130 * Return a Pager of objects matching the given query string, optionally filtered by class,
131 * optionally with a particular MatchMode
133 * @return a paged list of instances of type T matching the queryString
135 public Pager
<T
> findByTitle(IIdentifiableEntityServiceConfigurator
<T
> configurator
);
139 * Return an Integer of how many objects matching the given query string, optionally filtered by class, optionally with a particular MatchMode
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
148 public Integer
countByTitle(Class
<?
extends T
> clazz
, String queryString
,MatchMode matchmode
, List
<Criterion
> criteria
);
151 * Return an Integer of how many objects matching the given query string, optionally filtered by class, optionally with a particular MatchMode
153 * @param configurator an {@link IIdentifiableEntityServiceConfigurator} object
157 public Integer
countByTitle(IIdentifiableEntityServiceConfigurator
<T
> configurator
);
161 * Return a List of objects matching the given query string, optionally filtered by class, optionally with a particular MatchMode
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)}
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
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
);
179 * Return a List of objects matching the given query string, optionally filtered by class, optionally with a particular MatchMode
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)}
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
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
);
197 * Returns a Paged List of IdentifiableEntity instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
199 * @param clazz filter the results by class (or pass null to return all IdentifiableEntity instances)
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)
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>
211 public Pager
<T
> search(Class
<?
extends T
> clazz
, String queryString
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
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
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
224 * @param matchStrategy
225 * @param mergeStrategy
226 * @return the number of merges performed during deduplication
228 public int deduplicate(Class
<?
extends T
> clazz
, IMatchStrategy matchStrategy
, IMergeStrategy mergeStrategy
);
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
241 public Pager
<T
> findTitleCache(Class
<?
extends T
> clazz
, String queryString
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, MatchMode matchMode
);
245 * Returns an Sourceable object according the
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
);
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)).
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
265 * @param includeCdmEntity if true the CDM entity is also returned (this may slow down performance for large datasets)
268 * @param propertyPaths
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
);