honeymoose
/
hapi-fhir
mirror of https://github.com/hapifhir/hapi-fhir.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'remotes/origin/master' into ks-flyway

This commit is contained in:
Ken Stevens 2019-11-25 11:46:20 -05:00
parent a32c62f83b 5becb613fe
commit e790b12d0e
9 changed files with 989 additions and 184 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
hapi-fhir-converter/pom.xml
View File

@ -165,6 +165,16 @@
</instructions>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<configuration>
<includeDependencySources>true</includeDependencySources>
<dependencySourceIncludes>
<include>ca.uhn.hapi.fhir:org.hl7.fhir.convertors</include>
</dependencySourceIncludes>
</configuration>
</plugin>
</plugins>
</build>
</project>

7
hapi-fhir-docs/pom.xml
View File

@ -104,6 +104,13 @@
<skip>true</skip>
</configuration>
</plugin>
<plugin>
<groupId>org.basepom.maven</groupId>
<artifactId>duplicate-finder-maven-plugin</artifactId>
<configuration>
<skip>true</skip>
</configuration>
</plugin>
</plugins>
<resources>
<resource>

41
hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/appendix/faq.md Normal file
View File

@ -0,0 +1,41 @@
# Frequently Asked Questions
# Getting Help
### Where can I ask questions or get help?
Please see [this page](https://github.com/jamesagnew/hapi-fhir/wiki/Getting-Help) in the HAPI FHIR Wiki for information on getting help.
# Using HAPI FHIR
### What JDK version does HAPI support?
See the [HAPI FHIR Versions](/docs/introduction/versions.html) page for information on the current minimum Java version required in order to use HAPI FHIR.
# JPA Server
### I would like to connect to the Derby database using a JDBC database browser (e.g. Squirrel, Toad, DBVisualizer) so that I can access the underlying tables. How do I do that?
By default Derby doesn't actually open any TCP ports for you to connect externally to it. Being an embedded database, it works a bit differently than other databases in that the client actually is the database and there's no outside communication with it possible.
There are a few options available to work around this fact:
* The easiest thing is to just load your data using the FHIR API. E.g. you can use HTTP/REST creates, transactions, etc to load data into your database directly.
* If you want to access the underlying database, the next easiest thing is to configure the database to use a filesystem directory, e.g. `jdbc:derby:directory:target/jpaserver_derby_files;create=true`. You can then shut the server down and use that same URL to connect a derby client (e.g. Squirrel or DBVisualizer) to the same path. You may need to use a fully qualified path instead of a relative one though.
* Another option is to use a different database (e.g. MySQL, Postgres, Oracle, etc.). HAPI's JPA server is based on JPA/Hibernate so it will support any database platform that hibernate supports.
* A final option is to start up Derby in network mode. Doing this is a bit more involved since you need to start the derby server separately, and then use a special URL to connect to it.
# Contributing
### My build is failing with the following error: *[ERROR] Failed to execute goal org.apache.maven.plugins:maven-surefire-plugin:2.19.1:test (default-test) on project hapi-fhir-jpaserver-base: Execution default-test of goal org.apache.maven.plugins:maven-surefire-plugin:2.19.1:test failed: The forked VM terminated without properly saying goodbye. VM crash or System.exit called?*
This typically means that your build is running out of memory. HAPI's unit tests execute by default in multiple threads (the thread count is determined by the number of CPU cores available) so in an environment with lots of cores but not enough RAM, you may run out. If you are getting this error, try executing the build with the following arguments:
```
mvn -P ALLMODULES,NOPARALLEL install
```
See [Hacking HAPI FHIR](/hacking.html) for more information on the build process.

116
hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/contributing/hacking_guide.md Normal file
View File

@ -0,0 +1,116 @@
# Hacking HAPI FHIR
This page contains useful information about how to get started in developing HAPI FHIR itself.
# Understanding the HAPI FHIR Codebase
The HAPI FHIR [Codebase](https://github.com/jamesagnew/hapi-fhir) has a number of subprojects. You will typically need to interact with several of them in order to develop HAPI, but you generally don't need all of them.
The following is a list of key subprojects you might open in your IDE:
* [hapi-fhir-base](https://github.com/jamesagnew/hapi-fhir/tree/master/hapi-fhir-base): This is the core library, containing the parsers, client/server frameworks, and many other features. Note that this module does not contain any model classes (e.g. the Patient model class) as these are found in "structures" projects below.
* hapi-fhir-structures-[version]: There are several structures projects (e.g. `hapi-fhir-structures-r4`), each of which contains model classes for a specific version of FHIR. Generally speaking you don't need to edit these project directly, as most (but not all) of their code is generated.
* hapi-fhir-jpaserver-base: This module contains the JPA server.
# Getting the Sources
<p style="float:right;">
<a class="externalLink" href="https://dev.azure.com/jamesagnew214/jamesagnew214/_build/latest?definitionId=1&branchName=master"><img src="https://dev.azure.com/jamesagnew214/jamesagnew214/_apis/build/status/jamesagnew.hapi-fhir?branchName=master" alt="Build Status" class="img-fluid"></a>
</p>
The best way to grab our sources is with Git. Grab the repository URL from our [GitHub page](https://github.com/jamesagnew/hapi-fhir). We try our best to ensure that the sources are always left in a buildable state. Check Azure Pipelines CI (see the image/link on the right) to see if the sources currently build.
# Building HAPI FHIR
HAPI is built primary using [Apache Maven](http://maven.apache.org/). Even if you are using an IDE, you should **start by performing a command line build** before trying to get everything working in an IDE. This step ensures that generated code is available to the IDE.
Execute the build with the following command:
```
mvn install
```
Note that this complete build takes a long time because of all of the unit tests being executed. At the end you should expect to see a screen resembling:
```
------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] HAPI-FHIR .......................................... SUCCESS [ 4.456 s]
[INFO] HAPI FHIR - Deployable Artifact Parent POM ......... SUCCESS [ 2.841 s]
[INFO] HAPI FHIR - Core Library ........................... SUCCESS [01:00 min]
[INFO] HAPI Tinder Plugin ................................. SUCCESS [ 19.259 s]
[INFO] HAPI FHIR Structures - DSTU1 (FHIR v0.80) .......... SUCCESS [01:40 min]
[INFO] HAPI FHIR Structures - DSTU2 (FHIR v1.0.0) ......... SUCCESS [01:14 min]
[INFO] HAPI FHIR Structures - DSTU3 ....................... SUCCESS [02:11 min]
.... some lines removed .....
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 20:45 min
[INFO] Finished at: 2016-02-27T15:05:35+00:00
```
# Troubleshooting
If the build fails to execute successfully, try the following:
* The first thing to try is always a fresh clean build when things aren't working:
```
mvn clean install
```
* **If you are trying to build a submodule** (e.g. `hapi-fhir-jpaserver-base`), try building the root project first. Especially when building from the Git <code>master</code>, often times there will be dependencies that require a fresh complete build (note that this is not generally an issue when building from a release version)
* If the build fails with memory issues (or mysteriously dies during unit tests), your build environment may be running out of memory. By default, the HAPI build executes unit tests in multiple parallel JVMs in order to save time. This can consume a lot of RAM and sometimes causes issues. Try executing with the following command to disable this behaviour:
```
mvn -P ALLMODULES,NOPARALLEL install
```
* If you figure something else out, please <b>let us know</b> so that we can add it to this list!
# Importing into Eclipse
This section shows how to import HAPI into Eclipse. There is no requirement to use Eclipse (IntelliJ/IDEA and Netbeans are both fine!) so feel free to skip this section.
**Maven Import**
Import the HAPI projects as Maven Modules by selecing **File -&gt; Import...** from the File menu. Then select **Existing Module Projects** as shown below.
<img src="../../images/hacking_import.png"/>
**Select the Projects**
Next, browse to the directory where you checked out the HAPI FHIR sources. You might want to select only the projects you are interested in editing, in order to keep Eclipse's memory use down. You can always come back and import more later.
<img src="../../images/hacking_import_step2.png"/>
##
<subsection name="Troubleshooting">
<p>
When importing the HAPI projects into Eclipse, sometimes Eclipse
will fail to correctly import libraries. If you import a module
into Eclipse and it fails to compile with many errors relating to
packages other than HAPI's, the following steps will fix this:
</p>
<ul>
<li>Delete the project from your Eclipse workspace</li>
<li>
On the local filesystem, delete the files <code>.project</code>
and <code>.classpath</code>, and the directory <code>.settings</code>
from each module you want to open.
</li>
<li>
Import each module again using the instructions above
</li>
</ul>
</subsection>
</section>
</body>
</document>

7
hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/files.properties
View File

@ -2,6 +2,9 @@
section.introduction.title=Welcome to HAPI FHIR
page.introduction.table_of_contents=Table of Contents
page.introduction.introduction=Introduction
page.introduction.versions=FHIR and HAPI FHIR Versions
page.introduction.modules=HAPI FHIR Modules
page.introduction.downloading_and_importing=Downloading and Importing
section.model.title=Working With The FHIR Model
page.model.working_with_resources=Working With Resources
@ -28,6 +31,10 @@ page.android.client=Android Client
section.tools.title=Tools
page.tools.hapi_fhir_cli=Command Line Interface (CLI) Tool
section.contributing.title=Contributing to HAPI FHIR
page.contributing.hacking_guide=Hacking Guide
section.appendix.title=Appendix
page.appendix.logging=Logging
page.appendix.changelog=Changelog
page.appendix.faq=FAQ

143
hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/introduction/downloading_and_importing.md Normal file
View File

@ -0,0 +1,143 @@
# Downloading/Importing HAPI FHIR
If you are developing applications in Java, the easiest way to use HAPI FHIR is to use a build system which handles dependency management automatically. The two most common such systems are [Apache Maven](http://maven.apache.org) and [Gradle](https://gradle.org/). These systems will automatically download "dependency" libraries and add them to your classpath. If you are **not** using one of these systems, you can still manually download the latest release of HAPI by looking in the [GitHub Release Section](https://github.com/jamesagnew/hapi-fhir/releases).
# Maven Users
To use HAPI in your application, at a minimum you need to include the HAPI-FHIR core JAR `hapi-fhir-base-[version].jar`, as well as at least one "structures" JAR.
The structures JAR contains classes with the resource and datatype definitions for a given version of FHIR.
If you are using Maven, the following example shows dependencies being added to include DSTU2 and R4 structures.
```xml
<dependencies>
<dependency>
<groupId>ca.uhn.hapi.fhir</groupId>
<artifactId>hapi-fhir-structures-dstu2</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>ca.uhn.hapi.fhir</groupId>
<artifactId>hapi-fhir-structures-r4</artifactId>
<version>${project.version}</version>
</dependency>
</dependencies>
```
Note that if you wish to perform validation, you may also want to include the "validation resources" JARs, which contain schemas, profiles, and other artifacts used by the validator for your given version.
```xml
<dependencies>
<dependency>
<groupId>ca.uhn.hapi.fhir</groupId>
<artifactId>hapi-fhir-validation-resources-dstu2</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>ca.uhn.hapi.fhir</groupId>
<artifactId>hapi-fhir-validation-resources-R4</artifactId>
<version>${project.version}</version>
</dependency>
</dependencies>
```
# Gradle Users
If you are using Gradle, you may use the following dependencies. Note that if you are doing Android development, you may want to use our [Android build](/docs/android/client.html) instead.
```groovy
compile 'ca.uhn.hapi.fhir:hapi-fhir-base:${project.version}'
compile 'ca.uhn.hapi.fhir:hapi-fhir-structures-dstu2:${project.version}'
compile 'ca.uhn.hapi.fhir:hapi-fhir-structures-r4:${project.version}'
```
# Snapshot Builds
The HAPI FHIR project generally releases a new full software release 4 times per year, or approximately every 3 months.
Generally speaking it is a good idea to use a stable build. However, FHIR is a fast moving specification, and there is a lot of ongoing work in HAPI as well. There may be times when you want to try out the latest unreleased version, either to test a new feature or to get a bugfix. You can ususally look at the [Changelog](/docs/introduction/changelog.html) to get a sense of what has changed in the next unreleased version.
## Using Snapshot Builds
Snapshot builds of HAPI are pre-release builds which can contain fixes and new features not yet released in a formal release. To use snapshot builds of HAPI you may need to add a reference to the OSS snapshot repository to your project build file.
Using a snapshot build generally involves appending *-SNAPSHOT* to the version number, e.g. `4.1.0-SNAPSHOT`. In order to automatically download snapshot builds, you may also need to add a snapshot repository to your build file as shown below:
### Using Maven:
To use a snapshot build, you
```xml
<repositories>
<repository>
<id>oss-snapshots</id>
<snapshots>
<enabled>true</enabled>
</snapshots>
<url>https://oss.sonatype.org/content/repositories/snapshots/</url>
</repository>
</repositories>
```
### Using Gradle:
```groovy
repositories {
mavenCentral()
maven {
url "https://oss.sonatype.org/content/repositories/snapshots"
}
}
```
# Dependencies
The HAPI-FHIR library depends on other libraries to provide specific functionality. Some of those libraries are listed here:
## Logging (SLF4j, Logback, etc.)
HAPI requires SLF4j for logging support, and it is recommended to include an underlying logging framework such as Logback. See the [logging documentation](/docs/appendix/logging.html) for more information.
## StAX / Woodstox
XML processing (for resource marshalling and unmarshalling) uses the Java StAX API, which is a fast and efficient API for XML processing. HAPI bundles (for release archives) and depends on (for Maven builds) the [Woodstox](http://woodstox.codehaus.org/) library, which is a good implementation of StAX.
Upon starting up, HAPI will emit a log line indicating which StAX implementation is being used, e.g:
```
08:01:32.044 [main] INFO ca.uhn.fhir.util.XmlUtil - FHIR XML procesing will use StAX implementation 'Woodstox XML-phrocessor' version '4.4.0'
```
Although most testing is done using the Woodstox implementation of StAX, it is not required and HAPI should work correctly with any compliant implementation of StAX.
You can force Woodstox in an environment where multiple StAX libraries are present by setting the following system properties:
```java
System.setProperty("javax.xml.stream.XMLInputFactory", "com.ctc.wstx.stax.WstxInputFactory");
System.setProperty("javax.xml.stream.XMLOutputFactory", "com.ctc.wstx.stax.WstxOutputFactory");
System.setProperty("javax.xml.stream.XMLEventFactory", "com.ctc.wstx.stax.WstxEventFactory");
```
## PH-Schematron
If you are using the [Schematron Validation](/docs/validation/schema.html) module, you will also need to include the Ph-Schematron library on your classpath. (Note that prior to HAPI FHIR 3.4.0 we used Phloc-Schamtron instead, but that library has been discontinued).
If you are using Maven, this library is not added by default (it is marked as an optional dependency) since not all applications need Schematron support. As a result you will need to manually add the following dependencies to your project pom.xml:
```xml
<dependencies>
<dependency>
<groupId>com.helger</groupId>
<artifactId>ph-schematron</artifactId>
<version>${ph_schematron_version}</version>
</dependency>
<dependency>
<groupId>com.helger</groupId>
<artifactId>ph-commons</artifactId>
<version>${ph_commons_version}</version>
</dependency>
</dependencies>
```

226
hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/introduction/modules.md Normal file
View File

@ -0,0 +1,226 @@
# HAPI FHIR Modules
The following table shows the modules that make up the HAPI FHIR library.
<table class="table table-condensed">
<tbody>
<tr>
<td colspan="3" style="text-align: center; font-size: 1.2em; background: #DDE; padding: 3px;">
Core Libraries
</td>
</tr>
<tr>
<td style="font-weight: bold; white-space: nowrap;">hapi-fhir-base</td>
<td>
<a href="../../apidocs/hapi-fhir-base/">JavaDoc</a>
</td>
<td>
This is the core HAPI FHIR library and is always required in order to use
the framework. It contains the context, parsers, and other support classes.
</td>
</tr>
<tr>
<td style="text-align: center; font-size: 1.2em; background: #DDE; padding: 3px;" colspan="3">
Structures
</td>
</tr>
<tr>
<td style="font-weight: bold; white-space: nowrap;">hapi-fhir-structures-dstu (retired)</td>
<td>
</td>
<td>
This module contained FHIR DSTU1 model classes. It was retired in HAPI FHIR 3.0.0.
</td>
</tr>
<tr>
<td style="font-weight: bold; white-space: nowrap;">hapi-fhir-structures-dstu2</td>
<td>
<a href="../../apidocs/hapi-fhir-structures-dstu2/">JavaDoc</a>
</td>
<td>
This module contains FHIR DSTU2 model classes.
</td>
</tr>
<tr>
<td style="font-weight: bold; white-space: nowrap;">hapi-fhir-structures-hl7org-dstu2</td>
<td>
<a href="../../apidocs/hapi-fhir-structures-hl7org-dstu2/">JavaDoc</a>
</td>
<td>
This module contains alternate FHIR DSTU2 model classes. The HAPI FHIR and FHIR "Java Reference
Implementation"
libraries were merged in 2015, and at the time there were two parallel sets of DSTU2 model
classes. This set more closely resembles the model classes for DSTU3+ where the other set
more closely resembles the original DSTU1 model classes. The two DSTU2 model JARs are functionally
identital, but the various utility methods on the classes are somewhat different.
</td>
</tr>
<tr>
<td style="font-weight: bold; white-space: nowrap;">hapi-fhir-structures-dstu3</td>
<td>
<a href="../../apidocs/hapi-fhir-structures-dstu3/">JavaDoc</a>
</td>
<td>
This module contains FHIR DSTU3 model classes.
</td>
</tr>
<tr>
<td style="font-weight: bold; white-space: nowrap;">hapi-fhir-structures-r4</td>
<td>
<a href="../../apidocs/hapi-fhir-structures-r4/">JavaDoc</a>
</td>
<td>
This module contains FHIR R4 model classes.
</td>
</tr>
<tr>
<td style="font-weight: bold; white-space: nowrap;">hapi-fhir-structures-r5</td>
<td>
<a href="../../apidocs/hapi-fhir-structures-r5/">JavaDoc</a>
</td>
<td>
This module contains FHIR R5 model classes.
</td>
</tr>
<tr>
<td style="font-weight: bold; white-space: nowrap;">hapi-fhir-converter</td>
<td>
<a href="../../apidocs/hapi-fhir-converter/">JavaDoc</a>
</td>
<td>
This module contains converters for converting between FHIR versions.
</td>
</tr>
<tr>
<td style="text-align: center; font-size: 1.2em; background: #DDE; padding: 3px;" colspan="3">Client
Framework
</td>
</tr>
<tr>
<td style="font-weight: bold; white-space: nowrap;">hapi-fhir-client</td>
<td>
<a href="../../apidocs/hapi-fhir-client/">JavaDoc</a>
</td>
<td>
This module contains the core FHIR client framework, including an
HTTP implementation based on
<a href="https://hc.apache.org/">Apache HttpClient</a>. It is required in order
to use client functionality in HAPI.
</td>
</tr>
<tr>
<td style="font-weight: bold; white-space: nowrap;">hapi-fhir-client-okhttp</td>
<td>
</td>
<td>
This module contains an alternate HTTP implementation based on
<a href="http://square.github.io/okhttp/">OKHTTP</a>.
</td>
</tr>
<tr>
<td style="font-weight: bold; white-space: nowrap;">hapi-fhir-android</td>
<td>
</td>
<td>
This module contains the Android HAPI FHIR framework, which is a FHIR
client framework which has been tailed specifically to run on Android.
</td>
</tr>
<tr>
<td style="text-align: center; font-size: 1.2em; background: #DDE; padding: 3px;" colspan="3">
Validation
</td>
</tr>
<tr>
<td style="font-weight: bold; white-space: nowrap;">hapi-fhir-validation</td>
<td>
</td>
<td>
This module contains the FHIR Profile Validator, which is used to
validate resource instances against FHIR Profiles (StructureDefinitions,
ValueSets, CodeSystems, etc.).
</td>
</tr>
<tr>
<td style="font-weight: bold; white-space: nowrap;">hapi-fhir-validation-resources-dstu2</td>
<td>
</td>
<td>
This module contains the StructureDefinitions, ValueSets, CodeSystems, Schemas,
and Schematrons for FHIR DSTU2
</td>
</tr>
<tr>
<td style="font-weight: bold; white-space: nowrap;">hapi-fhir-validation-resources-dstu2.1</td>
<td>
</td>
<td>
This module contains the StructureDefinitions, ValueSets, CodeSystems, Schemas,
and Schematrons for FHIR DSTU2.1
</td>
</tr>
<tr>
<td style="font-weight: bold; white-space: nowrap;">hapi-fhir-validation-resources-dstu3</td>
<td>
</td>
<td>
This module contains the StructureDefinitions, ValueSets, CodeSystems, Schemas,
and Schematrons for FHIR DSTU3
</td>
</tr>
<tr>
<td style="font-weight: bold; white-space: nowrap;">hapi-fhir-validation-resources-r4</td>
<td>
</td>
<td>
This module contains the StructureDefinitions, ValueSets, CodeSystems, Schemas,
and Schematrons for FHIR R4
</td>
</tr>
<tr>
<td style="font-weight: bold; white-space: nowrap;">hapi-fhir-validation-resources-r5</td>
<td>
</td>
<td>
This module contains the StructureDefinitions, ValueSets, CodeSystems for R5. As of FHIR
R5, Schema and Schematron files are no longer distributed with HAPI FHIR.
</td>
</tr>
<tr>
<td style="text-align: center; font-size: 1.2em; background: #DDE; padding: 3px;" colspan="3">Server</td>
</tr>
<tr>
<td style="font-weight: bold; white-space: nowrap;">hapi-fhir-server</td>
<td>
<a href="../../apidocs/hapi-fhir-server/">JavaDoc</a>
</td>
<td>
This module contains the HAPI FHIR Server framework, which can be used to
develop FHIR compliant servers against your own data storage layer.
</td>
</tr>
<tr>
<td style="font-weight: bold; white-space: nowrap;">hapi-fhir-jpaserver-base</td>
<td>
<a href="../../apidocs/hapi-fhir-jpaserver-base/">JavaDoc</a>
</td>
<td>
This module contains the HAPI FHIR "JPA Server", which is a complete
FHIR server solution including a database and implementations of many
advanced FHIR server features.
</td>
</tr>
<tr>
<td style="font-weight: bold; white-space: nowrap;">hapi-fhir-testpage-overlay</td>
<td>
</td>
<td>
This module contains the web based "testpage overlay", which is the
UI that powers our
<a href="http://fhirtest.uhn.ca">Public Demo Server</a>
and can also be added to your applications.
</td>
</tr>
</tbody>
</table>

253
hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/introduction/versions.md Normal file
View File

@ -0,0 +1,253 @@
# FHIR and HAPI FHIR Versions
The following table shows the various versions of the HAPI FHIR library, and the versions of the FHIR standard that they support. Note that support for stable releases of FHIR are shown in <span style="background: #CEC; padding: 3px;">GREEN</span> and support for draft pre-release versions of FHIR are shown in <span style="background: #EEB; padding: 3px;">YELLOW</span>.
Note also that after the release of the FHIR DSTU2 specification, the FHIR
standard itself stopped using the DSTUx naming scheme, in favour or naming new releases STUx or simply Rx. Because HAPI FHIR already had draft support for what was then called DSTU3 at this time, we did not update our naming conventions until R4 in order to avoid breaking existing users' code. From the perspective of a user of HAPI FHIR, consider the terms DSTU3 / STU3 / R3 to be interchangeable.
<table class="table table-condensed">
<thead>
<tr>
<td><b>HAPI Version</b></td>
<td><b>Min JDK</b></td>
<td><b>DSTU1</b></td>
<td><b>DSTU2</b></td>
<td><b>DSTU2.1</b></td>
<td><b>DSTU3</b></td>
<td><b>R4</b></td>
<td><b>R5</b></td>
</tr>
</thead>
<tbody>
<tr>
<td>HAPI FHIR 1.1</td>
<td>JDK6</td>
<td style="background: #CEC;">0.0.82</td>
<td style="background: #EEB;">0.5.0<span class="download-version-hash">-5843</span></td>
<td style="background: #DDD;"></td>
<td style="background: #DDD;"></td>
<td style="background: #DDD;"></td>
<td style="background: #DDD;"></td>
</tr>
<tr>
<td>HAPI FHIR 1.2</td>
<td>JDK6</td>
<td style="background: #CEC;">0.0.82</td>
<td style="background: #EEB;">0.5.0<span class="download-version-hash">-5843</span></td>
<td style="background: #DDD;"></td>
<td style="background: #DDD;"></td>
<td style="background: #DDD;"></td>
<td style="background: #DDD;"></td>
</tr>
<tr>
<td>HAPI FHIR 1.3</td>
<td>JDK6</td>
<td style="background: #CEC;">0.0.82</td>
<td style="background: #CEC;">1.0.2</td>
<td style="background: #DDD;"></td>
<td style="background: #DDD;"></td>
<td style="background: #DDD;"></td>
<td style="background: #DDD;"></td>
</tr>
<tr>
<td>HAPI FHIR 1.4</td>
<td>JDK6</td>
<td style="background: #CEC;">0.0.82</td>
<td style="background: #CEC;">1.0.2</td>
<td style="background: #DDD;"></td>
<td style="background: #EEB;">1.3.0<span class="download-version-hash">-7602</span></td>
<td style="background: #DDD;"></td>
<td style="background: #DDD;"></td>
</tr>
<tr>
<td>HAPI FHIR 1.5</td>
<td>JDK6</td>
<td style="background: #CEC;">0.0.82</td>
<td style="background: #CEC;">1.0.2</td>
<td style="background: #DDD;"></td>
<td style="background: #EEB;">1.4.0<span class="download-version-hash">-8138</span></td>
<td style="background: #DDD;"></td>
<td style="background: #DDD;"></td>
</tr>
<tr>
<td>HAPI FHIR 1.6</td>
<td>JDK6</td>
<td style="background: #CEC;">0.0.82</td>
<td style="background: #CEC;">1.0.2</td>
<td style="background: #DDD;"></td>
<td style="background: #EEB;">1.4.0<span class="download-version-hash">-8636</span></td>
<td style="background: #DDD;"></td>
<td style="background: #DDD;"></td>
</tr>
<tr>
<td>HAPI FHIR 2.0</td>
<td>JDK6</td>
<td style="background: #CEC;">0.0.82</td>
<td style="background: #CEC;">1.0.2</td>
<td style="background: #DDD;"></td>
<td style="background: #EEB;">1.6.0<span class="download-version-hash">-9663</span></td>
<td style="background: #DDD;"></td>
<td style="background: #DDD;"></td>
</tr>
<tr>
<td>HAPI FHIR 2.1</td>
<td>JDK6</td>
<td style="background: #CEC;">0.0.82</td>
<td style="background: #CEC;">1.0.2</td>
<td style="background: #DDD;"></td>
<td style="background: #EEB;">1.7.0<span class="download-version-hash">-10129</span></td>
<td style="background: #DDD;"></td>
<td style="background: #DDD;"></td>
</tr>
<tr>
<td>HAPI FHIR 2.2</td>
<td>JDK6</td>
<td style="background: #CEC;">0.0.82</td>
<td style="background: #CEC;">1.0.2</td>
<td style="background: #EEB;">1.4.0</td>
<td style="background: #EEB;">1.8.0<span class="download-version-hash">-10528</span></td>
<td style="background: #DDD;"></td>
<td style="background: #DDD;"></td>
</tr>
<tr>
<td>HAPI FHIR 2.3</td>
<td>JDK6</td>
<td style="background: #CEC;">0.0.82</td>
<td style="background: #CEC;">1.0.2</td>
<td style="background: #EEB;">1.4.0</td>
<td style="background: #EEB;">1.9.0<span class="download-version-hash">-11501</span></td>
<td style="background: #DDD;"></td>
<td style="background: #DDD;"></td>
</tr>
<tr>
<td>HAPI FHIR 2.4</td>
<td>JDK6</td>
<td style="background: #CEC;">0.0.82</td>
<td style="background: #CEC;">1.0.2</td>
<td style="background: #EEB;">1.4.0</td>
<td style="background: #CEC;">3.0.1</td>
<td style="background: #DDD;"></td>
<td style="background: #DDD;"></td>
</tr>
<tr>
<td>HAPI FHIR 2.5</td>
<td>JDK6</td>
<td style="background: #CEC;">0.0.82</td>
<td style="background: #CEC;">1.0.2</td>
<td style="background: #EEB;">1.4.0</td>
<td style="background: #CEC;">3.0.1</td>
<td style="background: #DDD;"></td>
<td style="background: #DDD;"></td>
</tr>
<tr>
<td>HAPI FHIR 3.0.0</td>
<td>JDK7</td>
<td style="background: #DDD;"></td>
<td style="background: #CEC;">1.0.2</td>
<td style="background: #EEB;">1.4.0</td>
<td style="background: #CEC;">3.0.1</td>
<td style="background: #EEB;">3.1.0<span class="download-version-hash">-12370</span></td>
<td style="background: #DDD;"></td>
</tr>
<tr>
<td>HAPI FHIR 3.1.0</td>
<td>JDK7</td>
<td style="background: #DDD;"></td>
<td style="background: #CEC;">1.0.2</td>
<td style="background: #EEB;">1.4.0</td>
<td style="background: #CEC;">3.0.1</td>
<td style="background: #EEB;">3.1.0<span class="download-version-hash">-12370</span></td>
<td style="background: #DDD;"></td>
</tr>
<tr>
<td>HAPI FHIR 3.2.0</td>
<td>JDK7</td>
<td style="background: #DDD;"></td>
<td style="background: #CEC;">1.0.2</td>
<td style="background: #EEB;">1.4.0</td>
<td style="background: #CEC;">3.0.1</td>
<td style="background: #EEB;">3.2.0<span class="download-version-hash">-12917</span></td>
<td style="background: #DDD;"></td>
</tr>
<tr>
<td>HAPI FHIR 3.3.0</td>
<td>JDK7</td>
<td style="background: #DDD;"></td>
<td style="background: #CEC;">1.0.2</td>
<td style="background: #EEB;">1.4.0</td>
<td style="background: #CEC;">3.0.1</td>
<td style="background: #EEB;">3.2.0<span class="download-version-hash">-13271</span></td>
<td style="background: #DDD;"></td>
</tr>
<tr>
<td>HAPI FHIR 3.4.0</td>
<td>JDK8</td>
<td style="background: #DDD;"></td>
<td style="background: #CEC;">1.0.2</td>
<td style="background: #EEB;">1.4.0</td>
<td style="background: #CEC;">3.0.1</td>
<td style="background: #EEB;">3.4.0<span class="download-version-hash">-13732</span></td>
<td style="background: #DDD;"></td>
</tr>
<tr>
<td>HAPI FHIR 3.5.0</td>
<td>JDK8</td>
<td style="background: #DDD;"></td>
<td style="background: #CEC;">1.0.2</td>
<td style="background: #EEB;">1.4.0</td>
<td style="background: #CEC;">3.0.1</td>
<td style="background: #EEB;">3.4.0<span class="download-version-hash">-13732</span></td>
<td style="background: #DDD;"></td>
</tr>
<tr>
<td>HAPI FHIR 3.6.0</td>
<td>JDK8</td>
<td style="background: #DDD;"></td>
<td style="background: #CEC;">1.0.2</td>
<td style="background: #EEB;">1.4.0</td>
<td style="background: #CEC;">3.0.1</td>
<td style="background: #EEB;">3.6.0<span class="download-version-hash">-1202b2eed0f</span></td>
<td style="background: #DDD;"></td>
</tr>
<tr>
<td>HAPI FHIR 3.7.0</td>
<td>JDK8</td>
<td style="background: #DDD;"></td>
<td style="background: #CEC;">1.0.2</td>
<td style="background: #EEB;">1.4.0</td>
<td style="background: #CEC;">3.0.1</td>
<td style="background: #CEC;">4.0.0</td>
<td style="background: #DDD;"></td>
</tr>
<tr>
<td>HAPI FHIR 3.8.0</td>
<td>JDK8</td>
<td style="background: #DDD;"></td>
<td style="background: #CEC;">1.0.2</td>
<td style="background: #EEB;">1.4.0</td>
<td style="background: #CEC;">3.0.1</td>
<td style="background: #CEC;">4.0.0</td>
<td style="background: #DDD;"></td>
</tr>
<tr>
<td>HAPI FHIR 4.0.0</td>
<td>JDK8</td>
<td style="background: #DDD;"></td>
<td style="background: #CEC;">1.0.2</td>
<td style="background: #EEB;">1.4.0</td>
<td style="background: #CEC;">3.0.1</td>
<td style="background: #CEC;">4.0.0</td>
<td style="background: #EEB;">4.1.0<span class="download-version-hash">-e0e3caf9ba</span></td>
</tr>
<tr>
<td>HAPI FHIR 4.1.0</td>
<td>JDK8</td>
<td style="background: #DDD;"></td>
<td style="background: #CEC;">1.0.2</td>
<td style="background: #EEB;">1.4.0</td>
<td style="background: #CEC;">3.0.2</td>
<td style="background: #CEC;">4.0.1</td>
<td style="background: #EEB;">4.1.0<span class="download-version-hash">-1a7623d866</span></td>
</tr>
</tbody>
</table>

370
src/site/xdoc/hacking_hapi_fhir.xml
View File

@ -1,184 +1,186 @@
<?xml version="1.0" encoding="UTF-8"?>
<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>
<title>Hacking HAPI FHIR</title>
</properties>
<body>
<section name="Hacking HAPI FHIR">
<p>
This page contains useful information about how to get started in developing
HAPI FHIR itself.
</p>
</section>
<section name="Understanding the HAPI FHIR Codebase">
<p>
The HAPI FHIR <a href="https://github.com/jamesagnew/hapi-fhir">Codebase</a>
has a number of subprojects. You will typically need to interact with several
of them in order to develop HAPI, but you generally don't need all of them.
</p>
<p>
The following is a list of key subprojects you might open in your IDE:
</p>
<ul>
<li>
<a href="https://github.com/jamesagnew/hapi-fhir/tree/master/hapi-fhir-base"><b>hapi-fhir-base</b></a>:
This is the core library, containing the parsers, client/server frameworks, and many other features. Note
that this module does not contain any model classes (e.g. the Patient model class) as these are found
in "structures" projects below.
</li>
<li>
<b>hapi-fhir-structures-[version]</b>:
There are several structures projects (e.g. <code>hapi-fhir-structures-dstu2</code>), each of
which contains model classes for a specific version of FHIR.It is generally a good idea
to open all of these in your IDE.
</li>
<li>
<b>hapi-fhir-validation-resources-[version]</b>:
There are several validation resources projects (e.g. <code>hapi-fhir-validation-resources-dstu2</code>), each of
which contains text resources for the given version. These resources are text resources produced
as a part of the FHIR specification build (e.g. StructureDefinitions, ValueSets, etc.)
</li>
<li>
<b>hapi-fhir-jpaserver-base</b>:
This module contains the JPA server.
</li>
</ul>
</section>
<section name="Getting the Sources">
<p style="float:right;">
<a href="https://travis-ci.org/jamesagnew/hapi-fhir"><img src="https://travis-ci.org/jamesagnew/hapi-fhir.svg?branch=master" alt="Build Status"/></a>
</p>
<p>
The best way to grab our sources is with Git. Grab the repository URL
from our <a href="https://github.com/jamesagnew/hapi-fhir">GitHub page</a>.
We try our best to ensure that the sources are always left in a buildable state. Check
Travis (see the image/link on the right) to see if the sources currently build.
</p>
</section>
<section name="Building HAPI FHIR">
<p>
HAPI is built primary using
<a href="http://maven.apache.org/">Apache Maven</a>. Even if you are using an IDE,
you should start by performing a command line build before trying to get
everything working in an IDE.
</p>
<p>
Execute the build with the following command:<br/>
<code>mvn install</code>
</p>
<p>
Note that this complete build takes a long time because of all of the unit tests
being executed. At the end you should expect to see a screen resembling:<br/>
<pre>[]INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] HAPI-FHIR .......................................... SUCCESS [ 4.456 s]
[INFO] HAPI FHIR - Deployable Artifact Parent POM ......... SUCCESS [ 2.841 s]
[INFO] HAPI FHIR - Core Library ........................... SUCCESS [01:00 min]
[INFO] HAPI Tinder Plugin ................................. SUCCESS [ 19.259 s]
[INFO] HAPI FHIR Structures - DSTU1 (FHIR v0.80) .......... SUCCESS [01:40 min]
[INFO] HAPI FHIR Structures - DSTU2 (FHIR v1.0.0) ......... SUCCESS [01:14 min]
[INFO] HAPI FHIR Structures - DSTU3 ....................... SUCCESS [02:11 min]
.... some lines removed .....
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 20:45 min
[INFO] Finished at: 2016-02-27T15:05:35+00:00</pre>
</p>
<subsection name="Troubleshooting">
<p>
If the build fails to execute successfully, try the following:
</p>
<ul>
<li>
The first thing to try is always a fresh clean build when things aren't working:<br/>
<pre>mvn clean install</pre>
</li>
<li>
<b>If you are trying to build a submodule</b> (e.g. <code>hapi-fhir-jpaserver-example</code>),
try building the root project first. Especially when building from the Git <code>master</code>,
often times there will be dependencies that require a fresh complete build (note that this is
not generally an issue when building from a release version)<br/>
<pre><![CDATA[cd [workspace]/hapi-fhir
mvn install]]></pre>
</li>
<li>
<b>If the build fails with memory issues (or mysteriously dies during unit tests)</b>,
your build environment may be running out of memory. By default, the HAPI build executes
unit tests in multiple parallel JVMs in order to save time. This can consume a lot of RAM
and sometimes causes issues. Try executing with the following command to disable
this behaviour:<br/>
<pre>mvn -P ALLMODULES,NOPARALLEL install</pre>
</li>
<li>
If you figure something else out, please <b>let us know</b> so that we can add it
to this list!
</li>
</ul>
</subsection>
</section>
<section name="Importing into Eclipse">
<p>
This section shows how to import HAPI into Eclipse. There is no requirement
to use Eclipse (IntelliJ/IDEA and Netbeans are both fine!) so feel free to
skip this section.
</p>
<p>
<b>Maven Import</b><br/>
Import the HAPI projects as Maven Modules by selecing
<code>File -&gt; Import...</code> from the File menu. Then select
<code>Existing Module Projects</code> as shown below.
</p>
<img src="./images/hacking_import.png"/><br/><br/>
<p>
<b>Select the Projects</b><br/>
Next, browse to the directory where you checked out the HAPI FHIR sources.
You might want to select only the projects you are interested in editing,
in order to keep Eclipse's memory use down. You can always come back and
import more later.
</p>
<img src="./images/hacking_import_step2.png"/>
<subsection name="Troubleshooting">
<p>
When importing the HAPI projects into Eclipse, sometimes Eclipse
will fail to correctly import libraries. If you import a module
into Eclipse and it fails to compile with many errors relating to
packages other than HAPI's, the following steps will fix this:
</p>
<ul>
<li>Delete the project from your Eclipse workspace</li>
<li>
On the local filesystem, delete the files <code>.project</code>
and <code>.classpath</code>, and the directory <code>.settings</code>
from each module you want to open.
</li>
<li>
Import each module again using the instructions above
</li>
</ul>
</subsection>
</section>
</body>
</document>
<?xml version="1.0" encoding="UTF-8"?>
<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">
<!-- This content has been migrated -->
<properties>
<title>Hacking HAPI FHIR</title>
</properties>
<body>
<section name="Hacking HAPI FHIR">
<p>
This page contains useful information about how to get started in developing
HAPI FHIR itself.
</p>
</section>
<section name="Understanding the HAPI FHIR Codebase">
<p>
The HAPI FHIR <a href="https://github.com/jamesagnew/hapi-fhir">Codebase</a>
has a number of subprojects. You will typically need to interact with several
of them in order to develop HAPI, but you generally don't need all of them.
</p>
<p>
The following is a list of key subprojects you might open in your IDE:
</p>
<ul>
<li>
<a href="https://github.com/jamesagnew/hapi-fhir/tree/master/hapi-fhir-base"><b>hapi-fhir-base</b></a>:
This is the core library, containing the parsers, client/server frameworks, and many other features. Note
that this module does not contain any model classes (e.g. the Patient model class) as these are found
in "structures" projects below.
</li>
<li>
<b>hapi-fhir-structures-[version]</b>:
There are several structures projects (e.g. <code>hapi-fhir-structures-dstu2</code>), each of
which contains model classes for a specific version of FHIR.It is generally a good idea
to open all of these in your IDE.
</li>
<li>
<b>hapi-fhir-validation-resources-[version]</b>:
There are several validation resources projects (e.g. <code>hapi-fhir-validation-resources-dstu2</code>), each of
which contains text resources for the given version. These resources are text resources produced
as a part of the FHIR specification build (e.g. StructureDefinitions, ValueSets, etc.)
</li>
<li>
<b>hapi-fhir-jpaserver-base</b>:
This module contains the JPA server.
</li>
</ul>
</section>
<section name="Getting the Sources">
<p style="float:right;">
<a href="https://travis-ci.org/jamesagnew/hapi-fhir"><img src="https://travis-ci.org/jamesagnew/hapi-fhir.svg?branch=master" alt="Build Status"/></a>
</p>
<p>
The best way to grab our sources is with Git. Grab the repository URL
from our <a href="https://github.com/jamesagnew/hapi-fhir">GitHub page</a>.
We try our best to ensure that the sources are always left in a buildable state. Check
Travis (see the image/link on the right) to see if the sources currently build.
</p>
</section>
<section name="Building HAPI FHIR">
<p>
HAPI is built primary using
<a href="http://maven.apache.org/">Apache Maven</a>. Even if you are using an IDE,
you should start by performing a command line build before trying to get
everything working in an IDE.
</p>
<p>
Execute the build with the following command:<br/>
<code>mvn install</code>
</p>
<p>
Note that this complete build takes a long time because of all of the unit tests
being executed. At the end you should expect to see a screen resembling:<br/>
<pre>[]INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] HAPI-FHIR .......................................... SUCCESS [ 4.456 s]
[INFO] HAPI FHIR - Deployable Artifact Parent POM ......... SUCCESS [ 2.841 s]
[INFO] HAPI FHIR - Core Library ........................... SUCCESS [01:00 min]
[INFO] HAPI Tinder Plugin ................................. SUCCESS [ 19.259 s]
[INFO] HAPI FHIR Structures - DSTU1 (FHIR v0.80) .......... SUCCESS [01:40 min]
[INFO] HAPI FHIR Structures - DSTU2 (FHIR v1.0.0) ......... SUCCESS [01:14 min]
[INFO] HAPI FHIR Structures - DSTU3 ....................... SUCCESS [02:11 min]
.... some lines removed .....
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 20:45 min
[INFO] Finished at: 2016-02-27T15:05:35+00:00</pre>
</p>
<subsection name="Troubleshooting">
<p>
If the build fails to execute successfully, try the following:
</p>
<ul>
<li>
The first thing to try is always a fresh clean build when things aren't working:<br/>
<pre>mvn clean install</pre>
</li>
<li>
<b>If you are trying to build a submodule</b> (e.g. <code>hapi-fhir-jpaserver-example</code>),
try building the root project first. Especially when building from the Git <code>master</code>,
often times there will be dependencies that require a fresh complete build (note that this is
not generally an issue when building from a release version)<br/>
<pre><![CDATA[cd [workspace]/hapi-fhir
mvn install]]></pre>
</li>
<li>
<b>If the build fails with memory issues (or mysteriously dies during unit tests)</b>,
your build environment may be running out of memory. By default, the HAPI build executes
unit tests in multiple parallel JVMs in order to save time. This can consume a lot of RAM
and sometimes causes issues. Try executing with the following command to disable
this behaviour:<br/>
<pre>mvn -P ALLMODULES,NOPARALLEL install</pre>
</li>
<li>
If you figure something else out, please <b>let us know</b> so that we can add it
to this list!
</li>
</ul>
</subsection>
</section>
<section name="Importing into Eclipse">
<p>
This section shows how to import HAPI into Eclipse. There is no requirement
to use Eclipse (IntelliJ/IDEA and Netbeans are both fine!) so feel free to
skip this section.
</p>
<p>
<b>Maven Import</b><br/>
Import the HAPI projects as Maven Modules by selecing
<code>File -&gt; Import...</code> from the File menu. Then select
<code>Existing Module Projects</code> as shown below.
</p>
<img src="./images/hacking_import.png"/><br/><br/>
<p>
<b>Select the Projects</b><br/>
Next, browse to the directory where you checked out the HAPI FHIR sources.
You might want to select only the projects you are interested in editing,
in order to keep Eclipse's memory use down. You can always come back and
import more later.
</p>
<img src="./images/hacking_import_step2.png"/>
<subsection name="Troubleshooting">
<p>
When importing the HAPI projects into Eclipse, sometimes Eclipse
will fail to correctly import libraries. If you import a module
into Eclipse and it fails to compile with many errors relating to
packages other than HAPI's, the following steps will fix this:
</p>
<ul>
<li>Delete the project from your Eclipse workspace</li>
<li>
On the local filesystem, delete the files <code>.project</code>
and <code>.classpath</code>, and the directory <code>.settings</code>
from each module you want to open.
</li>
<li>
Import each module again using the instructions above
</li>
</ul>
</subsection>
</section>
</body>
</document>