Package org.gbif.api.service.collections

Interface DescriptorChangeSuggestionService

public interface DescriptorChangeSuggestionService
Service interface for managing descriptor change suggestions in collections. This service handles the creation, updating, and management of descriptor change suggestions, including file handling and status management. Note: File storage is handled internally using unique identifiers. The provided filename is used only for display and metadata purposes.

  • Method Details

    • createSuggestion

      DescriptorChangeSuggestion createSuggestion(InputStream fileStream, String filename, DescriptorChangeSuggestionRequest request) throws IOException
      Creates a new descriptor change suggestion.
      Parameters:
      fileStream - The input stream containing the descriptor data
      filename - The original filename (used for display and metadata only)
      request - The suggestion request containing metadata
      Returns:
      The created DescriptorChangeSuggestion
      Throws:
      IOException - If there's an error processing the file
      IllegalArgumentException - If the request is invalid

    • updateSuggestion

      DescriptorChangeSuggestion updateSuggestion(long key, DescriptorChangeSuggestionRequest request, InputStream fileStream, String filename) throws IOException
      Updates an existing descriptor change suggestion. Only pending suggestions can be updated.
      Parameters:
      key - The key of the suggestion to update
      request - The updated suggestion request
      fileStream - Optional new file stream to replace the existing one
      filename - The original filename if fileStream is provided (used for display and metadata only)
      Returns:
      The updated DescriptorChangeSuggestion
      Throws:
      IOException - If there's an error processing the file
      IllegalArgumentException - If the suggestion is not in PENDING state
      IllegalStateException - If the suggestion cannot be updated

    • getSuggestion

      DescriptorChangeSuggestion getSuggestion(long key)
      Retrieves a descriptor change suggestion by its key.
      Parameters:
      key - The key of the suggestion to retrieve
      Returns:
      The DescriptorChangeSuggestion or null if not found

    • getSuggestionFile

      InputStream getSuggestionFile(long key) throws IOException
      Retrieves the file associated with a descriptor change suggestion.
      Parameters:
      key - The key of the suggestion
      Returns:
      InputStream containing the suggestion file data
      Throws:
      IllegalArgumentException - If the suggestion is not found
      IOException - If there's an error reading the file

    • applySuggestion

      void applySuggestion(long key) throws IOException
      Applies a pending descriptor change suggestion. This will create or update the descriptor group based on the suggestion.
      Parameters:
      key - The key of the suggestion to apply
      Throws:
      IOException - If there's an error processing the file
      IllegalArgumentException - If the suggestion is not in PENDING state
      IllegalStateException - If the suggestion cannot be applied

    • discardSuggestion

      void discardSuggestion(long key)
      Discards a pending descriptor change suggestion.
      Parameters:
      key - The key of the suggestion to discard
      Throws:
      IllegalArgumentException - If the suggestion is not in PENDING state
      IllegalStateException - If the suggestion cannot be discarded

    • list

      PagingResponse<DescriptorChangeSuggestion> list(Pageable pageable, Status status, Type type, String proposerEmail, UUID collectionKey)
      Lists descriptor change suggestions with optional filters.
      Parameters:
      pageable - Pagination details
      status - Filter by status (PENDING, APPROVED, DISCARDED)
      type - Filter by type (CREATE, UPDATE, DELETE)
      proposerEmail - Filter by proposer's email
      collectionKey - Filter by collection key
      Returns:
      PagingResponse containing the filtered suggestions

    • count

      long count(Status status, Type type, String proposerEmail, UUID collectionKey)
      Counts the total number of descriptor change suggestions based on filters.
      Parameters:
      status - Filter by status
      type - Filter by type
      proposerEmail - Filter by proposer's email
      collectionKey - Filter by collection key
      Returns:
      Total number of matching suggestions