Package com.ibm.fhir.persistence

Interface FHIRPersistence

All Known Implementing Classes:

FHIRPersistenceJDBCImpl

public interface FHIRPersistence

This interface defines the contract between the FHIR Server's REST API layer and the underlying persistence layer that is responsible for interacting with a particular datastore to manage instances of FHIR Resources.

Method Summary

Modifier and Type	Method	Description
List<ResourceChangeLogRecord>	changes(int resourceCount, Instant fromLastModified, Long afterResourceId, String resourceTypeName)	Fetch up to resourceCount records from the RESOURCE_CHANGE_LOG table
<T extends Resource> SingleResourceResult<T>	createWithMeta(FHIRPersistenceContext context, T resource)	Stores a new FHIR Resource in the datastore.
default <T extends Resource> SingleResourceResult<T>	delete(FHIRPersistenceContext context, Class<T> resourceType, String logicalId)	Deletes the specified FHIR Resource from the datastore.
default ResourceEraseRecord	erase(EraseDTO eraseDto)	Erases part or a whole of a resource in the data layer
ResourcePayload	fetchResourcePayloads(Class<? extends Resource> resourceType, Instant fromLastModified, Instant toLastModified, Function<ResourcePayload,Boolean> process)	Special function for high speed export of resource payloads.
String	generateResourceId()	Generates a resource ID.
OperationOutcome	getHealth()	Returns an OperationOutcome indicating the current status of the persistence store / backend
FHIRPersistenceTransaction	getTransaction()	Returns a FHIRPersistenceTransaction object associated with the persistence layer implementation in use.
<T extends Resource> MultiResourceResult<T>	history(FHIRPersistenceContext context, Class<T> resourceType, String logicalId)	Retrieves all of the versions of the specified FHIR Resource.
default boolean	isChangesSupported()	Returns true iff the persistence layer implementation supports the "changes" special operation
default boolean	isDeleteSupported()	Returns true iff the persistence layer implementation supports the "delete" operation.
default boolean	isReindexSupported()	Returns true iff the persistence layer implementation supports the "reindex" special operation
boolean	isTransactional()	Returns true iff the persistence layer implementation supports transactions.
default boolean	isUpdateCreateEnabled()	Returns true iff the persistence layer implementation supports update/create and it has been configured in the persistence config.
<T extends Resource> SingleResourceResult<T>	read(FHIRPersistenceContext context, Class<T> resourceType, String logicalId)	Retrieves the most recent version of a FHIR Resource from the datastore.
int	reindex(FHIRPersistenceContext context, OperationOutcome.Builder operationOutcomeResult, Instant tstamp, List<Long> indexIds, String resourceLogicalId)	Initiates reindexing for either a specified list of index IDs, or a randomly chosen resource.
List<Long>	retrieveIndex(int count, Instant notModifiedAfter, Long afterIndexId, String resourceTypeName)	Retrieves a list of index IDs available for reindexing.
MultiResourceResult<Resource>	search(FHIRPersistenceContext context, Class<? extends Resource> resourceType)	Performs a search on the specified target resource type using the specified search parameters.
Future<PayloadKey>	storePayload(Resource resource, String logicalId, int newVersionNumber)	Offload payload storage to another provider.
<T extends Resource> SingleResourceResult<T>	updateWithMeta(FHIRPersistenceContext context, T resource)	Updates an existing FHIR Resource by storing a new version in the datastore.
<T extends Resource> SingleResourceResult<T>	vread(FHIRPersistenceContext context, Class<T> resourceType, String logicalId, String versionId)	Retrieves a specific version of a FHIR Resource from the datastore.

Method Detail

createWithMeta

<T extends Resource> SingleResourceResult<T> createWithMeta(FHIRPersistenceContext context,
                                                            T resource)
                                                     throws FHIRPersistenceException

Stores a new FHIR Resource in the datastore. The resource is not modified before it is stored. It must therefore already include correct Meta fields. Should be used instead of method create(FHIRPersistenceContext, Resource).

Parameters:

context - the FHIRPersistenceContext instance associated with the current request

resource - the FHIR Resource instance to be created in the datastore

Returns:

a SingleResourceResult with the unmodified resource and/or an OperationOutcome with hints, warnings, or errors related to the interaction

Throws:

FHIRPersistenceException

read

<T extends Resource> SingleResourceResult<T> read(FHIRPersistenceContext context,
                                                  Class<T> resourceType,
                                                  String logicalId)
                                           throws FHIRPersistenceException

