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