Setting Up Your Development Environment | HL7 FHIR for Java Developers

Prerequisites

Before starting FHIR development in Java, ensure you have:

Java Development Kit (JDK): 11 or higher (17+ recommended)
Build Tool: Maven 3.6+ or Gradle 7+
IDE: IntelliJ IDEA, Eclipse, or VS Code with Java extensions
Optional: Docker for running FHIR servers locally

Maven Dependencies

HAPI FHIR Core Dependencies

HAPI FHIR is a complete, open-source implementation of the HL7 FHIR standard for Java. The following Maven dependencies provide the essential building blocks: the base library for core functionality, structures for your target FHIR version (R4 in this case), client libraries for server communication, and validation support for ensuring data conformance. Add these dependencies to your pom.xml:

<!-- pom.xml -->
<properties>
    <hapi.fhir.version>6.10.0</hapi.fhir.version>
    <apache.camel.version>4.0.3</apache.camel.version>
    <java.version>17</java.version>
</properties>

<dependencies>
    <!-- HAPI FHIR Core -->
    <dependency>
        <groupId>ca.uhn.hapi.fhir</groupId>
        <artifactId>hapi-fhir-base</artifactId>
        <version>${hapi.fhir.version}</version>
    </dependency>

    <!-- FHIR R4 Structures -->
    <dependency>
        <groupId>ca.uhn.hapi.fhir</groupId>
        <artifactId>hapi-fhir-structures-r4</artifactId>
        <version>${hapi.fhir.version}</version>
    </dependency>

    <!-- HAPI FHIR Client -->
    <dependency>
        <groupId>ca.uhn.hapi.fhir</groupId>
        <artifactId>hapi-fhir-client</artifactId>
        <version>${hapi.fhir.version}</version>
    </dependency>

    <!-- HAPI FHIR Validation -->
    <dependency>
        <groupId>ca.uhn.hapi.fhir</groupId>
        <artifactId>hapi-fhir-validation</artifactId>
        <version>${hapi.fhir.version}</version>
    </dependency>

    <!-- HAPI FHIR Validation Resources (for R4) -->
    <dependency>
        <groupId>ca.uhn.hapi.fhir</groupId>
        <artifactId>hapi-fhir-validation-resources-r4</artifactId>
        <version>${hapi.fhir.version}</version>
    </dependency>

    <!-- Apache Camel FHIR Component -->
    <dependency>
        <groupId>org.apache.camel</groupId>
        <artifactId>camel-fhir</artifactId>
        <version>${apache.camel.version}</version>
    </dependency>

    <!-- Apache Camel Core -->
    <dependency>
        <groupId>org.apache.camel</groupId>
        <artifactId>camel-core</artifactId>
        <version>${apache.camel.version}</version>
    </dependency>

    <!-- SLF4J Logging -->
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-api</artifactId>
        <version>2.0.9</version>
    </dependency>

    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-classic</artifactId>
        <version>1.4.11</version>
    </dependency>
</dependencies>

Gradle Dependencies (Alternative)

Gradle offers an alternative to Maven with a more concise syntax and flexible build configuration. The dependencies remain the same, but the declaration format differs. Gradle’s Kotlin or Groovy DSL provides powerful scripting capabilities for complex build requirements, making it popular in modern Java projects.

If you prefer Gradle, use this configuration:

// build.gradle
plugins {
    id 'java'
    id 'application'
}

java {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}

ext {
    hapiFhirVersion = '6.10.0'
    apacheCamelVersion = '4.0.3'
}

