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