<?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>Introduction</title>
		<author email="jamesagnew@users.sourceforge.net">James Agnew</author>
	</properties>

	<body>

		<!-- The body of the document contains a number of sections -->
		<section name="Introduction to HAPI FHIR">
			
			<p>
				The HAPI FHIR library is an implementation of the 
				<a href="http://hl7.org/implement/standards/fhir/">HL7 FHIR specification</a>
				for Java. Explaining what FHIR is would be beyond the scope of this documentation,
				so if you have not previously worked with FHIR, the specification is a good place to
				start. This is often not actually the case when discussing messaging protocols, but
				in this case it is so: The FHIR specification is designed to be readable and
				implementable, and is filled with good information.
			</p>
			
			<p>
				Part of the key to why FHIR is a good specification is the fact that its design
				is based on the design of other successful APIs (in particular, the FHIR designers
				often reference the Highrise API as a key influence in the design of the spec.)
			</p>
			
			<p>
				HAPI FHIR is based on the same principle, but applied to the Java implementation: We
				have based the design of this API on the JAXB and JAX-WS APIs, which we consider to be
				very well thought-out, and very usable APIs. This does <b>not</b> mean that HAPI-FHIR
				actually uses these two APIs however, or that HAPI-FHIR is in any way compliant with
				JAXB (<a href="https://jcp.org/en/jsr/detail?id=222">JSR222</a>) or JAX-WS 
				(<a href="https://jcp.org/en/jsr/detail?id=222">JSR224</a>), only that we have tried 
				to emluate the easy-to-use, but flexible design of these specifications. 
			</p>
						
		</section>

		<section name="Getting Started">
			
			<p>
				To get started with HAPI FHIR, first download a copy and add it
				to your project. See the <a href="./download.html">Download Page</a>
				for instructions.
			</p>			
			
			<subsection name="A Note on FHIR Versions">
			
				<p>
					Before discussing HAPI itself, a quick word about FHIR versions. FHIR 
					is not yet a finalized "1.0" standard. It is currently in the DSTU phase,
					which means that it is changing in subtle and non-subtle ways between releases.
					Before trying to use FHIR, you will need to determine which version of FHIR
					you want to support in your application. Typically this would be the
					latest version, but if you are looking to interact with an application which 
					already exists, you will probably want to implement the same version implemented
					by that application.
				</p>
				<p>
					See the
					<a href="doc_dstu2.html">note on DSTU2 support</a>
					for more information on supporting multiple versions of FHIR.
				</p>
			
			</subsection>
			
			<subsection name="Introducing the FHIR Context">

				<p>
					HAPI defines model classes for every resource type and datatype defined by the FHIR specification.
					For example, here is the <a href="./apidocs/ca/uhn/fhir/model/dstu/resource/Patient.html">Patient</a>
					resource specification. If you browse the JavaDoc you will see getters and setters for the
					various properties that make up a Patient resource.
				</p>

				<p>
					We will come back to how to interact with these objects in a moment, but first 
					we need to create a 
					<a href="./apidocs/ca/uhn/fhir/context/FhirContext.html">FhirContext</a>. 
					FhirContext is the starting point to using HAPI, and acts as a factory for most
					other parts of the API as well as a runtime cache of information that HAPI needs
					to operate. Users of the JAXB API may find this class to be similar in purpose to
					the 
					<a href="http://docs.oracle.com/javaee/5/api/javax/xml/bind/JAXBContext.html">JAXBContext</a>
					class from that API.
				</p>
	
				<p>
					Creating a FhirContext is as simple as instantiating one. A FhirContext instance is
					specific to a given version of the FHIR specification, so it is recommended that you
					use one of the factory methods indicating the FHIR version you wish to support in your
					application, as shown in the following snippet:
				</p>
	
				<macro name="snippet">
					<param name="id" value="creatingContext" />
					<param name="file" value="examples/src/main/java/example/FhirContextIntro.java" />
				</macro>

			</subsection>
			
			<subsection name="Parsing a resource from a String">
								
				<p>
					This 
					<a href="./apidocs/ca/uhn/fhir/parser/IParser.html">Parser instance</a> 
					can then be used to parse messages. Note that you may use the context to
					create as many parsers are you want. 
				</p>
				
				<p>
					<b>Performance tip: </b>
					The FhirContext is an expensive object to create, so you should try to create
					it once and keep it around during the life of your application. Parsers, on
					the other hand, are	very lightweight and do not need to be reused.
				</p>
				
				<macro name="snippet">
					<param name="id" value="parseMsg" />
					<param name="file" value="examples/src/main/java/example/FhirContextIntro.java" />
				</macro>

			</subsection>

			<subsection name="Encoding a Resource to a String">
								
				<p>
					The parser can also be used to encode a resource (which you can populate
					with your own values) just as easily. 
				</p>
				
				<macro name="snippet">
					<param name="id" value="encodeMsg" />
					<param name="file" value="examples/src/main/java/example/FhirContextIntro.java" />
				</macro>
				
				<!-- ****** The section below on fluent references the snippet above
				     ****** so be careful about any reordering! -->

				<p>
					This code gives the following output:
				</p>

				<source><![CDATA[<Patient xmlns="http://hl7.org/fhir">
   <identifier>
      <system value="http://example.com/fictitious-mrns"/>
      <value value="MRN001"/>
   </identifier>
   <name>
      <use value="official"/>
      <family value="Tester"/>
      <given value="John"/>
      <given value="Q"/>
   </name>
</Patient>]]></source>

			</subsection>

			<subsection name="Fluent Programming">
			
				<p>
					Much of the HAPI FHIR API is designed using a fluent style,
					where method calls can be chained in a natural way. This
					leads to tighter and easier-to-read code.
				</p>
				
				<p>
					The following snippet is functionally identical to the
					example above:
				</p>

				<macro name="snippet">
					<param name="id" value="encodeMsgFluent" />
					<param name="file" value="examples/src/main/java/example/FhirContextIntro.java" />
				</macro>
			
			</subsection>
			
			<subsection name="JSON Encoding">
								
				<p>
					JSON parsing/encoding is also supported. 
				</p>
				
				<macro name="snippet">
					<param name="id" value="encodeMsgJson" />
					<param name="file" value="examples/src/main/java/example/FhirContextIntro.java" />
				</macro>

				<p>
					This code gives the following output:
				</p>

				<source><![CDATA[{
    "resourceType":"Patient",
    "identifier":[
        {
            "system":"http://example.com/fictitious-mrns",
            "value":"MRN001"
        }
    ],
    "name":[
        {
            "use":"official",
            "family":[
                "Tester"
            ],
            "given":[
                "John",
                "Q"
            ]
        }
    ]
}]]></source>

			</subsection>

		</section>

	</body>

</document>
