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.reference.Reference;
  17 import eu.etaxonomy.cdm.model.taxon.TaxonBase;
  18 import eu.etaxonomy.cdm.persistence.dto.UuidAndTitleCache;
  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         @Override
  40     public Pager<Reference> search(Class<? extends Reference> clazz, String queryString, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
  41
  42         /**
  43          * Returns a map that holds uuid, titleCache pairs of all references in the current database
  44          *
  45          * @return
  46          *                      a <code>Map</code> containing uuid and titleCache of references
  47          */
  48         public List<UuidAndTitleCache<Reference>> getUuidAndTitle();
  49
  50         /**
  51          * TODO candidate for harmonization: rename to listForPublishing
  52          * @return
  53          */
  54         public List<Reference> getAllReferencesForPublishing();
  55
  56         /**
  57          * TODO candidate for harmonization: rename to listNomenclaturalReferences
  58          * @return
  59          */
  60         public List<Reference> getAllNomenclaturalReferences();
  61
  62         /**
  63          * returns
  64          *
  65          * <ol>
  66          * <li>all taxa directly covered by this reference</li>
  67          * <li>all taxa covered by the according in references of this reference</li>
  68          * </ol>
  69          *
  70          * searches for taxa using the following relations:
  71          * <ul>
  72          * <li>taxon.name.nomenclaturalreference</li>
  73          * <li>taxon.descriptions.descriptionElement.sources.citation</li>
  74          * <li>taxon.descriptions.descriptionSources</li>
  75          * <li>taxon.name.descriptions.descriptionElement.sources</li>
  76          * <li>taxon.name.descriptions.descriptionSources</li>
  77          * </ul>
  78          *
  79          * @param reference
  80          * @param includeSubordinateReferences TODO
  81          * @param propertyPaths
  82          * @return
  83          */
  84         public List<TaxonBase> listCoveredTaxa(Reference reference, boolean includeSubordinateReferences, List<String> propertyPaths);
  85 }