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
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description java.util.List<ResourceChangeLogRecord>
changes(FHIRPersistenceContext context, int resourceCount, java.time.Instant sinceLastModified, java.time.Instant beforeLastModified, java.lang.Long changeIdMarker, java.util.List<java.lang.String> resourceTypeNames, boolean excludeTransactionTimeoutWindow, HistorySortOrder historySortOrder)
Fetch up to resourceCount records from the RESOURCE_CHANGE_LOG table.<T extends Resource>
SingleResourceResult<T>create(FHIRPersistenceContext context, T resource)
Stores a new FHIR Resource in the datastore.default <T extends Resource>
voiddelete(FHIRPersistenceContext context, java.lang.Class<T> resourceType, java.lang.String logicalId, int versionId, Instant lastUpdated)
Deletes the FHIR resource from the datastore.default ResourceEraseRecord
erase(FHIRPersistenceContext context, EraseDTO eraseDto)
Erases part or a whole of a resource in the data layer.ResourcePayload
fetchResourcePayloads(java.lang.Class<? extends Resource> resourceType, java.time.Instant fromLastModified, java.time.Instant toLastModified, java.util.function.Function<ResourcePayload,java.lang.Boolean> process)
Special function for high speed export of resource payloads.java.lang.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.MultiResourceResult
history(FHIRPersistenceContext context, java.lang.Class<? extends Resource> resourceType, java.lang.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
isOffloadingSupported()
Returns true iff the persistence layer implementation supports offloading and this has been configured for the tenant/datasource.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, java.lang.Class<T> resourceType, java.lang.String logicalId)
Retrieves the most recent version of a FHIR Resource from the datastore.java.util.List<Resource>
readResourcesForRecords(java.util.List<ResourceChangeLogRecord> records)
Read the resources for each of the change log records in the list, aligning the entries in the returned list to match the entries in the records list.int
reindex(FHIRPersistenceContext context, OperationOutcome.Builder operationOutcomeResult, java.time.Instant tstamp, java.util.List<java.lang.Long> indexIds, java.lang.String resourceLogicalId, boolean force)
Initiates reindexing for either a specified list of index IDs, or a randomly chosen resource.java.util.List<java.lang.Long>
retrieveIndex(FHIRPersistenceContext context, int count, java.time.Instant notModifiedAfter, java.lang.Long afterIndexId, java.lang.String resourceTypeName)
Retrieves a list of index IDs available for reindexing.MultiResourceResult
search(FHIRPersistenceContext context, java.lang.Class<? extends Resource> resourceType)
Performs a search on the specified target resource type using the specified search parameters.PayloadPersistenceResponse
storePayload(Resource resource, java.lang.String logicalId, int newVersionNumber, java.lang.String resourcePayloadKey)
Offload payload storage to another provider.<T extends Resource>
SingleResourceResult<T>update(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, java.lang.Class<T> resourceType, java.lang.String logicalId, java.lang.String versionId)
Retrieves a specific version of a FHIR Resource from the datastore.
-
-
-
Method Detail
-
create
<T extends Resource> SingleResourceResult<T> create(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.- Parameters:
context
- the FHIRPersistenceContext instance associated with the current requestresource
- the FHIR Resource instance to be created in the datastore- Returns:
- a SingleResourceResult with a ResourceResult that holds 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, java.lang.Class<T> resourceType, java.lang.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 requestresourceType
- the resource type of the Resource instance to be retrievedlogicalId
- the logical id of the Resource instance to be retrieved- Returns:
- a SingleResourceResult with a ResourceResult populated from 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, java.lang.Class<T> resourceType, java.lang.String logicalId, java.lang.String versionId) throws FHIRPersistenceException
Retrieves a specific version of a FHIR Resource from the datastore.- Parameters:
context
- the FHIRPersistenceContext instance associated with the current requestresourceType
- the resource type of the Resource instance to be retrievedlogicalId
- the logical id of the Resource instance to be retrievedversionId
- the version of the Resource instance to be retrieved- Returns:
- a SingleResourceResult with a ResourceResult populated from the datastore and/or an OperationOutcome with hints, warnings, or errors related to the interaction
- Throws:
FHIRPersistenceException
-
update
<T extends Resource> SingleResourceResult<T> update(FHIRPersistenceContext context, T resource) throws FHIRPersistenceException
Updates an existing FHIR Resource by storing a new version in the datastore. 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 requestresource
- the new contents of the FHIR Resource to be stored- Returns:
- a SingleResourceResult with a ResourceResult that holds a copy of the input resource and/or an OperationOutcome with hints, warnings, or errors related to the interaction
- Throws:
FHIRPersistenceException
-
delete
default <T extends Resource> void delete(FHIRPersistenceContext context, java.lang.Class<T> resourceType, java.lang.String logicalId, int versionId, Instant lastUpdated) throws FHIRPersistenceException
Deletes the FHIR resource from the datastore. The delete is a soft-delete, resulting in a new version being created to act as a deletion marker. This version is created without a payload body. The versionId must match the latest version of the resource. This must be checked by theFHIRPersistence
implementation, which should throw a FHIRPersistenceVersionIdMismatchException is there is a mismatch (likely an indication of concurrent changes to the resource).- Type Parameters:
T
-- Parameters:
context
- the FHIRPersistenceContext instance associated with the current requestresourceType
- the resource type of the Resource instance to be deletedlogicalId
- the logical id of the Resource instance to be deletedversionId
- the current version of the Resource instance to be deletedlastUpdated
- the modification timestamp to use for the deletion- Throws:
FHIRPersistenceException
-
history
MultiResourceResult history(FHIRPersistenceContext context, java.lang.Class<? extends Resource> resourceType, java.lang.String logicalId) throws FHIRPersistenceException
Retrieves all of the versions of the specified FHIR Resource.- Parameters:
context
- the FHIRPersistenceContext instance associated with the current requestresourceType
- the resource type of the Resource instances to be retrievedlogicalId
- 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 search(FHIRPersistenceContext context, java.lang.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 requestresourceType
- 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
-
readResourcesForRecords
java.util.List<Resource> readResourcesForRecords(java.util.List<ResourceChangeLogRecord> records) throws FHIRPersistenceException
Read the resources for each of the change log records in the list, aligning the entries in the returned list to match the entries in the records list.- Parameters:
records
-- Returns:
- a list of Resources with the same number of entries as the given records list
- 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.- Returns:
-
isDeleteSupported
default boolean isDeleteSupported()
Returns true iff the persistence layer implementation supports the "delete" operation.- Returns:
-
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
java.lang.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:
-
isOffloadingSupported
default boolean isOffloadingSupported()
Returns true iff the persistence layer implementation supports offloading and this has been configured for the tenant/datasource.- Returns:
-
reindex
int reindex(FHIRPersistenceContext context, OperationOutcome.Builder operationOutcomeResult, java.time.Instant tstamp, java.util.List<java.lang.Long> indexIds, java.lang.String resourceLogicalId, boolean force) 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 thisOperationOutcome.Builder
tstamp
- only reindex resources with a reindex_tstamp less than thisindexIds
- list of index IDs of resources to reindex, or nullresourceLogicalId
- resourceType/logicalId value of a specific resource to reindex, or null; this parameter is ignored if the indexIds parameter value is non-nullforce
- if true, always replace the stored parameters- Returns:
- count of the number of resources reindexed by this call
- Throws:
FHIRPersistenceException
-
fetchResourcePayloads
ResourcePayload fetchResourcePayloads(java.lang.Class<? extends Resource> resourceType, java.time.Instant fromLastModified, java.time.Instant toLastModified, java.util.function.Function<ResourcePayload,java.lang.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 searchfromLastModified
- start reading from this timestampfromResourceId
- start reading from this resourceId if provided (can be null)toLastModified
- do not read beyond this timestampspanSeconds
- max number of seconds to include fromLastModifiedprocess
- 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
java.util.List<ResourceChangeLogRecord> changes(FHIRPersistenceContext context, int resourceCount, java.time.Instant sinceLastModified, java.time.Instant beforeLastModified, java.lang.Long changeIdMarker, java.util.List<java.lang.String> resourceTypeNames, boolean excludeTransactionTimeoutWindow, HistorySortOrder historySortOrder) throws FHIRPersistenceException
Fetch up to resourceCount records from the RESOURCE_CHANGE_LOG table.- Parameters:
context
- the FHIRPersistenceContext associated with the current requestresourceCount
- the max number of resource change records to fetchsinceLastModified
- filter records with record.lastUpdate >= sinceLastModified. Optional.beforeLastModified
- filter records with record.lastUpdate <= beforeLastModified. Optional.afterResourceId
- filter records with record.resourceId > afterResourceId. Optional.resourceTypeNames
- filter records matching any resource type name in the listexcludeTransactionTimeoutWindow
- flag to exclude resources falling inside server's tx timeout windowhistorySortOrder
- the type of sorting to apply- Returns:
- a list containing up to resourceCount elements describing resources which have changed
- Throws:
FHIRPersistenceException
-
erase
default ResourceEraseRecord erase(FHIRPersistenceContext context, EraseDTO eraseDto) throws FHIRPersistenceException
Erases part or a whole of a resource in the data layer.- Parameters:
context
- the FHIRPersistenceContext associated with this requesteraseDto
- the details of the user input- Returns:
- a record indicating the success or partial success of the erase
- Throws:
FHIRPersistenceException
-
retrieveIndex
java.util.List<java.lang.Long> retrieveIndex(FHIRPersistenceContext context, int count, java.time.Instant notModifiedAfter, java.lang.Long afterIndexId, java.lang.String resourceTypeName) throws FHIRPersistenceException
Retrieves a list of index IDs available for reindexing.- Parameters:
context
- the FHIRPersistenceContext associated with this requestcount
- the maximum nuber of index IDs to retrievenotModifiedAfter
- only retrieve index IDs for resources not last updated after the specified timestampafterIndexId
- retrieve index IDs starting after this specified index ID, or null to start with first index IDresourceTypeName
- the resource type of index IDs to return, or null- Returns:
- list of index IDs available for reindexing
- Throws:
FHIRPersistenceException
-
storePayload
PayloadPersistenceResponse storePayload(Resource resource, java.lang.String logicalId, int newVersionNumber, java.lang.String resourcePayloadKey) throws FHIRPersistenceException
Offload payload storage to another provider. If result is not null, the returnedFuture
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). AFuture
is used because the offloading storage operation may be asynchronous. This Future must be resolved prior to the transaction commit.- Parameters:
resource
-logicalId
-newVersionNumber
-resourcePayloadKey
-- Returns:
- Throws:
FHIRPersistenceException
-
-