3 * Copyright (C) 2009 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
.io
.IOException
;
14 import java
.util
.Collection
;
15 import java
.util
.List
;
17 import java
.util
.UUID
;
19 import org
.apache
.lucene
.index
.CorruptIndexException
;
20 import org
.apache
.lucene
.queryParser
.ParseException
;
21 import org
.hibernate
.search
.spatial
.impl
.Rectangle
;
23 import eu
.etaxonomy
.cdm
.api
.facade
.DerivedUnitFacade
;
24 import eu
.etaxonomy
.cdm
.api
.facade
.DerivedUnitFacadeNotSupportedException
;
25 import eu
.etaxonomy
.cdm
.api
.service
.config
.SpecimenDeleteConfigurator
;
26 import eu
.etaxonomy
.cdm
.api
.service
.dto
.DerivateHierarchyDTO
;
27 import eu
.etaxonomy
.cdm
.api
.service
.pager
.Pager
;
28 import eu
.etaxonomy
.cdm
.api
.service
.search
.SearchResult
;
29 import eu
.etaxonomy
.cdm
.api
.service
.util
.TaxonRelationshipEdge
;
30 import eu
.etaxonomy
.cdm
.model
.common
.CdmBase
;
31 import eu
.etaxonomy
.cdm
.model
.common
.ICdmBase
;
32 import eu
.etaxonomy
.cdm
.model
.common
.Language
;
33 import eu
.etaxonomy
.cdm
.model
.common
.UuidAndTitleCache
;
34 import eu
.etaxonomy
.cdm
.model
.description
.DescriptionBase
;
35 import eu
.etaxonomy
.cdm
.model
.description
.IndividualsAssociation
;
36 import eu
.etaxonomy
.cdm
.model
.description
.TaxonDescription
;
37 import eu
.etaxonomy
.cdm
.model
.location
.Country
;
38 import eu
.etaxonomy
.cdm
.model
.media
.Media
;
39 import eu
.etaxonomy
.cdm
.model
.molecular
.DnaSample
;
40 import eu
.etaxonomy
.cdm
.model
.molecular
.Sequence
;
41 import eu
.etaxonomy
.cdm
.model
.name
.HomotypicalGroup
;
42 import eu
.etaxonomy
.cdm
.model
.name
.SpecimenTypeDesignation
;
43 import eu
.etaxonomy
.cdm
.model
.occurrence
.DerivationEvent
;
44 import eu
.etaxonomy
.cdm
.model
.occurrence
.DerivedUnit
;
45 import eu
.etaxonomy
.cdm
.model
.occurrence
.DeterminationEvent
;
46 import eu
.etaxonomy
.cdm
.model
.occurrence
.FieldUnit
;
47 import eu
.etaxonomy
.cdm
.model
.occurrence
.SpecimenOrObservationBase
;
48 import eu
.etaxonomy
.cdm
.model
.taxon
.Taxon
;
49 import eu
.etaxonomy
.cdm
.model
.taxon
.TaxonBase
;
50 import eu
.etaxonomy
.cdm
.model
.taxon
.TaxonRelationship
;
51 import eu
.etaxonomy
.cdm
.persistence
.dao
.initializer
.IBeanInitializer
;
52 import eu
.etaxonomy
.cdm
.persistence
.query
.OrderHint
;
55 * @author a.babadshanjan
58 public interface IOccurrenceService
extends IIdentifiableEntityService
<SpecimenOrObservationBase
> {
60 public Country
getCountryByIso(String iso639
);
62 public List
<Country
> getCountryByName(String name
);
65 * Returns a paged list of occurrences that have been determined to belong
66 * to the taxon concept determinedAs, optionally restricted to objects
67 * belonging to a class that that extends SpecimenOrObservationBase.
69 * In contrast to {@link #listByAnyAssociation(Class, Taxon, List)} this
70 * method only takes SpecimenOrObservationBase instances into account which
71 * are actually determined as the taxon specified by
72 * <code>determinedAs</code>.
75 * The type of entities to return (can be null to count all
76 * entities of type <T>)
78 * the taxon concept that the occurrences have been determined to
81 * The maximum number of objects returned (can be null for all
84 * The offset (in pageSize chunks) from the start of the result
85 * set (0 - based, can be null, equivalent of starting at the
86 * beginning of the recordset)
88 * Supports path like <code>orderHints.propertyNames</code> which
89 * include *-to-one properties like createdBy.username or
90 * authorTeam.persistentTitleCache
91 * @param propertyPaths
92 * properties to be initialized
95 public Pager
<SpecimenOrObservationBase
> list(Class
<?
extends SpecimenOrObservationBase
> type
, TaxonBase determinedAs
, Integer limit
, Integer start
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
98 * Returns a List of Media that are associated with a given occurence
100 * @param occurence the occurence associated with these media
101 * @param pageSize The maximum number of media returned (can be null for all related media)
102 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
103 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
104 * @return a Pager of media instances
106 public Pager
<Media
> getMedia(SpecimenOrObservationBase occurence
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
109 * Returns a count of determinations that have been made for a given occurence and for a given taxon concept
111 * @param occurence the occurence associated with these determinations (can be null for all occurrences)
112 * @param taxonbase the taxon concept associated with these determinations (can be null for all taxon concepts)
113 * @return a count of determination events
115 public int countDeterminations(SpecimenOrObservationBase occurence
,TaxonBase taxonbase
);
118 * Returns a List of determinations that have been made for a given occurence
120 * @param occurence the occurence associated with these determinations (can be null for all occurrences)
121 * @param taxonbase the taxon concept associated with these determinations (can be null for all taxon concepts)
122 * @param pageSize The maximum number of determinations returned (can be null for all related determinations)
123 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
124 * @return a Pager of determination instances
126 public Pager
<DeterminationEvent
> getDeterminations(SpecimenOrObservationBase occurence
, TaxonBase taxonBase
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
129 * Returns a list of derivation events that have involved creating new DerivedUnits from this occurence
131 * @param occurence the occurence that was a source of these derivation events
132 * @param pageSize The maximum number of derivation events returned (can be null for all related derivation events)
133 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
134 * @return a Pager of derivation events
136 public Pager
<DerivationEvent
> getDerivationEvents(SpecimenOrObservationBase occurence
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
139 * Returns a Paged List of SpecimenOrObservationBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
141 * @param clazz filter the results by class (or pass null to return all SpecimenOrObservationBase instances)
143 * @param pageSize The maximum number of occurrences returned (can be null for all matching occurrences)
144 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
146 * Supports path like <code>orderHints.propertyNames</code> which
147 * include *-to-one properties like createdBy.username or
148 * authorTeam.persistentTitleCache
149 * @param propertyPaths properties to be initialized
150 * @return a Pager SpecimenOrObservationBase instances
151 * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
154 public Pager
<SpecimenOrObservationBase
> search(Class
<?
extends SpecimenOrObservationBase
> clazz
, String query
, Integer pageSize
,Integer pageNumber
, List
<OrderHint
> orderHints
,List
<String
> propertyPaths
);
157 * Retrieves the {@link UUID} and the string representation (title cache) of all
158 * {@link FieldUnit}s found in the data base.
159 * @return a list of {@link UuidAndTitleCache}
161 public List
<UuidAndTitleCache
<FieldUnit
>> getFieldUnitUuidAndTitleCache();
164 * Retrieves the {@link UUID} and the string representation (title cache) of all
165 * {@link DerivedUnit}s found in the data base.
166 * @return a list of {@link UuidAndTitleCache}
168 public List
<UuidAndTitleCache
<DerivedUnit
>> getDerivedUnitUuidAndTitleCache();
170 public DerivedUnitFacade
getDerivedUnitFacade(DerivedUnit derivedUnit
, List
<String
> propertyPaths
) throws DerivedUnitFacadeNotSupportedException
;
172 public List
<DerivedUnitFacade
> listDerivedUnitFacades(DescriptionBase description
, List
<String
> propertyPaths
);
175 * Lists all instances of {@link SpecimenOrObservationBase} which are
176 * associated with the <code>taxon</code> specified as parameter.
177 * SpecimenOrObservationBase instances can be associated to taxa in multiple
178 * ways, all these possible relations are taken into account:
180 * <li>The {@link IndividualsAssociation} elements in a
181 * {@link TaxonDescription} contain {@link DerivedUnit}s</li>
182 * <li>{@link SpecimenTypeDesignation}s may be associated with any
183 * {@link HomotypicalGroup} related to the specific {@link Taxon}.</li>
184 * <li>A {@link Taxon} may be referenced by the {@link DeterminationEvent}
185 * of the {@link SpecimenOrObservationBase}</li>
187 * Further more there also can be taxa which are associated with the taxon
188 * in question (parameter associatedTaxon) by {@link TaxonRelationship}s. If
189 * the parameter <code>includeRelationships</code> is containing elements,
190 * these according {@TaxonRelationshipType}s and
191 * directional information will be used to collect further
192 * {@link SpecimenOrObservationBase} instances found this way.
196 * @param associatedTaxon
197 * @param Set<TaxonRelationshipVector> includeRelationships. TaxonRelationships will not be taken into account if this is <code>NULL</code>.
198 * @param maxDepth TODO
202 * @param propertyPaths
205 public <T
extends SpecimenOrObservationBase
> List
<T
> listByAssociatedTaxon(Class
<T
> type
, Set
<TaxonRelationshipEdge
> includeRelationships
,
206 Taxon associatedTaxon
, Integer maxDepth
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
209 * Lists all instances of {@link FieldUnit} which are
210 * associated <b>directly or indirectly</b>with the <code>taxon</code> specified
211 * as parameter. "Indirectly" means that a sub derivate of the FieldUnit is
212 * directly associated with the given taxon.
213 * SpecimenOrObservationBase instances can be associated to taxa in multiple
214 * ways, all these possible relations are taken into account:
216 * <li>The {@link IndividualsAssociation} elements in a
217 * {@link TaxonDescription} contain {@link DerivedUnit}s</li>
218 * <li>{@link SpecimenTypeDesignation}s may be associated with any
219 * {@link HomotypicalGroup} related to the specific {@link Taxon}.</li>
220 * <li>A {@link Taxon} may be referenced by the {@link DeterminationEvent}
221 * of the {@link SpecimenOrObservationBase}</li>
223 * Further more there also can be taxa which are associated with the taxon
224 * in question (parameter associatedTaxon) by {@link TaxonRelationship}s. If
225 * the parameter <code>includeRelationships</code> is containing elements,
226 * these according {@TaxonRelationshipType}s and
227 * directional information will be used to collect further
228 * {@link SpecimenOrObservationBase} instances found this way.
232 * @param associatedTaxon
233 * @param Set<TaxonRelationshipVector> includeRelationships. TaxonRelationships will not be taken into account if this is <code>NULL</code>.
234 * @param maxDepth TODO
238 * @param propertyPaths
241 public Collection
<SpecimenOrObservationBase
> listFieldUnitsByAssociatedTaxon(Taxon associatedTaxon
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
244 * See {@link #listFieldUnitsByAssociatedTaxon(Set, Taxon, Integer, Integer, Integer, List, List)}
246 public Pager
<SpecimenOrObservationBase
> pageFieldUnitsByAssociatedTaxon(Set
<TaxonRelationshipEdge
> includeRelationships
,
247 Taxon associatedTaxon
, Integer maxDepth
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
250 * See {@link #listByAssociatedTaxon(Class, Set, Taxon, Integer, Integer, Integer, List, List)}
253 * @param includeRelationships
254 * @param associatedTaxon
259 * @param propertyPaths
262 public <T
extends SpecimenOrObservationBase
> Pager
<T
> pageByAssociatedTaxon(Class
<T
> type
, Set
<TaxonRelationshipEdge
> includeRelationships
,
263 Taxon associatedTaxon
, Integer maxDepth
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
266 * Retrieves all {@link FieldUnit}s for the {@link SpecimenOrObservationBase} with the given {@link UUID}.<br>
267 * @param specimenUuid the UUID of the specimen
268 * @return either a collection of FieldUnits this specimen was derived from, the FieldUnit itself
269 * if this was a FieldUnit or an empty collection if no FieldUnits were found
271 public Collection
<FieldUnit
> getFieldUnits(UUID specimenUuid
);
277 * @param highlightFragments
281 * @param propertyPaths
283 * @throws CorruptIndexException
284 * @throws IOException
285 * @throws ParseException
287 Pager
<SearchResult
<SpecimenOrObservationBase
>> findByFullText(Class
<?
extends SpecimenOrObservationBase
> clazz
,
288 String queryString
, Rectangle boundingBox
, List
<Language
> languages
, boolean highlightFragments
, Integer pageSize
,
289 Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
) throws CorruptIndexException
,
290 IOException
, ParseException
;
292 * See {@link #listByAssociatedTaxon(Class, Set, String, Integer, Integer, Integer, List, List)}
295 * @param includeRelationships
296 * @param associatedTaxon
301 * @param propertyPaths
304 public <T
extends SpecimenOrObservationBase
> Pager
<T
> pageByAssociatedTaxon(Class
<T
> type
, Set
<TaxonRelationshipEdge
> includeRelationships
,
305 String taxonUUID
, Integer maxDepth
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
308 * Moves the given {@link Sequence} from one {@link DnaSample} to another
309 * @param from the DnaSample from which the sequence will be removed
310 * @param to the DnaSample which to which the sequence will be added
311 * @param sequence the Sequence to move
312 * @return <code>true</code> if successfully moved, <code>false</code> otherwise
314 public boolean moveSequence(DnaSample from
, DnaSample to
, Sequence sequence
);
317 * Moves the given {@link DerivedUnit} from one {@link SpecimenOrObservationBase} to another.
318 * @param from the SpecimenOrObservationBase from which the DerivedUnit will be removed
319 * @param to the SpecimenOrObservationBase to which the DerivedUnit will be added
320 * @param derivate the DerivedUnit to move
321 * @return <code>true</code> if successfully moved, <code>false</code> otherwise
323 public boolean moveDerivate(SpecimenOrObservationBase
<?
> from
, SpecimenOrObservationBase
<?
> to
, DerivedUnit derivate
);
326 * Assembles a {@link DerivateHierarchyDTO} for the given field unit uuid which is associated to the {@link Taxon}.<br>
328 * For the meaning of "associated" see also {@link #listFieldUnitsByAssociatedTaxon(Set, Taxon, Integer, Integer, Integer, List, List)}
330 * @param associatedTaxonUuid
333 public DerivateHierarchyDTO
assembleDerivateHierarchyDTO(FieldUnit fieldUnit
, UUID associatedTaxonUuid
);
336 * Returns a collection of {@link ICdmBase}s that are not persisted via cascading when saving the given specimen (mostly DefinedTerms).
337 * @param specimen the specimen that is checked for non-cascaded elements.
338 * @return collection of non-cascaded element associated with the specimen
340 public Collection
<ICdmBase
> getNonCascadedAssociatedElements(SpecimenOrObservationBase
<?
> specimen
);
343 * Deletes the specified specimen according to the setting in the {@link SpecimenDeleteConfigurator}.<br>
344 * @param specimen the specimen which shoul be deleted
345 * @param config specifies options if and how the specimen should be deleted like e.g. including all
347 * @return the {@link DeleteResult} which holds information about the outcome of this operation
349 public DeleteResult
delete(SpecimenOrObservationBase
<?
> specimen
, SpecimenDeleteConfigurator config
);
352 * Deletes the specified specimen and all sub derivates.<br>
353 * <b>Note:</b> Be sure to allow child deletion in the config.
354 * @param from the specimen which should be deleted with all its sub derivates
355 * @param config the {@link SpecimenDeleteConfigurator} to specify how the deletion should be handled
356 * @return the {@link DeleteResult} which holds information about the outcome of this operation
358 public DeleteResult
deleteDerivateHierarchy(CdmBase from
, SpecimenDeleteConfigurator config
);
361 * Retrieves all {@link IndividualsAssociation} with the given specimen.<br>
362 * @param specimen the specimen for which the associations are retrieved
366 * @param propertyPaths
367 * @return collection of all associations
369 public Collection
<IndividualsAssociation
> listIndividualsAssociations(SpecimenOrObservationBase
<?
> specimen
, Integer limit
, Integer start
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
372 * Retrieves all {@link SpecimenTypeDesignation}s which have the given specimen as a type specimen.
373 * @param specimen the type specimen
377 * @param propertyPaths
378 * @return collection of all designations with the given type specimen
380 public Collection
<SpecimenTypeDesignation
> listTypeDesignations(SpecimenOrObservationBase
<?
> specimen
, Integer limit
, Integer start
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
383 * Retrieves all {@link DescriptionBase}s that have the given specimen set as described specimen.
384 * @param specimen the described specimen
388 * @param propertyPaths
389 * @return collection of all descriptions with the given described specimen
391 public Collection
<DescriptionBase
<?
>> listDescriptionsWithDescriptionSpecimen(SpecimenOrObservationBase
<?
> specimen
, Integer limit
, Integer start
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);