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

   1 /**
   2 * Copyright (C) 2017 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 package eu.etaxonomy.cdm.api.service;
  10
  11 import java.io.IOException;
  12 import java.util.Collection;
  13 import java.util.List;
  14 import java.util.Map;
  15 import java.util.Optional;
  16 import java.util.Set;
  17 import java.util.UUID;
  18
  19 import eu.etaxonomy.cdm.api.service.pager.Pager;
  20 import eu.etaxonomy.cdm.model.common.User;
  21 import eu.etaxonomy.cdm.model.name.Registration;
  22 import eu.etaxonomy.cdm.model.name.RegistrationStatus;
  23 import eu.etaxonomy.cdm.model.name.TaxonName;
  24 import eu.etaxonomy.cdm.model.name.TypeDesignationStatusBase;
  25 import eu.etaxonomy.cdm.model.reference.Reference;
  26 import eu.etaxonomy.cdm.persistence.query.MatchMode;
  27 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  28
  29 /**
  30  * @author a.kohlbecker
  31  * @since May 2, 2017
  32  *
  33  */
  34 public interface IRegistrationService extends IAnnotatableService<Registration> {
  35
  36     /**
  37      * Returns a sublist of Registration instances stored in the database. A
  38      * maximum of 'limit' objects are returned, starting at object with index
  39      * 'start'. The bean properties specified by the parameter
  40      * <code>propertyPaths</code> and recursively initialized for each of the
  41      * entities in the resultset
  42      *
  43      * For detailed description and examples regarding
  44      * <code>propertyPaths</code> <b>please refer to:</b>
  45      * {@link IBeanInitializer#initialize(Object, List)}
  46      *
  47      * @param pageSize
  48      *            The maximum number of objects returned (can be null for all
  49      *            matching objects)
  50      * @param pageNumber
  51      *            The offset (in pageSize chunks) from the start of the result
  52      *            set (0 - based, can be null, equivalent of starting at the
  53      *            beginning of the recordset)
  54      * @param reference
  55      *            filters the Registration by the reference of the nomenclatural
  56      *            act for which the Registration as been created. The name and
  57      *            all type designations associated with the Registration are
  58      *            sharing the same citation. If the Optional itself is
  59      *            <code>null</code> the parameter is neglected. If Optional
  60      *            contains the value <code>null</code> all registrations with a
  61      *            name or type designation that has no reference are returned.
  62      *            Also those registrations having no name and type designation
  63      *            at all.
  64      * @param includedStatus
  65      *            filters the Registration by the RegistrationStatus. Only
  66      *            Registration having one of the supplied status will included.
  67      *            // * @param orderHints // * Supports path like
  68      *            <code>orderHints.propertyNames</code> which // * include
  69      *            *-to-one properties like createdBy.username or // *
  70      *            authorTeam.persistentTitleCache
  71      * @param propertyPaths
  72      * @return
  73      * @throws DataAccessException
  74      */
  75     public Pager<Registration> page(Optional<Reference> reference, Collection<RegistrationStatus> includedStatus,
  76             Integer pageSize, Integer pageIndex, List<String> propertyPaths);
  77
  78     /**
  79      * Returns a sublist of Registration instances stored in the database. A
  80      * maximum of 'limit' objects are returned, starting at object with index
  81      * 'start'. The bean properties specified by the parameter
  82      * <code>propertyPaths</code> and recursively initialized for each of the
  83      * entities in the resultset
  84      *
  85      * For detailed description and examples regarding
  86      * <code>propertyPaths</code> <b>please refer to:</b>
  87      * {@link IBeanInitializer#initialize(Object, List)}
  88      *
  89      * @param submitter
  90      *            Limits the result set to Registrations having the given
  91      *            submitter. This filter is ignored if set to <code>null</code>.
  92      * @param includedStatus
  93      *            filters the Registration by the RegistrationStatus. Only
  94      *            Registration having one of the supplied status will included.
  95      * @param identifierFilterPattern
  96      *            filters the Registration by this pattern, The asterisk can be used
  97      *            * as wildcard in any position of the pattern string
  98      * @param taxonNameFilterPattern
  99      *            filters the registered taxon name by this pattern, The asterisk can be used
 100      *            * as wildcard in any position of the pattern string
 101      * @param typeDesignationStatus
 102      * @param pageSize
 103      *            The maximum number of objects returned (can be null for all
 104      *            matching objects)
 105      * @param pageNumber
 106      *            The offset (in pageSize chunks) from the start of the result
 107      *            set (0 - based, can be null, equivalent of starting at the
 108      *            beginning of the recordset)
 109      * @param orderHints
 110      *            Supports path like <code>orderHints.propertyNames</code> which
 111      *            include *-to-one properties like createdBy.username or
 112      *            authorTeam.persistentTitleCache
 113      * @param propertyPaths
 114      * @return
 115      * @throws DataAccessException
 116      */
 117     public Pager<Registration> page(User submitter, Collection<RegistrationStatus> includedStatus,
 118             String identifierFilterPattern, String taxonNameFilterPattern, Set<TypeDesignationStatusBase> typeDesignationStatus, Integer pageSize,
 119             Integer pageIndex, List<OrderHint> orderHints, List<String> propertyPaths);
 120
 121     Pager<Registration> pageByIdentifier(String identifier, Integer pageIndex, Integer pageSize, List<String> propertyPaths) throws IOException;
 122
 123     public Map<UUID, RegistrationStatus> statusByIdentifier(String identifier) throws IOException;
 124
 125     /**
 126      * @param submitterUuid
 127      * @param includedStatusUuids
 128      * @param identifierFilterPattern
 129      * @param taxonNameFilterPattern
 130      * @param typeDesignationStatusUuids
 131      * @param pageSize
 132      * @param pageIndex
 133      * @param orderHints
 134      * @param propertyPaths
 135      * @return
 136      */
 137     Pager<Registration> page(UUID submitterUuid, Collection<RegistrationStatus> includedStatus, String identifierFilterPattern,
 138             String taxonNameFilterPattern, Collection<UUID> typeDesignationStatusUuids, Integer pageSize,
 139             Integer pageIndex, List<OrderHint> orderHints, List<String> propertyPaths);
 140
 141     public Pager<Registration> page(UUID submitterUuid, Collection<RegistrationStatus> includedStatus,
 142             Collection<UUID> taxonNameUUIDs,
 143             Integer pageSize, Integer pageIndex, List<OrderHint> orderHints, List<String> propertyPaths);
 144
 145     public Pager<Registration> pageTaxomicInclusion(UUID submitterUuid, Collection<RegistrationStatus> includedStatus,
 146             String taxonNameFilterPattern, MatchMode matchMode,
 147             Integer pageSize, Integer pageIndex, List<OrderHint> orderHints, List<String> propertyPaths);
 148
 149     // ============= functionality to be moved into a "RegistrationManagerBean" ==================
 150
 151     public Registration newRegistration();
 152
 153     Registration assureIsPersisted(Registration reg);
 154
 155     /**
 156      * Create and persist a new Registration for the name having the supplied UUID.
 157      *
 158      * @param taxonNameUuid
 159      * @return
 160      */
 161     Registration createRegistrationForName(UUID taxonNameUuid);
 162
 163     boolean checkRegistrationExistsFor(TaxonName name);
 164
 165     public void addTypeDesignation(UUID registrationUUID, UUID typeDesignationUuid);
 166
 167     /**
 168      * @param registration
 169      * @param typeDesignationUuid
 170      */
 171     public void addTypeDesignation(Registration registration, UUID typeDesignationUuid);
 172
 173     // ============================================================================================
 174
 175 }