diff --git a/hapi-fhir-converter/pom.xml b/hapi-fhir-converter/pom.xml index df5856bb360..30f39fdbb73 100644 --- a/hapi-fhir-converter/pom.xml +++ b/hapi-fhir-converter/pom.xml @@ -165,6 +165,16 @@ + + org.apache.maven.plugins + maven-javadoc-plugin + + true + + ca.uhn.hapi.fhir:org.hl7.fhir.convertors + + + diff --git a/hapi-fhir-docs/pom.xml b/hapi-fhir-docs/pom.xml index b608d91aff9..dd7780e2efd 100644 --- a/hapi-fhir-docs/pom.xml +++ b/hapi-fhir-docs/pom.xml @@ -104,6 +104,13 @@ true + + org.basepom.maven + duplicate-finder-maven-plugin + + true + + diff --git a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/appendix/faq.md b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/appendix/faq.md new file mode 100644 index 00000000000..c641e45c6e5 --- /dev/null +++ b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/appendix/faq.md @@ -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. diff --git a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/contributing/hacking_guide.md b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/contributing/hacking_guide.md new file mode 100644 index 00000000000..9601ad2352f --- /dev/null +++ b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/contributing/hacking_guide.md @@ -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 + +

+Build Status +

+ +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 master, 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 let us know 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 -> Import...** from the File menu. Then select **Existing Module Projects** as shown below. + + + +**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. + + + +## + + +

+ 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: +

+
    +
  • Delete the project from your Eclipse workspace
    • +
  • + On the local filesystem, delete the files .project + and .classpath, and the directory .settings + from each module you want to open. +
    • +
  • + Import each module again using the instructions above +
    • +
+ + + + + + + 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 24f21a3fad0..34db88963b9 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 @@ -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 diff --git a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/introduction/downloading_and_importing.md b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/introduction/downloading_and_importing.md new file mode 100644 index 00000000000..28a50bd78f8 --- /dev/null +++ b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/introduction/downloading_and_importing.md @@ -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 + + + ca.uhn.hapi.fhir + hapi-fhir-structures-dstu2 + ${project.version} + + + ca.uhn.hapi.fhir + hapi-fhir-structures-r4 + ${project.version} + + +``` + +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 + + + ca.uhn.hapi.fhir + hapi-fhir-validation-resources-dstu2 + ${project.version} + + + ca.uhn.hapi.fhir + hapi-fhir-validation-resources-R4 + ${project.version} + + +``` + +# 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 + + + oss-snapshots + + true + + https://oss.sonatype.org/content/repositories/snapshots/ + + +``` + +### 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 + + + com.helger + ph-schematron + ${ph_schematron_version} + + + com.helger + ph-commons + ${ph_commons_version} + + +``` + diff --git a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/introduction/modules.md b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/introduction/modules.md new file mode 100644 index 00000000000..4a03f44dba0 --- /dev/null +++ b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/introduction/modules.md @@ -0,0 +1,226 @@ +# HAPI FHIR Modules + +The following table shows the modules that make up the HAPI FHIR library. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Core Libraries +
hapi-fhir-base + JavaDoc + + 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. +
+ Structures +
hapi-fhir-structures-dstu (retired) + + This module contained FHIR DSTU1 model classes. It was retired in HAPI FHIR 3.0.0. +
hapi-fhir-structures-dstu2 + JavaDoc + + This module contains FHIR DSTU2 model classes. +
hapi-fhir-structures-hl7org-dstu2 + JavaDoc + + 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. +
hapi-fhir-structures-dstu3 + JavaDoc + + This module contains FHIR DSTU3 model classes. +
hapi-fhir-structures-r4 + JavaDoc + + This module contains FHIR R4 model classes. +
hapi-fhir-structures-r5 + JavaDoc + + This module contains FHIR R5 model classes. +
hapi-fhir-converter + JavaDoc + + This module contains converters for converting between FHIR versions. +
Client + Framework +
hapi-fhir-client + JavaDoc + + This module contains the core FHIR client framework, including an + HTTP implementation based on + Apache HttpClient. It is required in order + to use client functionality in HAPI. +
hapi-fhir-client-okhttp + + This module contains an alternate HTTP implementation based on + OKHTTP. +
hapi-fhir-android + + This module contains the Android HAPI FHIR framework, which is a FHIR + client framework which has been tailed specifically to run on Android. +
+ Validation +
hapi-fhir-validation + + This module contains the FHIR Profile Validator, which is used to + validate resource instances against FHIR Profiles (StructureDefinitions, + ValueSets, CodeSystems, etc.). +
hapi-fhir-validation-resources-dstu2 + + This module contains the StructureDefinitions, ValueSets, CodeSystems, Schemas, + and Schematrons for FHIR DSTU2 +
hapi-fhir-validation-resources-dstu2.1 + + This module contains the StructureDefinitions, ValueSets, CodeSystems, Schemas, + and Schematrons for FHIR DSTU2.1 +
hapi-fhir-validation-resources-dstu3 + + This module contains the StructureDefinitions, ValueSets, CodeSystems, Schemas, + and Schematrons for FHIR DSTU3 +
hapi-fhir-validation-resources-r4 + + This module contains the StructureDefinitions, ValueSets, CodeSystems, Schemas, + and Schematrons for FHIR R4 +
hapi-fhir-validation-resources-r5 + + This module contains the StructureDefinitions, ValueSets, CodeSystems for R5. As of FHIR + R5, Schema and Schematron files are no longer distributed with HAPI FHIR. +
Server
hapi-fhir-server + JavaDoc + + This module contains the HAPI FHIR Server framework, which can be used to + develop FHIR compliant servers against your own data storage layer. +
hapi-fhir-jpaserver-base + JavaDoc + + 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. +
hapi-fhir-testpage-overlay + + This module contains the web based "testpage overlay", which is the + UI that powers our + Public Demo Server + and can also be added to your applications. +
+ diff --git a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/introduction/versions.md b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/introduction/versions.md new file mode 100644 index 00000000000..bf95cfe4580 --- /dev/null +++ b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/introduction/versions.md @@ -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 GREEN and support for draft pre-release versions of FHIR are shown in YELLOW. + +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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
HAPI VersionMin JDKDSTU1DSTU2DSTU2.1DSTU3R4R5
HAPI FHIR 1.1JDK60.0.820.5.0-5843
HAPI FHIR 1.2JDK60.0.820.5.0-5843
HAPI FHIR 1.3JDK60.0.821.0.2
HAPI FHIR 1.4JDK60.0.821.0.21.3.0-7602
HAPI FHIR 1.5JDK60.0.821.0.21.4.0-8138
HAPI FHIR 1.6JDK60.0.821.0.21.4.0-8636
HAPI FHIR 2.0JDK60.0.821.0.21.6.0-9663
HAPI FHIR 2.1JDK60.0.821.0.21.7.0-10129
HAPI FHIR 2.2JDK60.0.821.0.21.4.01.8.0-10528
HAPI FHIR 2.3JDK60.0.821.0.21.4.01.9.0-11501
HAPI FHIR 2.4JDK60.0.821.0.21.4.03.0.1
HAPI FHIR 2.5JDK60.0.821.0.21.4.03.0.1
HAPI FHIR 3.0.0JDK71.0.21.4.03.0.13.1.0-12370
HAPI FHIR 3.1.0JDK71.0.21.4.03.0.13.1.0-12370
HAPI FHIR 3.2.0JDK71.0.21.4.03.0.13.2.0-12917
HAPI FHIR 3.3.0JDK71.0.21.4.03.0.13.2.0-13271
HAPI FHIR 3.4.0JDK81.0.21.4.03.0.13.4.0-13732
HAPI FHIR 3.5.0JDK81.0.21.4.03.0.13.4.0-13732
HAPI FHIR 3.6.0JDK81.0.21.4.03.0.13.6.0-1202b2eed0f
HAPI FHIR 3.7.0JDK81.0.21.4.03.0.14.0.0
HAPI FHIR 3.8.0JDK81.0.21.4.03.0.14.0.0
HAPI FHIR 4.0.0JDK81.0.21.4.03.0.14.0.04.1.0-e0e3caf9ba
HAPI FHIR 4.1.0JDK81.0.21.4.03.0.24.0.14.1.0-1a7623d866
diff --git a/src/site/xdoc/hacking_hapi_fhir.xml b/src/site/xdoc/hacking_hapi_fhir.xml index 839ba2036bf..684507f5738 100644 --- a/src/site/xdoc/hacking_hapi_fhir.xml +++ b/src/site/xdoc/hacking_hapi_fhir.xml @@ -1,184 +1,186 @@ - - - - - Hacking HAPI FHIR - - - - -
- -

