001package org.gbif.api.service.collections;
002
003import java.util.Set;
004import java.util.UUID;
005import javax.validation.Valid;
006import javax.validation.constraints.NotNull;
007import org.gbif.api.model.collections.descriptors.Descriptor;
008import org.gbif.api.model.collections.descriptors.DescriptorGroup;
009import org.gbif.api.model.collections.request.DescriptorGroupSearchRequest;
010import org.gbif.api.model.collections.request.DescriptorSearchRequest;
011import org.gbif.api.model.common.export.ExportFormat;
012import org.gbif.api.model.common.paging.PagingResponse;
013
014/** API service to work with collection descriptors. */
015public interface DescriptorsService {
016
017  /**
018   * Creates a new descriptor group.
019   *
020   * <p>// TODO
021   *
022   * @return key of the created descriptor group.
023   */
024  long createDescriptorGroup(
025      @NotNull @Valid byte[] descriptorsGroupFile,
026      @NotNull ExportFormat format,
027      @NotNull String title,
028      String description,
029      @NotNull UUID collectionKey);
030
031  /**
032   * Deletes a descriptor group by key.
033   *
034   * @param key of the descriptor group to be deleted.
035   */
036  void deleteDescriptorGroup(@NotNull long key);
037
038  /**
039   * Retrieves a descriptor group by its key.
040   *
041   * @param key of the descriptor group to be retrieved.
042   * @return the descriptor group
043   */
044  DescriptorGroup getDescriptorGroup(@NotNull long key);
045
046  /**
047   * Updates an existing descriptor group.
048   *
049   * @param // TODO
050   */
051  void updateDescriptorGroup(
052      @NotNull long descriptorGroupKey,
053      @NotNull byte[] descriptorsGroupFile,
054      @NotNull ExportFormat format,
055      @NotNull String title,
056      String description);
057
058  /**
059   * Pages {@link DescriptorGroup} entities based on the parameters received.
060   *
061   * @param searchRequest {@link DescriptorGroupSearchRequest} with all the parameters
062   * @return a list of entities ordered by their creation date, newest coming first
063   */
064  PagingResponse<DescriptorGroup> listDescriptorGroups(
065      @NotNull UUID collectionKey, DescriptorGroupSearchRequest searchRequest);
066
067  /**
068   * Retrieves a descriptor by its key.
069   *
070   * @param key of the descriptor to be retrieved.
071   * @return the descriptor
072   */
073  Descriptor getDescriptor(@NotNull long key);
074
075  /**
076   * Pages {@link Descriptor} entities based on the parameters received.
077   *
078   * @param searchRequest {@link DescriptorSearchRequest} with all the parameters
079   * @return a list of entities ordered by their creation date, newest coming first
080   */
081  PagingResponse<Descriptor> listDescriptors(DescriptorSearchRequest searchRequest);
082
083  /**
084   * Counts the number of {@link Descriptor} for the request received.
085   *
086   * @param searchRequest {@link DescriptorSearchRequest} with all the parameters
087   * @return number of descriptors
088   */
089  long countDescriptors(DescriptorSearchRequest searchRequest);
090
091  /**
092   * Get the names of the verbatim fields of a descriptor group.
093   *
094   * @param descriptorGroupKey key of the descriptor group.
095   * @return the names
096   */
097  Set<String> getVerbatimNames(long descriptorGroupKey);
098
099  /**
100   * Reinterprets a descriptor group.
101   *
102   * @param descriptorGroupKey key of the descriptor group.
103   */
104  void reinterpretDescriptorGroup(@NotNull long descriptorGroupKey);
105
106  /**
107   * Reinterprets all the descriptor groups of a collection.
108   *
109   * @param collectionKey key of the collection
110   */
111  void reinterpretCollectionDescriptorGroups(@NotNull UUID collectionKey);
112
113  /** Reinterprets all the descriptor groups of all collections. */
114  void reinterpretAllDescriptorGroups();
115}