cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/IAgentService.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 import java.util.UUID;
  15
  16 import eu.etaxonomy.cdm.api.service.pager.Pager;
  17 import eu.etaxonomy.cdm.model.agent.Address;
  18 import eu.etaxonomy.cdm.model.agent.AgentBase;
  19 import eu.etaxonomy.cdm.model.agent.Institution;
  20 import eu.etaxonomy.cdm.model.agent.InstitutionalMembership;
  21 import eu.etaxonomy.cdm.model.agent.Person;
  22 import eu.etaxonomy.cdm.model.agent.Team;
  23 import eu.etaxonomy.cdm.persistence.dto.UuidAndTitleCache;
  24 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  25 import eu.etaxonomy.cdm.strategy.merge.MergeException;
  26
  27 public interface IAgentService extends IIdentifiableEntityService<AgentBase> {
  28
  29         public List<Institution> searchInstitutionByCode(String code);
  30
  31         /**
  32          * Return a paged list of the institutional memberships held by a person
  33          *
  34          * @param person the person
  35          * @param pageSize The maximum number of memberships returned (can be null for all memberships)
  36          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
  37          * @return a Pager containing InstitutionalMembership  instances
  38          */
  39         public Pager<InstitutionalMembership> getInstitutionalMemberships(Person person, Integer pageSize, Integer pageNumber);
  40
  41         /**
  42          * Return a paged list of the members of a team
  43          *
  44          * @param team the team
  45          * @param pageSize The maximum number of members returned (can be null for all members)
  46          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
  47          * @return a Pager containing Person  instances
  48          */
  49         public Pager<Person> getMembers(Team team, Integer pageSize, Integer pageNumber);
  50
  51         /**
  52          * Return a paged list of the addresses of an agent
  53          *
  54          * @param agent the agent
  55          * @param pageSize The maximum number of addresses returned (can be null for all members)
  56          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
  57          * @return a Pager containing Address  instances
  58          */
  59         public Pager<Address> getAddresses(AgentBase agent, Integer pageSize, Integer pageNumber);
  60
  61         /**
  62          * Returns a Paged List of AgentBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
  63          *
  64          * @param clazz filter the results by class (or pass null to return all AgentBase instances)
  65          * @param queryString
  66          * @param pageSize The maximum number of agents returned (can be null for all matching agents)
  67          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
  68          * @param orderHints
  69          *            Supports path like <code>orderHints.propertyNames</code> which
  70          *            include *-to-one properties like createdBy.username or
  71          *            authorTeam.persistentTitleCache
  72          * @param propertyPaths properties to be initialized
  73          * @return a Pager Agent instances
  74          * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
  75          */
  76         @Override
  77     public Pager<AgentBase> search(Class<? extends AgentBase> clazz, String queryString, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
  78
  79         /**
  80          * Returns a list of <code>UuidAndTitleCache</code> containing all <code>Person</code>s
  81          *
  82          * @return a list of <code>UuidAndTitleCache</code> instances
  83          */
  84         public List<UuidAndTitleCache<Person>> getPersonUuidAndTitleCache();
  85
  86         /**
  87          * Returns a list of <code>UuidAndTitleCache</code> containing all <code>TeamOrPersonBase</code> objects
  88          * with their respective titleCache
  89          *
  90          * @return a list of <code>UuidAndTitleCache</code> instances
  91          */
  92         public List<UuidAndTitleCache<Team>> getTeamUuidAndTitleCache();
  93
  94         /**
  95          * Returns a list of <code>UuidAndTitleCache</code> containing all <code>TeamOrPersonBase</code> objects
  96          * with their respective nomenclaturalTitle instead of regular titleCache
  97          *
  98          * @return a list of <code>UuidAndTitleCache</code> instances
  99          */
 100         public List<UuidAndTitleCache<Team>> getTeamUuidAndNomenclaturalTitle();
 101
 102         /**
 103          * Returns a list of <code>UuidAndTitleCache</code> containing all {@link Institution} objects
 104          * with their respective titleCache
 105          *
 106          * @return a list of <code>UuidAndTitleCache</code> instances
 107          */
 108         public List<UuidAndTitleCache<Institution>> getInstitutionUuidAndTitleCache();
 109
 110
 111         /**
 112      * Returns a list of <code>UuidAndTitleCache</code> containing all {@link Institution} objects
 113      * with their respective NomenclaturalTitleCache
 114      *
 115      * @return a list of <code>UuidAndTitleCache</code> instances
 116      */
 117     public List<UuidAndTitleCache<AgentBase>> getUuidAndAbbrevTitleCache();
 118
 119     /**
 120      * @param teamUuid
 121      * @return
 122      * @throws MergeException
 123      */
 124     public UpdateResult convertTeam2Person(UUID teamUuid) throws MergeException;
 125
 126         /**
 127          * If the given {@link Team} is a single member team all links to the team are redirected to the
 128          * single member and the team itself is deleted.
 129          * <BR>
 130          * If the given {@link Team} has no members (protected caches) a new {@link Person} is created
 131          * and all links to the team are redirected to the new person and the team itself is deleted.
 132          * <BR>
 133          * Otherwise, an {@link IllegalArgumentException} is thrown.
 134          *
 135          * @param team the team to be converted
 136          * @return the existing or new person that replaces the given team
 137          * @throws IllegalArgumentException if team has > 1 members
 138          * @throws MergeException if anything else goes wrong during merge
 139          */
 140         public UpdateResult convertTeam2Person(Team team) throws MergeException, IllegalArgumentException;
 141
 142
 143     /**
 144      * @param personUuid
 145      * @return
 146      * @throws MergeException
 147      * @throws IllegalArgumentException
 148      */
 149     public UpdateResult convertPerson2Team(UUID personUuid) throws MergeException, IllegalArgumentException;
 150
 151         /**
 152          * If possible replaces the given person by a new {@link Team}.
 153          * <BR>This is only possible if the person is at no place used in person only mode, which
 154          * is the case e.g. at User.person or FieldUnit.primaryCollector.
 155          * <BR>
 156          * If the person can not be replaced a {@link MergeException} is thrown.
 157          *
 158          * @param person the {@link Person} to be converted
 159          * @return the new team that replaces the given person
 160          * @throws MergeException if anything else goes wrong during merge
 161          */
 162         public UpdateResult convertPerson2Team(Person person) throws MergeException, IllegalArgumentException;
 163
 164 }