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

   1 // $Id$
   2 /**
   3 * Copyright (C) 2007 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.util.List;
  14
  15 import eu.etaxonomy.cdm.api.service.config.ITaxonServiceConfigurator;
  16 import eu.etaxonomy.cdm.api.service.pager.Pager;
  17 import eu.etaxonomy.cdm.model.common.IdentifiableEntity;
  18 import eu.etaxonomy.cdm.model.common.OrderedTermVocabulary;
  19 import eu.etaxonomy.cdm.model.common.RelationshipBase;
  20 import eu.etaxonomy.cdm.model.media.MediaRepresentation;
  21 import eu.etaxonomy.cdm.model.name.Rank;
  22 import eu.etaxonomy.cdm.model.reference.ReferenceBase;
  23 import eu.etaxonomy.cdm.model.taxon.Synonym;
  24 import eu.etaxonomy.cdm.model.taxon.SynonymRelationship;
  25 import eu.etaxonomy.cdm.model.taxon.SynonymRelationshipType;
  26 import eu.etaxonomy.cdm.model.taxon.Taxon;
  27 import eu.etaxonomy.cdm.model.taxon.TaxonBase;
  28 import eu.etaxonomy.cdm.model.taxon.TaxonNode;
  29 import eu.etaxonomy.cdm.model.taxon.TaxonRelationship;
  30 import eu.etaxonomy.cdm.model.taxon.TaxonRelationshipType;
  31 import eu.etaxonomy.cdm.persistence.dao.BeanInitializer;
  32 import eu.etaxonomy.cdm.persistence.fetch.CdmFetch;
  33 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  34
  35
  36 public interface ITaxonService extends IIdentifiableEntityService<TaxonBase>{
  37
  38         /**
  39          * Computes all taxon bases.
  40          * FIXME could substitute with list(Synonym.class, limit, start)
  41          * @param limit
  42          * @param start
  43          * @return
  44          */
  45         public List<Synonym> getAllSynonyms(int limit, int start);
  46
  47         /**
  48          * Computes all taxon bases.
  49          * FIXME could substitute with list(Taxon.class, limit,start)
  50          * @param limit
  51          * @param start
  52          * @return
  53          */
  54         public List<Taxon> getAllTaxa(int limit, int start);
  55
  56         /**
  57          * Computes all Taxon instances that do not have a taxonomic parent and has at least one child.
  58          * @param sec The concept reference that the taxon belongs to
  59          * @return The List<Taxon> of root taxa.
  60          * @deprecated obsolete when using taxonomicTree
  61          */
  62         public List<Taxon> getRootTaxa(ReferenceBase sec);
  63
  64
  65         /**
  66          * Computes all Taxon instances that do not have a taxonomic parent.
  67          * @param sec The concept reference that the taxon belongs to
  68          *
  69          * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
  70          * @return The List<Taxon> of root taxa.
  71          * @deprecated obsolete when using taxonomicTree
  72          */
  73         public List<Taxon> getRootTaxa(ReferenceBase sec, CdmFetch cdmFetch, boolean onlyWithChildren);
  74
  75         /**
  76          * Computes all Taxon instances that do not have a taxonomic parent.
  77          * @param sec The concept reference that the taxon belongs to
  78          * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
  79          * @param withMisapplications if false taxa that have at least one misapplied name relationship in which they are
  80          * the misapplied name are not returned.<Br>Default: true.
  81          * @return The List<Taxon> of root taxa.
  82          * @deprecated obsolete when using taxonomicTree
  83          */
  84         public List<Taxon> getRootTaxa(ReferenceBase sec, boolean onlyWithChildren, boolean withMisapplications);
  85
  86         /**
  87          * Computes all Taxon instances which name is of a certain Rank.
  88          * @param rank The rank of the taxon name
  89          * @param sec The concept reference that the taxon belongs to
  90          * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
  91          * @param withMisapplications if false taxa that have at least one misapplied name relationship in which they are
  92          * the misapplied name are not returned.<Br>Default: true.
  93          * @param propertyPaths
  94          *            properties to be initialized, For detailed description and
  95          *            examples <b>please refer to:</b>
  96          *            {@link BeanInitializer#initialize(Object, List)}. <Br>
  97          *            Default: true.
  98          * @return The List<Taxon> of root taxa.
  99          * @deprecated obsolete when using taxonomicTree
 100          */
 101         public List<Taxon> getRootTaxa(Rank rank, ReferenceBase sec, boolean onlyWithChildren, boolean withMisapplications, List<String> propertyPaths);
 102
 103         /**
 104          * Computes all relationships.
 105          * @param limit
 106          * @param start
 107          * @return
 108          */
 109     public List<RelationshipBase> getAllRelationships(int limit, int start);
 110
 111         /**
 112          * Returns TaxonRelationshipType vocabulary
 113          * @return
 114          * @deprecated use TermService#getVocabulary(VocabularyType) instead
 115          */
 116         public OrderedTermVocabulary<TaxonRelationshipType> getTaxonRelationshipTypeVocabulary();
 117
 118         /** */
 119         public List<TaxonBase> searchTaxaByName(String name, ReferenceBase sec);
 120
 121         /**
 122          * Changes an accepted taxon to a synonym of another taxon.
 123          *
 124          * @param oldTaxonNode
 125          *                              the <code>TaxonNode</code> of the accepted taxon that will be changed into a synonym
 126          * @param newAcceptedTaxonNode
 127          *                              the <code>TaxonNode</code> of the accepted taxon, the old taxon will become a synonym of
 128          * @param synonymType
 129          *                              <code>SynonymRelationshipType</code> to indicate whether hetero or homotypic
 130          * @param citation
 131          *                              the reference for this assumption
 132          * @param citationMicroReference
 133          *                              the micro citation
 134          * @return
 135          *                              the newly created synonym
 136          */
 137         public Synonym changeAcceptedTaxonToSynonym (TaxonNode oldTaxonNode, TaxonNode newAcceptedTaxonNode, SynonymRelationshipType synonymType, ReferenceBase citation, String citationMicroReference);
 138
 139         /**
 140          * Swaps given synonym and accepted taxon.
 141          * In particular:
 142          * <ul>
 143          *              <li>A new accepted taxon with the synonyms name is created</li>
 144          *              <li>The synonym is deleted from the old accepted taxons synonym list</li>
 145          *              <li>A new synonym with the name of the old accepted taxon is created</li>
 146          *              <li>The newly created synonym get related to the newly created accepted taxon</li>
 147          * </ul>
 148          *
 149          * @param synonym
 150          * @param acceptedTaxon
 151          * @param synonymRelationshipType the relationship type the newly created synonym will have. Defaults to SYNONYM_OF
 152          */
 153         public void swapSynonymAndAcceptedTaxon(Synonym synonym, Taxon acceptedTaxon, SynonymRelationshipType synonymRelationshipType );
 154
 155         /**
 156          * Change a synonym into an accepted taxon and removes existing synonym relationship to the given accepted taxon.
 157          *
 158          * @param synonym
 159          *                              the synonym to change into an accepted taxon
 160          * @param acceptedTaxon
 161          *                              an accepted taxon, the synonym had a relationship to
 162          * @return
 163          *                              the newly created accepted taxon
 164          */
 165         public Taxon changeSynonymToAcceptedTaxon(Synonym synonym, Taxon acceptedTaxon);
 166
 167         /**
 168          * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
 169          * where the supplied taxon is relatedTo.
 170          *
 171          * @param taxon The taxon that is relatedTo
 172          * @param type The type of TaxonRelationship (can be null)
 173          * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 174          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 175          * @param orderHints Properties to order by
 176          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 177          * @return a List of TaxonRelationship instances
 178          */
 179         public List<TaxonRelationship> listToTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 180
 181         /**
 182          * Returns the TaxonRelationships (of where relationship.type == type, if this arguement is supplied)
 183          * where the supplied taxon is relatedTo.
 184          *
 185          * @param taxon The taxon that is relatedTo
 186          * @param type The type of TaxonRelationship (can be null)
 187          * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 188          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 189          * @param orderHints Properties to order by
 190          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 191          * @return a Pager of TaxonRelationship instances
 192          */
 193         public Pager<TaxonRelationship> pageToTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 194
 195         /**
 196          * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
 197          * where the supplied taxon is relatedFrom.
 198          *
 199          * @param taxon The taxon that is relatedFrom
 200          * @param type The type of TaxonRelationship (can be null)
 201          * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 202          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 203          * @param orderHints Properties to order by
 204          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 205          * @return a List of TaxonRelationship instances
 206          */
 207         public List<TaxonRelationship> listFromTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 208
 209         /**
 210          * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
 211          * where the supplied taxon is relatedFrom.
 212          *
 213          * @param taxon The taxon that is relatedFrom
 214          * @param type The type of TaxonRelationship (can be null)
 215          * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 216          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 217          * @param orderHints Properties to order by
 218          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 219          * @return a Pager of TaxonRelationship instances
 220          */
 221         public Pager<TaxonRelationship> pageFromTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 222
 223         /**
 224          * Returns the SynonymRelationships (of where relationship.type == type, if this argument is supplied)
 225          * where the supplied synonym is relatedFrom.
 226          *
 227          * @param taxon The synonym that is relatedFrom
 228          * @param type The type of SynonymRelationship (can be null)
 229          * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 230          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 231          * * @param orderHints Properties to order by
 232          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 233          * @return a Pager of SynonymRelationship instances
 234          */
 235         public Pager<SynonymRelationship> getSynonyms(Synonym synonym, SynonymRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 236
 237         /**
 238          * Returns the SynonymRelationships (of where relationship.type == type, if this argument is supplied)
 239          * where the supplied taxon is relatedTo.
 240          *
 241          * @param taxon The taxon that is relatedTo
 242          * @param type The type of SynonymRelationship (can be null)
 243          * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 244          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 245          * * @param orderHints Properties to order by
 246          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 247          * @return a Pager of SynonymRelationship instances
 248          */
 249         public Pager<SynonymRelationship> getSynonyms(Taxon taxon, SynonymRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 250
 251         public List<Synonym> getHomotypicSynonymsByHomotypicGroup(Taxon taxon, List<String> propertyPaths);
 252
 253         public List<List<Synonym>> getHeterotypicSynonymyGroups(Taxon taxon, List<String> propertyPaths);
 254
 255         /**
 256          * Returns a Paged List of TaxonBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
 257          *
 258          * @param clazz filter the results by class (or pass null to return all TaxonBase instances)
 259          * @param queryString
 260          * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
 261          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 262          * @param orderHints
 263          *            Supports path like <code>orderHints.propertyNames</code> which
 264          *            include *-to-one properties like createdBy.username or
 265          *            authorTeam.persistentTitleCache
 266          * @param propertyPaths properties to be initialized
 267          * @return a Pager Taxon instances
 268          * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
 269          */
 270         public Pager<TaxonBase> search(Class<? extends TaxonBase> clazz, String queryString, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 271
 272         /**
 273          * Returns a list of TaxonBase instances where the
 274          * taxon.name properties match the parameters passed.
 275          *
 276          * @param clazz optionally filter by class
 277          * @param uninomial
 278          * @param infragenericEpithet
 279          * @param specificEpithet
 280          * @param infraspecificEpithet
 281          * @param rank
 282          * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
 283          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 284          * @return a Pager of TaxonBase instances
 285          */
 286         public Pager<TaxonBase> findTaxaByName(Class<? extends TaxonBase> clazz, String uninomial, String infragenericEpithet, String specificEpithet, String infraspecificEpithet, Rank rank, Integer pageSize, Integer pageNumber);
 287
 288         /**
 289          * Returns a list of IdentifiableEntity instances (in particular, TaxonNameBase and TaxonBase instances)
 290          * that match the properties specified in the configurator.
 291          * @param configurator
 292          * @return
 293          */
 294         public Pager<IdentifiableEntity> findTaxaAndNames(ITaxonServiceConfigurator configurator);
 295
 296         /**
 297          *
 298          * @param taxon
 299          * @param size
 300          * @param height
 301          * @param widthOrDuration
 302          * @param mimeTypes
 303          * @return
 304          */
 305         public List<MediaRepresentation> getAllMedia(Taxon taxon, int size, int height, int widthOrDuration, String[] mimeTypes);
 306 }