2.1Parsers and Serializers

 

HAPI FHIR has built-in support for the FHIR JSON and XML encoding formats.

A built in parser can be used to convert HAPI FHIR Java objects into a serialized form, and to parse serialized data into Java objects. Note that unlike some other frameworks, HAPI FHIR does not have separate parsers and serializers. Both of these functions are handled by a single object called the Parser.

2.1.1Parsing (aka Deserializing)

 

As with many parts of the HAPI FHIR API, parsing begins with a FhirContext object. The FhirContext can be used to request an IParser for your chosen encoding style that is then used to parse.

// Create a FHIR context
FhirContext ctx = FhirContext.forR4();

// The following example is a simple serialized Patient resource to parse
String input = "{" +
   "\"resourceType\" : \"Patient\"," +
   "  \"name\" : [{" +
   "    \"family\": \"Simpson\"" +
   "  }]" +
   "}";

// Instantiate a new parser
IParser parser = ctx.newJsonParser();

// Parse it
Patient parsed = parser.parseResource(Patient.class, input);
System.out.println(parsed.getName().get(0).getFamily());

2.1.2Encoding (aka Serializing)

 

As with many parts of the HAPI FHIR API, parsing begins with a FhirContext object. The FhirContext can be used to request an IParser for your chosen encoding style that is then used to serialize.

The following example shows a JSON Parser being used to serialize a FHIR resource.

// Create a FHIR context
FhirContext ctx = FhirContext.forR4();

// Create a Patient resource to serialize
Patient patient = new Patient();
patient.addName().setFamily("Simpson").addGiven("James");

// Instantiate a new JSON parser
IParser parser = ctx.newJsonParser();

// Serialize it
String serialized = parser.encodeResourceToString(patient);
System.out.println(serialized);

// Using XML instead
serialized = ctx.newXmlParser().encodeResourceToString(patient);
System.out.println(serialized);

Pretty Printing

By default, the parser will output in condensed form, with no newlines or indenting. This is good for machine-to-machine communication since it reduces the amount of data to be transferred but it is harder to read. To enable pretty printed output:

// Create a parser
IParser parser = ctx.newJsonParser();

// Indent the output
parser.setPrettyPrint(true);

// Serialize it
String serialized = parser.encodeResourceToString(patient);
System.out.println(serialized);

// You can also chain these statements together
ctx.newJsonParser().setPrettyPrint(true).encodeResourceToString(patient);

Encoding Configuration

There are plenty of other options too that can be used to control the output by the parser. A few examples are shown below. See the IParser JavaDoc for more information.

// Create a parser
IParser parser = ctx.newJsonParser();

// Blacklist certain fields from being encoded
parser.setDontEncodeElements(Sets.newHashSet("Patient.identifier", "Patient.active"));

// Don't include resource narratives
parser.setSuppressNarratives(true);

// Use versioned references for these reference elements
parser.setDontStripVersionsFromReferencesAtPaths("Patient.organization");

// Serialize it
String serialized = parser.encodeResourceToString(patient);
System.out.println(serialized);