Site updates

examples/src/main/java/example/ClientTransactionExamples.java

@@ -8,10 +8,12 @@ import ca.uhn.fhir.model.dstu2.resource.Observation;
 import ca.uhn.fhir.model.dstu2.resource.Patient;
 import ca.uhn.fhir.model.dstu2.valueset.AdministrativeGenderEnum;
 import ca.uhn.fhir.model.dstu2.valueset.BundleTypeEnum;
+import ca.uhn.fhir.model.dstu2.valueset.HTTPVerbEnum;
 import ca.uhn.fhir.model.dstu2.valueset.ObservationStatusEnum;
 import ca.uhn.fhir.model.primitive.IdDt;
+import ca.uhn.fhir.rest.client.IGenericClient;
 
-public class TransactionClientTest {
+public class ClientTransactionExamples {
 
    public static void main(String[] args) {
       conditionalCreate();
@@ -19,22 +21,25 @@ public class TransactionClientTest {
 
    private static void conditionalCreate() {
       
+      //START SNIPPET: conditional
       // Create a patient object
       Patient patient = new Patient();
-      patient
+      patient.addIdentifier()
-         .addIdentifier()
          .setSystem("http://acme.org/mrns")
          .setValue("12345");
-      patient
+      patient.addName()
-         .addName()
+         .addFamily("Jameson")
-            .addFamily("Jones")
+         .addGiven("J")
-            .addGiven("Johnson");
+         .addGiven("Jonah");
       patient.setGender(AdministrativeGenderEnum.MALE);
       
+      // Give the patient a temporary UUID so that other resources in
+      // the transaction can refer to it
+      patient.setId(IdDt.newRandomUuid());
+      
       // Create an observation object
       Observation observation = new Observation();
       observation.setStatus(ObservationStatusEnum.FINAL);
-      observation.setSubject(new ResourceReferenceDt(patient));
       observation
          .getCode()
             .addCoding()
@@ -48,17 +53,47 @@ public class TransactionClientTest {
             .setSystem("http://unitsofmeasure.org")
             .setCode("10*12/L"));
 
+      // The observation refers to the patient using the ID, which is already
+      // set to a temporary UUID  
+      observation.setSubject(new ResourceReferenceDt(patient.getId().getValue()));
+
+      // Create a bundle that will be used as a transaction
       Bundle bundle = new Bundle();
       bundle.setType(BundleTypeEnum.TRANSACTION);
       
-      patient.setId(IdDt.newRandomUuid());
+      // Add the patient as an entry. This entry is a POST with an 
-      bundle
+      // If-None-Exist header (conditional create) meaning that it
-         .addEntry()
+      // will only be created if there isn't already a Patient with
+      // the identifier 12345
+      bundle.addEntry()
+         .setFullUrl(patient.getId().getValue())
          .setResource(patient)
          .getRequest()
-               .setUrl(patient.getId().getValue());
+            .setUrl("Patient")
+            .setIfNoneExist("Patient?identifier=http://acme.org/mrns|12345")
+            .setMethod(HTTPVerbEnum.POST);
+      
+      // Add the observation. This entry is a POST with no header
+      // (normal create) meaning that it will be created even if
+      // a similar resource already exists.
+      bundle.addEntry()
+         .setResource(observation)
+         .getRequest()
+            .setUrl("Observation")
+            .setMethod(HTTPVerbEnum.POST);
+      
+      // Log the request
+      FhirContext ctx = FhirContext.forDstu2();
+      System.out.println(ctx.newXmlParser().setPrettyPrint(true).encodeResourceToString(bundle));
+      
+      // Create a client and post the transaction to the server
+      IGenericClient client = ctx.newRestfulGenericClient("http://fhirtest.uhn.ca/baseDstu2");
+      Bundle resp = client.transaction().withBundle(bundle).execute();
+
+      // Log the response
+      System.out.println(ctx.newXmlParser().setPrettyPrint(true).encodeResourceToString(resp));
+      //END SNIPPET: conditional
       
-      System.out.println(FhirContext.forDstu2().newXmlParser().setPrettyPrint(true).encodeResourceToString(bundle));
    }
    
 }

src/changes/changes.xml

@@ -221,7 +221,7 @@
 				Add ability for a server REST resource provider @Search method
 				to declare that it should allow even parameters it doesn't 
 				understand.
-			<action>
+			</action>
 		</release>
 		<release version="1.2" date="2015-09-18">
 			<action type="add">

src/site/site.xml

@@ -93,6 +93,7 @@
 				<item name="Annotation Client" href="./doc_rest_client_annotation.html" />
 				<item name="Interceptors (client)" href="./doc_rest_client_interceptor.html"/>
 				<item name="Client HTTP Configuration" href="./doc_rest_client_http_config.html"/>
+				<item name="Client Examples" href="./doc_rest_client_examples.html"/>
 			</item>
 			<item name="RESTful Server" href="./doc_rest_server.html" >
 				<item name="Using RESTful Server" href="./doc_rest_server.html" />

src/site/xdoc/doc_rest_client_examples.xml

@@ -0,0 +1,126 @@
+<?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>RESTful Client Examples</title>
+		<author email="jamesagnew@users.sourceforge.net">James Agnew</author>
+	</properties>
+
+	<body>
+
+		<section name="Client Examples">
+
+			<p>
+				This page contains examples of how to use the client to perform
+				complete tasks. If you have an example you could contribute, we'd
+				love to hear from you!
+			</p>
+
+			<subsection name="Transaction With Placeholder IDs">
+				
+				<p>
+					The following example shows how to post a transaction with two resources,
+					where one resource contains a reference to the other. A temporary ID (a UUID)
+					is used as an ID to refer to, and this ID will be replaced by the server by
+					a permanent ID. 
+				</p>
+				
+				<macro name="snippet">
+					<param name="id" value="conditional" />
+					<param name="file" value="examples/src/main/java/example/ClientTransactionExamples.java" />
+				</macro>
+				
+				<p>
+					This code creates the following transaction bundle:<br/>
+					<source><![CDATA[<Bundle xmlns="http://hl7.org/fhir">
+   <type value="transaction"/>
+   <entry>
+      <fullUrl value="urn:uuid:47709cc7-b3ec-4abc-9d26-3df3d3d57907"/>
+      <resource>
+         <Patient xmlns="http://hl7.org/fhir">
+            <identifier>
+               <system value="http://acme.org/mrns"/>
+               <value value="12345"/>
+            </identifier>
+            <name>
+               <family value="Jameson"/>
+               <given value="J"/>
+               <given value="Jonah"/>
+            </name>
+            <gender value="male"/>
+         </Patient>
+      </resource>
+      <request>
+         <method value="POST"/>
+         <url value="Patient"/>
+         <ifNoneExist value="Patient?identifier=http://acme.org/mrns|12345"/>
+      </request>
+   </entry>
+   <entry>
+      <resource>
+         <Observation xmlns="http://hl7.org/fhir">
+            <status value="final"/>
+            <code>
+               <coding>
+                  <system value="http://loinc.org"/>
+                  <code value="789-8"/>
+                  <display value="Erythrocytes [#/volume] in Blood by Automated count"/>
+               </coding>
+            </code>
+            <subject>
+               <reference value="urn:uuid:47709cc7-b3ec-4abc-9d26-3df3d3d57907"/>
+            </subject>
+            <valueQuantity>
+               <value value="4.12"/>
+               <unit value="10 trillion/L"/>
+               <system value="http://unitsofmeasure.org"/>
+               <code value="10*12/L"/>
+            </valueQuantity>
+         </Observation>
+      </resource>
+      <request>
+         <method value="POST"/>
+         <url value="Observation"/>
+      </request>
+   </entry>
+</Bundle>]]></source>
+				</p>
+				
+				<p>
+					The server responds with the following response. Note that
+					the ID of the already existing patient is returned, and the
+					ID of the newly created Observation is too.<br/>
+					
+					<source><![CDATA[<Bundle xmlns="http://hl7.org/fhir">
+   <id value="dd1f75b8-e472-481e-97b3-c5eebb99a5e0"/>
+   <type value="transaction-response"/>
+   <link>
+      <relation value="self"/>
+      <url value="http://fhirtest.uhn.ca/baseDstu2"/>
+   </link>
+   <entry>
+      <response>
+         <status value="200 OK"/>
+         <location value="Patient/966810/_history/1"/>
+         <etag value="1"/>
+         <lastModified value="2015-10-29T07:25:42.465-04:00"/>
+      </response>
+   </entry>
+   <entry>
+      <response>
+         <status value="201 Created"/>
+         <location value="Observation/966828/_history/1"/>
+         <etag value="1"/>
+         <lastModified value="2015-10-29T07:33:28.047-04:00"/>
+      </response>
+   </entry>
+</Bundle>]]></source>
+				</p>
+					
+			</subsection>
+
+		</section>
+
+	</body>
+
+</document>

src/site/xdoc/docindex.xml

@@ -35,6 +35,7 @@
 				<li><a href="./doc_rest_client_annotation.html">Annotation Client</a></li>
 				<li><a href="./doc_rest_client_interceptor.html">Interceptors (client)</a></li>
 				<li><a href="./doc_rest_client_http_config.html">Client HTTP Configuration</a></li>
+				<li><a href="./doc_rest_client_examples.html">Client Examples</a></li>
 			</ul>
 			
 			<h4>RESTful Server</h4>