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.Collection;
  14 import java.util.List;
  15 import java.util.Map;
  16 import java.util.UUID;
  17
  18 //import org.springframework.transaction.TransactionStatus;
  19
  20 import eu.etaxonomy.cdm.api.service.config.ITaxonServiceConfigurator;
  21 import eu.etaxonomy.cdm.api.service.pager.Pager;
  22 import eu.etaxonomy.cdm.model.common.IdentifiableEntity;
  23 import eu.etaxonomy.cdm.model.common.OrderedTermVocabulary;
  24 import eu.etaxonomy.cdm.model.common.RelationshipBase;
  25 import eu.etaxonomy.cdm.model.common.TermVocabulary;
  26 import eu.etaxonomy.cdm.model.name.HomotypicalGroup;
  27 import eu.etaxonomy.cdm.model.name.NameRelationshipType;
  28 import eu.etaxonomy.cdm.model.name.Rank;
  29 import eu.etaxonomy.cdm.model.reference.ReferenceBase;
  30 import eu.etaxonomy.cdm.model.taxon.Synonym;
  31 import eu.etaxonomy.cdm.model.taxon.SynonymRelationship;
  32 import eu.etaxonomy.cdm.model.taxon.SynonymRelationshipType;
  33 import eu.etaxonomy.cdm.model.taxon.Taxon;
  34 import eu.etaxonomy.cdm.model.taxon.TaxonBase;
  35 import eu.etaxonomy.cdm.model.taxon.TaxonRelationship;
  36 import eu.etaxonomy.cdm.model.taxon.TaxonRelationshipType;
  37 import eu.etaxonomy.cdm.persistence.dao.BeanInitializer;
  38 import eu.etaxonomy.cdm.persistence.fetch.CdmFetch;
  39 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  40
  41
  42 public interface ITaxonService extends IIdentifiableEntityService<TaxonBase>{
  43
  44         /**
  45          * FIXME candidate for harmonization?
  46          */
  47         public abstract TaxonBase getTaxonByUuid(UUID uuid);
  48
  49         /**
  50          * FIXME candidate for harmonization?
  51          * save a taxon and return its UUID
  52          */
  53         public abstract UUID saveTaxon(TaxonBase taxon);
  54
  55         /**
  56          * FIXME candidate for harmonization?
  57          *  save a taxon and return its UUID
  58          */
  59         //public abstract UUID saveTaxon(TaxonBase taxon, TransactionStatus txStatus);
  60
  61         /**
  62          * FIXME candidate for harmonization?
  63          * save a collection of taxa and return its UUID
  64          */
  65         public abstract Map<UUID, ? extends TaxonBase> saveTaxonAll(Collection<? extends TaxonBase> taxonCollection);
  66
  67
  68         /**
  69          * FIXME candidate for harmonization?
  70          * delete a taxon and return its UUID
  71          */
  72         public abstract UUID removeTaxon(TaxonBase taxon);
  73
  74         /**
  75          * Computes all taxon bases.
  76          * FIXME could substitute with list(Synonym.class, limit, start)
  77          * @param limit
  78          * @param start
  79          * @return
  80          */
  81         public abstract List<Synonym> getAllSynonyms(int limit, int start);
  82
  83         /**
  84          * Computes all taxon bases.
  85          * FIXME could substitute with list(Taxon.class, limit,start)
  86          * @param limit
  87          * @param start
  88          * @return
  89          */
  90         public abstract List<Taxon> getAllTaxa(int limit, int start);
  91
  92         /**
  93          * Computes all taxon bases.
  94          * FIXME could substitute with list(limit,start) from superclass
  95          * @param limit
  96          * @param start
  97          * @return
  98          */
  99         public abstract List<TaxonBase> getAllTaxonBases(int limit, int start);
 100
 101         /**
 102          * Computes all Taxon instances that do not have a taxonomic parent and has at least one child.
 103          * @param sec The concept reference that the taxon belongs to
 104          * @return The List<Taxon> of root taxa.
 105          */
 106         public abstract List<Taxon> getRootTaxa(ReferenceBase sec);
 107
 108         /**
 109          * Computes all Taxon instances that do not have a taxonomic parent.
 110          * @param sec The concept reference that the taxon belongs to
 111          *
 112          * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
 113          * @return The List<Taxon> of root taxa.
 114          */
 115         public abstract List<Taxon> getRootTaxa(ReferenceBase sec, CdmFetch cdmFetch, boolean onlyWithChildren);
 116
 117         /**
 118          * Computes all Taxon instances that do not have a taxonomic parent.
 119          * @param sec The concept reference that the taxon belongs to
 120          * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
 121          * @param withMisapplications if false taxa that have at least one misapplied name relationship in which they are
 122          * the misapplied name are not returned.<Br>Default: true.
 123          * @return The List<Taxon> of root taxa.
 124          */
 125         public abstract List<Taxon> getRootTaxa(ReferenceBase sec, boolean onlyWithChildren, boolean withMisapplications);
 126
 127         /**
 128          * Computes all Taxon instances which name is of a certain Rank.
 129          * @param rank The rank of the taxon name
 130          * @param sec The concept reference that the taxon belongs to
 131          * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
 132          * @param withMisapplications if false taxa that have at least one misapplied name relationship in which they are
 133          * the misapplied name are not returned.<Br>Default: true.
 134          * @param propertyPaths
 135          *            properties to be initialized, For detailed description and
 136          *            examples <b>please refer to:</b>
 137          *            {@link BeanInitializer#initialize(Object, List)}. <Br>
 138          *            Default: true.
 139          * @return The List<Taxon> of root taxa.
 140          */
 141         public abstract List<Taxon> getRootTaxa(Rank rank, ReferenceBase sec, boolean onlyWithChildren, boolean withMisapplications, List<String> propertyPaths);
 142
 143         /**
 144          * Computes all relationships.
 145          * @param limit
 146          * @param start
 147          * @return
 148          */
 149     public abstract List<RelationshipBase> getAllRelationships(int limit, int start);
 150
 151         /**
 152          * Returns TaxonRelationshipType vocabulary
 153          * @return
 154          */
 155         public OrderedTermVocabulary<TaxonRelationshipType> getTaxonRelationshipTypeVocabulary();
 156
 157         /** */
 158         public abstract List<TaxonBase> searchTaxaByName(String name, ReferenceBase sec);
 159
 160         public Synonym makeTaxonSynonym (Taxon oldTaxon, Taxon newAcceptedTaxon, SynonymRelationshipType synonymType, ReferenceBase citation, String citationMicroReference);
 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> getRelatedTaxa(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 175
 176         /**
 177          * Returns the SynonymRelationships (of where relationship.type == type, if this arguement is supplied)
 178          * where the supplied taxon is relatedTo.
 179          *
 180          * @param taxon The taxon that is relatedTo
 181          * @param type The type of SynonymRelationship (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 Pager of SynonymRelationship instances
 187          */
 188         public Pager<SynonymRelationship> getSynonyms(Taxon taxon, SynonymRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 189
 190         public List<Synonym> getHomotypicSynonymsByHomotypicGroup(Taxon taxon, List<String> propertyPaths);
 191
 192         public List<List<Synonym>> getHeterotypicSynonymyGroups(Taxon taxon, List<String> propertyPaths);
 193
 194         /**
 195          * Returns a Paged List of TaxonBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
 196          *
 197          * @param clazz filter the results by class (or pass null to return all TaxonBase instances)
 198          * @param queryString
 199          * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
 200          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 201          * @param orderHints
 202          *            Supports path like <code>orderHints.propertyNames</code> which
 203          *            include *-to-one properties like createdBy.username or
 204          *            authorTeam.persistentTitleCache
 205          * @param propertyPaths properties to be initialized
 206          * @return a Pager Taxon instances
 207          * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
 208          */
 209         public Pager<TaxonBase> search(Class<? extends TaxonBase> clazz, String queryString, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 210
 211         /**
 212          * Returns a list of TaxonBase instances where the
 213          * taxon.name properties match the parameters passed.
 214          *
 215          * @param clazz optionally filter by class
 216          * @param uninomial
 217          * @param infragenericEpithet
 218          * @param specificEpithet
 219          * @param infraspecificEpithet
 220          * @param rank
 221          * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
 222          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 223          * @return a Pager of TaxonBase instances
 224          */
 225         public Pager<TaxonBase> findTaxaByName(Class<? extends TaxonBase> clazz, String uninomial, String infragenericEpithet, String specificEpithet, String infraspecificEpithet, Rank rank, Integer pageSize, Integer pageNumber);
 226
 227         /**
 228          * Returns a list of IdentifiableEntity instances (in particular, TaxonNameBase and TaxonBase instances)
 229          * that match the properties specified in the configurator.
 230          * @param configurator
 231          * @return
 232          */
 233         public Pager<IdentifiableEntity> findTaxaAndNames(ITaxonServiceConfigurator configurator);
 234 }