diff --git a/hapi-fhir-base/src/changes/changes.xml b/hapi-fhir-base/src/changes/changes.xml index 4ff34116fab..651160a3b35 100644 --- a/hapi-fhir-base/src/changes/changes.xml +++ b/hapi-fhir-base/src/changes/changes.xml @@ -8,9 +8,6 @@
+ * You may also pass in a value of "*" which indicates to the server + * that any value is allowable and will be passed to this parameter. This is + * helpful if you want to explicitly declare support for some includes, but also + * allow others implicitly (e.g. imports from other resources) + *
*/ String[] allow() default {}; diff --git a/hapi-fhir-base/src/main/java/ca/uhn/fhir/rest/method/BaseMethodBinding.java b/hapi-fhir-base/src/main/java/ca/uhn/fhir/rest/method/BaseMethodBinding.java index 563ee1a77e8..0b83da97d11 100644 --- a/hapi-fhir-base/src/main/java/ca/uhn/fhir/rest/method/BaseMethodBinding.java +++ b/hapi-fhir-base/src/main/java/ca/uhn/fhir/rest/method/BaseMethodBinding.java @@ -61,7 +61,6 @@ import ca.uhn.fhir.rest.annotation.Validate; import ca.uhn.fhir.rest.api.MethodOutcome; import ca.uhn.fhir.rest.client.BaseHttpClientInvocation; import ca.uhn.fhir.rest.client.exceptions.NonFhirResponseException; -import ca.uhn.fhir.rest.param.IncludeParameter; import ca.uhn.fhir.rest.server.BundleProviders; import ca.uhn.fhir.rest.server.Constants; import ca.uhn.fhir.rest.server.EncodingEnum; diff --git a/hapi-fhir-base/src/main/java/ca/uhn/fhir/rest/param/IncludeParameter.java b/hapi-fhir-base/src/main/java/ca/uhn/fhir/rest/method/IncludeParameter.java similarity index 93% rename from hapi-fhir-base/src/main/java/ca/uhn/fhir/rest/param/IncludeParameter.java rename to hapi-fhir-base/src/main/java/ca/uhn/fhir/rest/method/IncludeParameter.java index 3f61fa27451..8c8a43cfec5 100644 --- a/hapi-fhir-base/src/main/java/ca/uhn/fhir/rest/param/IncludeParameter.java +++ b/hapi-fhir-base/src/main/java/ca/uhn/fhir/rest/method/IncludeParameter.java @@ -1,4 +1,4 @@ -package ca.uhn.fhir.rest.param; +package ca.uhn.fhir.rest.method; /* * #%L @@ -34,11 +34,11 @@ import ca.uhn.fhir.model.api.Include; import ca.uhn.fhir.model.api.PathSpecification; import ca.uhn.fhir.model.dstu.valueset.SearchParamTypeEnum; import ca.uhn.fhir.rest.annotation.IncludeParam; -import ca.uhn.fhir.rest.method.QualifiedParamList; +import ca.uhn.fhir.rest.param.BaseQueryParameter; import ca.uhn.fhir.rest.server.exceptions.InternalErrorException; import ca.uhn.fhir.rest.server.exceptions.InvalidRequestException; -public class IncludeParameter extends BaseQueryParameter { +class IncludeParameter extends BaseQueryParameter { private SetThe generic client supports queries using a fluent interface which is inspired by the fantastic @@ -69,23 +68,77 @@ you to take advantage of intellisense/code completion in your favourite IDE.
-
- The following example shows how to query using this interface:
+ Note that most fluent operations end with an execute()
+ statement which actually performs the invocation. You may also invoke
+ several configuration operations just prior to the execute() statement,
+ such as encodedJson()
or encodedXml()
.
+ The following example shows how to perform a create + operation using the generic client: +
+ The following example shows how to query using the generic client: +
++ If the server supports paging results, the client has a page method + which can be used to load subsequent pages. +
+
+ To retrieve the server's conformance statement, simply call the conformance()
+ method as shown below.
+
+ The following example shows how to execute a transaction using the generic client: +
++ HAPI also provides a second style of client caled the annotation-driven client. +
+The design of the annotation-driven client is intended to be similar to that of @@ -95,10 +148,24 @@ annotated methods which HAPI binds to calls against a server.
++ The annotation-driven client is particularly useful if you have a server that + exposes a set of specific operations (search parameter combinations, named queries, etc.) + and you want to let developers have a stongly/statically typed interface to that + server. +
++ There is no difference in terms of capability between the two styles of + client. There is simply a difference in programming style and complexity. It + is probably safe to say that the generic client is easier to use and leads to + more readable code, at the expense of not giving any visibility into the + specific capabilities of the server you are interacting with. +
+- The first step in creating a FHIR RESTful Client is to define a + The first step in creating an annotation-driven client is to define a restful client interface.
@@ -134,7 +201,7 @@diff --git a/hapi-fhir-base/src/site/xdoc/doc_rest_operations.xml b/hapi-fhir-base/src/site/xdoc/doc_rest_operations.xml index cc80fc6004e..95398292051 100644 --- a/hapi-fhir-base/src/site/xdoc/doc_rest_operations.xml +++ b/hapi-fhir-base/src/site/xdoc/doc_rest_operations.xml @@ -466,14 +466,14 @@
To allow a search using given search parameters, add one or more parameters to your search method and tag these parameters as either - @RequiredParam + @RequiredParam or - @OptionalParam + @OptionalParam .
@@ -734,13 +734,13 @@ may (or may not) be optional. To add a second required parameter, annotate the parameter with - @RequiredParam + @RequiredParam . To add an optional parameter (which will be passed in asnull
if no value
is supplied), annotate the method with
- @OptionalParam
+ @OptionalParam
.
@@ -821,13 +821,31 @@
+
+ It is worth noting that according to the FHIR specification, you can have an
+ AND relationship combining multiple OR relationships, but not vice-versa. In
+ other words, it's possible to support a search like
+ ("name" = ("joe" or "john")) AND ("age" = (11 or 12))
but not
+ a search like
+ ("language" = ("en" AND "fr") OR ("address" = ("Canada" AND "Quebec"))
+
To accept a composite parameter, use a parameter type which implements the IQueryParameterOr - interface. For example, to accept searches for - Observations matching any of a collection of names: + interface. +
++ Each parameter type (StringParam, TokenParam, etc.) has a corresponding parameter + which accepts an OR list of parameters. These types are called "[type]OrListParam", for example: + StringOrListParam and TokenOrListParam. +
++ The following example shows a search for Observation by name, where a list of + names may be passed in (and the expectation is that the server will return Observations + that match any of these names):
- See the section below on
- date ranges
- for
- one example of an AND parameter.
+ An example follows which shows a search for Patients by address, where multiple string
+ lists may be supplied by the client. For example, the client might request that the
+ address match ("Montreal" OR "Sherbrooke") AND ("Quebec" OR "QC")
using
+ the following query:
+
+ http://fhir.example.com/Patient?address=Montreal,Sherbrooke&address=Quebec,QC
+
+ The following code shows how to receive this parameter using a + StringAndListParameter, + which can handle an AND list of multiple OR lists of strings. +
+ ++ Dates are a bit of a special case, since it is a common scenario to want to match + a date range (which is really just an AND query on two qualified date parameters). + See the section below on date ranges + for an example of a DateRangeParameter.