cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/IReferenceService.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.pager.Pager;
  16 import eu.etaxonomy.cdm.model.common.UuidAndTitleCache;
  17 import eu.etaxonomy.cdm.model.reference.Reference;
  18 import eu.etaxonomy.cdm.model.taxon.TaxonBase;
  19 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  20
  21
  22 public interface IReferenceService extends IIdentifiableEntityService<Reference> {
  23
  24         /**
  25          * Returns a Paged List of Reference instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
  26          *
  27          * @param clazz filter the results by class (or pass null to return all Reference instances)
  28          * @param queryString
  29          * @param pageSize The maximum number of references returned (can be null for all matching references)
  30          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
  31          * @param orderHints
  32          *            Supports path like <code>orderHints.propertyNames</code> which
  33          *            include *-to-one properties like createdBy.username or
  34          *            authorTeam.persistentTitleCache
  35          * @param propertyPaths properties to be initialized
  36          * @return a Pager Reference instances
  37          * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
  38          */
  39         public Pager<Reference> search(Class<? extends Reference> clazz, String queryString, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
  40
  41         /**
  42          * Returns a map that holds uuid, titleCache pairs of all references in the current database
  43          *
  44          * @return
  45          *                      a <code>Map</code> containing uuid and titleCache of references
  46          */
  47         public List<UuidAndTitleCache<Reference>> getUuidAndTitle();
  48
  49         /**
  50          * TODO candidate for harmonization: rename to listForPublishing
  51          * @return
  52          */
  53         public List<Reference> getAllReferencesForPublishing();
  54
  55         /**
  56          * TODO candidate for harmonization: rename to listNomenclaturalReferences
  57          * @return
  58          */
  59         public List<Reference> getAllNomenclaturalReferences();
  60
  61         /**
  62          * returns
  63          *
  64          * <ol>
  65          * <li>all taxa directly covered by this reference</li>
  66          * <li>all taxa covered by the according in references of this reference</li>
  67          * </ol>
  68          *
  69          * searches for taxa using the following relations:
  70          * <ul>
  71          * <li>taxon.name.nomenclaturalreference</li>
  72          * <li>taxon.descriptions.descriptionElement.sources.citation</li>
  73          * <li>taxon.descriptions.descriptionSources</li>
  74          * <li>taxon.name.descriptions.descriptionElement.sources</li>
  75          * <li>taxon.name.descriptions.descriptionSources</li>
  76          * </ul>
  77          *
  78          * @param reference
  79          * @param includeSubordinateReferences TODO
  80          * @param propertyPaths
  81          * @return
  82          */
  83         public List<TaxonBase> listCoveredTaxa(Reference reference, boolean includeSubordinateReferences, List<String> propertyPaths);
  84 }