Retrieves the most recent version of a FHIR Resource from the datastore.

Parameters:

context - the FHIRPersistenceContext instance associated with the current request

resourceType - the resource type of the Resource instance to be retrieved

logicalId - the logical id of the Resource instance to be retrieved

Returns:

a SingleResourceResult with the FHIR Resource that was retrieved from the datastore and/or an OperationOutcome with hints, warnings, or errors related to the interaction

Throws:

FHIRPersistenceException

vread

<T extends Resource> SingleResourceResult<T> vread(FHIRPersistenceContext context,
                                                   Class<T> resourceType,
                                                   String logicalId,
                                                   String versionId)
                                            throws FHIRPersistenceException

Retrieves a specific version of a FHIR Resource from the datastore.

Parameters:

context - the FHIRPersistenceContext instance associated with the current request

resourceType - the resource type of the Resource instance to be retrieved

logicalId - the logical id of the Resource instance to be retrieved

versionId - the version of the Resource instance to be retrieved

Returns:

a SingleResourceResult with the FHIR Resource that was retrieved from the datastore and/or an OperationOutcome with hints, warnings, or errors related to the interaction

Throws:

FHIRPersistenceException

updateWithMeta

<T extends Resource> SingleResourceResult<T> updateWithMeta(FHIRPersistenceContext context,
                                                            T resource)
                                                     throws FHIRPersistenceException

Updates an existing FHIR Resource by storing a new version in the datastore. This implementation is added to replace the deprecated update(FHIRPersistenceContext, String, Resource) method This new method expects the resource being passed in to already be modified with correct meta and id information. It no longer updates the meta itself.

Parameters:

context - the FHIRPersistenceContext instance associated with the current request

resource - the new contents of the FHIR Resource to be stored

Returns:

a SingleResourceResult with a copy of resource with fields updated by the persistence layer and/or an OperationOutcome with hints, warnings, or errors related to the interaction

Throws:

FHIRPersistenceException

delete

default <T extends Resource> SingleResourceResult<T> delete(FHIRPersistenceContext context,
                                                            Class<T> resourceType,
                                                            String logicalId)
                                                     throws FHIRPersistenceException

Deletes the specified FHIR Resource from the datastore.

Parameters:

context - the FHIRPersistenceContext instance associated with the current request

resourceType - The type of FHIR Resource to be deleted.

logicalId - the logical id of the FHIR Resource to be deleted

Returns:

a SingleResourceResult with the FHIR Resource that was deleted or null if the specified resource doesn't exist and/or an OperationOutcome with hints, warnings, or errors related to the interaction

Throws:

FHIRPersistenceException

history

<T extends Resource> MultiResourceResult<T> history(FHIRPersistenceContext context,
                                                    Class<T> resourceType,
                                                    String logicalId)
                                             throws FHIRPersistenceException

Retrieves all of the versions of the specified FHIR Resource.

Parameters:

context - the FHIRPersistenceContext instance associated with the current request

resourceType - the resource type of the Resource instances to be retrieved

logicalId - the logical id of the Resource instances to be retrieved

Returns:

a MultiResourceResult with a list containing the available versions of the specified FHIR Resource and/or an OperationOutcome with hints, warnings, or errors related to the interaction

Throws:

FHIRPersistenceException

search

MultiResourceResult<Resource> search(FHIRPersistenceContext context,
                                     Class<? extends Resource> resourceType)
                              throws FHIRPersistenceException

Performs a search on the specified target resource type using the specified search parameters.

Parameters:

context - the FHIRPersistenceContext instance associated with the current request

resourceType - the resource type which is the target of the search

Returns:

a MultiResourceResult with the list of FHIR Resources in the search result set and/or an OperationOutcome with hints, warnings, or errors related to the interaction

Throws:

FHIRPersistenceException

isTransactional

boolean isTransactional()

Returns true iff the persistence layer implementation supports transactions.

getHealth

OperationOutcome getHealth()
                    throws FHIRPersistenceException

Returns an OperationOutcome indicating the current status of the persistence store / backend

Returns:

An OperationOutcome with a list of 0 or more OperationalOutcomeIssue indicating the status of the underlying datastore

Throws:

FHIRPersistenceException

getTransaction

FHIRPersistenceTransaction getTransaction()

Returns a FHIRPersistenceTransaction object associated with the persistence layer implementation in use. This can then be used to control transactional boundaries.

isDeleteSupported

default boolean isDeleteSupported()

