Update docs

This commit is contained in:
jamesagnew 2016-01-08 07:32:17 -05:00
parent 9c712f2f0e
commit b717c1f0c3
9 changed files with 145 additions and 160 deletions

View File

@ -25,6 +25,11 @@
<artifactId>hapi-fhir-structures-dstu2</artifactId> <artifactId>hapi-fhir-structures-dstu2</artifactId>
<version>1.4-SNAPSHOT</version> <version>1.4-SNAPSHOT</version>
</dependency> </dependency>
<dependency>
<groupId>ca.uhn.hapi.fhir</groupId>
<artifactId>hapi-fhir-structures-dstu2.1</artifactId>
<version>1.4-SNAPSHOT</version>
</dependency>
<dependency> <dependency>
<groupId>ca.uhn.hapi.fhir</groupId> <groupId>ca.uhn.hapi.fhir</groupId>
<artifactId>hapi-fhir-structures-hl7org-dstu2</artifactId> <artifactId>hapi-fhir-structures-hl7org-dstu2</artifactId>

View File

@ -26,12 +26,11 @@ FhirContext ctxDstu2 = FhirContext.forDstu2();
@SuppressWarnings("unused") @SuppressWarnings("unused")
public static void creatingContextHl7org() { public static void creatingContextHl7org() {
// START SNIPPET: creatingContextHl7org // START SNIPPET: creatingContextHl7org
// To use the RI structures, you need to specifically use a FhirContext configured // Create a context for DSTU2.1
// for HL7.org Structures FhirContext ctx = FhirContext.forDstu2_1();
FhirContext ctx = FhirContext.forDstu2Hl7Org();
// Working with RI structures is similar to how it works with the HAPI structures // Working with RI structures is similar to how it works with the HAPI structures
org.hl7.fhir.instance.model.Patient patient = new org.hl7.fhir.instance.model.Patient(); org.hl7.fhir.dstu21.model.Patient patient = new org.hl7.fhir.dstu21.model.Patient();
patient.addName().addGiven("John").addFamily("Smith"); patient.addName().addGiven("John").addFamily("Smith");
patient.getBirthDateElement().setValueAsString("1998-02-22"); patient.getBirthDateElement().setValueAsString("1998-02-22");

View File

@ -296,7 +296,7 @@
<artifactId>maven-surefire-plugin</artifactId> <artifactId>maven-surefire-plugin</artifactId>
<configuration> <configuration>
<runOrder>alphabetical</runOrder> <runOrder>alphabetical</runOrder>
<argLine>-Xmx1024m</argLine> <argLine>-Xmx1324m</argLine>
</configuration> </configuration>
</plugin> </plugin>
<plugin> <plugin>

View File

@ -46,10 +46,9 @@ import ca.uhn.fhir.context.FhirContext;
public class FhirInstanceValidatorDstu21Test { public class FhirInstanceValidatorDstu21Test {
private static final DefaultProfileValidationSupport VALIDATION_SUPPORT = new DefaultProfileValidationSupport();
private static FhirContext ourCtx = FhirContext.forDstu2_1(); private static FhirContext ourCtx = FhirContext.forDstu2_1();
private static final org.slf4j.Logger ourLog = org.slf4j.LoggerFactory.getLogger(FhirInstanceValidatorDstu21Test.class); private static final org.slf4j.Logger ourLog = org.slf4j.LoggerFactory.getLogger(FhirInstanceValidatorDstu21Test.class);
private DefaultProfileValidationSupport myDefaultValidationSupport = VALIDATION_SUPPORT; private DefaultProfileValidationSupport myDefaultValidationSupport = new DefaultProfileValidationSupport();
private FhirInstanceValidator myInstanceVal; private FhirInstanceValidator myInstanceVal;
private IValidationSupport myMockSupport; private IValidationSupport myMockSupport;
@ -70,7 +69,7 @@ public class FhirInstanceValidatorDstu21Test {
myVal.setValidateAgainstStandardSchema(false); myVal.setValidateAgainstStandardSchema(false);
myVal.setValidateAgainstStandardSchematron(false); myVal.setValidateAgainstStandardSchematron(false);
myInstanceVal = new FhirInstanceValidator(VALIDATION_SUPPORT); myInstanceVal = new FhirInstanceValidator(myDefaultValidationSupport);
myVal.registerValidatorModule(myInstanceVal); myVal.registerValidatorModule(myInstanceVal);
mySupportedCodeSystemsForExpansion = new HashMap<String, ValueSet.ValueSetExpansionComponent>(); mySupportedCodeSystemsForExpansion = new HashMap<String, ValueSet.ValueSetExpansionComponent>();

Binary file not shown.

Before

Width:  |  Height:  |  Size: 19 KiB

File diff suppressed because one or more lines are too long

After

Width:  |  Height:  |  Size: 9.5 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 24 KiB

File diff suppressed because one or more lines are too long

After

Width:  |  Height:  |  Size: 12 KiB

View File

@ -2,157 +2,39 @@
<document xmlns="http://maven.apache.org/XDOC/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd"> <document xmlns="http://maven.apache.org/XDOC/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
<properties> <properties>
<title>FHIR DSTU2 Support</title> <title>FHIR DSTU2.1 Support</title>
<author email="jamesagnew@users.sourceforge.net">James Agnew</author> <author email="jamesagnew@gmail.com">James Agnew</author>
</properties> </properties>
<body> <body>
<section name="Working with DSTU2"> <section name="Working with DSTU2.1">
<p> <p>
Although DSTU2 has not yet been balloted and finalized by HL7, Although DSTU2.1 has not yet been balloted and finalized by HL7,
there are several proposed changes which have been incorporated there are several proposed changes which have been incorporated
into the current into the current
<a href="http://hl7-fhir.github.io/">Continuous Integration Builds</a> <a href="http://hl7-fhir.github.io/">Continuous Integration Builds</a>
of the FHIR specification itself and many (if not most) of these changes will of the FHIR specification itself and many of these changes are used
end up in the final DSTU2 specification which is expected to be released as a part of testing scenarios in FHIR Connectathons.
in mid-to-late-2015.
</p> </p>
<p> <p>
DSTU2 is a significant upgrade to FHIR. While many things are unchanged, HAPI has support for DSTU2.1 definitions, based on the snapshot
lots of things have changed. Some of the the more interesting differences include: of the resource definitions available at the time that
</p> a given version of HAPI is released. These structures are found
<ul> in the <code>hapi-fhir-structures-dstu2.1-[version].jar</code>
<li> library, with the associated Schemas, ValueSets, and other
A new textual resources being found in
<a href="http://hl7-fhir.github.io/bundle.html">Bundle</a> <code>hapi-fhir-validation-resources-[version].jar</code>.
format which is no longer based on Atom. The new format does resemble the For information on where to find these libraries, see the
Atom format so it will not be unfamiliar to anyone who is used to DSTU1 bundles <a href="./downloads.html">Downloads</a> page.
but it has a few differences. On a conceptual level FHIR now defines a Bundle as
just another type of resource.
</li>
<li>
New
<a href="http://hl7-fhir.github.io/resource.html">"id" and "meta"</a>
elements which are present on all resources and explicitly state the resource's
ID, version, tags, and a few other things. All of these concepts had previously
existed in FHIR but were not a part of the resource body itself (rather they lived
in URLs and HTTP headers outside of the payload)
</li>
<li>
Numerous changes to the model, including attribute changes to existing resources,
the addition of a number of new resources, and the removal of a few redundant ones
as well.
</li>
</ul>
<subsection name="Supporting DSTU2 In your Applications">
<p>
As of HAPI FHIR 0.9, support for DSTU2 has been added to the library. Although upgrading
existing applications from DSTU1 to DSTU2 will not be painless, we have
tried as much as possible to make it easy.
</p>
<p>
First, support for DSTU2 capabilities has been added in a second optional dependency JAR which
you must add to your classpath. This JAR is called <code>hapi-structures-dstu2-[version].jar</code>.
See the <a href="./download.html">download page</a> for information on adding this JAR.
</p>
<p>
The FHIR version you are targeting is a property of the
<a href="http://jamesagnew.github.io/hapi-fhir/apidocs/ca/uhn/fhir/context/FhirContext.html">FhirContext</a>.
This means that if you use a FhirContext instance that is configured for DSTU2, any parsers, clients,
servers, etc. which use that context will be operating in DSTU2 mode.
</p>
<p>
To create a DSTU2 context, simply use the "forDstu2" factory method on the FhirContext class:
</p>
<macro name="snippet">
<param name="id" value="context" />
<param name="file" value="examples/src/main/java/example/Dstu2Examples.java" />
</macro>
</subsection>
<subsection name="DSTU2 Servers">
<p>
To support DSTU2 in your server, simply set the FhirContext in the server to be
one configured for DSTU2.
</p>
<macro name="snippet">
<param name="id" value="server" />
<param name="file" value="examples/src/main/java/example/Dstu2Examples.java" />
</macro>
<p>
Note that it is possible to share your resource provider classes between
servers supporting DSTU1 and servers supporting DSTU2 (including in the same WAR
instance on the same web server). This should make the process of upgrading your
server to the latest version of FHIR a bit easier.
</p>
</subsection>
<subsection name="New Bundle Format">
<p>
In FHIR DSTU2, the Atom specification for Bundles has been dropped in
favour of a new Bundle format that is a native FHIR resource. In order to
support this change, a new Bundle structure class has been added to the
resource structures in the DSTU2 structures JAR
<a href="./apidocs-dstu2/ca/uhn/fhir/model/dstu2/resource/Bundle.html">here</a>.
</p>
<p>
If you are working with Bundles directly in your application, it is recommended
to migrate to this new bundle structure. The "old"
<a href="./apidocs/ca/uhn/fhir/model/api/Bundle.html">Bundle</a>
class will work, but the new one is generated from the FHIR specification so it
is better aligned to the spec in terms of method names, JavaDocs, etc.
</p>
<p>
Because the new bundle type is a resource like any other resource, you should
parse and encode it using the
<code><a href="./apidocs/ca/uhn/fhir/parser/IParser.html#parseResource(java.lang.Class,%20java.lang.String)">parseResource</a></code>
and <code>encodeResource</code> methods instead of the previously used <code>parseBundle</code> and <code>encodeBundle</code>.
</p>
</subsection>
</section>
<section name="HL7.org &quot;Reference Implementation&quot; Structure Classes">
<p>
Since the early days of FHIR, HL7.org has provided an
open source "Java Reference Implementation", which is an implementation
of a FHIR data model, parser, and client in Java.
</p> </p>
<p> <p>
HAPI was originally started as a separate Java implementation of FHIR, Migrating to DSTU2.1 doesd require some effort, as the resource
with a fairly different focus: implementing servers with an easily definitions have been migrated to use the "Reference Implementation"
extendible data model. Over time though, the two Java implementations have structures. These are the resource definitions supplied by HL7,
shown a fair bit of overlap, so at the 2014 meaning that the process to merge these two libraries has now
<a href="http://fhir.furore.com/Events/DevDaysEval2014">DevDays</a> we decided begun.
to try and harmonize the two libraries.
</p>
<p>
HAPI FHIR 1.1 begins the availability of a harmonized library.
</p>
<p>
<b>For HAPI FHIR users:</b> This integration will bring the ability to use powerful features
from the RI in your applications, such as the resource validator and the narrative
generator.
</p>
<p>
<b>For RI users:</b> This integration will bring the ability to use HAPI's client
and server frameworks in your application, as well as the ability to take advantage
of HAPI's code-first statically bound extension mechanism.
</p> </p>
<subsection name="The RI Data Model"> <subsection name="The RI Data Model">
@ -175,27 +57,21 @@
All RI resource classes will be in the package <code>org.hl7.fhir.instance.model</code>, All RI resource classes will be in the package <code>org.hl7.fhir.instance.model</code>,
as shown below. as shown below.
</p> </p>
<img src="./images/hapi-1.1-structs-resource.png" alt="Structures"/> <img src="./images/hapi-1.1-structs-resource.svg" alt="Structures"/>
<p> <p>
Datatypes will also be found inthe same package. Unlike HAPI datatype structures, 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 which all end with "Dt", the RI primitive structure names end with "Type" and the
RI composite structures have no suffix, as shown below. RI composite structures have no suffix, as shown below.
</p> </p>
<img src="./images/hapi-1.1-structs-datatypes.png" alt="Structures"/> <img src="./images/hapi-1.1-structs-datatypes.svg" alt="Structures"/>
</subsection> </subsection>
<subsection name="Using the RI Structures in Your Application"> <subsection name="Using the DSTU2.1 Structures in Your Application">
<p> <p>
If you want to use the RI structures in your application, Using these structures is similar to using other structures:
you will need to use the "hapi-fhir-structures-hl7org-dstu2-[version].jar"
library.
</p>
<p>
Using these structures is then similar to using other structures.
</p> </p>
<macro name="snippet"> <macro name="snippet">
@ -204,10 +80,10 @@
</macro> </macro>
</subsection> </subsection>
</section> </section>
<section name="Upgrading Existing Applications to HAPI FHIR 1.1"> <section name="Upgrading Existing Applications to DSTU2.1">
<p> <p>
If you have an existing application built using a version of previous If you have an existing application built using a version of previous
@ -218,7 +94,8 @@
</p> </p>
<p> <p>
For these methods, you may cast the <code>IBaseResource</code> to For these methods, you may cast the <code>IBaseResource</code> to
<code>IResource</code>. <code>IResource</code> if you are using DSTU2 structures, or to
<code>IAnyResource</code> if you are using DSTU2.1 structures.
</p> </p>
<p> <p>
@ -227,6 +104,105 @@
if it's happening to you, it's happening to others. We're happy to help. if it's happening to you, it's happening to others. We're happy to help.
</p> </p>
<subsection name="Code changes in DSTU2.1 Structrues">
<p>
The following is a list of things that have changed in the DSTU2.1
structures which you will need to accomodate in your code as you
upgrade:
</p>
<h4>Package Structure</h4>
<ul>
<li>
Structures are all found in the
<code>org.hl7.fhir.dstu21.model</code> package,
instead of the <code>ca.uhn.fhir.model.dstu2.resource</code>,
<code>ca.uhn.fhir.model.dstu2.composite</code>, and
<code>ca.uhn.fhir.model.dstu2.valueset</code> packages.
</li>
</ul>
<h4>Datatypes</h4>
<ul>
<li>
<b>Primitive Types are renamed</b> from
<code>[foo]Dt</code> to <code>[foo]Type</code>,
e.g. <code>StringType</code> and <code>DecimalType</code>
</li>
<li>
<b>Composite Types are renamed</b> from
<code>[foo]Dt</code> to <code>[foo]</code>,
e.g. <code>CodeableConcept</code> and <code>HumanName</code>
</li>
<li>
<b>ResourceReferenceDt is renamed</b> to
<code>Reference</code>
<li>
<b>Reference#getReference()</b> returns the reference text, where
<code>Reference#getReferenceElement()</code> returns the <code>IdType</code>
representing the reference.
</li>
</li>
</ul>
<h4>Setter Names</h4>
<ul>
<li>
<b>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: <code>setName(String)</code> and
<code>setName(StringDt)</code>. In the new structures,
the setters are called <code>setName(String)</code> and
<code>setNameElement(StringType)</code>. This is more
consistent with the way the getters are named.</b>
</li>
</ul>
<h4>Resource Metadata</h4>
<ul>
<li>
<b>Resource#getId() returns the string ID</b> (e.g. <code>http://example.com/Patient/1</code>)
</li>
<li>
<b>Resource#getIdElement() returns the IdType</b> previously returned by <code>Resource#getId()</code>
</li>
<li>
<b>Resource metadata (e.g. last update time, tags, etc.) lives in a</b>
<code>Meta</code> object accessed using <code>Resource#getMeta()</code>
instead of using the <code>#getResourceMetadata()</code> hashmap.
<li><code>Resource#getMeta()#getLastUpdate()</code> returns the resource's last update time</li>
<li><code>Resource#getMeta()#getTag()</code> returns the resource's tag list</li>
<li><code>Resource#getMeta()#getProfile()</code> returns the resource's profile list</li>
</li>
</ul>
<h4>Contained Resources</h4>
<ul>
<li><b>Resource#getContained() returns the list</b> of contained resources (previously it returned a useless ContainedDt object which held the list of contained resources)</li>
</ul>
<h4>Enums for ValueSets</h4>
<ul>
<li>Enums are named <code>[EnumName]</code> instead of <code>[EnumName]Enum</code>. For example, <code>ConditionVerificationStatusEnum</code> is now called <code>ConditionVerificationStatus</code></li>
</ul>
<h4>
Resource/Datatype Components
</h4>
<ul>
<li>
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 <code>Entry</code> in the HAPI structures
but is called <code>BundleEntryComponent</code> in the RI structures.
</li>
</ul>
</subsection>
</section> </section>
</body> </body>