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

   1 /**
   2 * Copyright (C) 2007 EDIT
   3 * European Distributed Institute of Taxonomy
   4 * http://www.e-taxonomy.eu
   5 *
   6 * The contents of this file are subject to the Mozilla Public License Version 1.1
   7 * See LICENSE.TXT at the top of this package for the full license terms.
   8 */
   9
  10 package eu.etaxonomy.cdm.api.service;
  11
  12 import java.util.List;
  13 import java.util.Set;
  14 import java.util.UUID;
  15
  16 import eu.etaxonomy.cdm.api.service.dto.IdentifiedEntityDTO;
  17 import eu.etaxonomy.cdm.api.service.pager.Pager;
  18 import eu.etaxonomy.cdm.model.reference.Reference;
  19 import eu.etaxonomy.cdm.model.reference.ReferenceType;
  20 import eu.etaxonomy.cdm.model.taxon.TaxonBase;
  21 import eu.etaxonomy.cdm.model.term.DefinedTerm;
  22 import eu.etaxonomy.cdm.persistence.dto.UuidAndTitleCache;
  23 import eu.etaxonomy.cdm.persistence.query.MatchMode;
  24 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  25
  26
  27 public interface IReferenceService extends IIdentifiableEntityService<Reference> {
  28
  29         /**
  30          * Returns a Paged List of Reference instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
  31          *
  32          * @param clazz filter the results by class (or pass null to return all Reference instances)
  33          * @param queryString
  34          * @param pageSize The maximum number of references returned (can be null for all matching references)
  35          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
  36          * @param orderHints
  37          *            Supports path like <code>orderHints.propertyNames</code> which
  38          *            include *-to-one properties like createdBy.username or
  39          *            authorTeam.persistentTitleCache
  40          * @param propertyPaths properties to be initialized
  41          * @return a Pager Reference instances
  42          * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
  43          */
  44         @Override
  45     public Pager<Reference> search(Class<? extends Reference> clazz, String queryString, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
  46
  47         /**
  48          * Returns a map that holds uuid, titleCache pairs of all references in the current database
  49          *
  50          * @return
  51          *                      a <code>Map</code> containing uuid and titleCache of references
  52          */
  53         public List<UuidAndTitleCache<Reference>> getUuidAndTitle();
  54
  55         /**
  56          * TODO candidate for harmonization: rename to listForPublishing
  57          * @return
  58          */
  59         public List<Reference> getAllReferencesForPublishing();
  60
  61         /**
  62          * TODO candidate for harmonization: rename to listNomenclaturalReferences
  63          * @return
  64          */
  65         public List<Reference> getAllNomenclaturalReferences();
  66
  67         /**
  68          * returns
  69          *
  70          * <ol>
  71          * <li>all taxa directly covered by this reference</li>
  72          * <li>all taxa covered by the according in references of this reference</li>
  73          * </ol>
  74          *
  75          * searches for taxa using the following relations:
  76          * <ul>
  77          * <li>taxon.name.nomenclaturalreference</li>
  78          * <li>taxon.descriptions.descriptionElement.sources.citation</li>
  79          * <li>taxon.descriptions.descriptionSources</li>
  80          * <li>taxon.name.descriptions.descriptionElement.sources</li>
  81          * <li>taxon.name.descriptions.descriptionSources</li>
  82          * </ul>
  83          *
  84          * @param reference
  85          * @param includeSubordinateReferences TODO
  86          * @param propertyPaths
  87          * @return
  88          */
  89         public List<TaxonBase> listCoveredTaxa(Reference reference, boolean includeSubordinateReferences, List<String> propertyPaths);
  90
  91
  92     public List<UuidAndTitleCache<Reference>> getUuidAndAbbrevTitleCache(Integer limit, String pattern);
  93
  94     /**
  95      * @param limit
  96      * @param pattern
  97      * @param type
  98      * @return
  99      */
 100    public List<UuidAndTitleCache<Reference>> getUuidAndAbbrevTitleCache(Integer limit, String pattern, ReferenceType type);
 101    /**
 102     * @param limit
 103     * @param pattern
 104     * @param type
 105     * @return
 106     */
 107     public List<UuidAndTitleCache<Reference>> getUuidAndTitleCache(Integer limit, String pattern, ReferenceType type);
 108
 109     /**
 110      * @param identifier
 111      * @param identifierType
 112      * @param matchmode
 113      * @param limit
 114      * @return
 115      */
 116     public List<IdentifiedEntityDTO<Reference>> listByIdentifierAbbrev(String identifier, DefinedTerm identifierType,
 117         MatchMode matchmode, Integer limit);
 118
 119     /**
 120      * @param limit
 121      * @param pattern
 122      * @param type
 123      * @return
 124      */
 125     List<UuidAndTitleCache<Reference>> getUuidAndAbbrevTitleCacheForAuthor(Integer limit, String pattern,
 126             ReferenceType type);
 127
 128     /**
 129      * @param uuids
 130      *
 131      * @return
 132      */
 133     List<UuidAndTitleCache<Reference>> getUuidAndTitleCacheForUUIDS(Set<UUID> uuids);
 134
 135     /**
 136      * @param identifier
 137      * @param identifierType
 138      * @param matchmode
 139      * @param limit
 140      * @return
 141      */
 142     List<IdentifiedEntityDTO<Reference>> listByIdentifierAndTitleCacheAbbrev(String identifier,
 143             DefinedTerm identifierType, MatchMode matchmode, Integer limit);
 144
 145 }