Returns true iff the persistence layer implementation supports the "delete" operation.

isUpdateCreateEnabled

default boolean isUpdateCreateEnabled()

Returns true iff the persistence layer implementation supports update/create and it has been configured in the persistence config.

Returns:

generateResourceId

String generateResourceId()

Generates a resource ID.

Returns:

resource ID

isReindexSupported

default boolean isReindexSupported()

Returns true iff the persistence layer implementation supports the "reindex" special operation

Returns:

reindex

int reindex(FHIRPersistenceContext context,
            OperationOutcome.Builder operationOutcomeResult,
            Instant tstamp,
            List<Long> indexIds,
            String resourceLogicalId)
     throws FHIRPersistenceException

Initiates reindexing for either a specified list of index IDs, or a randomly chosen resource. The number of resources processed is returned. This can be used by a controller to continue processing until everything is complete.

Parameters:

context - the FHIRPersistenceContext instance associated with the current request.

operationOutcomeResult - accumulate issues in this OperationOutcome.Builder

tstamp - only reindex resources with a reindex_tstamp less than this

indexIds - list of index IDs of resources to reindex, or null

resourceLogicalId - resourceType/logicalId value of a specific resource to reindex, or null; this parameter is ignored if the indexIds parameter value is non-null

Returns:

count of the number of resources reindexed by this call

Throws:

FHIRPersistenceException

fetchResourcePayloads

ResourcePayload fetchResourcePayloads(Class<? extends Resource> resourceType,
                                      Instant fromLastModified,
                                      Instant toLastModified,
                                      Function<ResourcePayload,Boolean> process)
                               throws FHIRPersistenceException

Special function for high speed export of resource payloads. The process function must process the InputStream before returning. Result processing will be stopped if the process function returns Boolean FALSE.

Parameters:

resourceType - the resource type which is the target of the search

fromLastModified - start reading from this timestamp

fromResourceId - start reading from this resourceId if provided (can be null)

toLastModified - do not read beyond this timestamp

spanSeconds - max number of seconds to include fromLastModified

process - function to process each payload record

Returns:

the last ResourcePayload processed, or null if no data was found

Throws:

FHIRPersistenceException

isChangesSupported

default boolean isChangesSupported()

Returns true iff the persistence layer implementation supports the "changes" special operation

Returns:

changes

List<ResourceChangeLogRecord> changes(int resourceCount,
                                      Instant fromLastModified,
                                      Long afterResourceId,
                                      String resourceTypeName)
                               throws FHIRPersistenceException

Fetch up to resourceCount records from the RESOURCE_CHANGE_LOG table

Parameters:

resourceCount - the max number of resource change records to fetch

fromLastModified - filter records with record.lastUpdate >= fromLastModified. Optional.

afterResourceId - filter records with record.resourceId > afterResourceId. Optional.

resourceTypeName - filter records with record.resourceType = resourceTypeName. Optional.

Returns:

a list containing up to resourceCount elements describing resources which have changed

Throws:

FHIRPersistenceException

erase

default ResourceEraseRecord erase(EraseDTO eraseDto)
                           throws FHIRPersistenceException

Erases part or a whole of a resource in the data layer

Parameters:

eraseDto - the details of the user input

Returns:

a record indicating the success or partial success of the erase

Throws:

FHIRPersistenceException

retrieveIndex

List<Long> retrieveIndex(int count,
                         Instant notModifiedAfter,
                         Long afterIndexId,
                         String resourceTypeName)
                  throws FHIRPersistenceException

Retrieves a list of index IDs available for reindexing.

Parameters:

count - the maximum nuber of index IDs to retrieve

notModifiedAfter - only retrieve index IDs for resources not last updated after the specified timestamp

afterIndexId - retrieve index IDs starting after this specified index ID, or null to start with first index ID

resourceTypeName - the resource type of index IDs to return, or null

Returns:

list of index IDs available for reindexing

Throws:

FHIRPersistenceException

storePayload

Future<PayloadKey> storePayload(Resource resource,
                                String logicalId,
                                int newVersionNumber)
                         throws FHIRPersistenceException

Offload payload storage to another provider. If result is not null, the returned Future can be used to obtain the status of the operation. If the result is null, then the implementation does not support offloading and the payload must be stored in the traditional manner (e.g. in the RDBMS). A Future is used because the offloading storage operation may be asynchronous.

Parameters:

resource -

logicalId -

newVersionNumber -

Returns:

Throws:

FHIRPersistenceException