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   * Takes the descriptor group file content, format, title, description, tags, and collection key as input.
021   *
022   * @param descriptorsGroupFile The byte array content of the descriptor group file.
023   * @param format The format of the descriptor group file (e.g., CSV, TSV).
024   * @param title The title of the descriptor group.
025   * @param description Optional description for the descriptor group.
026   * @param tags Optional set of tags associated with the descriptor group.
027   * @param collectionKey The UUID key of the collection this descriptor group belongs to.
028   * @return key of the created descriptor group.
029   */
030  long createDescriptorGroup(
031      @NotNull @Valid byte[] descriptorsGroupFile,
032      @NotNull ExportFormat format,
033      @NotNull String title,
034      String description,
035      Set<String> tags,
036      @NotNull UUID collectionKey);
037
038  /**
039   * Deletes a descriptor group by key.
040   *
041   * @param key of the descriptor group to be deleted.
042   */
043  void deleteDescriptorGroup(@NotNull long key);
044
045  /**
046   * Retrieves a descriptor group by its key.
047   *
048   * @param key of the descriptor group to be retrieved.
049   * @return the descriptor group
050   */
051  DescriptorGroup getDescriptorGroup(@NotNull long key);
052
053  /**
054   * Updates an existing descriptor group.
055   *
056   * @param descriptorGroupKey The key of the descriptor group to update.
057   * @param descriptorsGroupFile The new byte array content of the descriptor group file.
058   * @param format The format of the new descriptor group file.
059   * @param title The new title for the descriptor group.
060   * @param tags An optional set of new tags for the descriptor group. Existing tags not included will be removed.
061   * @param description An optional new description for the descriptor group.
062   */
063  void updateDescriptorGroup(
064      @NotNull long descriptorGroupKey,
065      byte[] descriptorsGroupFile,
066      @NotNull ExportFormat format,
067      @NotNull String title,
068      Set<String> tags,
069      String description);
070
071  /**
072   * Pages {@link DescriptorGroup} entities based on the parameters received.
073   *
074   * @param searchRequest {@link DescriptorGroupSearchRequest} with all the parameters
075   * @return a list of entities ordered by their creation date, newest coming first
076   */
077  PagingResponse<DescriptorGroup> listDescriptorGroups(
078      @NotNull UUID collectionKey, DescriptorGroupSearchRequest searchRequest);
079
080  /**
081   * Retrieves a descriptor by its key.
082   *
083   * @param key of the descriptor to be retrieved.
084   * @return the descriptor
085   */
086  Descriptor getDescriptor(@NotNull long key);
087
088  /**
089   * Pages {@link Descriptor} entities based on the parameters received.
090   *
091   * @param searchRequest {@link DescriptorSearchRequest} with all the parameters
092   * @return a list of entities ordered by their creation date, newest coming first
093   */
094  PagingResponse<Descriptor> listDescriptors(DescriptorSearchRequest searchRequest);
095
096  /**
097   * Counts the number of {@link Descriptor} for the request received.
098   *
099   * @param searchRequest {@link DescriptorSearchRequest} with all the parameters
100   * @return number of descriptors
101   */
102  long countDescriptors(DescriptorSearchRequest searchRequest);
103
104  /**
105   * Get the names of the verbatim fields of a descriptor group.
106   *
107   * @param descriptorGroupKey key of the descriptor group.
108   * @return the names
109   */
110  Set<String> getVerbatimNames(long descriptorGroupKey);
111
112  /**
113   * Reinterprets a descriptor group.
114   *
115   * @param descriptorGroupKey key of the descriptor group.
116   */
117  void reinterpretDescriptorGroup(@NotNull long descriptorGroupKey);
118
119  /**
120   * Reinterprets all the descriptor groups of a collection.
121   *
122   * @param collectionKey key of the collection
123   */
124  void reinterpretCollectionDescriptorGroups(@NotNull UUID collectionKey);
125
126  /** Reinterprets all the descriptor groups of all collections. */
127  void reinterpretAllDescriptorGroups();
128}