James Agnew

# HAPI FHIR Changelog

## 0.9 TBA

Support for DSTU2 features introduced: New Bundle encoding style, as well as new extension encoding in JSON. (add)
Library now checks if custom resource types can be instantiated on startup (e.g. because they don't have a no-argument constructor) in order to avoid failing later (add)
<<<<<<< HEAD Bump a few dependency JARs to the latest versions in Maven POM: <ul> <li>SLF4j (in base module) - Bumped to 1.7.9</li> <li>Apache HTTPClient (in base module) - Bumped to 4.3.6</li> <li>Hibernate (in JPA module) - Bumped to 4.3.7</li> </ul> ======= IdDt failed to recognize local identifiers containing fragments that look like real identifiers as being local identifiers even though they started with '#'. For example, a local resource reference of "#aa/_history/aa" would be incorrectly parsed as a non-local reference. Thanks to Mohammad Jafari for reporting! >>>>>>> 31d61100db41590b9760daf9e0942ad553ff69e2 (fix, 67) (add)

## 0.8 2014-Dec-17

<b>API CHANGE:</b> The "FHIR structures" for DSTU1 (the classes which model the resources and composite datatypes) have been moved out of the core JAR into their own JAR, in order to allow support for DEV resources, and DSTU2 resources when thast version is finalized. See <a href="./doc_upgrading.html">upgrading</a> for more information. (add)
<b>Deprocated API Removal</b>: The following classes (which were deprocated previously) have now been removed: <ul> <li><b>ISecurityManager</b>: If you are using this class, the same functionality is available through the more general purpose <a href="http://jamesagnew.github.io/hapi-fhir/doc_rest_server_interceptor.html">server interceptor</a> capabilities. <li><b>CodingListParam</b>: This class was made redundant by the <a href="http://jamesagnew.github.io/hapi-fhir/apidocs/ca/uhn/fhir/rest/param/TokenOrListParam.html">TokenOrListParam</a> class, which can be used in its place. </ul> (fix)
<b>API Change</b>: The IResource#getResourceMetadata() method has been changed from returning <code>Map&lt;ResourceMetadataKeyEnum&lt;?&gt;, Object&gt;<code> to returning a new type called <code>ResourceMetadataMap</code>. This new type implements <code>Map&lt;ResourceMetadataKeyEnum&lt;?&gt;, Object&gt;<code> itself, so this change should not break existing code, but may require a clean build in order to run correctly. (add)
Profile generation on the server was not working due to IdDt being incorrectly used. Thanks to Bill de Beaubien for the pull request! (add, 38, wdebeau1)
Profiles did not generate correctly if a resource definition class had a defined extension which was of a composite type. Thanks to Bill de Beaubien for the pull request! (add, 42, wdebeau1)
Remove unnecessary IOException from narrative generator API. Thanks to Petro Mykhailysyn for the pull request! (add, 44, petromykhailysyn)
Introduced a new <code>@ProvidesResources</code> annotation which can be added to resource provider and servers to allow them to declare additional resource classes they are able to serve. This is useful if you have a server which can serve up multiple classes for the same resource type (e.g. a server that sometimes returns a default Patient, but sometimes uses a custom subclass). Thanks to Bill de Beaubien for the pull request! (add, 48, wdebeau1)
Introduced a new <code>@Destroy</code> annotation which can be added to a resource provider method. This method will be called by the server when it is being closed/destroyed (e.g. when the application is being undeployed, the container is being shut down, etc.) Thanks to Bill de Beaubien for the pull request! (add, 49, wdebeau1)
Add a new method handleException to the server interceptor framework which allows interceptors to be notified of any exceptions and runtime errors within server methods. Interceptors may optionally also override the default error handling behaviour of the RestfulServer. (add)
Add constants to BaseResource for the "_id" search parameter which all resources should support. (add, wdebeau1)
DateRangeParam parameters on the server now return correct <code>getLowerBoundAsInstant()</code> and <code>getUpperBoundAsInstant()</code> values if a single unqualified value is passed in. For example, if a query containing <code>&birthdate=2012-10-01</code> is received, previously these two methods would both return the same value, but with this fix <code>getUpperBoundAsInstant()</code> now returns the instant at 23:59:59.9999. (fix)
Resource fields with a type of "*" (or Any) sometimes failed to parse if a value type of "code" was used. Thanks to Bill de Beaubien for reporting! (fix)
Remove dependency on JAXB libraries, which were used to parse and encode dates and times (even in the JSON parser). JAXB is built in to most JDKs but the version bundled with IBM's JDK is flaky and resulted in a number of problems when deploying to Websphere. (add, lmds)
Primitive datatypes now preserve their original string value when parsing resources, as well as containing the "parsed value". For instance, a DecimalDt field value of <code>1.0000</code> will be parsed into the corresponding decimal value, but will also retain the original value with the corresponding level of precision. This allows vadliator rules to be applied to original values as received "over the wire", such as well formatted but invalid dates, e.g. "2001-15-01". Thanks to Joe Athman for reporting and helping to come up with a fix! (fix, 50, jjathman)
When using Generic Client, if performing a create or update operation using a String as the resource body, the client will auto-detect the FHIR encoding style and send an appropriate Content-Type header. (add)
JPA module (and public HAPI-FHIR test server) were unable to process resource types where at least one search parameter has no path specified. These now correctly save (although the server does not yet process these params, and it should). Thanks to GitHub user shvoidlee for reporting and help with analysis! (fix, 52)
Generic/Fluent Client "create" and "update" method requests were not setting a content type header (fix)
DateDt left precision value as null in the constructor DateDt(Date). (add, 53, petromykhailysyn)
RESTful server now doesn't overwrite resource IDs if they are absolute. In other words, if a server's Resource Provider returns a resource with ID "Patient/123" it will be translated to "[base url]/Patient/123" but if the RP returns ID "http://foo/Patient/123" the ID will be returned exactly as is. Thanks to Bill de Beaubien for the suggestion! (fix)
JPA module Transaction operation was not correctly replacing logical IDs beginning with "cid:" with server assigned IDs, as required by the specification. (fix, 55)
FhirTerser did not visit or find children in contained resources when searching a resource. This caused server implementations to not always return contained resources when they are included with a resource being returned. (fix, tahurac)
Add a method String IResource#getResourceName() which returns the name of the resource in question (e.g. "Patient", or "Observation"). This is intended as a convenience to users. (add, lmds)
Do not strip version from resource references in resources returned from server search methods. Thanks to Bill de Beaubien for reporting! (fix)
Correct an issue with the validator where changes to the underlying OperationOutcome produced by a validation cycle cause the validation results to be incorrect. (fix, 54, jjathman)
Client interceptors registered to an interface based client instance were applied to other client instances for the same client interface as well. (Issue did not affect generic/fluent clients) (fix)
DateDt, DateTimeDt and types InstantDt types now do not throw an exception if they are used to parse a value with the wrong level of precision for the given type but do throw an exception if the wrong level of precision is passed into their constructors.<br/><br/> This means that HAPI FHIR can now successfully parse resources from external sources that have the wrong level of precision, but will generate a validation error if the resource is validated. Thanks to Alexander Kley for the suggestion! (fix, 57)
Encoding a Binary resource without a content type set should not result in a NullPointerException. Thanks to Alexander Kley for reporting! (fix)
Server gives a more helpful error message if multiple IResourceProvider implementations are provided for the same resource type. Thanks to wanghaisheng for the idea! (add)
Bring DSTU1 resource definitions up to version 0.0.82-2929<br/> Bring DEV resource definitions up to 0.4.0-3775<br/> Thanks to crinacimpian for reporting! (add, 61)
JPA server did not correctly process _include requests if included resources were present with a non-numeric identifier. Thanks to Bill de Beaubien for reporting! (add, 62)
Client requests which include a resource/bundle body (e.g. create, update, transaction) were not including a charset in the content type header, leading to servers incorrectly assuming ISO-8859/1. Thanks to shvoidlee for reporting! (fix, 60)
Clean up the way that Profile resources are automatically exported by the server for custom resource profile classes. See the <a href="http://jamesagnew.github.io/hapi-fhir/apidocs/ca/uhn/fhir/model/api/annotation/ResourceDef.html">@ResourceDef</a> JavaDoc for information on how this works. (fix, 59, wdebeau1)

## 0.7 2014-Oct-23

<b>API CHANGE:</b> The TagList class previously implemented ArrayList semantics, but this has been replaced with LinkedHashMap semantics. This means that the list of tags will no longer accept duplicate tags, but that tag order will still be preserved. Thanks to Bill de Beaubien for reporting! (add, 30)
Server was incorrectly including contained resources being returned as both contained resources, and as top-level resources in the returned bundle for search operations. Thanks to Bill de Beaubien for reporting! This also fixes Issue #20, thanks to lephty for reporting! (fix, 33)
Documentation fixes (add, suranga)
Add a collection of new methods on the generic client which support the <b><a href="./apidocs/ca/uhn/fhir/rest/client/IGenericClient.html#read(java.lang.Class,%20ca.uhn.fhir.model.primitive.UriDt)">read</a></b>, <b><a href="./apidocs/ca/uhn/fhir/rest/client/IGenericClient.html#vread(java.lang.Class,%20ca.uhn.fhir.model.primitive.UriDt)">read</a></b>, and <b><a href="./apidocs/ca/uhn/fhir/rest/client/IGenericClient.html#search(java.lang.Class,%20ca.uhn.fhir.model.primitive.UriDt)">search</a></b> operations using an absolute URL. This allows developers to perform these operations using URLs they obtained from other sources (or external resource references within resources). In addition, the existing read/vread operations will now access absolute URL references if they are passed in. Thanks to Doug Martin of the Regenstrief Center for Biomedical Informatics for contributing this implementation! (add, dougmartin)
Server implementation was not correctly figuring out its own FHIR Base URL when deployed on Amazon Web Service server. Thanks to Jeffrey Ting and Bill De Beaubien of Systems Made Simple for their help in figuring out this issue! (fix)
XML Parser failed to encode fields with both a resource reference child and a primitive type child. Thanks to Jeffrey Ting and Bill De Beaubien of Systems Made Simple for their help in figuring out this issue! (fix)
HAPI now runs successfully on Servlet 2.5 containers (such as Tomcat 6). Thanks to Bernard Gitaadji for reporting and diagnosing the issue! (fix)
Summary (in the bundle entry) is now encoded by the XML and JSON parsers if supplied. Thanks to David Hay of Orion Health for reporting this! (fix)
Conformance profiles which are automatically generated by the server were missing a few mandatory elements, which meant that the profile did not correctly validate. Thanks to Bill de Beaubien of Systems Made Simple for reporting this! (fix, 24)
XHTML (in narratives) containing escapable characters (e.g. < or ") will now always have those characters escaped properly in encoded messages. (fix)
Resources containing entities which are not valid in basic XML (e.g. &sect;) will have those entities converted to their equivalent unicode characters when resources are encoded, since FHIR does not allow extended entities in resource instances. (fix)
Add a new client interceptor which adds HTTP Authorization Bearer Tokens (for use with OAUTH2 servers) to client requests. (add)
Add phloc-commons dependency explicitly, which resolves an issue building HAPI from source on some platforms. Thanks to Odysseas Pentakalos for the patch! (fix)
HAPI now logs a single line indicating the StAX implementation being used upon the first time an XML parser is created. (add)
Update methods on the server did not return a "content-location" header, but only a "location" header. Both are required according to the FHIR specification. Thanks to Bill de Beaubien of Systems Made Simple for reporting this! (fix)
Parser failed to correctly read contained Binary resources. Thanks to Alexander Kley for the patch! (fix, 26, akley)
Calling encode multiple times on a resource with contained resources caused the contained resources to be re-added (and the actual message to grow) with each encode pass. Thanks to Alexander Kley for the test case! (fix, 29, akley)
JSON-encoded contained resources with the incorrect "_id" element (which should be "id", but some incorrect examples exist on the FHIR specification) now parse correctly. In other words, HAPI previously only accepted the correct "id" element, but now it also accepts the incorrect "_id" element just to be more lenient. (fix)
Several unit tests failed on Windows (or any platform with non UTF-8 default encoding). This may have also caused resource validation to fail occasionally on these platforms as well. Thanks to Bill de Beaubien for reporting! (fix)
toString() method on TokenParam was incorrectly showing the system as the value. Thanks to Bill de Beaubien for reporting! (fix)
Documentation on contained resources contained a typo and did not actually produce contained resources. Thanks to David Hay of Orion Health for reporting! (update)
Add a <a href="https://www.vagrantup.com/">Vagrant</a> based environment (basically a fully built, self contained development environment) for trying out the HAPI server modules. Thanks to Preston Lee for the pull request, and for offering to maintain this! (add, 31, preston)
Change validation API so that it uses a return type instead of exceptions to communicate validation failures. Thanks to Joe Athman for the pull request! (add, 32, jjathman)
Add a client interceptor which adds an HTTP cookie to each client request. Thanks to Petro Mykhailysyn for the pull request! (add, 35, petromykhailysyn)

## 0.6 2014-Sep-08

This release brings a number of new features and bug fixes!

Add server interceptor framework, and new interceptor for logging incoming requests. (add)
Add server validation framework for validating resources against the FHIR schemas and schematrons (add)
Tester UI created double _format and _pretty param entries in searches. Thanks to Gered King of University Health Network for reporting! (fix)
Create method was incorrectly returning an HTTP 204 on sucessful completion, but should be returning an HTTP 200 per the FHIR specification. Thanks to wanghaisheng for reporting! (fix, 4)
FHIR Tester UI now correctly sends UTF-8 charset in responses so that message payloads containing non US-ASCII characters will correctly display in the browser (fix)
JSON parser was incorrectly encoding extensions on composite elements outside the element itself (as is done correctly for non-composite elements) instead of inside of them. Thanks to David Hay of Orion for reporting this! (fix)
Contained/included resource instances received by a client are now automatically added to any ResourceReferenceDt instancea in other resources which reference them. (add)
Add documentation on how to use eBay CORS Filter to support Cross Origin Resource Sharing (CORS) to server. CORS support that was built in to the server itself has been removed, as it did not work correctly (and was reinventing a wheel that others have done a great job inventing). Thanks to Peter Bernhardt of Relay Health for all the assistance in testing this! (add)
IResource interface did not expose the getLanguage/setLanguage methods from BaseResource, so the resource language was difficult to access. (fix)
JSON Parser now gives a more friendly error message if it tries to parse JSON with invalid use of single quotes (fix)
Transaction server method is now allowed to return an OperationOutcome in addition to the incoming resources. The public test server now does this in order to return status information about the transaction processing. (add)
Update method in the server can now flag (via a field on the MethodOutcome object being returned) that the result was actually a creation, and Create method can indicate that it was actually an update. This has no effect other than to switch between the HTTP 200 and HTTP 201 status codes on the response, but this may be useful in some circumstances. (add)
Annotation client search methods with a specific resource type (e.g. List<Patient> search()) won't return any resources that aren't of the correct type that are received in a response bundle (generally these are referenced resources, so they are populated in the reference fields instead). Thanks to Tahura Chaudhry of University Health Network for the unit test! (fix, tahurac)
Added narrative generator template for OperationOutcome resource (add)
Date/time types did not correctly parse values in the format "yyyymmdd" (although the FHIR-defined format is "yyyy-mm-dd" anyhow, and this is correctly handled). Thanks to Jeffrey Ting of Systems Made Simple for reporting! (fix)
Server search method for an unnamed query gets called if the client requests a named query with the same parameter list. Thanks to Neal Acharya of University Health Network for reporting! (fix)
Category header (for tags) is correctly read in client for "read" operation (fix)
Transaction method in server can now have parameter type Bundle instead of List<IResource> (add)
HAPI parsers now use field access to get/set values instead of method accessors and mutators. This should give a small performance boost. (add)
JSON parser encodes resource references incorrectly, using the name "resource" instead of the name "reference" for the actual reference. Thanks to Ricky Nguyen for reporting and tracking down the issue! (fix)
Rename NotImpementedException to NotImplementedException (to correct typo) (fix)
Server setUseBrowserFriendlyContentType setting also respected for errors (e.g. OperationOutcome with 4xx/5xx status) (fix)
Fix performance issue in date/time datatypes where pattern matchers were not static (fix)
Server now gives a more helpful error message if a @Read method has a search parameter (which is invalid, but previously lead to a very unhelpful error message). Thanks to Tahura Chaudhry of UHN for reporting! (fix)
Resource of type "List" failed to parse from a bundle correctly. Thanks to David Hay of Orion Health for reporting! (fix)
QuantityParam correctly encodes approximate (~) prefix to values (fix)
If a server defines a method with parameter "_id", incoming search requests for that method may get delegated to the wrong method. Thanks to Neal Acharya for reporting! (fix, 14)
SecurityEvent.Object structural element has been renamed to SecurityEvent.ObjectElement to avoid conflicting names with the java Object class. Thanks to Laurie Macdougall-Sookraj of UHN for reporting! (add)
Text/narrative blocks that were created with a non-empty namespace prefix (e.g. <xhtml:div xmlns:xhtml="...">...</xhtml:div>) failed to encode correctly (prefix was missing in encoded resource) (fix)
Resource references previously encoded their children (display and reference) in the wrong order so references with both would fail schema validation. (fix)
SecurityEvent resource's enums now use friendly enum names instead of the unfriendly numeric code values. Thanks to Laurie MacDougall-Sookraj of UHN for the suggestion! (add)

## 0.5 2014-Jul-30

HAPI has a number of RESTful method parameter types that have similar but not identical purposes and confusing names. A cleanup has been undertaken to clean this up. This means that a number of existing classes have been deprocated in favour of new naming schemes. <br/><br/> All annotation-based clients and all server search method parameters are now named (type)Param, for example: StringParam, TokenParam, etc. <br/><br/> All generic/fluent client method parameters are now named (type)ClientParam, for example: StringClientParam, TokenClientParam, etc. <br/><br/> All renamed classes have been retained and deprocated, so this change should not cause any issues for existing applications but those applications should be refactored to use the new parameters when possible. (add)
Allow server methods to return wildcard generic types (e.g. List<? extends IResource>) (add)
Search parameters are not properly escaped and unescaped. E.g. for a token parameter such as "&identifier=system|codepart1\|codepart2" (add)
Add support for OPTIONS verb (which returns the server conformance statement) (add)
Add support for CORS headers in server (add)
Bump SLF4j dependency to latest version (1.7.7) (add)
Add interceptor framework for clients (annotation based and generic), and add interceptors for configurable logging, capturing requests and responses, and HTTP basic auth. (add)
Transaction client invocations with XML encoding were using the wrong content type ("application/xml+fhir" instead of the correct "application/atom+xml"). Thanks to David Hay of Orion Health for surfacing this one! (fix)
Bundle entries now support a link type of "search". Thanks to David Hay for the suggestion! (add)
If a client receives a non 2xx response (e.g. HTTP 500) and the response body is a text/plain message or an OperationOutcome resource, include the message in the exception message so that it will be more conveniently displayed in logs and other places. Thanks to Neal Acharya for the suggestion! (add, 1)
Read invocations in the client now process the "Content-Location" header and use it to populate the ID of the returned resource. Thanks to Neal Acharya for the suggestion! (add, 2)
Fix issue where vread invocations on server incorrectly get routed to instance history method if one is defined. Thanks to Neal Acharya from UHN for surfacing this one! (fix, 3)
Binary reads on a server not include the Content-Disposition header, to prevent HTML in binary blobs from being used for nefarious purposes. See <a href="http://gforge.hl7.org/gf/project/fhir/tracker/?action=TrackerItemEdit&tracker_id=677&tracker_item_id=3298">FHIR Tracker Bug 3298</a> for more information. (add)
Support has been added for using an HTTP proxy for outgoing requests. (add)
Fix: Primitive extensions declared against custom resource types are encoded even if they have no value. Thanks to David Hay of Orion for reporting this! (fix)
Fix: RESTful server deployed to a location where the URL to access it contained a space (e.g. a WAR file with a space in the name) failed to work correctly. Thanks to David Hay of Orion for reporting this! (fix)

## 0.4 2014-Jul-13

<b>BREAKING CHANGE:</b>: IdDt has been modified so that it contains a partial or complete resource identity. Previously it contained only the simple alphanumeric id of the resource (the part at the end of the "read" URL for that resource) but it can now contain a complete URL or even a partial URL (e.g. "Patient/123") and can optionally contain a version (e.g. "Patient/123/_history/456"). New methods have been added to this datatype which provide just the numeric portion. See the JavaDoc for more information. (add)
<b>API CHANGE:</b>: Most elements in the HAPI FHIR model contain a getId() and setId() method. This method is confusing because it is only actually used for IDREF elements (which are rare) but its name makes it easy to confuse with more important identifiers. For this reason, these methods have been deprocated and replaced with get/setElementSpecificId() methods. The old methods will be removed at some point. Resource types are unchanged and retain their get/setId methods. (add)
Allow use of QuantityDt as a service parameter to support the "quantity" type. Previously QuantityDt did not implement IQueryParameterType so it was not valid, and there was no way to support quantity search parameters on the server (e.g. Observation.value-quantity) (add)
Introduce StringParameter type which can be used as a RESTful operation search parameter type. StringParameter allows ":exact" matches to be specified in clients, and handled in servers. (add)
Parsers (XML/JSON) now support deleted entries in bundles (add)
Transaction method now supported in servers (add)
Support for Binary resources added (in servers, clients, parsers, etc.) (add)
Support for Query resources fixed (in parser) (fix)
Nested contained resources (e.g. encoding a resource with a contained resource that itself contains a resource) now parse and encode correctly, meaning that all contained resources are placed in the "contained" element of the root resource, and the parser looks in the root resource for all container levels when stitching contained resources back together. (fix)
Server methods with @Include parameter would sometimes fail when no _include was actually specified in query strings. (fix)
Client requests for IdentifierDt types (such as Patient.identifier) did not create the correct query string if the system is null. (fix)
Add support for paging responses from RESTful servers. (add)
Don't fail on narrative blocks in JSON resources with only an XML declaration but no content (these are produced by the Health Intersections server) (fix)
Server now automatically compresses responses if the client indicates support (fix)
Server failed to support optional parameters when type is String and :exact qualifier is used (fix)
Read method in client correctly populated resource ID in returned object (fix)
Support added for deleted-entry by/name, by/email, and comment from Tombstones spec (add)

## 0.3 2014-May-12

This release corrects lots of bugs and introduces the fluent client mode