HAPI provides support for HTTP ETags, which are a standard way of providing faster reads when content has not changed and optimistic locking for updates.

Client Side ETags

ETag features are added simply by adding fluent method calls to the client method chain, as shown in the following examples.

Read / VRead

To notify the server that it should return an HTTP 301 Not Modified if the content has not changed, add an ifVersionMatches(foo).[operation] invocation.

// search for patient 123
Patient patient = client.read()
                        .resource(Patient.class)
                        .withId("123")
                        .ifVersionMatches("001").returnNull()
                        .execute(); 
if (patient == null) {
   // resource has not changed
}

This method will add the following header to the request:

If-None-Match: "001"

Update

To implement version aware updates, specify a version in the request. This will notify the server that it should only update the resource on the server if the version matches the given version. This is useful to prevent two clients from attempting to modify the resource at the same time, and having one client's updates overwrite the other's.

         // First, let's retrive the latest version of a resource
         // from the server
         Patient patient = client.read().resource(Patient.class).withId("123").execute();

         // If the server is a version aware server, we should now know the latest version
         // of the resource
         System.out.println("Version ID: " + patient.getId().getVersionIdPart());
         
         // Now let's make a change to the resource
         patient.setGender(AdministrativeGenderEnum.FEMALE);

         // Invoke the server update method - Because the resource has
         // a version, it will be included in the request sent to 
         // the server
         try {
            MethodOutcome outcome = client
               .update()
               .resource(patient)
               .execute();
         } catch (PreconditionFailedException e) {
            // If we get here, the latest version has changed
            // on the server so our update failed.
         }

The following header will be added to the request as a part of this interaction.

If-Match: "001"

Server Side ETags

ETag support is automatically enabled in the RESTful server. This has the following effects:

  • Read/VRead method responses will include an ETag header, noting the version being returned.
  • If an incoming Read method includes an If-None-Match header with the same version as the latest version being returned, the server will automatically return an HTTP 304 Not Modified instead of returning the resource body.

Disabling ETag Support

To disable ETag support, simply invoke the setETagSupport method, as in the following example.

   @WebServlet(urlPatterns = { "/fhir/*" }, displayName = "FHIR Server")
   public class RestfulServerWithLogging extends RestfulServer {

      @Override
      protected void initialize() throws ServletException {
         // ... define your resource providers here ...
         
         // ETag support is enabled by default
         setETagSupport(ETagSupportEnum.ENABLED);
      }
      
   }

Back to top

Reflow Maven skin by Andrius Velykis.