dependencies {
    implementation "ca.uhn.hapi.fhir:hapi-fhir-base:${hapiFhirVersion}"
    implementation "ca.uhn.hapi.fhir:hapi-fhir-structures-r4:${hapiFhirVersion}"
    implementation "ca.uhn.hapi.fhir:hapi-fhir-client:${hapiFhirVersion}"
    implementation "ca.uhn.hapi.fhir:hapi-fhir-validation:${hapiFhirVersion}"
    implementation "ca.uhn.hapi.fhir:hapi-fhir-validation-resources-r4:${hapiFhirVersion}"

    implementation "org.apache.camel:camel-fhir:${apacheCamelVersion}"
    implementation "org.apache.camel:camel-core:${apacheCamelVersion}"

    implementation 'org.slf4j:slf4j-api:2.0.9'
    implementation 'ch.qos.logback:logback-classic:1.4.11'

    testImplementation 'junit:junit:4.13.2'
}

Project Structure

A well-organized project structure improves maintainability and helps team members navigate the codebase efficiently. Separating concerns into distinct packages (client, resources, validation) follows Java best practices and makes testing easier. This structure also aligns with common enterprise patterns for healthcare integration projects.

Organize your FHIR project with this recommended structure:

fhir-tutorial/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/
│   │   │       └── healthcare/
│   │   │           └── fhir/
│   │   │               ├── client/
│   │   │               │   ├── FhirClientExample.java
│   │   │               │   └── FhirClientFactory.java
│   │   │               ├── resources/
│   │   │               │   ├── PatientExample.java
│   │   │               │   └── ObservationExample.java
│   │   │               ├── camel/
│   │   │               │   └── FhirCamelRoutes.java
│   │   │               └── validation/
│   │   │                   └── FhirValidationExample.java
│   │   └── resources/
│   │       ├── logback.xml
│   │       └── application.properties
│   └── test/
│       └── java/
└── pom.xml

Setting Up Logging

Proper logging is essential for debugging FHIR operations and monitoring production systems. HAPI FHIR uses SLF4J for logging, allowing you to choose your preferred logging implementation. Logback is recommended for its performance and flexibility. Configure appropriate log levels for development (DEBUG) and production (INFO or WARN) to balance visibility with performance.

Create src/main/resources/logback.xml for proper logging:

<configuration>
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <logger name="ca.uhn.fhir" level="INFO"/>
    <logger name="org.apache.camel" level="INFO"/>

    <root level="INFO">
        <appender-ref ref="STDOUT" />
    </root>
</configuration>

Running a Local FHIR Server

A local FHIR server provides a safe environment for development and testing without affecting production data. Docker makes it easy to spin up a fully functional HAPI FHIR server in seconds. This isolated environment is perfect for integration testing, learning FHIR operations, and validating your code before deployment.

For development and testing, you can run a local HAPI FHIR server using Docker:

docker run -p 8080:8080 hapiproject/hapi:latest

This gives you a fully functional FHIR R4 server at http://localhost:8080/fhir.

Verifying Your Setup

Before diving into complex FHIR operations, verify that your development environment is correctly configured. This simple test class creates a FhirContext, builds a basic Patient resource, and serializes it to JSON. If this runs successfully, all your dependencies are properly configured and you are ready to build FHIR applications.

Create a simple test class to verify everything is working:

import ca.uhn.fhir.context.FhirContext;
import org.hl7.fhir.r4.model.Patient;

public class SetupVerification {
    public static void main(String[] args) {
        // Create FHIR context
        FhirContext ctx = FhirContext.forR4();

        // Create a simple patient
        Patient patient = new Patient();
        patient.addName().setFamily("Test").addGiven("Setup");

        // Serialize to JSON
        String json = ctx.newJsonParser()
            .setPrettyPrint(true)
            .encodeResourceToString(patient);

        System.out.println("Setup successful! Sample patient:");
        System.out.println(json);
    }
}

If this runs without errors and prints a JSON patient, your environment is ready!

Get started with FHIR development with these detailed setup guides:

FHIR Programming using Java HAPI - Setting Up Your Environment - Complete Java environment setup
FHIR Programming using .NET - Setting Up Your Environment - .NET development setup
FHIR .NET - Introduction to Libraries - Overview of .NET FHIR libraries
Basics of FHIR - Understanding FHIR fundamentals before coding

Quiz: Setting Up Your Development Environment

Question 1 of 4