cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/IOccurrenceService.java

   1 // $Id$
   2 /**
   3 * Copyright (C) 2009 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.io.IOException;
  14 import java.util.Collection;
  15 import java.util.List;
  16 import java.util.Set;
  17 import java.util.UUID;
  18
  19 import org.apache.lucene.index.CorruptIndexException;
  20 import org.apache.lucene.queryParser.ParseException;
  21 import org.hibernate.search.spatial.impl.Rectangle;
  22
  23 import eu.etaxonomy.cdm.api.facade.DerivedUnitFacade;
  24 import eu.etaxonomy.cdm.api.facade.DerivedUnitFacadeNotSupportedException;
  25 import eu.etaxonomy.cdm.api.service.config.IIdentifiableEntityServiceConfigurator;
  26 import eu.etaxonomy.cdm.api.service.config.SpecimenDeleteConfigurator;
  27 import eu.etaxonomy.cdm.api.service.dto.FieldUnitDTO;
  28 import eu.etaxonomy.cdm.api.service.dto.PreservedSpecimenDTO;
  29 import eu.etaxonomy.cdm.api.service.pager.Pager;
  30 import eu.etaxonomy.cdm.api.service.search.SearchResult;
  31 import eu.etaxonomy.cdm.api.service.util.TaxonRelationshipEdge;
  32 import eu.etaxonomy.cdm.model.common.CdmBase;
  33 import eu.etaxonomy.cdm.model.common.ICdmBase;
  34 import eu.etaxonomy.cdm.model.common.Language;
  35 import eu.etaxonomy.cdm.model.description.DescriptionBase;
  36 import eu.etaxonomy.cdm.model.description.DescriptionElementBase;
  37 import eu.etaxonomy.cdm.model.description.IndividualsAssociation;
  38 import eu.etaxonomy.cdm.model.description.TaxonDescription;
  39 import eu.etaxonomy.cdm.model.location.Country;
  40 import eu.etaxonomy.cdm.model.media.Media;
  41 import eu.etaxonomy.cdm.model.molecular.DnaSample;
  42 import eu.etaxonomy.cdm.model.molecular.Sequence;
  43 import eu.etaxonomy.cdm.model.name.HomotypicalGroup;
  44 import eu.etaxonomy.cdm.model.name.SpecimenTypeDesignation;
  45 import eu.etaxonomy.cdm.model.occurrence.DerivationEvent;
  46 import eu.etaxonomy.cdm.model.occurrence.DerivedUnit;
  47 import eu.etaxonomy.cdm.model.occurrence.DeterminationEvent;
  48 import eu.etaxonomy.cdm.model.occurrence.FieldUnit;
  49 import eu.etaxonomy.cdm.model.occurrence.SpecimenOrObservationBase;
  50 import eu.etaxonomy.cdm.model.occurrence.SpecimenOrObservationType;
  51 import eu.etaxonomy.cdm.model.taxon.Taxon;
  52 import eu.etaxonomy.cdm.model.taxon.TaxonBase;
  53 import eu.etaxonomy.cdm.model.taxon.TaxonRelationship;
  54 import eu.etaxonomy.cdm.persistence.dao.initializer.IBeanInitializer;
  55 import eu.etaxonomy.cdm.persistence.dto.UuidAndTitleCache;
  56 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  57
  58 /**
  59  * @author a.babadshanjan
  60  * @created 01.09.2008
  61  */
  62 public interface IOccurrenceService extends IIdentifiableEntityService<SpecimenOrObservationBase> {
  63
  64     public Country getCountryByIso(String iso639);
  65
  66     public List<Country> getCountryByName(String name);
  67
  68     /**
  69      * Returns a paged list of occurrences that have been determined to belong
  70      * to the taxon concept determinedAs, optionally restricted to objects
  71      * belonging to a class that that extends SpecimenOrObservationBase.
  72      * <p>
  73      * In contrast to {@link #listByAnyAssociation(Class, Taxon, List)} this
  74      * method only takes SpecimenOrObservationBase instances into account which
  75      * are actually determined as the taxon specified by
  76      * <code>determinedAs</code>.
  77      *
  78      * @param type
  79      *            The type of entities to return (can be null to count all
  80      *            entities of type <T>)
  81      * @param determinedAs
  82      *            the taxon concept that the occurrences have been determined to
  83      *            belong to
  84      * @param pageSize
  85      *            The maximum number of objects returned (can be null for all
  86      *            matching objects)
  87      * @param pageNumber
  88      *            The offset (in pageSize chunks) from the start of the result
  89      *            set (0 - based, can be null, equivalent of starting at the
  90      *            beginning of the recordset)
  91      * @param orderHints
  92      *            Supports path like <code>orderHints.propertyNames</code> which
  93      *            include *-to-one properties like createdBy.username or
  94      *            authorTeam.persistentTitleCache
  95      * @param propertyPaths
  96      *            properties to be initialized
  97      * @return
  98      */
  99     public Pager<SpecimenOrObservationBase> list(Class<? extends SpecimenOrObservationBase> type, TaxonBase determinedAs, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 100
 101     /**
 102      * Returns a List of Media that are associated with a given occurence
 103      *
 104      * @param occurence the occurence associated with these media
 105      * @param pageSize The maximum number of media returned (can be null for all related media)
 106      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 107      * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
 108      * @return a Pager of media instances
 109      */
 110     public Pager<Media> getMedia(SpecimenOrObservationBase occurence, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 111
 112     /**
 113      * Returns a count of determinations that have been made for a given occurence and for a given taxon concept
 114      *
 115      * @param occurence the occurence associated with these determinations (can be null for all occurrences)
 116      * @param taxonbase the taxon concept associated with these determinations (can be null for all taxon concepts)
 117      * @return a count of determination events
 118      */
 119     public int countDeterminations(SpecimenOrObservationBase occurence,TaxonBase taxonbase);
 120
 121     /**
 122      * Returns a List of determinations that have been made for a given occurence
 123      *
 124      * @param occurence the occurence associated with these determinations (can be null for all occurrences)
 125      * @param taxonbase the taxon concept associated with these determinations (can be null for all taxon concepts)
 126      * @param pageSize The maximum number of determinations returned (can be null for all related determinations)
 127      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 128      * @return a Pager of determination instances
 129      */
 130     public Pager<DeterminationEvent> getDeterminations(SpecimenOrObservationBase occurence, TaxonBase taxonBase, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 131
 132     /**
 133      * Returns a list of derivation events that have involved creating new DerivedUnits from this occurence
 134      *
 135      * @param occurence the occurence that was a source of these derivation events
 136      * @param pageSize The maximum number of derivation events returned (can be null for all related derivation events)
 137      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 138      * @return a Pager of derivation events
 139      */
 140     public Pager<DerivationEvent> getDerivationEvents(SpecimenOrObservationBase occurence, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 141
 142     /**
 143      * Returns a Paged List of SpecimenOrObservationBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
 144      *
 145      * @param clazz filter the results by class (or pass null to return all SpecimenOrObservationBase instances)
 146      * @param queryString
 147      * @param pageSize The maximum number of occurrences returned (can be null for all matching occurrences)
 148      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 149      * @param orderHints
 150      *            Supports path like <code>orderHints.propertyNames</code> which
 151      *            include *-to-one properties like createdBy.username or
 152      *            authorTeam.persistentTitleCache
 153      * @param propertyPaths properties to be initialized
 154      * @return a Pager SpecimenOrObservationBase instances
 155      * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
 156      */
 157     @Override
 158     public Pager<SpecimenOrObservationBase> search(Class<? extends SpecimenOrObservationBase> clazz, String query, Integer pageSize,Integer pageNumber, List<OrderHint> orderHints,List<String> propertyPaths);
 159
 160     /**
 161      * Retrieves the {@link UUID} and the string representation (title cache) of all
 162      * {@link FieldUnit}s found in the data base.
 163      * @return a list of {@link UuidAndTitleCache}
 164      */
 165     public List<UuidAndTitleCache<FieldUnit>> getFieldUnitUuidAndTitleCache();
 166
 167     /**
 168      * Retrieves the {@link UUID} and the string representation (title cache) of all
 169      * {@link DerivedUnit}s found in the data base.
 170      * @return a list of {@link UuidAndTitleCache}
 171      */
 172     public List<UuidAndTitleCache<DerivedUnit>> getDerivedUnitUuidAndTitleCache();
 173
 174     public DerivedUnitFacade getDerivedUnitFacade(DerivedUnit derivedUnit, List<String> propertyPaths) throws DerivedUnitFacadeNotSupportedException;
 175
 176     public List<DerivedUnitFacade> listDerivedUnitFacades(DescriptionBase description, List<String> propertyPaths);
 177
 178     /**
 179      * Lists all instances of {@link SpecimenOrObservationBase} which are
 180      * associated with the <code>taxon</code> specified as parameter.
 181      * SpecimenOrObservationBase instances can be associated to taxa in multiple
 182      * ways, all these possible relations are taken into account:
 183      * <ul>
 184      * <li>The {@link IndividualsAssociation} elements in a
 185      * {@link TaxonDescription} contain {@link DerivedUnit}s</li>
 186      * <li>{@link SpecimenTypeDesignation}s may be associated with any
 187      * {@link HomotypicalGroup} related to the specific {@link Taxon}.</li>
 188      * <li>A {@link Taxon} may be referenced by the {@link DeterminationEvent}
 189      * of the {@link SpecimenOrObservationBase}</li>
 190      * </ul>
 191      * Further more there also can be taxa which are associated with the taxon
 192      * in question (parameter associatedTaxon) by {@link TaxonRelationship}s. If
 193      * the parameter <code>includeRelationships</code> is containing elements,
 194      * these according {@TaxonRelationshipType}s and
 195      * directional information will be used to collect further
 196      * {@link SpecimenOrObservationBase} instances found this way.
 197      *
 198      * @param <T>
 199      * @param type
 200      * @param associatedTaxon
 201      * @param Set<TaxonRelationshipVector> includeRelationships. TaxonRelationships will not be taken into account if this is <code>NULL</code>.
 202      * @param maxDepth TODO
 203      * @param pageSize
 204      * @param pageNumber
 205      * @param orderHints
 206      * @param propertyPaths
 207      * @return
 208      */
 209     public <T extends SpecimenOrObservationBase> List<T> listByAssociatedTaxon(Class<T> type, Set<TaxonRelationshipEdge> includeRelationships,
 210             Taxon associatedTaxon, Integer maxDepth, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 211
 212     /**
 213      * Lists all instances of {@link FieldUnit} which are
 214      * associated <b>directly or indirectly</b>with the <code>taxon</code> specified
 215      * as parameter. "Indirectly" means that a sub derivate of the FieldUnit is
 216      * directly associated with the given taxon.
 217      * SpecimenOrObservationBase instances can be associated to taxa in multiple
 218      * ways, all these possible relations are taken into account:
 219      * <ul>
 220      * <li>The {@link IndividualsAssociation} elements in a
 221      * {@link TaxonDescription} contain {@link DerivedUnit}s</li>
 222      * <li>{@link SpecimenTypeDesignation}s may be associated with any
 223      * {@link HomotypicalGroup} related to the specific {@link Taxon}.</li>
 224      * <li>A {@link Taxon} may be referenced by the {@link DeterminationEvent}
 225      * of the {@link SpecimenOrObservationBase}</li>
 226      * </ul>
 227      * Further more there also can be taxa which are associated with the taxon
 228      * in question (parameter associatedTaxon) by {@link TaxonRelationship}s. If
 229      * the parameter <code>includeRelationships</code> is containing elements,
 230      * these according {@TaxonRelationshipType}s and
 231      * directional information will be used to collect further
 232      * {@link SpecimenOrObservationBase} instances found this way.
 233      *
 234      * @param <T>
 235      * @param type
 236      * @param associatedTaxon
 237      * @param Set<TaxonRelationshipVector> includeRelationships. TaxonRelationships will not be taken into account if this is <code>NULL</code>.
 238      * @param maxDepth TODO
 239      * @param pageSize
 240      * @param pageNumber
 241      * @param orderHints
 242      * @param propertyPaths
 243      * @return
 244      */
 245     public Collection<SpecimenOrObservationBase> listFieldUnitsByAssociatedTaxon(Taxon associatedTaxon, List<OrderHint> orderHints, List<String> propertyPaths);
 246
 247     /**
 248      * See {@link #listFieldUnitsByAssociatedTaxon(Set, Taxon, Integer, Integer, Integer, List, List)}
 249      */
 250     public Pager<SpecimenOrObservationBase> pageFieldUnitsByAssociatedTaxon(Set<TaxonRelationshipEdge> includeRelationships,
 251             Taxon associatedTaxon, Integer maxDepth, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 252
 253     /**
 254      * See {@link #listByAssociatedTaxon(Class, Set, Taxon, Integer, Integer, Integer, List, List)}
 255      *
 256      * @param type
 257      * @param includeRelationships
 258      * @param associatedTaxon
 259      * @param maxDepth
 260      * @param pageSize
 261      * @param pageNumber
 262      * @param orderHints
 263      * @param propertyPaths
 264      * @return a Pager
 265      */
 266     public <T extends SpecimenOrObservationBase> Pager<T> pageByAssociatedTaxon(Class<T> type, Set<TaxonRelationshipEdge> includeRelationships,
 267             Taxon associatedTaxon, Integer maxDepth, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 268
 269     /**
 270      * Retrieves all {@link FieldUnit}s for the {@link SpecimenOrObservationBase} with the given {@link UUID}.<br>
 271      * @param specimenUuid the UUID of the specimen
 272      * @return either a collection of FieldUnits this specimen was derived from, the FieldUnit itself
 273      * if this was a FieldUnit or an empty collection if no FieldUnits were found
 274      */
 275     public Collection<FieldUnit> getFieldUnits(UUID specimenUuid);
 276
 277     /**
 278      * @param clazz
 279      * @param queryString
 280      * @param languages
 281      * @param highlightFragments
 282      * @param pageSize
 283      * @param pageNumber
 284      * @param orderHints
 285      * @param propertyPaths
 286      * @return
 287      * @throws CorruptIndexException
 288      * @throws IOException
 289      * @throws ParseException
 290      */
 291     Pager<SearchResult<SpecimenOrObservationBase>> findByFullText(Class<? extends SpecimenOrObservationBase> clazz,
 292             String queryString, Rectangle boundingBox, List<Language> languages, boolean highlightFragments, Integer pageSize,
 293             Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths) throws CorruptIndexException,
 294             IOException, ParseException;
 295     /**
 296      * See {@link #listByAssociatedTaxon(Class, Set, String, Integer, Integer, Integer, List, List)}
 297      *
 298      * @param type
 299      * @param includeRelationships
 300      * @param associatedTaxon
 301      * @param maxDepth
 302      * @param pageSize
 303      * @param pageNumber
 304      * @param orderHints
 305      * @param propertyPaths
 306      * @return a Pager
 307      */
 308     public <T extends SpecimenOrObservationBase> Pager<T>  pageByAssociatedTaxon(Class<T> type, Set<TaxonRelationshipEdge> includeRelationships,
 309             String taxonUUID, Integer maxDepth, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 310
 311     /**
 312      * Moves the given {@link Sequence} from one {@link DnaSample} to another
 313      * @param from the DnaSample from which the sequence will be removed
 314      * @param to the DnaSample which to which the sequence will be added
 315      * @param sequence the Sequence to move
 316      * @return <code>true</code> if successfully moved, <code>false</code> otherwise
 317      */
 318     public boolean moveSequence(DnaSample from, DnaSample to, Sequence sequence);
 319
 320     /**
 321      * Moves the given {@link DerivedUnit} from one {@link SpecimenOrObservationBase} to another.
 322      * @param from the SpecimenOrObservationBase from which the DerivedUnit will be removed
 323      * @param to the SpecimenOrObservationBase to which the DerivedUnit will be added
 324      * @param derivate the DerivedUnit to move
 325      * @return <code>true</code> if successfully moved, <code>false</code> otherwise
 326      */
 327     public boolean moveDerivate(SpecimenOrObservationBase<?> from, SpecimenOrObservationBase<?> to, DerivedUnit derivate);
 328
 329     /**
 330      * Assembles a {@link FieldUnitDTO} for the given field unit uuid which is associated to the {@link Taxon}.<br>
 331      * <br>
 332      * For the meaning of "associated" see also {@link #listFieldUnitsByAssociatedTaxon(Set, Taxon, Integer, Integer, Integer, List, List)}
 333      * @param fieldUnit
 334      * @param associatedTaxonUuid
 335      * @return a DTO with all the assembled information
 336      */
 337     public FieldUnitDTO assembleFieldUnitDTO(FieldUnit fieldUnit, UUID associatedTaxonUuid);
 338
 339     /**
 340      * Assembles a {@link PreservedSpecimenDTO} for the given derived unit.
 341      * @param derivedUnit
 342      * @return a DTO with all the assembled information
 343      */
 344     public PreservedSpecimenDTO assemblePreservedSpecimenDTO(DerivedUnit derivedUnit);
 345
 346     /**
 347      * Returns a collection of {@link ICdmBase}s that are not persisted via cascading when saving the given specimen (mostly DefinedTerms).
 348      * @param specimen the specimen that is checked for non-cascaded elements.
 349      * @return collection of non-cascaded element associated with the specimen
 350      */
 351     public Collection<ICdmBase> getNonCascadedAssociatedElements(SpecimenOrObservationBase<?> specimen);
 352
 353     /**
 354      * Deletes the specified specimen according to the setting in the {@link SpecimenDeleteConfigurator}.<br>
 355      * @param specimen the specimen which shoul be deleted
 356      * @param config specifies options if and how the specimen should be deleted like e.g. including all
 357      * of its children
 358      * @return the {@link DeleteResult} which holds information about the outcome of this operation
 359      */
 360     public DeleteResult delete(SpecimenOrObservationBase<?> specimen, SpecimenDeleteConfigurator config);
 361
 362     /**
 363      * Deletes the specified specimen and all sub derivates.<br>
 364      * <b>Note:</b> Be sure to allow child deletion in the config.
 365      * @param from the specimen which should be deleted with all its sub derivates
 366      * @param config the {@link SpecimenDeleteConfigurator} to specify how the deletion should be handled
 367      * @return the {@link DeleteResult} which holds information about the outcome of this operation
 368      */
 369     public DeleteResult deleteDerivateHierarchy(CdmBase from, SpecimenDeleteConfigurator config);
 370
 371     /**
 372      * Retrieves all {@link IndividualsAssociation} with the given specimen.<br>
 373      * @param specimen the specimen for which the associations are retrieved
 374      * @param limit
 375      * @param start
 376      * @param orderHints
 377      * @param propertyPaths
 378      * @return collection of all associations
 379      */
 380     public Collection<IndividualsAssociation> listIndividualsAssociations(SpecimenOrObservationBase<?> specimen, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 381
 382     /**
 383      * Retrieves all {@link SpecimenTypeDesignation}s which have the given specimen as a type specimen.
 384      * @param specimen the type specimen
 385      * @param limit
 386      * @param start
 387      * @param orderHints
 388      * @param propertyPaths
 389      * @return collection of all designations with the given type specimen
 390      */
 391     public Collection<SpecimenTypeDesignation> listTypeDesignations(SpecimenOrObservationBase<?> specimen, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 392
 393     /**
 394      * Retrieves all {@link DescriptionBase}s that have the given specimen set as described specimen.
 395      * @param specimen the described specimen
 396      * @param limit
 397      * @param start
 398      * @param orderHints
 399      * @param propertyPaths
 400      * @return collection of all descriptions with the given described specimen
 401      */
 402     public Collection<DescriptionBase<?>> listDescriptionsWithDescriptionSpecimen(SpecimenOrObservationBase<?> specimen, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 403
 404     /**
 405      * Gets all description elements that are used for describing the character
 406      * states of the given specimen
 407      *
 408      * @param specimen
 409      *            the specimen for which the character state description
 410      *            elements should be retrieved
 411      * @return a collection of all character state description elements for this
 412      *         specimen
 413      */
 414     public Collection<DescriptionElementBase> getCharacterDataForSpecimen(SpecimenOrObservationBase<?> specimen);
 415
 416     /**
 417      * Gets all description elements that are used for describing the character
 418      * states of the given specimen
 419      *
 420      * @param specimenUuid
 421      *            the specimen {@link UUID} for which the character state description
 422      *            elements should be retrieved
 423      * @return a collection of all character state description elements for this
 424      *         specimen
 425      */
 426     public Collection<DescriptionElementBase> getCharacterDataForSpecimen(UUID specimenUuid);
 427
 428     /**
 429      * Returns the most significant identifier for the given {@link DerivedUnit}.
 430      * @param derivedUnit the derived unit to check
 431      * @return the identifier string
 432      */
 433     public String getMostSignificantIdentifier(DerivedUnit derivedUnit);
 434
 435     /**
 436      * Returns the number of specimens that match the given parameters
 437      * @param clazz the class to match
 438      * @param queryString the queryString to match
 439      * @param type the {@link SpecimenOrObservationType} to match
 440      * @param associatedTaxon the taxon these specimens are in any way associated to via
 441      * determination, type designations, individuals associations, etc.
 442      * @param matchmode determines how the query string should be matched
 443      * @param limit
 444      *            the maximum number of entities returned (can be null to return
 445      *            all entities)
 446      * @param start
 447      * @param orderHints
 448      *            Supports path like <code>orderHints.propertyNames</code> which
 449      *            include *-to-one properties like createdBy.username or
 450      *            authorTeam.persistentTitleCache
 451      * @return the number of found specimens
 452      */
 453     public int countOccurrences(IIdentifiableEntityServiceConfigurator<SpecimenOrObservationBase> config);
 454
 455     /**
 456      * Return the all {@link SpecimenOrObservationBase}s of the complete
 457      * derivative hierarchy i.e. all parent and child derivatives and the given
 458      * specimen itself.
 459      *
 460      * @param specimen
 461      *            a specimen or observation
 462      * @return the derivative hierarchy as an unordered list of all specimens or observation
 463      */
 464     public List<SpecimenOrObservationBase<?>> getAllHierarchyDerivatives(SpecimenOrObservationBase<?> specimen);
 465
 466     /**
 467      * Returns all child derivatives of the given specimen.
 468      * @param specimen a specimen or observation
 469      * @return an unordered list of all child derivatives
 470      */
 471     public List<DerivedUnit> getAllChildDerivatives(SpecimenOrObservationBase<?> specimen);
 472
 473
 474 }