hapi-fhir-android module has been streamlined in order to reduce its footprint. Previous versions of the library included both an XML and a JSON parser but this has been streamlined to only include JSON support in order to reduce the number of libraries required in an Android build.
+
+When using the HAPI FHIR Android client, the client will request only JSON responses (via the HTTP Accept header) and will not be able to communicate with FHIR servers that support only XML encoding (few, if any, servers actually exist with this limitation that we are aware of).
+
+The Android client also uses the hapi-fhir-client-okhttp module, which is an HTTP client based on the OkHttp library. This library has proven to be more powerful and less likely to cause issues on Android than the Apache HttpClient implementation which is bundled by default.
+
+Note that the Android JAR is still new and hasn't received as much testing as other parts of the library. We would greatly appreciate feedback, testing, etc. Also note that because mobile apps run on less powerful hardware compared to desktop and server applications, it is all the more important to keep a single instance of the `FhirContext` around for good performance, since this object is expensive to create. We are hoping to improve performance of the creation of this object in a future release. If you are an Android developer and would like to help with this, please get in touch!
+
+## Get the Android JAR
+
+To add the HAPI library via Gradle, you should add the [hapi-fhir-android](https://search.maven.org/search?q=g:ca.uhn.hapi.fhir%20AND%20a:hapi-fhir-android&core=gav) library to your Gradle file, as well as a structures library for the appropriate version of FHIR that you want to support, e.g. [hapi-fhir-structures-r4](https://search.maven.org/search?q=g:ca.uhn.hapi.fhir%20AND%20a:hapi-fhir-structures-r4&core=gav).
+
+```groovy
+dependencies {
+ compile "ca.uhn.hapi.fhir:hapi-fhir-android:3.1.0-SNAPSHOT"
+ compile "ca.uhn.hapi.fhir:hapi-fhir-structures-dstu2:3.1.0-SNAPSHOT"
+}
+```
+
+You will also need to manually exclude the Woodstox StAX library from inclusion, as this library uses namespaces which are prohibited on Android. You should also exclude:
+
+```groovy
+configurations {
+ all*.exclude group: 'org.codehaus.woodstox'
+ all*.exclude group: 'org.apache.httpcomponents'
+}
+```
+
+To see a sample Gradle file for a working Android project using HAPI FHIR, see the [Android Integration Test](https://github.com/hapifhir/hapi-fhir-android-integration-test) project.
+
+# Performance
+
+On mobile devices, performance problems are particularly noticeable. This is made worse by the fact that some economy Android devices have much slower performance than modern desktop computers. See the [Client Configuration Performance](/docs/client/rest_client_http_config.html#performance) page for some tips on how to improve client performance.
+
+# Examples
+
+The following is intended to be a selection of publicly available open source Android applications which use HAPI FHIR and might be useful as a reference.
+
+If you know of others, please let us know!
+
+* [https://github.com/hapifhir/hapi-fhir-android-integration-test](https://github.com/hapifhir/hapi-fhir-android-integration-test) - hapi-fhir-android Integration Test and Reference Application is our test platform for validating new releases. Created by Thomas Andersen.
+* [https://github.com/SynappzMA/FHIR-Android](https://github.com/SynappzMA/FHIR-Android) - Nice FHIR DSTU2 search app
diff --git a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/files.properties b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/files.properties
index 3a29c5f2e49..e5496399bf6 100644
--- a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/files.properties
+++ b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/files.properties
@@ -3,5 +3,19 @@ section.introduction.title=Welcome to HAPI FHIR
page.introduction.table_of_contents=Table of Contents
page.introduction.introduction=Introduction
+section.model.title=Working With The FHIR Model
+page.model.profiles_and_extensions=Profiles and Extensions
+page.model.converter=Version Converters
+page.model.custom_structures=Custom Structures
+
+section.server.title=Server
+page.server.cors=CORS
+
+section.android.title=Android Support
+page.android.client=Android Client
+
+section.tools.title=Tools
+page.tools.hapi_fhir_cli=Command Line Interface (CLI) Tool
+
section.appendix.title=Appendix
page.appendix.changelog=Changelog
diff --git a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/favicon.png b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/favicon.png
new file mode 100644
index 00000000000..f96cc5a3e6a
Binary files /dev/null and b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/favicon.png differ
diff --git a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/github-logo-mini.png b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/github-logo-mini.png
new file mode 100644
index 00000000000..815160af4cb
Binary files /dev/null and b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/github-logo-mini.png differ
diff --git a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hacking_import.png b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hacking_import.png
new file mode 100644
index 00000000000..1ec8496616f
Binary files /dev/null and b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hacking_import.png differ
diff --git a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hacking_import_step2.png b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hacking_import_step2.png
new file mode 100644
index 00000000000..71c52ea430c
Binary files /dev/null and b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hacking_import_step2.png differ
diff --git a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hapi-1.1-structs-datatypes.svg b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hapi-1.1-structs-datatypes.svg
new file mode 100644
index 00000000000..8ae16122ad2
--- /dev/null
+++ b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hapi-1.1-structs-datatypes.svg
@@ -0,0 +1,3 @@
+
+
+
diff --git a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hapi-1.1-structs-resource.svg b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hapi-1.1-structs-resource.svg
new file mode 100644
index 00000000000..a737fe63e9f
--- /dev/null
+++ b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hapi-1.1-structs-resource.svg
@@ -0,0 +1,3 @@
+
+
+
diff --git a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hapi-fhir-cli-run-server.png b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hapi-fhir-cli-run-server.png
new file mode 100644
index 00000000000..a84018df579
Binary files /dev/null and b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hapi-fhir-cli-run-server.png differ
diff --git a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hapi-fhir-cli.png b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hapi-fhir-cli.png
new file mode 100644
index 00000000000..d503f80ed09
Binary files /dev/null and b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hapi-fhir-cli.png differ
diff --git a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hapi-usage.png b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hapi-usage.png
new file mode 100644
index 00000000000..b6109c12694
Binary files /dev/null and b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hapi-usage.png differ
diff --git a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hapi_authorizationinterceptor_read_normal.svg b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hapi_authorizationinterceptor_read_normal.svg
new file mode 100644
index 00000000000..5a4bac103c1
--- /dev/null
+++ b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hapi_authorizationinterceptor_read_normal.svg
@@ -0,0 +1,2 @@
+
+
\ No newline at end of file
diff --git a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hapi_authorizationinterceptor_write_normal.svg b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hapi_authorizationinterceptor_write_normal.svg
new file mode 100644
index 00000000000..cb9aee69a3d
--- /dev/null
+++ b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hapi_authorizationinterceptor_write_normal.svg
@@ -0,0 +1,2 @@
+
+
\ No newline at end of file
diff --git a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hapi_fhir_banner.png b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hapi_fhir_banner.png
new file mode 100644
index 00000000000..c264336271e
Binary files /dev/null and b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hapi_fhir_banner.png differ
diff --git a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hapi_fhir_banner_right.png b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hapi_fhir_banner_right.png
new file mode 100644
index 00000000000..f40e438546a
Binary files /dev/null and b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/hapi_fhir_banner_right.png differ
diff --git a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/jpa_architecture.png b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/jpa_architecture.png
new file mode 100644
index 00000000000..9e82adfc7c1
Binary files /dev/null and b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/jpa_architecture.png differ
diff --git a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/littlehapiface.png b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/littlehapiface.png
new file mode 100644
index 00000000000..4215aecdf96
Binary files /dev/null and b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/littlehapiface.png differ
diff --git a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/littlehapiface2020.png b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/littlehapiface2020.png
new file mode 100644
index 00000000000..e9f02033c3b
Binary files /dev/null and b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/littlehapiface2020.png differ
diff --git a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/logos/maven-feather.png b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/logos/maven-feather.png
new file mode 100644
index 00000000000..b5ada836e9e
Binary files /dev/null and b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/logos/maven-feather.png differ
diff --git a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/maven-logo-mini.png b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/maven-logo-mini.png
new file mode 100644
index 00000000000..aa47bd5226e
Binary files /dev/null and b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/maven-logo-mini.png differ
diff --git a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/model/converter.md b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/model/converter.md
new file mode 100644
index 00000000000..35497d7c636
--- /dev/null
+++ b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/model/converter.md
@@ -0,0 +1,37 @@
+
+# HL7 FHIR Converter
+
+Beginning in HAPI FHIR 2.3, a new module called `hapi-fhir-converter` has been added to the project. This is an experimental feature so use it with caution!
+
+This feature allows automated conversion from earlier versions of the FHIR structures to a later version.
+
+The following page shows some basic examples. Please get in touch if you are able to contribute better examples!
+
+## Importing the Module
+
+To use the `hapi-fhir-converter` module, import the following dependency into your project pom.xml (or equivalent)
+
+```xml
++This is an advanced features and isn't needed for most uses of HAPI-FHIR. Feel free to skip this page. +
+ +# Custom Resource Structure + +The following example shows a custom resource structure class: + +```java +{{snippet:classpath:/ca/uhn/hapi/fhir/docs/customtype/CustomResource.java|resource}} +``` + +## Custom Datatype Structure + +The following example shows a custom datatype structure class: + +```java +{{snippet:classpath:/ca/uhn/hapi/fhir/docs/customtype/CustomDatatype.java|datatype}} +``` + +## Using the Custom Structure + +And now let's try the custom structure out: + +```java +{{snippet:classpath:/ca/uhn/hapi/fhir/docs/customtype/CustomUsage.java|usage}} +``` + +This produces the following output (some spacing has been added for readability): + +```xml ++Note on FHIR Versions: Because of the differences in the way the structures work between DSTU2 and DSTU3, we have provided two versions of many of the examples on this page. See the download page for more information on FHIR versions. +
+ +Extensions are a key part of the FHIR specification, providing a standardized way of placing additional data in a resource. + +The simplest way to interact with extensions (i.e. to add them to resources you are creating, or to read them from resources you are consuming) is to treat them as "undeclared extensions". Undeclared extensions can be added to any of the built in FHIR resource types that come with HAPI-FHIR. + +### DSTU2 + +```java +{{snippet:classpath:/ca/uhn/hapi/fhir/docs/ExtensionsDstu2.java|resourceExtension}} +``` + +### DSTU3 and Later + +```java +{{snippet:classpath:/ca/uhn/hapi/fhir/docs/ExtensionsDstu3.java|resourceExtension}} +``` + +Undeclared extensions can also be added to datatypes (composite or primitive). + +### DSTU2 + +```java +{{snippet:classpath:/ca/uhn/hapi/fhir/docs/ExtensionsDstu2.java|resourceStringExtension}} +``` + +### DSTU3 and Later + +```java +{{snippet:classpath:/ca/uhn/hapi/fhir/docs/ExtensionsDstu3.java|resourceStringExtension}} +``` + +## Sub-Extensions + +Extensions may also have child extensions as their content, instead of a datatype. This is done by adding a child undeclared extension to the parent extension. + +### DSTU2 + +```java +{{snippet:classpath:/ca/uhn/hapi/fhir/docs/ExtensionsDstu2.java|subExtension}} +``` + +### DSTU3 and Later + +```java +{{snippet:classpath:/ca/uhn/hapi/fhir/docs/ExtensionsDstu3.java|subExtension}} +``` + +## Retrieving Extension Values + +HAPI provides a few ways of accessing extension values in resources which are received from other sources (i.e. downloaded by a client). + +### DSTU2 + +```java +{{snippet:classpath:/ca/uhn/hapi/fhir/docs/ExtensionsDstu2.java|parseExtension}} +``` + +### DSTU3 and Later + +```java +{{snippet:classpath:/ca/uhn/hapi/fhir/docs/ExtensionsDstu3.java|parseExtension}} +``` + +# Custom Resource Types + +The most elegant way of adding extensions to a resource is through the use of custom fields. The following example shows a custom type which extends the FHIR Patient resource definition through two extensions. + +```java +{{snippet:classpath:/ca/uhn/hapi/fhir/docs/MyPatient.java|patientDef}} +``` + +Using this custom type is as simple as instantiating the type and working with the new fields. + +```java +{{snippet:classpath:/ca/uhn/hapi/fhir/docs/MyPatientUse.java|patientUse}} +``` + +This example produces the following output: + +```xml ++Note that in previous revisions of this document we recommended using the eBay CORS Filter, but as of 2016 the eBay filter is no longer being maintained and contains known bugs. We now recommend against using this filter. +
+ +If you are intending to support JavaScript clients in your server application, you will generally need to enable Cross Origin Resource Sharing (CORS). There are a number of ways of supporting this, so two are shown here: + +* An approach using a HAPI FHIR Server Interceptor (Requires SpringFramework) +* An approach using a servlet Filter (Container Specific) + +## HAPI FHIR Server Interceptor + +The HAPI FHIR server framework includes an interceptor that can be used to provide CORS functionality on your server. This mechanism is nice because it relies purely on Java configuration (no messing around with web.xml files). HAPI's interceptor is a thin wrapper around Spring Framework's CorsProcessor class, so it requires Spring to be present on your classpath. + +Spring is generally unlikely to conflict with other libraries so it is usually safe to add it to your classpath, but it is a fairly large library so if size is a concern you might opt to use a filter instead. + +The following steps outline how to enable HAPI's CorsInterceptor: + +Add the following dependency to your POM. Note the exclusion of commons-logging, as we are using SLF4j without commons-logging in most of our examples. If your application uses commons-logging you don't need to exclude that dependency. + +```xml +
+
+## Download and Installation - Mac/OSX
+
+hapi-fhir-cli is available as a Homebrew package for Mac. It can be installed using the following command:
+
+```bash
+brew install hapi-fhir-cli
+```
+
+## Troubleshooting
+
+The tool should work correctly on any system that has Java 8 (or newer) installed. If it is not working correctly, first try the following command to test if Java is installed:
+
+```bash
+java -version
+```
+
+If this command does not produce output similar to the following, you should install/reinstall Java.
+
+```
+java version "1.8.0_60"
+Java(TM) SE Runtime Environment (build 1.8.0_60-b27)
+Java HotSpot(TM) 64-Bit Server VM (build 25.60-b23, mixed mode)
+```
+If this does not help, please post a question on our [Google Group](https://groups.google.com/d/forum/hapi-fhir).
+
+# Server (run-server)
+
+The CLI tool can be used to start a local, fully functional FHIR server which you can use for testing. To start this server, simply issue the command hapi-fhir-cli run-server as shown in the example below:
+
+
+
+Once the server has started, you can access the testing webpage by pointing your browser at http://localhost:8080/. The FHIR server base URL will be http://localhost:8080/baseDstu2/.
+
+Note that by default this server will not be populated with any resources at all. You can easily populate it with the FHIR example resources by leaving it running and opening a second terminal window, then using the hapi-fhir-cli upload-examples command (see the section below).
+
+The server uses a local Derby database instance for storage. You may want to execute this command in an empty directory, which you can clear if you want to reset the server.
+
+# Upload Example Resources (upload-examples)
+
+The upload-examples command downloads the complete set of FHIR example resources from the HL7 website, and uploads them to a server of your choice. This can be useful to populate a server with test data.
+
+To execute this command, uploading test resources to a local CLI server, issue the following: `hapi-fhir-cli upload-examples -t http://localhost:8080/baseDstu2`
+
+Note that this command may take a surprisingly long time to complete because of the large number of examples.
+
+# Upload Terminology
+
+The HAPI FHIR JPA server has a terminology server, and has the ability to be populated with "external" code systems. These code systems are systems that contain large numbers of codes, so the codes are not stored directly inside the resource body.
+
+HAPI has methods for uploading several popular code systems into its tables using the distribution files produced by the respective code systems. This is done using the upload-terminology command. The following examples show how to do this for several popular code systems.
+
+Note that the path and exact filename of the terminology files will likely need to be adjusted for your local disk structure.
+
+### SNOMED CT
+
+```
+./hapi-fhir-cli upload-terminology -d Downloads/SnomedCT_RF2Release_INT_20160131.zip -f dstu3 -t http://localhost:8080/baseDstu3 -u http://snomed.info/sct
+```
+
+### LOINC
+
+```
+./hapi-fhir-cli upload-terminology -d Downloads/LOINC_2.54_MULTI-AXIAL_HIERARCHY.zip -d Downloads/LOINC_2.54_Text.zip -f dstu3 -t http://localhost:8080/baseDstu3 -u http://loinc.org
+```
+
+# Migrate Database
+
+The `migrate-database` command may be used to Migrate a database schema when upgrading a HAPI FHIR JPA project from one version of HAPI FHIR to another version.
+
+See Upgrading HAPI FHIR JPA for information on how to use this command.
diff --git a/hapi-fhir-structures-r5/src/test/java/ca/uhn/fhir/rest/client/GenericClientTest.java b/hapi-fhir-structures-r5/src/test/java/ca/uhn/fhir/rest/client/GenericClientTest.java
index 1b0069e6c64..e1ec9f95469 100644
--- a/hapi-fhir-structures-r5/src/test/java/ca/uhn/fhir/rest/client/GenericClientTest.java
+++ b/hapi-fhir-structures-r5/src/test/java/ca/uhn/fhir/rest/client/GenericClientTest.java
@@ -1293,7 +1293,7 @@ public class GenericClientTest {
assertThat(capt.getValue().getURI().toString(), containsString("http://example.com/fhir/Patient?"));
assertThat(capt.getValue().getURI().toString(), containsString("_include=" + UrlUtil.escapeUrlParam(Patient.INCLUDE_ORGANIZATION.getValue())));
- assertThat(capt.getValue().getURI().toString(), containsString("_include%3Arecurse=" + UrlUtil.escapeUrlParam(Patient.INCLUDE_LINK.getValue())));
+ assertThat(capt.getValue().getURI().toString(), containsString("_include%3Aiterate=" + UrlUtil.escapeUrlParam(Patient.INCLUDE_LINK.getValue())));
assertThat(capt.getValue().getURI().toString(), containsString("_include=*"));
}
diff --git a/src/site/xdoc/doc_android.xml.vm b/src/site/xdoc/doc_android.xml.vm
index 4780747e4bf..1b9096581e3 100644
--- a/src/site/xdoc/doc_android.xml.vm
+++ b/src/site/xdoc/doc_android.xml.vm
@@ -1,6 +1,8 @@
- Beginning in HAPI FHIR 2.3, a new experimental feature called
- hapi-fhir-converter has been added to the project. This
- is an experimental feature so use it with caution!
-
- This feature allows automated conversion from earlier versions - of the FHIR structures to a later version. -
- -- The following page shows some basic examples. Please get in touch - if you are able to contribute better examples! -
- -
- To use the hapi-fhir-converter module, import the following
- dependency into your project pom.xml (or equivalent)
-
- The following example shows a conversion from a
- hapi-fhir-structures-hl7org-dstu2
- structure to a
- hapi-fhir-structures-dstu3 structure.
-
- The following example shows a conversion from a
- hapi-fhir-structures-dstu2.1
- structure to a
- hapi-fhir-structures-dstu3 structure.
-
+ Beginning in HAPI FHIR 2.3, a new experimental feature called
+ hapi-fhir-converter has been added to the project. This
+ is an experimental feature so use it with caution!
+
+ This feature allows automated conversion from earlier versions + of the FHIR structures to a later version. +
+ ++ The following page shows some basic examples. Please get in touch + if you are able to contribute better examples! +
+ +
+ To use the hapi-fhir-converter module, import the following
+ dependency into your project pom.xml (or equivalent)
+
+ The following example shows a conversion from a
+ hapi-fhir-structures-hl7org-dstu2
+ structure to a
+ hapi-fhir-structures-dstu3 structure.
+
+ The following example shows a conversion from a
+ hapi-fhir-structures-dstu2.1
+ structure to a
+ hapi-fhir-structures-dstu3 structure.
+
- Note that in previous revisions of this document we recommended using the - eBay CORS Filter, but - as of 2016 the eBay filter is no longer being maintained and contains known bugs. - We now recommend against using this filter. -
- -- If you are intending to support JavaScript clients in your server application, - you will generally need to enable Cross Origin Resource Sharing (CORS). There are - a number of ways of supporting this, so two are shown here: -
-- The HAPI FHIR server framework includes an interceptor that can be - used to provide CORS functionality on your server. This mechanism is - nice because it relies purely on Java configuration (no messing around with - web.xml files). HAPI's interceptor is a thin wrapper around Spring Framework's - CorsProcessor class, so it requires Spring to be present on your classpath. -
- -- Spring is generally unlikely to conflict with other libraries so it is usually - safe to add it to your classpath, but it is a fairly large library so if size is - a concern you might opt to use a filter instead. -
- -- The following steps outline how to enable HAPI's CorsInterceptor: -
- -- Add the following dependency to your POM. Note the exclusion of - commons-logging, as we are using SLF4j without commons-logging in - most of our examples. If your application uses commons-logging you don't need - to exclude that dependency. -
-- In your server's initialization method, create and register - a CorsInterceptor: -
-
- The following examples show how to use the Apache Tomcat CorsFilter to enable
- CORS support. The filter being used
- (org.apache.catalina.filters.CorsFilter) is bundled with Apache
- Tomcat so if you are deploying to that server you can use the filter.
-
- Other containers have similar filters you can use, so consult the documentation - for the given container you are using for more information. (If you have - an example for how to configure a different CORS filter, please send it - our way! Examples are always useful!) -
- -- In your web.xml file (within the WEB-INF directory in your WAR file), - the following filter definition adds the CORS filter, including support - for the X-FHIR-Starter header defined by SMART Platforms. -
- -+ Note that in previous revisions of this document we recommended using the + eBay CORS Filter, but + as of 2016 the eBay filter is no longer being maintained and contains known bugs. + We now recommend against using this filter. +
+ ++ If you are intending to support JavaScript clients in your server application, + you will generally need to enable Cross Origin Resource Sharing (CORS). There are + a number of ways of supporting this, so two are shown here: +
++ The HAPI FHIR server framework includes an interceptor that can be + used to provide CORS functionality on your server. This mechanism is + nice because it relies purely on Java configuration (no messing around with + web.xml files). HAPI's interceptor is a thin wrapper around Spring Framework's + CorsProcessor class, so it requires Spring to be present on your classpath. +
+ ++ Spring is generally unlikely to conflict with other libraries so it is usually + safe to add it to your classpath, but it is a fairly large library so if size is + a concern you might opt to use a filter instead. +
+ ++ The following steps outline how to enable HAPI's CorsInterceptor: +
+ ++ Add the following dependency to your POM. Note the exclusion of + commons-logging, as we are using SLF4j without commons-logging in + most of our examples. If your application uses commons-logging you don't need + to exclude that dependency. +
++ In your server's initialization method, create and register + a CorsInterceptor: +
+
+ The following examples show how to use the Apache Tomcat CorsFilter to enable
+ CORS support. The filter being used
+ (org.apache.catalina.filters.CorsFilter) is bundled with Apache
+ Tomcat so if you are deploying to that server you can use the filter.
+
+ Other containers have similar filters you can use, so consult the documentation + for the given container you are using for more information. (If you have + an example for how to configure a different CORS filter, please send it + our way! Examples are always useful!) +
+ ++ In your web.xml file (within the WEB-INF directory in your WAR file), + the following filter definition adds the CORS filter, including support + for the X-FHIR-Starter header defined by SMART Platforms. +
+ +- Typically, when working with FHIR the right way to provide your - own extensions is to work with existing resource types and simply - add your own extensions and/or constrain out fields you don't - need. -
-- This process is described on the - Profiles & Extensions - page. -
-- There are situations however when you might want to create an - entirely custom resource type. This feature should be used - only if there is no other option, since it means you are creating - a resource type that will not be interoperable with other FHIR - implementations. -
-- This is an advanced features and isn't needed for most uses of - HAPI-FHIR. Feel free to skip this page. -
- -- The following example shows a custom resource structure - class: -
-- The following example shows a custom datatype structure - class: -
-- And now let's try the custom structure out: -
-- This produces the following output (some spacing has been added for readability): -
-+ Typically, when working with FHIR the right way to provide your + own extensions is to work with existing resource types and simply + add your own extensions and/or constrain out fields you don't + need. +
++ This process is described on the + Profiles & Extensions + page. +
++ There are situations however when you might want to create an + entirely custom resource type. This feature should be used + only if there is no other option, since it means you are creating + a resource type that will not be interoperable with other FHIR + implementations. +
++ This is an advanced features and isn't needed for most uses of + HAPI-FHIR. Feel free to skip this page. +
+ ++ The following example shows a custom resource structure + class: +
++ The following example shows a custom datatype structure + class: +
++ And now let's try the custom structure out: +
++ This produces the following output (some spacing has been added for readability): +
+- Note on FHIR Versions: Because of the differences in the way the structures - work between DSTU2 and DSTU3, we have provided two versions of many of the - examples on this page. See the download page - for more information on FHIR versions. -
- -- Extensions are a key part of the FHIR specification, providing a standardized - way of placing additional data in a resource. -
- -- The simplest way to interact with extensions (i.e. to add them to resources you are creating, or - to read them from resources you are consuming) is to treat them as "undeclared extensions". - Undeclared extensions can be added to any of the built in FHIR resource types that come with HAPI-FHIR. -
- -- DSTU2 -
-- DSTU3 -
-- Undeclared extensions can also be added to datatypes (composite or primitive). -
- -- DSTU2 -
-- DSTU3 -
-- Extensions may also have child extensions as their content, instead - of a datatype. This is done by adding a child undeclared extension to the - parent extension. -
- -- DSTU2 -
-- DSTU3 -
-- HAPI provides a few ways of accessing extension values in resources - which are received from other sources (i.e. downloaded by a client). -
- -- DSTU2 -
-- DSTU3 -
-- The most elegant way of adding extensions to a resource is through the - use of custom fields. The following example shows a custom type which - extends the FHIR Patient resource definition through two extensions. -
- -- Using this custom type is as simple as instantiating the type - and working with the new fields. -
- -- This example produces the following output: -
- -- Parsing messages using your new custom type is equally simple. - These types can also be used as method return types in clients - and servers. -
- -- If you are using a client and wish to use a specific custom structure, - you may simply use the custom structure as you would a build in - HAPI type. -
-- You may also explicitly use custom types in searches and other - operations which return resources. -
-- You can also explicitly declare a preferred response resource custom - type. This is useful for some operations that do not otherwise - declare their resource types in the method signature. -
-- Sometimes you may not know in advance exactly which - type you will be receiving. For example, there are Patient resources - which conform to several different profiles on a server and you - aren't sure which profile you will get back for a specific read, - you can declare the "primary" type for a given profile. -
-- This is declared at the FhirContext level, and will apply to any - clients created from this context (including clients created before - the default was set). -
-- If you are using a client and wish to use a specific custom structure, - you may simply use the custom structure as you would a build in - HAPI type. -
-- The following example shows a resource containing a composite - extension. -
- -- This could be used to create a resource such as the - following: -
-+ Note on FHIR Versions: Because of the differences in the way the structures + work between DSTU2 and DSTU3, we have provided two versions of many of the + examples on this page. See the download page + for more information on FHIR versions. +
+ ++ Extensions are a key part of the FHIR specification, providing a standardized + way of placing additional data in a resource. +
+ ++ The simplest way to interact with extensions (i.e. to add them to resources you are creating, or + to read them from resources you are consuming) is to treat them as "undeclared extensions". + Undeclared extensions can be added to any of the built in FHIR resource types that come with HAPI-FHIR. +
+ ++ DSTU2 +
++ DSTU3 +
++ Undeclared extensions can also be added to datatypes (composite or primitive). +
+ ++ DSTU2 +
++ DSTU3 +
++ Extensions may also have child extensions as their content, instead + of a datatype. This is done by adding a child undeclared extension to the + parent extension. +
+ ++ DSTU2 +
++ DSTU3 +
++ HAPI provides a few ways of accessing extension values in resources + which are received from other sources (i.e. downloaded by a client). +
+ ++ DSTU2 +
++ DSTU3 +
++ The most elegant way of adding extensions to a resource is through the + use of custom fields. The following example shows a custom type which + extends the FHIR Patient resource definition through two extensions. +
+ ++ Using this custom type is as simple as instantiating the type + and working with the new fields. +
+ ++ This example produces the following output: +
+ ++ Parsing messages using your new custom type is equally simple. + These types can also be used as method return types in clients + and servers. +
+ ++ If you are using a client and wish to use a specific custom structure, + you may simply use the custom structure as you would a build in + HAPI type. +
++ You may also explicitly use custom types in searches and other + operations which return resources. +
++ You can also explicitly declare a preferred response resource custom + type. This is useful for some operations that do not otherwise + declare their resource types in the method signature. +
++ Sometimes you may not know in advance exactly which + type you will be receiving. For example, there are Patient resources + which conform to several different profiles on a server and you + aren't sure which profile you will get back for a specific read, + you can declare the "primary" type for a given profile. +
++ This is declared at the FhirContext level, and will apply to any + clients created from this context (including clients created before + the default was set). +
++ If you are using a client and wish to use a specific custom structure, + you may simply use the custom structure as you would a build in + HAPI type. +
++ The following example shows a resource containing a composite + extension. +
+ ++ This could be used to create a resource such as the + following: +
+