Merge pull request #529 from IBM/lee-master-patch1

issue #528 - update Conformance.md and tweak datetime precision

Author: prb112

docs/src/pages/Conformance.md

@@ -85,8 +85,8 @@ FHIR search modifiers are described at https://www.hl7.org/fhir/R4/search.html#m
 |Reference                 |`:[type]`,`:missing`            |exact match search|
 |URI                       |`:below`,`:above`,`:missing`    |exact match search|
 |Token                     |`:missing`                      |exact match search|
-|Number                    |`:missing`                      |exact match search|
-|Date                      |`:missing`                      |exact match search|
+|Number                    |`:missing`                      |implicit range search (see http://hl7.org/fhir/R4/search.html#number)|
+|Date                      |`:missing`                      |implicit range search (see https://www.hl7.org/fhir/search.html#date)|
 |Quantity                  |`:missing`                      |implicit range search (see http://hl7.org/fhir/R4/search.html#quantity)|
 |Composite                 |`:missing`                      |processes each parameter component according to its type|
 |Special (near)            | none                           |searches a bounding area according to the value of the `fhirServer/search/useBoundingRadius` property|
@@ -124,16 +124,25 @@ The `eb` and `ap` prefixes are not supported for searches which target values of
 If not specified on a query string, the default prefix is `eq`.
 
 ### Searching on Date
-The FHIR server adheres to the specification except in cases where a time is included in the search query value. When a time is specified, the implementation requires an hour, minute, second, and timezone value. Including these values is consistent with the way in which `instant` and `dateTime` data types are defined at https://www.hl7.org/fhir/R4/datatypes.html#primitive. However, the implementation differs from the description at https://www.hl7.org/fhir/R4/search.html#date, which allows clients to include hours and minutes, but to omit values for seconds and time zone.
+The IBM FHIR Server adheres to the specification with two minor exceptions:
+* The server supports search query values with fractional seconds; any search query value given with fractional seconds is treated as precise value, whereas search query values without fractional seconds are handled as an implicit range (e.g. `2000-04-30T23:59:00` becomes the range `[2000-04-30T23:59:00, 2000-04-30T23:59:01)`).
+* Dates and DateTimes (and query parameter values for date search parameters) which are expressed without timezones are handled as UTC values.
+* This differs slightly from the specification which indicates that "Where both search parameters and resource element date times do not have time zones, the servers local time zone should be assumed". However, because both the element values AND search query parameters are handled in the same way, this difference matters only when timezones are specified on one side (resource element or search query parameter) but not the other. For example, a query like `Patient?birthdate=2019-01-01` would match a resource with a value of `2019-01-01`, but would *not* match a resource with a value of `2019-01-01T20:00:00-04:00`.
 
-The IBM FHIR Server stores up to 6 fractional seconds (microsecond granularity) for Instant and DateTime values (when present) and allows clients to search with these as well.
+The IBM FHIR Server supports up to 6 fractional seconds (microsecond granularity) for Instant and DateTime values and all extracted parameter values are stored in the database in UTC in order to improve data portability.
 
-Query parameter values without fractional seconds will be handled as an implicit range. For example, a search like `Patient?date=2019-01-01T12:00:00Z` would include resources with the following effectiveDateTime values:
+Dates and DateTimes which are expressed without timezones are assumed to be in the local timezone of the application server at the time of parameter extraction.
+Similarly, query parameter date values with no timezone are assumed to be in the local time of the server at the time the search is invoked.
+To ensure consistency of search results, clients are recommended to include the timezone on all search query values that include a time.
+
+Finally, the server extends the specified capabilities with support for "exact match" semantics on fractional seconds.
+
+Query parameter values without fractional seconds is handled as an implicit range. For example, a search like `Observatoin?date=2019-01-01T12:00:00Z` would return resources with the following effectiveDateTime values:
 * 2019-01-01T12:00:00Z
 * 2019-01-01T12:00:00.1Z
 * 2019-01-01T12:00:00.999999Z
 
-Query parameter values with fractional seconds will be handled with exact match semantics (ignoring precision). For example, a search like `Patient?date=2019-01-01T12:00:00.100Z` would include resources with the following effectiveDateTime values:
+Query parameter values with fractional seconds is handled with exact match semantics (ignoring precision). For example, a search like `Patient?birthdate=2019-01-01T12:00:00.1Z` would include resources with the following effectiveDateTime values:
 * 2019-01-01T12:00:00.1Z
 * 2019-01-01T12:00:00.100Z
 * 2019-01-01T12:00:00.100000Z

fhir-examples/src/main/resources/json/ibm/basic/BasicDate.json

@@ -14,7 +14,7 @@
     },
     {
       "url": "http://example.org/dateTime",
-      "valueDateTime": "2018-10-29T17:12:00-04:00"
+      "valueDateTime": "2019-12-31T20:00:00-04:00"
     },
     {
       "url": "http://example.org/time",

fhir-persistence-jdbc/src/main/java/com/ibm/fhir/persistence/jdbc/util/JDBCParameterBuildingVisitor.java

@@ -652,7 +652,7 @@ private void setDateValues(DateParmVal p, Date date) {
             java.time.Instant inst = DateTimeHandler.generateValue(date.getValue());
             p.setValueDate(DateTimeHandler.generateTimestamp(inst));
             p.setValueDateStart(DateTimeHandler.generateTimestamp(inst));
-            inst = DateTimeHandler.generateUpperBound(date.getValue());
+            inst = DateTimeHandler.generateUpperBound(date);
             p.setValueDateEnd(DateTimeHandler.generateTimestamp(inst));
         }
     }
@@ -671,7 +671,7 @@ private void setDateValues(DateParmVal p, DateTime dateTime) {
             java.time.Instant inst = DateTimeHandler.generateValue(dateTime.getValue());
             p.setValueDate(DateTimeHandler.generateTimestamp(inst));
             p.setValueDateStart(DateTimeHandler.generateTimestamp(inst));
-            inst = DateTimeHandler.generateUpperBound(dateTime.getValue());
+            inst = DateTimeHandler.generateUpperBound(dateTime);
             p.setValueDateEnd(DateTimeHandler.generateTimestamp(inst));
         }
     }

fhir-persistence-jdbc/src/main/java/com/ibm/fhir/persistence/jdbc/util/type/DateParmBehaviorUtil.java

@@ -11,7 +11,6 @@
 import static com.ibm.fhir.persistence.jdbc.JDBCConstants.DATE_END;
 import static com.ibm.fhir.persistence.jdbc.JDBCConstants.DATE_START;
 import static com.ibm.fhir.persistence.jdbc.JDBCConstants.DOT;
-import static com.ibm.fhir.persistence.jdbc.JDBCConstants.EQ;
 import static com.ibm.fhir.persistence.jdbc.JDBCConstants.GT;
 import static com.ibm.fhir.persistence.jdbc.JDBCConstants.GTE;
 import static com.ibm.fhir.persistence.jdbc.JDBCConstants.LEFT_PAREN;
@@ -172,25 +171,17 @@ public void buildCommonClause(StringBuilder whereClauseSegment, List<Timestamp>
      */
     public void buildEqualsRangeClause(StringBuilder whereClauseSegment, List<Timestamp> bindVariables,
             String tableAlias, Instant lowerBound, Instant upperBound) {
-        bindVariables.add(generateTimestamp(lowerBound));
+        // @formatter:off
+        whereClauseSegment
+                .append(LEFT_PAREN)
+                    .append(tableAlias).append(DOT).append(DATE_START).append(GTE).append(BIND_VAR)
+                .append(AND)
+                    .append(tableAlias).append(DOT).append(DATE_END).append(LTE).append(BIND_VAR)
+                .append(RIGHT_PAREN);
+        // @formatter:on
 
-        if (!lowerBound.equals(upperBound)) {
-            // @formatter:off
-            whereClauseSegment
-                    .append(LEFT_PAREN)
-                        .append(tableAlias).append(DOT).append(DATE_START).append(GTE).append(BIND_VAR)
-                    .append(AND)
-                        .append(tableAlias).append(DOT).append(DATE_END).append(LTE).append(BIND_VAR)
-                    .append(RIGHT_PAREN);
-            // @formatter:on
-            bindVariables.add(generateTimestamp(upperBound));
-        } else {
-            // Exact match of an instant. 
-            whereClauseSegment
-                    .append(LEFT_PAREN)
-                        .append(tableAlias).append(DOT).append(DATE_START).append(EQ).append(BIND_VAR)
-                    .append(RIGHT_PAREN);
-        }
+        bindVariables.add(generateTimestamp(lowerBound));
+        bindVariables.add(generateTimestamp(upperBound));
     }
 
     /**