- This page contains useful information about how to get started in developing - HAPI FHIR itself. -

- -
- -
- -

- The HAPI FHIR Codebase - 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: - 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-dstu2), 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. -
    • -
  • - hapi-fhir-validation-resources-[version]: - There are several validation resources projects (e.g. hapi-fhir-validation-resources-dstu2), 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.) -
    • -
  • - hapi-fhir-jpaserver-base: - This module contains the JPA server. -
    • -
- -
- -
-

- Build Status -

-

- The best way to grab our sources is with Git. Grab the repository URL - from our GitHub page. - 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. -

-
- -
-

- HAPI is built primary using - Apache Maven. 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. -

-

- 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] ------------------------------------------------------------------------
-[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
-

- - - -

- 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-example), - try building the root project first. Especially when building from the Git master, - 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 let us know so that we can add it - to this list! -
    • -
- - - -
- -
-

- 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 -> Import... from the File menu. Then select - Existing Module Projects as shown below. -

-

-

- 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. -

- - - - -

- 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: -

-
    -
  • Delete the project from your Eclipse workspace
    • -
  • - On the local filesystem, delete the files .project - and .classpath, and the directory .settings - from each module you want to open. -
    • -
  • - Import each module again using the instructions above -
    • -
- - - -
- - - + + + + + + + Hacking HAPI FHIR + + + + +
+ +

+ This page contains useful information about how to get started in developing + HAPI FHIR itself. +

+ +
+ +
+ +

+ The HAPI FHIR Codebase + 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: + 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-dstu2), 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. +
    • +
  • + hapi-fhir-validation-resources-[version]: + There are several validation resources projects (e.g. hapi-fhir-validation-resources-dstu2), 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.) +
    • +
  • + hapi-fhir-jpaserver-base: + This module contains the JPA server. +
    • +
+ +
+ +
+

+ Build Status +

+

+ The best way to grab our sources is with Git. Grab the repository URL + from our GitHub page. + 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. +

+
+ +
+

+ HAPI is built primary using + Apache Maven. 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. +

+

+ 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] ------------------------------------------------------------------------
+[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
+

+ + + +

+ 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-example), + try building the root project first. Especially when building from the Git master, + 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 let us know so that we can add it + to this list! +
    • +
+ + + +
+ +
+

+ 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 -> Import... from the File menu. Then select + Existing Module Projects as shown below. +

+

+

+ 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. +

+ + + + +

+ 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: +

+
    +
  • Delete the project from your Eclipse workspace
    • +
  • + On the local filesystem, delete the files .project + and .classpath, and the directory .settings + from each module you want to open. +
    • +
  • + Import each module again using the instructions above +
    • +
+ + + +
+ + +