Package com.ibm.fhir.server.util

Class FHIRRestHelper

  • All Implemented Interfaces:
    FHIRResourceHelpers
    public class FHIRRestHelper
extends java.lang.Object
implements FHIRResourceHelpers
    Helper methods for performing the "heavy lifting" with respect to implementing FHIR interactions.

    • Field Detail

      • PARSER_FORMATTER

        public static final java.time.format.DateTimeFormatter PARSER_FORMATTER

    • Method Detail

      • doCreate

        public FHIRRestOperationResponse doCreate​(java.lang.String type,
                                          Resource resource,
                                          java.lang.String ifNoneExist,
                                          boolean doValidation)
                                   throws java.lang.Exception
        Description copied from interface: FHIRResourceHelpers
        Performs the heavy lifting associated with a 'create' interaction.
        Specified by:
        doCreate in interface FHIRResourceHelpers
        Parameters:
        type - the resource type specified as part of the request URL
        resource - the Resource to be stored.
        ifNoneExist - whether to create the resource if none exists
        doValidation - if true, validate the resource; if false, assume the resource has already been validated
        Returns:
        a FHIRRestOperationResponse object containing the results of the operation
        Throws:
        java.lang.Exception

      • doPatch

        public FHIRRestOperationResponse doPatch​(java.lang.String type,
                                         java.lang.String id,
                                         FHIRPatch patch,
                                         java.lang.String ifMatchValue,
                                         java.lang.String searchQueryString,
                                         boolean skippableUpdate)
                                  throws java.lang.Exception
        Description copied from interface: FHIRResourceHelpers
        Performs a patch operation (a new version of the Resource will be stored).
        Specified by:
        doPatch in interface FHIRResourceHelpers
        Parameters:
        type - the type of the resource to be updated
        id - the id of the Resource being updated
        patch - the patch to apply
        ifMatchValue - an optional "If-Match" header value to request a version-aware update
        searchQueryString - an optional search query string to request a conditional update
        skippableUpdate - if true, and the result of the patch matches the existing resource on the server, then skip the update; if false, then always attempt the update
        Returns:
        a FHIRRestOperationResponse that contains the results of the operation
        Throws:
        java.lang.Exception

      • doUpdate

        public FHIRRestOperationResponse doUpdate​(java.lang.String type,
                                          java.lang.String id,
                                          Resource newResource,
                                          java.lang.String ifMatchValue,
                                          java.lang.String searchQueryString,
                                          boolean skippableUpdate,
                                          boolean doValidation,
                                          java.lang.Integer ifNoneMatch)
                                   throws java.lang.Exception
        Description copied from interface: FHIRResourceHelpers
        Performs an update operation (a new version of the Resource will be stored).
        Specified by:
        doUpdate in interface FHIRResourceHelpers
        Parameters:
        type - the type of the resource to be updated
        id - the id of the Resource being updated
        newResource - the new resource to be stored
        ifMatchValue - an optional "If-Match" header value to request a version-aware update
        searchQueryString - an optional search query string to request a conditional update
        skippableUpdate - if true, and the resource content in the update matches the existing resource on the server, then skip the update; if false, then always attempt the update
        doValidation - if true, validate the resource; if false, assume the resource has already been validated
        ifNoneMatch - conditional create-on-update
        Returns:
        a FHIRRestOperationResponse that contains the results of the operation
        Throws:
        java.lang.Exception

      • doDelete

        public FHIRRestOperationResponse doDelete​(java.lang.String type,
                                          java.lang.String id,
                                          java.lang.String searchQueryString)
                                   throws java.lang.Exception
        Description copied from interface: FHIRResourceHelpers
        Performs a 'delete' operation on the specified resource.
        Specified by:
        doDelete in interface FHIRResourceHelpers
        Parameters:
        type - the resource type associated with the Resource to be deleted
        id - the id of the Resource to be deleted
        searchQueryString - a search query associated with a conditional delete request (mutually exclusive with id)
        Returns:
        a FHIRRestOperationResponse that contains the results of the operation
        Throws:
        java.lang.Exception

      • doRead

        public SingleResourceResult<? extends Resource> doRead​(java.lang.String type,
                                                       java.lang.String id,
                                                       boolean throwExcOnNull,
                                                       boolean includeDeleted,
                                                       Resource contextResource)
                                                throws java.lang.Exception
        Description copied from interface: FHIRResourceHelpers
        Performs a 'read' operation to retrieve a Resource.
        Specified by:
        doRead in interface FHIRResourceHelpers
        Parameters:
        type - the resource type associated with the Resource to be retrieved
        id - the id of the Resource to be retrieved
        throwExcOnNull - whether to throw an exception on null
        includeDeleted - allow the read, even if the resource has been deleted
        contextResource - the resource
        Returns:
        a SingleResourceResult wrapping the resource and including its deletion status
        Throws:
        java.lang.Exception

      • doRead

        public SingleResourceResult<? extends Resource> doRead​(java.lang.String type,
                                                       java.lang.String id,
                                                       boolean throwExcOnNull,
                                                       boolean includeDeleted,
                                                       Resource contextResource,
                                                       javax.ws.rs.core.MultivaluedMap<java.lang.String,​java.lang.String> queryParameters)
                                                throws java.lang.Exception
        Description copied from interface: FHIRResourceHelpers
        Performs a 'read' operation to retrieve a Resource with select query parameters.
        Specified by:
        doRead in interface FHIRResourceHelpers
        Parameters:
        type - the resource type associated with the Resource to be retrieved
        id - the id of the Resource to be retrieved
        throwExcOnNull - whether to throw an exception on null
        includeDeleted - allow the read, even if the resource has been deleted
        contextResource - the resource
        queryParameters - for supporting _elements and _summary for resource read
        Returns:
        a SingleResourceResult wrapping the resource and including its deletion status
        Throws:
        java.lang.Exception

      • doVRead

        public Resource doVRead​(java.lang.String type,
                        java.lang.String id,
                        java.lang.String versionId,
                        javax.ws.rs.core.MultivaluedMap<java.lang.String,​java.lang.String> queryParameters)
                 throws java.lang.Exception
        Description copied from interface: FHIRResourceHelpers
        Performs a 'vread' operation by retrieving the specified version of a Resource.
        Specified by:
        doVRead in interface FHIRResourceHelpers
        Parameters:
        type - the resource type associated with the Resource to be retrieved
        id - the id of the Resource to be retrieved
        versionId - the version id of the Resource to be retrieved
        queryParameters - for supporting _elements and _summary for resource vread
        Returns:
        the Resource
        Throws:
        java.lang.Exception

      • doHistory

        public Bundle doHistory​(java.lang.String type,
                        java.lang.String id,
                        javax.ws.rs.core.MultivaluedMap<java.lang.String,​java.lang.String> queryParameters,
                        java.lang.String requestUri)
                 throws java.lang.Exception
        Description copied from interface: FHIRResourceHelpers
        Performs the work of retrieving versions of a Resource.
        Specified by:
        doHistory in interface FHIRResourceHelpers
        Parameters:
        type - the resource type associated with the Resource to be retrieved
        id - the id of the Resource to be retrieved
        queryParameters - a Map containing the query parameters from the request URL
        Returns:
        a Bundle containing the history of the specified Resource
        Throws:
        java.lang.Exception

      • doSearch

        public Bundle doSearch​(java.lang.String type,
                       java.lang.String compartment,
                       java.lang.String compartmentId,
                       javax.ws.rs.core.MultivaluedMap<java.lang.String,​java.lang.String> queryParameters,
                       java.lang.String requestUri,
                       Resource contextResource)
                throws java.lang.Exception
        Description copied from interface: FHIRResourceHelpers
        Performs heavy lifting associated with a 'search' operation.
        Specified by:
        doSearch in interface FHIRResourceHelpers
        Parameters:
        type - the resource type associated with the search
        compartment - the compartment type to search in, or null if not a compartment search
        compartmentId - the specific compartment to search in, or null if not a compartment search
        queryParameters - a Map containing the query parameters from the request URL
        requestUri - the request URI
        contextResource - the resource context
        Returns:
        a Bundle containing the search result set
        Throws:
        java.lang.Exception

      • doSearch

        public Bundle doSearch​(java.lang.String type,
                       java.lang.String compartment,
                       java.lang.String compartmentId,
                       javax.ws.rs.core.MultivaluedMap<java.lang.String,​java.lang.String> queryParameters,
                       java.lang.String requestUri,
                       Resource contextResource,
                       boolean checkInteractionAllowed,
                       boolean alwaysIncludeResources)
                throws java.lang.Exception
        Description copied from interface: FHIRResourceHelpers
        Performs heavy lifting associated with a 'search' operation.
        Specified by:
        doSearch in interface FHIRResourceHelpers
        Parameters:
        type - the resource type associated with the search
        compartment - the compartment type to search in, or null if not a compartment search
        compartmentId - the specific compartment to search in, or null if not a compartment search
        queryParameters - a Map containing the query parameters from the request URL
        requestUri - the request URI
        contextResource - the resource context
        checkInteractionAllowed - if true, check that the search interaction is permitted
        alwaysIncludeResources - if true, ignore any return preference and always include the resource in the search result bundle
        Returns:
        a Bundle containing the search result set
        Throws:
        java.lang.Exception

      • doInvoke

        public Resource doInvoke​(FHIROperationContext operationContext,
                         java.lang.String resourceTypeName,
                         java.lang.String logicalId,
                         java.lang.String versionId,
                         Resource resource,
                         javax.ws.rs.core.MultivaluedMap<java.lang.String,​java.lang.String> queryParameters)
                  throws java.lang.Exception
        Description copied from interface: FHIRResourceHelpers
        Helper method which invokes a custom operation.
        Specified by:
        doInvoke in interface FHIRResourceHelpers
        Parameters:
        operationContext - the FHIROperationContext associated with the request
        resourceTypeName - the resource type associated with the request
        logicalId - the resource logical id associated with the request
        versionId - the resource version id associated with the request
        resource - the input resource associated with the custom operation to be invoked
        queryParameters - query parameters may be passed instead of a Parameters resource for certain custom operations invoked via GET
        Returns:
        a Resource that represents the response to the custom operation
        Throws:
        java.lang.Exception

      • doBundle

        public Bundle doBundle​(Bundle inputBundle,
                       boolean skippableUpdates)
                throws java.lang.Exception
        Description copied from interface: FHIRResourceHelpers
        Processes a bundled request (batch or transaction type).
        Specified by:
        doBundle in interface FHIRResourceHelpers
        Parameters:
        inputBundle - the request Bundle
        skippableUpdates - if true, and the bundle contains an update for which the resource content in the update matches the existing resource on the server, then skip the update; if false, then always attempt the updates specified in the bundle
        Returns:
        the response Bundle
        Throws:
        java.lang.Exception

      • updateOperationContext

        public void updateOperationContext​(FHIROperationContext operationContext,
                                   java.lang.String method)
        common update to the operationContext
        Parameters:
        operationContext -
        method -

      • createSearchResponseBundle

        Bundle createSearchResponseBundle​(java.util.List<ResourceResult<? extends Resource>> resourceResults,
                                  FHIRSearchContext searchContext,
                                  java.lang.String type)
                           throws java.lang.Exception
        Creates a bundle that will hold results for a search operation.
        Parameters:
        resourceResults - the list of resource results to include in the bundle
        searchContext - the FHIRSearchContext object associated with the search
        type - the name of the resource type being searched
        Returns:
        the bundle
        Throws:
        java.lang.Exception

      • getRequestBaseUri

        public static java.lang.String getRequestBaseUri​(java.lang.String type)
                                          throws java.lang.Exception
        This method returns the "base URI" associated with the current request. For example, if a client invoked POST https://myhost:9443/fhir-server/api/v4/Patient to create a Patient resource, this method would return "https://myhost:9443/fhir-server/api/v4".
        Parameters:
        type - The resource type associated with the request URI (e.g. "Patient" in the case of https://myhost:9443/fhir-server/api/v4/Patient), or null if there is no such resource type
        Returns:
        The base endpoint URI associated with the current request.
        Throws:
        java.lang.Exception - if an error occurs while reading the config

      • buildPersistenceEventProperties

        public java.util.Map<java.lang.String,​java.lang.Object> buildPersistenceEventProperties​(java.lang.String type,
                                                                                              java.lang.String id,
                                                                                              java.lang.String version,
                                                                                              FHIRSearchContext searchContext,
                                                                                              FHIRSystemHistoryContext systemHistoryContext)
                                                                                       throws FHIRPersistenceException
        Description copied from interface: FHIRResourceHelpers
        Builds a collection of properties that will be passed to the persistence interceptors.
        Specified by:
        buildPersistenceEventProperties in interface FHIRResourceHelpers
        Parameters:
        type - the resource type
        id - the resource logical ID
        version - the resource version
        searchContext - the request search context
        systemHistoryContext - the request system history context
        Returns:
        a map of persistence event properties
        Throws:
        FHIRPersistenceException

      • doReindex

        public int doReindex​(FHIROperationContext operationContext,
                     OperationOutcome.Builder operationOutcomeResult,
                     java.time.Instant tstamp,
                     java.util.List<java.lang.Long> indexIds,
                     java.lang.String resourceLogicalId)
              throws java.lang.Exception
        Description copied from interface: FHIRResourceHelpers
        Invoke the FHIR persistence reindex operation for either a specified list of indexIds, or a randomly chosen resource, last reindexed before the given timestamp.
        Specified by:
        doReindex in interface FHIRResourceHelpers
        Parameters:
        operationContext - the operation context
        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 (e.g. "Patient"), or resourceType/logicalId a specific resource (e.g. "Patient/abc123"), 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:
        java.lang.Exception

      • doReindexList

        public int doReindexList​(OperationOutcome.Builder operationOutcomeResult,
                         java.time.Instant tstamp,
                         java.util.List<java.lang.Long> indexIds)
                  throws java.lang.Exception
        encapsulates the logic to process a list with graduated backoff through the full list of indexIds
        Parameters:
        operationOutcomeResult -
        tstamp -
        indexIds -
        Returns:
        Throws:
        java.lang.Exception

      • doReindexSingle

        public int doReindexSingle​(OperationOutcome.Builder operationOutcomeResult,
                           java.time.Instant tstamp,
                           java.lang.String resourceLogicalId)
                    throws java.lang.Exception
        do a single reindex on a specific resourceLogicalId
        Parameters:
        operationOutcomeResult -
        tstamp -
        resourceLogicalId -
        Returns:
        Throws:
        java.lang.Exception

      • doHistory

        public Bundle doHistory​(javax.ws.rs.core.MultivaluedMap<java.lang.String,​java.lang.String> queryParameters,
                        java.lang.String requestUri,
                        java.lang.String resourceType)
                 throws java.lang.Exception
        Description copied from interface: FHIRResourceHelpers
        Implement the system level history operation to obtain a list of changes to resources with an optional resourceType which supports for example [base]/Patient/_history requests to return the complete history of changes filtered to a specific resource type. Because the resource type is included in the path, this variant allows only a single resource type to be specified. To obtain history for more than one resource type, the [base]/_history whole system history endpoint should be used instead with a list of resource types specified using the _type query parameter.
        Specified by:
        doHistory in interface FHIRResourceHelpers
        Parameters:
        queryParameters - a Map containing the query parameters from the request URL
        requestUri - the request URI
        resourceType - optional resourceType to filter the history
        Returns:
        a Bundle containing the history of the specified Resource
        Throws:
        java.lang.Exception

      • doRetrieveIndex

        public java.util.List<java.lang.Long> doRetrieveIndex​(FHIROperationContext operationContext,
                                                      java.lang.String resourceTypeName,
                                                      int count,
                                                      java.time.Instant notModifiedAfter,
                                                      java.lang.Long afterIndexId)
                                               throws java.lang.Exception
        Description copied from interface: FHIRResourceHelpers
        Invoke the FHIR persistence retrieve index operation to retrieve a list of indexIds available for reindexing.
        Specified by:
        doRetrieveIndex in interface FHIRResourceHelpers
        Parameters:
        operationContext - the operation context
        resourceTypeName - the resource type of index IDs to return, or null
        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 ID, or null to start with first ID
        Returns:
        list of index IDs available for reindexing
        Throws:
        java.lang.Exception

      • generateResourceId

        public java.lang.String generateResourceId()
        Description copied from interface: FHIRResourceHelpers
        Generate a new resource id. This is typically delegated to the persistence layer, which may want to create FHIR-compliant ids optimized for a certain type of storage.
        Specified by:
        generateResourceId in interface FHIRResourceHelpers
        Returns:

      • getCurrentInstant

        protected Instant getCurrentInstant()
        Get the current time which can be used for the lastUpdated field
        Returns:
        current time in UTC

      • storePayload

        public PayloadPersistenceResponse storePayload​(Resource resource,
                                               java.lang.String logicalId,
                                               int newVersionNumber,
                                               java.lang.String resourcePayloadKey)
                                        throws java.lang.Exception
        Description copied from interface: FHIRResourceHelpers
        If the underlying persistence layer supports offloading payload storage, initiate the request here.
        Specified by:
        storePayload in interface FHIRResourceHelpers
        Parameters:
        resource - the resource to store (with correct Meta fields)
        logicalId - the logical id of the resource
        newVersionNumber - the version number to use
        resourcePayloadKey - the key used to tie the RDBMS record with the offload record
        Returns:
        a response to the payload store operation, or null if it is not supported
        Throws:
        java.lang.Exception