001package org.gbif.api.service.collections;
002
003import java.io.IOException;
004import java.io.InputStream;
005import java.util.UUID;
006
007import org.gbif.api.model.collections.descriptors.DescriptorChangeSuggestion;
008import org.gbif.api.model.collections.descriptors.DescriptorChangeSuggestionRequest;
009import org.gbif.api.model.collections.suggestions.Status;
010import org.gbif.api.model.collections.suggestions.Type;
011import org.gbif.api.model.common.paging.Pageable;
012import org.gbif.api.model.common.paging.PagingResponse;
013import org.gbif.api.vocabulary.Country;
014
015/**
016 * Service interface for managing descriptor change suggestions in collections.
017 * This service handles the creation, updating, and management of descriptor change suggestions,
018 * including file handling and status management.
019 *
020 * Note: File storage is handled internally using unique identifiers. The provided filename
021 * is used only for display and metadata purposes.
022 */
023public interface DescriptorChangeSuggestionService {
024
025  /**
026   * Creates a new descriptor change suggestion.
027   *
028   * @param fileStream The input stream containing the descriptor data
029   * @param filename The original filename (used for display and metadata only)
030   * @param request The suggestion request containing metadata
031   * @return The created DescriptorChangeSuggestion
032   * @throws IOException If there's an error processing the file
033   * @throws IllegalArgumentException If the request is invalid
034   */
035  DescriptorChangeSuggestion createSuggestion(InputStream fileStream, String filename, DescriptorChangeSuggestionRequest request) throws IOException;
036
037  /**
038   * Updates an existing descriptor change suggestion.
039   * Only pending suggestions can be updated.
040   *
041   * @param key The key of the suggestion to update
042   * @param request The updated suggestion request
043   * @param fileStream Optional new file stream to replace the existing one
044   * @param filename The original filename if fileStream is provided (used for display and metadata only)
045   * @return The updated DescriptorChangeSuggestion
046   * @throws IOException If there's an error processing the file
047   * @throws IllegalArgumentException If the suggestion is not in PENDING state
048   * @throws IllegalStateException If the suggestion cannot be updated
049   */
050  DescriptorChangeSuggestion updateSuggestion(long key, DescriptorChangeSuggestionRequest request, InputStream fileStream, String filename) throws IOException;
051
052  /**
053   * Retrieves a descriptor change suggestion by its key.
054   *
055   * @param key The key of the suggestion to retrieve
056   * @return The DescriptorChangeSuggestion or null if not found
057   */
058  DescriptorChangeSuggestion getSuggestion(long key);
059
060  /**
061   * Retrieves the file associated with a descriptor change suggestion.
062   *
063   * @param key The key of the suggestion
064   * @return InputStream containing the suggestion file data
065   * @throws IllegalArgumentException If the suggestion is not found
066   * @throws IOException If there's an error reading the file
067   */
068  InputStream getSuggestionFile(long key) throws IOException;
069
070  /**
071   * Applies a pending descriptor change suggestion.
072   * This will create or update the descriptor group based on the suggestion.
073   *
074   * @param key The key of the suggestion to apply
075   * @throws IOException If there's an error processing the file
076   * @throws IllegalArgumentException If the suggestion is not in PENDING state
077   * @throws IllegalStateException If the suggestion cannot be applied
078   */
079  void applySuggestion(long key) throws IOException;
080
081  /**
082   * Discards a pending descriptor change suggestion.
083   *
084   * @param key The key of the suggestion to discard
085   * @throws IllegalArgumentException If the suggestion is not in PENDING state
086   * @throws IllegalStateException If the suggestion cannot be discarded
087   */
088  void discardSuggestion(long key);
089
090
091  /**
092   * Lists descriptor change suggestions with optional filters.
093   *
094   * @param pageable Pagination details
095   * @param status Filter by status (PENDING, APPROVED, DISCARDED)
096   * @param type Filter by type (CREATE, UPDATE, DELETE)
097   * @param proposerEmail Filter by proposer's email
098   * @param collectionKey Filter by collection key
099   * @param country Filter by collection's country
100   * @return PagingResponse containing the filtered suggestions
101   */
102  PagingResponse<DescriptorChangeSuggestion> list(Pageable pageable, Status status, Type type, String proposerEmail, UUID collectionKey, Country country);
103
104  /**
105   * Counts the total number of descriptor change suggestions based on filters.
106   *
107   * @param status Filter by status
108   * @param type Filter by type
109   * @param proposerEmail Filter by proposer's email
110   * @param collectionKey Filter by collection key
111   * @param country Filter by collection's country
112   * @return Total number of matching suggestions
113   */
114  long count(Status status, Type type, String proposerEmail, UUID collectionKey, Country country);
115}