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