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 Summary

Modifier and Type	Method	Description
void	applySuggestion(long key)	Applies a pending descriptor change suggestion.
long	count(Status status, Type type, String proposerEmail, UUID collectionKey, Country country)	Counts the total number of descriptor change suggestions based on filters.
DescriptorChangeSuggestion	createSuggestion(InputStream fileStream, String filename, DescriptorChangeSuggestionRequest request)	Creates a new descriptor change suggestion.
void	discardSuggestion(long key)	Discards a pending descriptor change suggestion.
DescriptorChangeSuggestion	getSuggestion(long key)	Retrieves a descriptor change suggestion by its key.
InputStream	getSuggestionFile(long key)	Retrieves the file associated with a descriptor change suggestion.
PagingResponse<DescriptorChangeSuggestion>	list(Pageable pageable, Status status, Type type, String proposerEmail, UUID collectionKey, Country country)	Lists descriptor change suggestions with optional filters.
DescriptorChangeSuggestion	updateSuggestion(long key, DescriptorChangeSuggestionRequest request, InputStream fileStream, String filename)	Updates an existing descriptor change suggestion.

Method Detail

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,
                                                Country country)

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

country - Filter by collection's country

Returns:

PagingResponse containing the filtered suggestions

count

long count(Status status,
           Type type,
           String proposerEmail,
           UUID collectionKey,
           Country country)

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

country - Filter by collection's country

Returns:

Total number of matching suggestions