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