Working with DSTU3
Although DSTU3 has not yet been balloted and finalized by HL7, there are several proposed changes which have been incorporated into the current Continuous Integration Builds of the FHIR specification itself and many of these changes are used as a part of testing scenarios in FHIR Connectathons.
HAPI has support for DSTU3 definitions, based on the snapshot of the resource definitions available at the time that a given version of HAPI is released. These structures are found in the
hapi-fhir-structures-dstu3-[version].jar library, with the associated Schemas, ValueSets, and other textual resources being found in
hapi-fhir-validation-resources-dstu3-[version].jar. For information on where to find these libraries, see the Download page.
Migrating to DSTU3 does require some effort, as the resource definitions have been migrated to use the "Reference Implementation" structures. These are the resource definitions supplied by HL7, meaning that the process to merge these two libraries has now begun.
The RI Data Model
Since the early days of the FHIR project, there have been two parallel Java implementations of the FHIR Specification: HAPI and the Reference Implementation (RI). The two libraries both had separate data models and parsers, but had little overlap in features other than that. HAPI has a server, database, and rich fluent client that the RI did not have. The RI had profile validation, snapshot generation, and a set other of great utilities that HAPI did not have.
Over the last year, we have been working to bring the two projects together, in order to reduce duplication of effort and let all Java users take advantage of the entire set of available tools.
The biggest change to HAPI users coming from this merging is the adoption of the new RI data structure classes. For users of FHIR DSTU2, we provided a parallel set of structures so that users could choose which library to use (
hapi-fhir-structures-dstu2 for HAPI structures, or
hapi-fhir-structures-hl7org-dstu2 for RI structures). For DSTU3 we will be using the RI structures only, so users will need to migrate to use these.
Using the new RI Structures
The reference implementation (RI) structures have been added as a new maven dependency library called
hapi-fhir-structures-dstu3. See the download page for information on the Maven dependencies for this version of the structures.
A new interface has been added which serves as a master interface for all resource classes:
org.hl7.fhir.instance.model.api.IBaseResource. All RI resource classes will be in the package
org.hl7.fhir.dstu3.model, as shown below.
Datatypes will also be found inthe same package. Unlike HAPI datatype structures, which all end with "Dt", the RI primitive structure names end with "Type" and the RI composite structures have no suffix, as shown below.
Using the DSTU3 Structures in Your Application
Using these structures is similar to using other structures:
// Create a context for DSTU3 FhirContext ctx = FhirContext.forDstu3(); // Working with RI structures is similar to how it works with the HAPI structures org.hl7.fhir.dstu3.model.Patient patient = new org.hl7.fhir.dstu3.model.Patient(); patient.addName().addGiven("John").setFamily("Smith"); patient.getBirthDateElement().setValueAsString("1998-02-22"); // Parsing and encoding works the same way too String encoded = ctx.newJsonParser().encodeResourceToString(patient);
Upgrading Existing Applications to DSTU3 Draft
If you have an existing application built using a version of previous version of HAPI FHIR, there is one change that may affect you. As shown above, a new interface called
IBaseResource has been introduced, and the
IResource interface extends from it. Many methods in the API which previously returned
IResource now return
For these methods, you may cast the
IResource if you are using DSTU2 structures, or to
IAnyResource if you are using DSTU3 structures.
Please post any problems you might encounter trying to upgrade on the Google Group. Chances are if it's happening to you, it's happening to others. We're happy to help.
Code changes in DSTU3 Structrues
The following is a list of things that have changed in the DSTU3 structures which you will need to accomodate in your code as you upgrade:
- Structures are all found in the
org.hl7.fhir.dstu3.modelpackage, instead of the
- Primitive Types are renamed from
- Composite Types are renamed from
- ResourceReferenceDt is renamed to
- Reference#getReference() returns the reference text, where
IdTyperepresenting the reference.
- Names for some component setters/mutators have changed in the new structures. In the old structures if the field type was a primitive (e.g. a string) there would be two setters:
setName(StringDt). In the new structures, the setters are called
setNameElement(StringType). This is more consistent with the way the getters are named.
- Resource#getId() returns the string ID (e.g.
- Resource#getIdElement() returns the IdType previously returned by
- Resource metadata (e.g. last update time, tags, etc.) lives in a
Metaobject accessed using
Resource#getMeta()instead of using the
Resource#getMeta()#getLastUpdate()returns the resource's last update time
Resource#getMeta()#getTag()returns the resource's tag list
Resource#getMeta()#getProfile()returns the resource's profile list
- Resource#getContained() returns the list of contained resources (previously it returned a useless ContainedDt object which held the list of contained resources)
Enums for ValueSets
- Enums are named
[EnumName]Enum. For example,
ConditionVerificationStatusEnumis now called
- The Java model classes representing sub-elements within a resource now have a longer name reflecting the containing element name and ending in "Component". For example, the Java structure representing the "Bundle.entry" component was called
Entryin the HAPI structures but is called
BundleEntryComponentin the RI structures.