// $Id$\r
/**\r
-* Copyright (C) 2008 EDIT\r
-* European Distributed Institute of Taxonomy \r
+* Copyright (C) 2009 EDIT\r
+* European Distributed Institute of Taxonomy\r
* http://www.e-taxonomy.eu\r
+*\r
+* The contents of this file are subject to the Mozilla Public License Version 1.1\r
+* See LICENSE.TXT at the top of this package for the full license terms.\r
*/\r
\r
package eu.etaxonomy.cdm.api.service;\r
\r
+import java.io.IOException;\r
+import java.util.Collection;\r
import java.util.List;\r
-import java.util.Map;\r
+import java.util.Set;\r
import java.util.UUID;\r
\r
+import org.apache.lucene.index.CorruptIndexException;\r
+import org.apache.lucene.queryParser.ParseException;\r
+import org.hibernate.search.spatial.impl.Rectangle;\r
+\r
+import eu.etaxonomy.cdm.api.facade.DerivedUnitFacade;\r
+import eu.etaxonomy.cdm.api.facade.DerivedUnitFacadeNotSupportedException;\r
+import eu.etaxonomy.cdm.api.service.dto.DerivateHierarchyDTO;\r
import eu.etaxonomy.cdm.api.service.pager.Pager;\r
-import eu.etaxonomy.cdm.model.location.WaterbodyOrCountry;\r
+import eu.etaxonomy.cdm.api.service.search.SearchResult;\r
+import eu.etaxonomy.cdm.api.service.util.TaxonRelationshipEdge;\r
+import eu.etaxonomy.cdm.model.common.Language;\r
+import eu.etaxonomy.cdm.model.common.UuidAndTitleCache;\r
+import eu.etaxonomy.cdm.model.description.DescriptionBase;\r
+import eu.etaxonomy.cdm.model.description.IndividualsAssociation;\r
+import eu.etaxonomy.cdm.model.description.TaxonDescription;\r
+import eu.etaxonomy.cdm.model.location.Country;\r
import eu.etaxonomy.cdm.model.media.Media;\r
-import eu.etaxonomy.cdm.model.occurrence.Collection;\r
+import eu.etaxonomy.cdm.model.molecular.DnaSample;\r
+import eu.etaxonomy.cdm.model.molecular.Sequence;\r
+import eu.etaxonomy.cdm.model.name.HomotypicalGroup;\r
+import eu.etaxonomy.cdm.model.name.SpecimenTypeDesignation;\r
import eu.etaxonomy.cdm.model.occurrence.DerivationEvent;\r
+import eu.etaxonomy.cdm.model.occurrence.DerivedUnit;\r
import eu.etaxonomy.cdm.model.occurrence.DeterminationEvent;\r
+import eu.etaxonomy.cdm.model.occurrence.FieldUnit;\r
import eu.etaxonomy.cdm.model.occurrence.SpecimenOrObservationBase;\r
-import eu.etaxonomy.cdm.persistence.dao.BeanInitializer;\r
+import eu.etaxonomy.cdm.model.taxon.Taxon;\r
+import eu.etaxonomy.cdm.model.taxon.TaxonBase;\r
+import eu.etaxonomy.cdm.model.taxon.TaxonRelationship;\r
+import eu.etaxonomy.cdm.persistence.dao.initializer.IBeanInitializer;\r
import eu.etaxonomy.cdm.persistence.query.OrderHint;\r
\r
/**\r
*/\r
public interface IOccurrenceService extends IIdentifiableEntityService<SpecimenOrObservationBase> {\r
\r
- /**\r
- * FIXME candidate for harmonization?\r
- * Computes all specimen or observation bases.\r
- * @param limit\r
- * @param start\r
- * @return\r
- */\r
- public abstract List<SpecimenOrObservationBase> getAllSpecimenOrObservationBases(int limit, int start);\r
-\r
- /**\r
- * FIXME candidate for harmonization? \r
- * Saves a collection of specimen or observation bases.\r
- * @return Map with UUID as key and SpecimenOrObservationBase as value.\r
- */\r
- public abstract Map<UUID, ? extends SpecimenOrObservationBase> \r
- saveSpecimenOrObservationBaseAll(java.util.Collection<? extends SpecimenOrObservationBase> specimenOrObservationBaseCollection);\r
-\r
- /** \r
- * FIXME candidate for harmonizaion?\r
- * save a specimen or observation and return its UUID\r
- */\r
- public abstract UUID saveSpecimenOrObservationBase (SpecimenOrObservationBase specimenOrObservationBase);\r
- \r
- public WaterbodyOrCountry getCountryByIso(String iso639);\r
- \r
- public List<WaterbodyOrCountry> getWaterbodyOrCountryByName(String name);\r
- \r
- /** */\r
- public abstract List<Collection> searchCollectionByCode(String code);\r
- \r
- public abstract UUID saveCollection(Collection collection);\r
- \r
- /**\r
+ public Country getCountryByIso(String iso639);\r
+\r
+ public List<Country> getCountryByName(String name);\r
+\r
+ /**\r
+ * Returns a paged list of occurrences that have been determined to belong\r
+ * to the taxon concept determinedAs, optionally restricted to objects\r
+ * belonging to a class that that extends SpecimenOrObservationBase.\r
+ * <p>\r
+ * In contrast to {@link #listByAnyAssociation(Class, Taxon, List)} this\r
+ * method only takes SpecimenOrObservationBase instances into account which\r
+ * are actually determined as the taxon specified by\r
+ * <code>determinedAs</code>.\r
+ *\r
+ * @param type\r
+ * The type of entities to return (can be null to count all\r
+ * entities of type <T>)\r
+ * @param determinedAs\r
+ * the taxon concept that the occurrences have been determined to\r
+ * belong to\r
+ * @param pageSize\r
+ * The maximum number of objects returned (can be null for all\r
+ * matching objects)\r
+ * @param pageNumber\r
+ * The offset (in pageSize chunks) from the start of the result\r
+ * set (0 - based, can be null, equivalent of starting at the\r
+ * beginning of the recordset)\r
+ * @param orderHints\r
+ * Supports path like <code>orderHints.propertyNames</code> which\r
+ * include *-to-one properties like createdBy.username or\r
+ * authorTeam.persistentTitleCache\r
+ * @param propertyPaths\r
+ * properties to be initialized\r
+ * @return\r
+ */\r
+ public Pager<SpecimenOrObservationBase> list(Class<? extends SpecimenOrObservationBase> type, TaxonBase determinedAs, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);\r
+\r
+ /**\r
* Returns a List of Media that are associated with a given occurence\r
- * \r
- * @param occurence the occurence associated with these media\r
- * @param pageSize The maximum number of media returned (can be null for all related media)\r
- * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)\r
- * @param propertyPaths properties to initialize - see {@link BeanInitializer#initialize(Object, List)}\r
+ *\r
+ * @param occurence the occurence associated with these media\r
+ * @param pageSize The maximum number of media returned (can be null for all related media)\r
+ * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)\r
+ * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}\r
* @return a Pager of media instances\r
*/\r
- public Pager<Media> getMedia(SpecimenOrObservationBase occurence, Integer pageSize, Integer pageNumber, List<String> propertyPaths);\r
- \r
- /**\r
+ public Pager<Media> getMedia(SpecimenOrObservationBase occurence, Integer pageSize, Integer pageNumber, List<String> propertyPaths);\r
+\r
+ /**\r
+ * Returns a count of determinations that have been made for a given occurence and for a given taxon concept\r
+ *\r
+ * @param occurence the occurence associated with these determinations (can be null for all occurrences)\r
+ * @param taxonbase the taxon concept associated with these determinations (can be null for all taxon concepts)\r
+ * @return a count of determination events\r
+ */\r
+ public int countDeterminations(SpecimenOrObservationBase occurence,TaxonBase taxonbase);\r
+\r
+ /**\r
* Returns a List of determinations that have been made for a given occurence\r
- * \r
- * @param occurence the occurence associated with these determinations\r
- * @param pageSize The maximum number of determinations returned (can be null for all related determinations)\r
- * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)\r
+ *\r
+ * @param occurence the occurence associated with these determinations (can be null for all occurrences)\r
+ * @param taxonbase the taxon concept associated with these determinations (can be null for all taxon concepts)\r
+ * @param pageSize The maximum number of determinations returned (can be null for all related determinations)\r
+ * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)\r
* @return a Pager of determination instances\r
*/\r
- public Pager<DeterminationEvent> getDeterminations(SpecimenOrObservationBase occurence, Integer pageSize, Integer pageNumber, List<String> propertyPaths);\r
- \r
- /**\r
+ public Pager<DeterminationEvent> getDeterminations(SpecimenOrObservationBase occurence, TaxonBase taxonBase, Integer pageSize, Integer pageNumber, List<String> propertyPaths);\r
+\r
+ /**\r
* Returns a list of derivation events that have involved creating new DerivedUnits from this occurence\r
- * \r
- * @param occurence the occurence that was a source of these derivation events\r
- * @param pageSize The maximum number of derivation events returned (can be null for all related derivation events)\r
- * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)\r
+ *\r
+ * @param occurence the occurence that was a source of these derivation events\r
+ * @param pageSize The maximum number of derivation events returned (can be null for all related derivation events)\r
+ * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)\r
* @return a Pager of derivation events\r
*/\r
- public Pager<DerivationEvent> getDerivationEvents(SpecimenOrObservationBase occurence, Integer pageSize, Integer pageNumber, List<String> propertyPaths);\r
- \r
- /**\r
- * Returns a Paged List of SpecimenOrObservationBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)\r
- * \r
- * @param clazz filter the results by class (or pass null to return all SpecimenOrObservationBase instances)\r
- * @param queryString\r
- * @param pageSize The maximum number of occurrences returned (can be null for all matching occurrences)\r
- * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)\r
- * @param orderHints\r
- * Supports path like <code>orderHints.propertyNames</code> which\r
- * include *-to-one properties like createdBy.username or\r
- * authorTeam.persistentTitleCache\r
- * @param propertyPaths properties to be initialized\r
- * @return a Pager SpecimenOrObservationBase instances\r
- * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>\r
- */\r
- public Pager<SpecimenOrObservationBase> search(Class<? extends SpecimenOrObservationBase> clazz, String query, Integer pageSize,Integer pageNumber, List<OrderHint> orderHints,List<String> propertyPaths);\r
+ public Pager<DerivationEvent> getDerivationEvents(SpecimenOrObservationBase occurence, Integer pageSize, Integer pageNumber, List<String> propertyPaths);\r
+\r
+ /**\r
+ * Returns a Paged List of SpecimenOrObservationBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)\r
+ *\r
+ * @param clazz filter the results by class (or pass null to return all SpecimenOrObservationBase instances)\r
+ * @param queryString\r
+ * @param pageSize The maximum number of occurrences returned (can be null for all matching occurrences)\r
+ * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)\r
+ * @param orderHints\r
+ * Supports path like <code>orderHints.propertyNames</code> which\r
+ * include *-to-one properties like createdBy.username or\r
+ * authorTeam.persistentTitleCache\r
+ * @param propertyPaths properties to be initialized\r
+ * @return a Pager SpecimenOrObservationBase instances\r
+ * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>\r
+ */\r
+ @Override\r
+ public Pager<SpecimenOrObservationBase> search(Class<? extends SpecimenOrObservationBase> clazz, String query, Integer pageSize,Integer pageNumber, List<OrderHint> orderHints,List<String> propertyPaths);\r
+\r
+ /**\r
+ * Retrieves the {@link UUID} and the string representation (title cache) of all\r
+ * {@link FieldUnit}s found in the data base.\r
+ * @return a list of {@link UuidAndTitleCache}\r
+ */\r
+ public List<UuidAndTitleCache<FieldUnit>> getFieldUnitUuidAndTitleCache();\r
+\r
+ /**\r
+ * Retrieves the {@link UUID} and the string representation (title cache) of all\r
+ * {@link DerivedUnit}s found in the data base.\r
+ * @return a list of {@link UuidAndTitleCache}\r
+ */\r
+ public List<UuidAndTitleCache<DerivedUnit>> getDerivedUnitUuidAndTitleCache();\r
+\r
+ public DerivedUnitFacade getDerivedUnitFacade(DerivedUnit derivedUnit, List<String> propertyPaths) throws DerivedUnitFacadeNotSupportedException;\r
+\r
+ public List<DerivedUnitFacade> listDerivedUnitFacades(DescriptionBase description, List<String> propertyPaths);\r
+\r
+ /**\r
+ * Lists all instances of {@link SpecimenOrObservationBase} which are\r
+ * associated with the <code>taxon</code> specified as parameter.\r
+ * SpecimenOrObservationBase instances can be associated to taxa in multiple\r
+ * ways, all these possible relations are taken into account:\r
+ * <ul>\r
+ * <li>The {@link IndividualsAssociation} elements in a\r
+ * {@link TaxonDescription} contain {@link DerivedUnit}s</li>\r
+ * <li>{@link SpecimenTypeDesignation}s may be associated with any\r
+ * {@link HomotypicalGroup} related to the specific {@link Taxon}.</li>\r
+ * <li>A {@link Taxon} may be referenced by the {@link DeterminationEvent}\r
+ * of the {@link SpecimenOrObservationBase}</li>\r
+ * </ul>\r
+ * Further more there also can be taxa which are associated with the taxon\r
+ * in question (parameter associatedTaxon) by {@link TaxonRelationship}s. If\r
+ * the parameter <code>includeRelationships</code> is containing elements,\r
+ * these according {@TaxonRelationshipType}s and\r
+ * directional information will be used to collect further\r
+ * {@link SpecimenOrObservationBase} instances found this way.\r
+ *\r
+ * @param <T>\r
+ * @param type\r
+ * @param associatedTaxon\r
+ * @param Set<TaxonRelationshipVector> includeRelationships. TaxonRelationships will not be taken into account if this is <code>NULL</code>.\r
+ * @param maxDepth TODO\r
+ * @param pageSize\r
+ * @param pageNumber\r
+ * @param orderHints\r
+ * @param propertyPaths\r
+ * @return\r
+ */\r
+ public <T extends SpecimenOrObservationBase> List<T> listByAssociatedTaxon(Class<T> type, Set<TaxonRelationshipEdge> includeRelationships,\r
+ Taxon associatedTaxon, Integer maxDepth, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);\r
+\r
+ /**\r
+ * Lists all instances of {@link FieldUnit} which are\r
+ * associated <b>directly or indirectly</b>with the <code>taxon</code> specified\r
+ * as parameter. "Indirectly" means that a sub derivate of the FieldUnit is\r
+ * directly associated with the given taxon.\r
+ * SpecimenOrObservationBase instances can be associated to taxa in multiple\r
+ * ways, all these possible relations are taken into account:\r
+ * <ul>\r
+ * <li>The {@link IndividualsAssociation} elements in a\r
+ * {@link TaxonDescription} contain {@link DerivedUnit}s</li>\r
+ * <li>{@link SpecimenTypeDesignation}s may be associated with any\r
+ * {@link HomotypicalGroup} related to the specific {@link Taxon}.</li>\r
+ * <li>A {@link Taxon} may be referenced by the {@link DeterminationEvent}\r
+ * of the {@link SpecimenOrObservationBase}</li>\r
+ * </ul>\r
+ * Further more there also can be taxa which are associated with the taxon\r
+ * in question (parameter associatedTaxon) by {@link TaxonRelationship}s. If\r
+ * the parameter <code>includeRelationships</code> is containing elements,\r
+ * these according {@TaxonRelationshipType}s and\r
+ * directional information will be used to collect further\r
+ * {@link SpecimenOrObservationBase} instances found this way.\r
+ *\r
+ * @param <T>\r
+ * @param type\r
+ * @param associatedTaxon\r
+ * @param Set<TaxonRelationshipVector> includeRelationships. TaxonRelationships will not be taken into account if this is <code>NULL</code>.\r
+ * @param maxDepth TODO\r
+ * @param pageSize\r
+ * @param pageNumber\r
+ * @param orderHints\r
+ * @param propertyPaths\r
+ * @return\r
+ */\r
+ public Collection<FieldUnit> listFieldUnitsByAssociatedTaxon(Set<TaxonRelationshipEdge> includeRelationships,\r
+ Taxon associatedTaxon, Integer maxDepth, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);\r
+\r
+ /**\r
+ * Assembles a {@link DerivateHierarchyDTO} for each "associated" {@link FieldUnit} found for the given {@link Taxon}.<br>\r
+ * <br>\r
+ * See also {@link #listFieldUnitsByAssociatedTaxon(Set, Taxon, Integer, Integer, Integer, List, List)}\r
+ * @param includeRelationships\r
+ * @param associatedTaxon\r
+ * @param maxDepth\r
+ * @param pageSize\r
+ * @param pageNumber\r
+ * @param orderHints\r
+ * @param propertyPaths\r
+ * @return\r
+ */\r
+ public Collection<DerivateHierarchyDTO> listDerivateHierarchyDTOsByAssociatedTaxon(Set<TaxonRelationshipEdge> includeRelationships,\r
+ Taxon associatedTaxon, Integer maxDepth, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);\r
+\r
+ /**\r
+ * See {@link #listByAssociatedTaxon(Class, Set, Taxon, Integer, Integer, Integer, List, List)}\r
+ *\r
+ * @param type\r
+ * @param includeRelationships\r
+ * @param associatedTaxon\r
+ * @param maxDepth\r
+ * @param pageSize\r
+ * @param pageNumber\r
+ * @param orderHints\r
+ * @param propertyPaths\r
+ * @return a Pager\r
+ */\r
+ public <T extends SpecimenOrObservationBase> Pager<T> pageByAssociatedTaxon(Class<T> type, Set<TaxonRelationshipEdge> includeRelationships,\r
+ Taxon associatedTaxon, Integer maxDepth, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);\r
+\r
+ /**\r
+ * Retrieves all {@link FieldUnit}s for the {@link SpecimenOrObservationBase} with the given {@link UUID}.<br>\r
+ * @param specimenUuid the UUID of the specimen\r
+ * @return either a collection of FieldUnits this specimen was derived from, the FieldUnit itself\r
+ * if this was a FieldUnit or an empty collection if no FieldUnits were found\r
+ */\r
+ public Collection<FieldUnit> getFieldUnits(UUID specimenUuid);\r
+\r
+ /**\r
+ * @param clazz\r
+ * @param queryString\r
+ * @param languages\r
+ * @param highlightFragments\r
+ * @param pageSize\r
+ * @param pageNumber\r
+ * @param orderHints\r
+ * @param propertyPaths\r
+ * @return\r
+ * @throws CorruptIndexException\r
+ * @throws IOException\r
+ * @throws ParseException\r
+ */\r
+ Pager<SearchResult<SpecimenOrObservationBase>> findByFullText(Class<? extends SpecimenOrObservationBase> clazz,\r
+ String queryString, Rectangle boundingBox, List<Language> languages, boolean highlightFragments, Integer pageSize,\r
+ Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths) throws CorruptIndexException,\r
+ IOException, ParseException;\r
+ /**\r
+ * See {@link #listByAssociatedTaxon(Class, Set, String, Integer, Integer, Integer, List, List)}\r
+ *\r
+ * @param type\r
+ * @param includeRelationships\r
+ * @param associatedTaxon\r
+ * @param maxDepth\r
+ * @param pageSize\r
+ * @param pageNumber\r
+ * @param orderHints\r
+ * @param propertyPaths\r
+ * @return a Pager\r
+ */\r
+ public <T extends SpecimenOrObservationBase> Pager<T> pageByAssociatedTaxon(Class<T> type, Set<TaxonRelationshipEdge> includeRelationships,\r
+ String taxonUUID, Integer maxDepth, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);\r
+\r
+ /**\r
+ * Moves the given {@link Sequence} from one {@link DnaSample} to another\r
+ * @param from the DnaSample from which the sequence will be removed\r
+ * @param to the DnaSample which to which the sequence will be added\r
+ * @param sequence the Sequence to move\r
+ * @return <code>true</code> if successfully moved, <code>false</code> otherwise\r
+ */\r
+ public boolean moveSequence(DnaSample from, DnaSample to, Sequence sequence);\r
+\r
+ /**\r
+ * Moves the given {@link DerivedUnit} from one {@link SpecimenOrObservationBase} to another.\r
+ * @param from the SpecimenOrObservationBase from which the DerivedUnit will be removed\r
+ * @param to the SpecimenOrObservationBase to which the DerivedUnit will be added\r
+ * @param derivate the DerivedUnit to move\r
+ * @return <code>true</code> if successfully moved, <code>false</code> otherwise\r
+ */\r
+ public boolean moveDerivate(SpecimenOrObservationBase<?> from, SpecimenOrObservationBase<?> to, DerivedUnit derivate);\r
+\r
}\r
BGBM BDI Projects / cdmlib.git / blobdiff