Add documentation for custom structures
This commit is contained in:
jamesagnew
parent
de65184afb
commit
8863ff25be
|
|
@ -0,0 +1,63 @@
|
|||
package example.customtype;
|
||||
|
||||
//START SNIPPET: datatype
|
||||
import org.hl7.fhir.dstu3.model.DateTimeType;
|
||||
import org.hl7.fhir.dstu3.model.StringType;
|
||||
import org.hl7.fhir.dstu3.model.Type;
|
||||
import org.hl7.fhir.instance.model.api.ICompositeType;
|
||||
|
||||
import ca.uhn.fhir.model.api.annotation.Child;
|
||||
import ca.uhn.fhir.model.api.annotation.DatatypeDef;
|
||||
import ca.uhn.fhir.util.ElementUtil;
|
||||
|
||||
/**
|
||||
* This is an example of a custom datatype.
|
||||
*
|
||||
* This is an STU3 example so it extends Type and implements ICompositeType. For
|
||||
* DSTU2 it would extend BaseIdentifiableElement and implement ICompositeDatatype.
|
||||
*/
|
||||
@DatatypeDef(name="CustomDatatype")
|
||||
public class CustomDatatype extends Type implements ICompositeType {
|
||||
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
@Child(name = "date", order = 0, min = 1, max = 1)
|
||||
private DateTimeType myDate;
|
||||
|
||||
@Child(name = "kittens", order = 1, min = 1, max = 1)
|
||||
private StringType myKittens;
|
||||
|
||||
public DateTimeType getDate() {
|
||||
if (myDate == null)
|
||||
myDate = new DateTimeType();
|
||||
return myDate;
|
||||
}
|
||||
|
||||
public StringType getKittens() {
|
||||
return myKittens;
|
||||
}
|
||||
|
||||
@Override
|
||||
public boolean isEmpty() {
|
||||
return ElementUtil.isEmpty(myDate, myKittens);
|
||||
}
|
||||
|
||||
public CustomDatatype setDate(DateTimeType theValue) {
|
||||
myDate = theValue;
|
||||
return this;
|
||||
}
|
||||
|
||||
public CustomDatatype setKittens(StringType theKittens) {
|
||||
myKittens = theKittens;
|
||||
return this;
|
||||
}
|
||||
|
||||
@Override
|
||||
protected CustomDatatype typedCopy() {
|
||||
CustomDatatype retVal = new CustomDatatype();
|
||||
super.copyValues(retVal);
|
||||
retVal.myDate = myDate;
|
||||
return retVal;
|
||||
}
|
||||
}
|
||||
//END SNIPPET: datatype
|
||||
|
|
@ -0,0 +1,86 @@
|
|||
package example.customtype;
|
||||
|
||||
// START SNIPPET: resource
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
|
||||
import org.hl7.fhir.dstu3.model.DomainResource;
|
||||
import org.hl7.fhir.dstu3.model.ResourceType;
|
||||
import org.hl7.fhir.dstu3.model.StringType;
|
||||
import org.hl7.fhir.dstu3.model.Type;
|
||||
|
||||
import ca.uhn.fhir.context.FhirVersionEnum;
|
||||
import ca.uhn.fhir.model.api.annotation.Child;
|
||||
import ca.uhn.fhir.model.api.annotation.ResourceDef;
|
||||
import ca.uhn.fhir.util.ElementUtil;
|
||||
|
||||
/**
|
||||
* This is an example of a custom resource that also uses a custom
|
||||
* datatype.
|
||||
*
|
||||
* Note that we are extensing DomainResource for an STU3
|
||||
* resource. For DSTU2 it would be BaseResource.
|
||||
*/
|
||||
@ResourceDef(name = "CustomResource", profile = "http://hl7.org/fhir/profiles/custom-resource")
|
||||
public class CustomResource extends DomainResource {
|
||||
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
/**
|
||||
* We give the resource a field with name "television". This field has no
|
||||
* specific type, so it's a choice[x] field for any type.
|
||||
*/
|
||||
@Child(name="television", min=1, max=Child.MAX_UNLIMITED, order=0)
|
||||
private List<Type> myTelevision;
|
||||
|
||||
/**
|
||||
* We'll give it one more field called "dogs"
|
||||
*/
|
||||
@Child(name = "dogs", min=0, max=1, order=1)
|
||||
private StringType myDogs;
|
||||
|
||||
@Override
|
||||
public CustomResource copy() {
|
||||
CustomResource retVal = new CustomResource();
|
||||
super.copyValues(retVal);
|
||||
retVal.myTelevision = myTelevision;
|
||||
retVal.myDogs = myDogs;
|
||||
return retVal;
|
||||
}
|
||||
|
||||
public List<Type> getTelevision() {
|
||||
if (myTelevision == null) {
|
||||
myTelevision = new ArrayList<Type>();
|
||||
}
|
||||
return myTelevision;
|
||||
}
|
||||
|
||||
public StringType getDogs() {
|
||||
return myDogs;
|
||||
}
|
||||
|
||||
@Override
|
||||
public ResourceType getResourceType() {
|
||||
return null;
|
||||
}
|
||||
|
||||
@Override
|
||||
public FhirVersionEnum getStructureFhirVersionEnum() {
|
||||
return FhirVersionEnum.DSTU3;
|
||||
}
|
||||
|
||||
@Override
|
||||
public boolean isEmpty() {
|
||||
return ElementUtil.isEmpty(myTelevision, myDogs);
|
||||
}
|
||||
|
||||
public void setTelevision(List<Type> theValue) {
|
||||
this.myTelevision = theValue;
|
||||
}
|
||||
|
||||
public void setDogs(StringType theDogs) {
|
||||
myDogs = theDogs;
|
||||
}
|
||||
|
||||
}
|
||||
// END SNIPPET: resource
|
||||
|
|
@ -0,0 +1,44 @@
|
|||
package example.customtype;
|
||||
|
||||
import java.util.Date;
|
||||
|
||||
import org.hl7.fhir.dstu3.model.DateTimeType;
|
||||
import org.hl7.fhir.dstu3.model.DateType;
|
||||
import org.hl7.fhir.dstu3.model.StringType;
|
||||
|
||||
import ca.uhn.fhir.context.FhirContext;
|
||||
|
||||
public class CustomUsage {
|
||||
|
||||
public static void main(String[] args) {
|
||||
|
||||
// START SNIPPET: usage
|
||||
// Create a context. Note that we declare the custom types we'll be using
|
||||
// on the context before actually using them
|
||||
FhirContext ctx = FhirContext.forDstu3();
|
||||
ctx.registerCustomType(CustomResource.class);
|
||||
ctx.registerCustomType(CustomDatatype.class);
|
||||
|
||||
// Now let's create an instance of our custom resource type
|
||||
// and populate it with some data
|
||||
CustomResource res = new CustomResource();
|
||||
|
||||
// Add some values, including our custom datatype
|
||||
DateType value0 = new DateType("2015-01-01");
|
||||
res.getTelevision().add(value0);
|
||||
|
||||
CustomDatatype value1 = new CustomDatatype();
|
||||
value1.setDate(new DateTimeType(new Date()));
|
||||
value1.setKittens(new StringType("FOO"));
|
||||
res.getTelevision().add(value1);
|
||||
|
||||
res.setDogs(new StringType("Some Dogs"));
|
||||
|
||||
// Now let's serialize our instance
|
||||
String output = ctx.newXmlParser().setPrettyPrint(true).encodeResourceToString(res);
|
||||
System.out.println(output);
|
||||
// END SNIPPET: usage
|
||||
|
||||
}
|
||||
|
||||
}
|
||||
5
pom.xml
5
pom.xml
|
|
@ -1086,6 +1086,11 @@
|
|||
<replacetoken>http://ajax.googleapis</replacetoken>
|
||||
<replacevalue>https://ajax.googleapis</replacevalue>
|
||||
</replace>
|
||||
<replace dir="target/site" summary="true">
|
||||
<include name="*.html"/>
|
||||
<replacetoken>\t</replacetoken>
|
||||
<replacevalue> </replacevalue>
|
||||
</replace>
|
||||
<replace dir="target/site" summary="true">
|
||||
<include name="index.html"/>
|
||||
<replacetoken><![CDATA[<h2 id="Welcome">Welcome</h2>]]></replacetoken>
|
||||
|
|
|
|||
|
|
@ -84,6 +84,7 @@
|
|||
<item name="Profiles & Extensions" href="./doc_extensions.html" />
|
||||
<item name="Tags" href="./doc_tags.html" />
|
||||
<item name="Validation" href="./doc_validation.html" />
|
||||
<item name="Custom Structures" href="./doc_custom_structures.html" />
|
||||
</item>
|
||||
<item name="RESTful Client" href="./doc_rest_client.html" >
|
||||
<item name="Fluent/Generic Client" href="./doc_rest_client.html" />
|
||||
|
|
|
|||
|
|
@ -0,0 +1,95 @@
|
|||
<?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>Custom Structures</title>
|
||||
</properties>
|
||||
|
||||
<body>
|
||||
|
||||
<section name="Custom Structures">
|
||||
|
||||
<p>
|
||||
Typically, when working with FHIR the right way to provide your
|
||||
own extensions is to work with existing resource types and simply
|
||||
ass your own extensions and/or constrain out fields you don't
|
||||
need.
|
||||
</p>
|
||||
<p>
|
||||
This process is described on the
|
||||
<a href="./doc_extensions.html">Profiles & Extensions</a>
|
||||
page.
|
||||
</p>
|
||||
<p>
|
||||
There are situations however when you might want to create an
|
||||
entirely custom resource type. This feature should be used
|
||||
only if there is no other option, since it means you are creating
|
||||
a resource type that will not be interoperable with other FHIR
|
||||
implementations.
|
||||
</p>
|
||||
<p class="doc_info_bubble">
|
||||
This is an advanced features and isn't needed for most uses of
|
||||
HAPI-FHIR. Feel free to skip this page.
|
||||
</p>
|
||||
|
||||
<subsection name="Custom Resource Structure">
|
||||
|
||||
<p>
|
||||
The following example shows a custom resource structure
|
||||
class:
|
||||
</p>
|
||||
<macro name="snippet">
|
||||
<param name="id" value="resource" />
|
||||
<param name="file" value="examples/src/main/java/example/customtype/CustomResource.java" />
|
||||
</macro>
|
||||
|
||||
</subsection>
|
||||
|
||||
<subsection name="Custom Datatype Structure">
|
||||
|
||||
<p>
|
||||
The following example shows a custom datatype structure
|
||||
class:
|
||||
</p>
|
||||
<macro name="snippet">
|
||||
<param name="id" value="datatype" />
|
||||
<param name="file" value="examples/src/main/java/example/customtype/CustomDatatype.java" />
|
||||
</macro>
|
||||
|
||||
</subsection>
|
||||
|
||||
<subsection name="Using the Custom Structure">
|
||||
|
||||
<p>
|
||||
And now let's try the custom structure out:
|
||||
</p>
|
||||
<macro name="snippet">
|
||||
<param name="id" value="usage" />
|
||||
<param name="file" value="examples/src/main/java/example/customtype/CustomUsage.java" />
|
||||
</macro>
|
||||
|
||||
<p>
|
||||
This produces the following output (some spacing has been added for readability):
|
||||
</p>
|
||||
<source><![CDATA[<CustomResource xmlns="http://hl7.org/fhir">
|
||||
<meta>
|
||||
<profile value="http://hl7.org/fhir/profiles/custom-resource"/>
|
||||
</meta>
|
||||
|
||||
<televisionDate value="2015-01-01"/>
|
||||
<televisionCustomDatatype>
|
||||
<date value="2016-05-22T08:30:36-04:00"/>
|
||||
<kittens value="FOO"/>
|
||||
</televisionCustomDatatype>
|
||||
|
||||
<dogs value="Some Dogs"/>
|
||||
|
||||
</CustomResource>]]></source>
|
||||
|
||||
</subsection>
|
||||
|
||||
</section>
|
||||
|
||||
</body>
|
||||
|
||||
</document>
|
||||
|
|
@ -80,6 +80,110 @@ $ mvn install]]></source>
|
|||
</subsection>
|
||||
</section>
|
||||
|
||||
<section name="Configuring The JPA Server">
|
||||
|
||||
<p>
|
||||
The JPA server is configured through a series of configuration files, most
|
||||
of which are documented inline.
|
||||
</p>
|
||||
<ul>
|
||||
<li>
|
||||
<a href="https://github.com/jamesagnew/hapi-fhir/blob/master/hapi-fhir-jpaserver-example/src/main/java/ca/uhn/fhir/jpa/demo/FhirServerConfig.java"><b>FhirServerConfig.java</b></a>:
|
||||
Configures the database connection settings
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
</section>
|
||||
|
||||
<section name="DaoConfig">
|
||||
|
||||
<p>
|
||||
The Spring confguration contains a definition for a bean called <code>daoConfig</code>,
|
||||
which will look something like the following:
|
||||
</p>
|
||||
<source><![CDATA[@Bean()
|
||||
public DaoConfig daoConfig() {
|
||||
DaoConfig retVal = new DaoConfig();
|
||||
retVal.setAllowMultipleDelete(true);
|
||||
retVal.setAllowInlineMatchUrlReferences(true);
|
||||
return retVal;
|
||||
}]]></source>
|
||||
|
||||
<p>
|
||||
You can use this method to change various configuration settings on the DaoConfig bean
|
||||
which define the way that the JPA server will behave.
|
||||
See the <a href="./apidocs-jpaserver/ca/uhn/fhir/jpa/dao/DaoConfig.html">DaoConfig JavaDoc</a>
|
||||
for information about the available settings.
|
||||
</p>
|
||||
|
||||
<subsection name="External/Absolute Resource References">
|
||||
|
||||
<p>
|
||||
Clients may sometimes post resources to your server that contain
|
||||
absolute resource references. For example, consider the following resource:
|
||||
</p>
|
||||
<source><![CDATA[<Patient xmlns="http://hl7.org/fhir">
|
||||
<id value="patient-infant-01"/>
|
||||
<name>
|
||||
<use value="official"/>
|
||||
<family value="Miller"/>
|
||||
<given value="Samuel"/>
|
||||
</name>
|
||||
<managingOrganization>
|
||||
<reference value="http://example.com/fhir/Organization/123"/>
|
||||
</managingOrganization>
|
||||
</Patient>]]></source>
|
||||
|
||||
<p>
|
||||
By default, the server will reject this reference, as only
|
||||
local references are permitted by the server. This can be changed
|
||||
however.
|
||||
</p>
|
||||
<p>
|
||||
If you want the server to recognize that this URL is actually a local
|
||||
reference (i.e. because the server will be deployed to the base URL
|
||||
<code>http://example.com/fhir/</code>) you can
|
||||
configure the server to recognize this URL via the following DaoConfig
|
||||
setting:
|
||||
</p>
|
||||
<source><![CDATA[@Bean()
|
||||
public DaoConfig daoConfig() {
|
||||
DaoConfig retVal = new DaoConfig();
|
||||
// ... other config ...
|
||||
retVal.getTreatBaseUrlsAsLocal().add("http://example.com/fhir/");
|
||||
return retVal;
|
||||
}]]></source>
|
||||
|
||||
<p>
|
||||
On the other hand, if you want the server to be configurable to
|
||||
allow remote references, you can set this with the confguration below.
|
||||
Using the <code>setAllowInlineMatchUrlReferences</code> means that
|
||||
it will be possible to search for references that refer to these
|
||||
external references.
|
||||
</p>
|
||||
|
||||
<source><![CDATA[@Bean()
|
||||
public DaoConfig daoConfig() {
|
||||
DaoConfig retVal = new DaoConfig();
|
||||
// Allow external references
|
||||
retVal.setAllowInlineMatchUrlReferences(true);
|
||||
|
||||
// If you are allowing external references, it is recommended to
|
||||
// also tell the server which references actually will be local
|
||||
retVal.getTreatBaseUrlsAsLocal().add("http://mydomain.com/fhir");
|
||||
return retVal;
|
||||
}]]></source>
|
||||
</subsection>
|
||||
|
||||
</section>
|
||||
|
||||
<section name="Not yet complete">
|
||||
<p>
|
||||
The documentation for the JPA server is not yet complete. Please get in touch
|
||||
if you are able to help us complete it!
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<section name="Architecture">
|
||||
|
||||
<img src="images/jpa_architecture.png" alt="Architecture" align="right"/>
|
||||
|
|
@ -135,110 +239,6 @@ $ mvn install]]></source>
|
|||
|
||||
</section>
|
||||
|
||||
<section name="Configuring The JPA Server">
|
||||
|
||||
<p>
|
||||
The JPA server is configured through a series of configuration files, most
|
||||
of which are documented inline.
|
||||
</p>
|
||||
<ul>
|
||||
<li>
|
||||
<a href="https://github.com/jamesagnew/hapi-fhir/blob/master/hapi-fhir-jpaserver-example/src/main/java/ca/uhn/fhir/jpa/demo/FhirServerConfig.java"><b>FhirServerConfig.java</b></a>:
|
||||
Configures the database connection settings
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
</section>
|
||||
|
||||
<section name="DaoConfig">
|
||||
|
||||
<p>
|
||||
The Spring confguration contains a definition for a bean called <code>daoConfig</code>,
|
||||
which will look something like the following:
|
||||
</p>
|
||||
<pre><![CDATA[@Bean()
|
||||
public DaoConfig daoConfig() {
|
||||
DaoConfig retVal = new DaoConfig();
|
||||
retVal.setAllowMultipleDelete(true);
|
||||
retVal.setAllowInlineMatchUrlReferences(true);
|
||||
return retVal;
|
||||
}]]></pre>
|
||||
|
||||
<p>
|
||||
You can use this method to change various configuration settings on the DaoConfig bean
|
||||
which define the way that the JPA server will behave.
|
||||
See the <a href="./apidocs-jpaserver/ca/uhn/fhir/jpa/dao/DaoConfig.html">DaoConfig JavaDoc</a>
|
||||
for information about the available settings.
|
||||
</p>
|
||||
|
||||
<subsection name="External/Absolute Resource References">
|
||||
|
||||
<p>
|
||||
Clients may sometimes post resources to your server that contain
|
||||
absolute resource references. For example, consider the following resource:
|
||||
</p>
|
||||
<pre><![CDATA[<Patient xmlns="http://hl7.org/fhir">
|
||||
<id value="patient-infant-01"/>
|
||||
<name>
|
||||
<use value="official"/>
|
||||
<family value="Miller"/>
|
||||
<given value="Samuel"/>
|
||||
</name>
|
||||
<managingOrganization>
|
||||
<reference value="http://example.com/fhir/Organization/123"/>
|
||||
</managingOrganization>
|
||||
</Patient>]]></pre>
|
||||
|
||||
<p>
|
||||
By default, the server will reject this reference, as only
|
||||
local references are permitted by the server. This can be changed
|
||||
however.
|
||||
</p>
|
||||
<p>
|
||||
If you want the server to recognize that this URL is actually a local
|
||||
reference (i.e. because the server will be deployed to the base URL
|
||||
<code>http://example.com/fhir/</code>) you can
|
||||
configure the server to recognize this URL via the following DaoConfig
|
||||
setting:
|
||||
</p>
|
||||
<pre><![CDATA[@Bean()
|
||||
public DaoConfig daoConfig() {
|
||||
DaoConfig retVal = new DaoConfig();
|
||||
// ... other config ...
|
||||
retVal.getTreatBaseUrlsAsLocal().add("http://example.com/fhir/");
|
||||
return retVal;
|
||||
}]]></pre>
|
||||
|
||||
<p>
|
||||
On the other hand, if you want the server to be configurable to
|
||||
allow remote references, you can set this with the confguration below.
|
||||
Using the <code>setAllowInlineMatchUrlReferences</code> means that
|
||||
it will be possible to search for references that refer to these
|
||||
external references.
|
||||
</p>
|
||||
|
||||
<pre><![CDATA[@Bean()
|
||||
public DaoConfig daoConfig() {
|
||||
DaoConfig retVal = new DaoConfig();
|
||||
// Allow external references
|
||||
retVal.setAllowInlineMatchUrlReferences(true);
|
||||
|
||||
// If you are allowing external references, it is recommended to
|
||||
// also tell the server which references actually will be local
|
||||
retVal.getTreatBaseUrlsAsLocal().add("http://mydomain.com/fhir");
|
||||
return retVal;
|
||||
}]]></pre>
|
||||
</subsection>
|
||||
|
||||
</section>
|
||||
|
||||
<section name="Not yet complete">
|
||||
<p>
|
||||
The documentation for the JPA server is not yet complete. Please get in touch
|
||||
if you are able to help us complete it!
|
||||
</p>
|
||||
</section>
|
||||
|
||||
</body>
|
||||
|
||||
</document>
|
||||
|
|
|
|||
|
|
@ -27,6 +27,7 @@
|
|||
<li><a href="./doc_resource_references.html">Resource References</a></li>
|
||||
<li><a href="./doc_tags.html">Tags</a></li>
|
||||
<li><a href="./doc_validation.html">Validation</a></li>
|
||||
<li><a href="./doc_custom_structures.html">Custom Structures</a></li>
|
||||
</ul>
|
||||
|
||||
<h4>RESTful Client</h4>
|
||||
|
|
|
|||
Loading…
Reference in New Issue