Issue #1980 - Introduce fhir-term-graph module

docs/src/pages/guides/FHIRServerUsersGuide.md

@@ -1953,6 +1953,9 @@ This section contains reference information about each of the configuration prop
 |`fhirServer/core/capabilityStatementCacheTimeout`|integer|The number of minutes that a tenant's CapabilityStatement is cached for the metadata endpoint. |
 |`fhirServer/core/extendedCodeableConceptValidation`|boolean|A boolean flag which indicates whether extended validation is performed by the server during object construction for code, Coding, CodeableConcept, Quantity, Uri, and String elements which have required bindings to value sets.|
 |`fhirServer/core/disabledOperations`|string|A comma-separated list of operations which are not allowed to run on the IBM FHIR Server, for example, `validate,import`. Note, do not include the dollar sign `$`|
+|`fhirServer/term/graphTermServiceProvider/enabled`|boolean|Indicates whether the graph term service provider should be used by the FHIR term service to access code system content|
+|`fhirServer/term/graphTermServiceProvider/timeLimit`|integer|Graph traversal time limit (in milliseconds)|
+|`fhirServer/term/graphTermServiceProvider/configuration`|object (name/value pairs)|A JSON object that contains the name/value pairs used to configure the graph database behind the graph term service provider see: [https://docs.janusgraph.org/basics/configuration-reference/](https://docs.janusgraph.org/basics/configuration-reference/)|
 |`fhirServer/resources/open`|boolean|Whether resources that are not explicitly listed in the configuration should be supported by the FHIR Server REST layer. When open is set to `false`, only the resources listed in fhir-server-config.json are supported.|
 |`fhirServer/resources/Resource/interactions`|string list|A list of strings that represent the RESTful interactions (create, read, vread, update, patch, delete, history, and/or search) supported for resource types. Omitting this property is equivalent to supporting all FHIR interactions for the supported resources. An empty list, `[]`, can be used to indicate that no REST methods are supported. This property can be overridden for specific resource types via the `fhirServer/resources/<resourceType>/interactions` property.|
 |`fhirServer/resources/Resource/searchParameters`|object|The set of search parameters to support for all supported resource types. Omitting this property is equivalent to supporting all search parameters in the server's registry that apply to resource type "Resource" (all resources). An empty object, `{}`, can be used to indicate that no global search parameters are supported.|
@@ -2073,6 +2076,8 @@ This section contains reference information about each of the configuration prop
 |`fhirServer/core/conditionalDeleteMaxNumber`|10|
 |`fhirServer/core/capabilityStatementCacheTimeout`|60|
 |`fhirServer/core/extendedCodeableConceptValidation`|true|
+|`fhirServer/term/graphTermServiceProvider/enabled`|false|
+|`fhirServer/term/graphTermServiceProvider/timeLimit`|90000|
 |`fhirServer/resources/open`|true|
 |`fhirServer/resources/Resource/interactions`|null (all interactions supported)|
 |`fhirServer/resources/Resource/searchParameters`|null (all global search parameters supported)|
@@ -2182,6 +2187,9 @@ must restart the server for that change to take effect.
 |`fhirServer/core/capabilityStatementCacheTimeout`|Y|Y|
 |`fhirServer/core/extendedCodeableConceptValidation`|N|N|
 |`fhirServer/core/disabledOperations`|N|N|
+|`fhirServer/term/graphTermServiceProvider/enabled`|N|N|
+|`fhirServer/term/graphTermServiceProvider/timeLimit`|N|N|
+|`fhirServer/term/graphTermServiceProvider/configuration`|N|N|
 |`fhirServer/resources/open`|Y|Y|
 |`fhirServer/resources/Resource/interactions`|Y|Y|
 |`fhirServer/resources/Resource/searchParameters`|Y|Y|

docs/src/pages/guides/FHIRTerminologyGuide.md

@@ -1,7 +1,7 @@
 ---
 slug:  "/FHIR/guides/FHIRTerminologyGuide/"
 title: "FHIR Terminology Guide"
-date:  "2020-06-04 12:00:00 -0400"
+date:  "2021-03-11"
 ---
 
 ## Overview
@@ -10,23 +10,37 @@ The IBM FHIR Server Terminology module ([fhir-term](https://github.com/IBM/FHIR/
 
 ## FHIR Terminology Service Provider Interface (SPI)
 
-The FHIR Terminology Service Provider interface provides a mechanism for implementers to provide terminology capabilities via the Java ServiceLoader. The interface includes method signatures for `expand`, `lookup`, `subsumes`, `closure`, `validateCode` (CodeSystem) and `validateCode` (ValueSet). Here is an excerpt (for brevity) of the SPI:
+The FHIR Terminology Service Provider interface provides a mechanism for implementers to provide terminology capabilities via the Java ServiceLoader. The interface includes method signatures for `closure`, `getConcept`, `getConcepts`, `hasConcept`, `isSupported` and `subsumes`:
 
 ```java
 public interface FHIRTermServiceProvider {
-    boolean isExpandable(ValueSet valueSet);
-    ValueSet expand(ValueSet valueSet, ExpansionParameters parameters);
-    LookupOutcome lookup(Coding coding, LookupParameters parameters);
-    ConceptSubsumptionOutcome subsumes(Coding codingA, Coding codingB);
-    Set<Concept> closure(Coding coding);
-    ValidationOutcome validateCode(CodeSystem codeSystem, Coding coding, ValidationParameters parameters);
-    ValidationOutcome validateCode(CodeSystem codeSystem, CodeableConcept codeableConcept, ValidationParameters parameters);
-    ValidationOutcome validateCode(ValueSet valueSet, Coding coding, ValidationParameters parameters);
-    ValidationOutcome validateCode(ValueSet valueSet, CodeableConcept codeableConcept, ValidationParameters parameters);
-    TranslationOutcome translate(ConceptMap conceptMap, Coding coding, TranslationParameters parameters);
-    TranslationOutcome translate(ConceptMap conceptMap, CodeableConcept codeableConcept, TranslationParameters parameters);
+    Set<Concept> closure(CodeSystem codeSystem, Code code);
+    Concept getConcept(CodeSystem codeSystem, Code code);
+    Set<Concept> getConcepts(CodeSystem codeSystem);
+    Set<Concept> getConcepts(CodeSystem codeSystem, List<Filter> filters);
+    boolean hasConcept(CodeSystem codeSystem, Code code);
+    boolean isSupported(CodeSystem codeSystem);
+    boolean subsumes(CodeSystem codeSystem, Code codeA, Code codeB);
 }
+```
+
+## Default Terminology Service Provider Implementation
 
+The default implementation of `FHIRTermServiceProvider` ([DefaultTermServiceProvider](https://github.com/IBM/FHIR/blob/main/fhir-term/src/main/java/com/ibm/fhir/term/service/provider/DefaultTermServiceProvider.java)) leverages terminology resources (`CodeSystem`, `ValueSet`, and `ConceptMap`) that have been made available through the FHIR registry module ([fhir-registry](https://github.com/IBM/FHIR/tree/main/fhir-registry)). It supports `CodeSystem` resources with *complete* content (`CodeSystem.content = 'complete'`) and `ValueSet` resources that reference `CodeSystem` resources that have complete content.
+
+## FHIR Terminology Service Singleton facade
+
+The FHIR Terminology Service Singleton facade ([FHIRTermService](https://github.com/IBM/FHIR/blob/main/fhir-term/src/main/java/com/ibm/fhir/term/service/FHIRTermService.java)) loads a list of `FHIRTermServiceProvider` instances from the ServiceLoader and includes an instance of the `DefaultTermServiceProvider`. Client code (Java) that requires terminology capabilities should access them via the `FHIRTermService` singleton facade. Here is an example:
+
+```java
+ValueSet valueSet = ValueSetSupport.getValueSet("http://ibm.com/fhir/ValueSet/vs1");
+Coding coding = Coding.builder()
+        .system(Uri.of("http://ibm.com/fhir/CodeSystem/cs1"))
+        .version(string("1.0.0"))
+        .code(Code.of("a")
+        .display(string("concept a")
+        .build();
+ValidationOutcome outcome = FHIRTermService.getInstance().validateCode(valueSet, coding);
 ```
 
 The `expand `, `lookup`, `validateCode` (CodeSystem), `validateCode` (ValueSet), and `translate` methods support the passing of optional parameters (e.g. `ExpansionParameters`, `LookupParameters`, etc.). Many of the methods also return an "outcome" object. These "parameter" and "outcome" objects are modeled after the input/output parameters specified in the terminology operations from the FHIR Terminology module: [http://hl7.org/fhir/terminology-module.html](http://hl7.org/fhir/terminology-module.html).
@@ -47,24 +61,7 @@ Parameters parameters = outcome.toParameters();
 
 This bridge to/from the `Parameters` resource enables implementers to build both native implementations of the SPI and implementations that access an existing external terminology service.
 
-## Default Terminology Service Provider Implementation
-
-The default implementation of `FHIRTermServiceProvider` ([DefaultTermServiceProvider](https://github.com/IBM/FHIR/blob/main/fhir-term/src/main/java/com/ibm/fhir/term/service/provider/DefaultTermServiceProvider.java)) leverages terminology resources (`CodeSystem`, `ValueSet`, and `ConceptMap`) that have been made available through the FHIR registry module ([fhir-registry](https://github.com/IBM/FHIR/tree/main/fhir-registry)). It supports `CodeSystem` resources with *complete* content (`CodeSystem.content = 'complete'`) and `ValueSet` resources that reference `CodeSystem` resources that have complete content. The default implementation does not support for optional parameters (e.g. `ExpansionParameters`, `TranslationParameters`, `ValidationParameters`, etc.).
-
-## FHIR Terminology Service Singleton facade
-
-The FHIR Terminology Service Singleton facade ([FHIRTermService](https://github.com/IBM/FHIR/blob/main/fhir-term/src/main/java/com/ibm/fhir/term/service/FHIRTermService.java)) loads a `FHIRTermServiceProvider` from the ServiceLoader, if one exists. Otherwise, it will instantiate a `DefaultTermServiceProvider`. Other FHIR server components and user code (Java) that requires terminology capabilities should access them via the `FHIRTermService` singleton facade. Here is an example:
-
-```java
-ValueSet valueSet = ValueSetSupport.getValueSet("http://ibm.com/fhir/ValueSet/vs1");
-Coding coding = Coding.builder()
-        .system(Uri.of("http://ibm.com/fhir/CodeSystem/cs1"))
-        .version(string("1.0.0"))
-        .code(Code.of("a")
-        .display(string("concept a")
-        .build();
-ValidationOutcome outcome = FHIRTermService.getInstance().validateCode(valueSet, coding);
-```
+NOTE: The current implementation does not support for optional parameters (e.g. `ExpansionParameters`, `TranslationParameters`, `ValidationParameters`, etc.).
 
 ## FHIR Server Terminology Extended Operations
 
@@ -99,3 +96,26 @@ Collection<FHIRPathNode> result = evaluator.evaluate("%terminologies.validateCod
 ```
 
 Additionally, the FHIRPath functions `subsumedBy` and `subsumes` have been implemented per: [http://hl7.org/fhir/fhirpath.html#functions](http://hl7.org/fhir/fhirpath.html#functions)
+
+## Graph Terminology Service Provider Implementation (experimental)
+
+The FHIR term graph module [fhir-term-graph](https://github.com/IBM/FHIR/tree/main/fhir-term-graph) provides an implementation of `FHIRTermServiceProvider` that is backed by a graph database ([JanusGraph](https://janusgraph.org)). The module also contains term graph loaders for SNOMED-CT Release Format 2 (RF2) files (SnomedTermGraphLoader), UMLS Rich Release Format (RRF) files (UMLSTermGraphLoader), and FHIR CodeSystem resources (CodeSystemTermGraphLoader). The GraphTermServiceProvider can be enabled through the `fhir-server-config.json` file per the configuration properties specified in the [FHIR Server User's Guide](https://ibm.github.io/FHIR/guides/FHIRServerUsersGuide#51-configuration-properties-reference). Example configuration:
+
+``` json
+        "term": {
+            "graphTermServiceProvider": {
+                "enabled": true,
+                "timeLimit": 30000,
+                "configuration": {
+                    "storage.backend": "cql",
+                    "storage.hostname": "127.0.0.1",
+                    "index.search.backend": "elasticsearch",
+                    "index.search.hostname": "127.0.0.1:9200",
+                    "storage.read-only": true,
+                    "query.batch": true,
+                    "query.batch-property-prefetch": true,
+                    "query.fast-property": true
+                }
+            }
+        }
+```

fhir-config/src/main/java/com/ibm/fhir/config/FHIRConfiguration.java

@@ -37,6 +37,11 @@ public class FHIRConfiguration {
     public static final String PROPERTY_EXTENDED_CODEABLE_CONCEPT_VALIDATION = "fhirServer/core/extendedCodeableConceptValidation";
     public static final String PROPERTY_DISABLED_OPERATIONS = "fhirServer/core/disabledOperations";
 
+    // Terminology service properties
+    public static final String PROPERTY_GRAPH_TERM_SERVICE_PROVIDER_ENABLED = "fhirServer/term/graphTermServiceProvider/enabled";
+    public static final String PROPERTY_GRAPH_TERM_SERVICE_PROVIDER_TIME_LIMIT = "fhirServer/term/graphTermServiceProvider/timeLimit";
+    public static final String PROPERTY_GRAPH_TERM_SERVICE_PROVIDER_CONFIGURATION = "fhirServer/term/graphTermServiceProvider/configuration";
+
     // Resources properties
     public static final String PROPERTY_RESOURCES = "fhirServer/resources";
     public static final String PROPERTY_FIELD_RESOURCES_OPEN = "open";

fhir-parent/pom.xml

@@ -47,6 +47,7 @@
         <module>../fhir-model</module>
         <module>../fhir-registry</module>
         <module>../fhir-term</module>
+        <module>../fhir-term-graph</module>
         <module>../fhir-path</module>
         <module>../fhir-profile</module>
         <module>../fhir-validation</module>
@@ -438,6 +439,36 @@
                 <artifactId>commons-text</artifactId>
                 <version>1.9</version>
             </dependency>
+            <dependency>
+                <groupId>org.janusgraph</groupId>
+                <artifactId>janusgraph-core</artifactId>
+                <version>0.5.3</version>
+            </dependency>
+            <dependency>
+                <groupId>org.janusgraph</groupId>
+                <artifactId>janusgraph-berkeleyje</artifactId>
+                <version>0.5.3</version>
+            </dependency>
+            <dependency>
+                <groupId>org.janusgraph</groupId>
+                <artifactId>janusgraph-cql</artifactId>
+                <version>0.5.3</version>
+            </dependency>
+            <dependency>
+                <groupId>org.janusgraph</groupId>
+                <artifactId>janusgraph-lucene</artifactId>
+                <version>0.5.3</version>
+            </dependency>
+            <dependency>
+                <groupId>org.janusgraph</groupId>
+                <artifactId>janusgraph-es</artifactId>
+                <version>0.5.3</version>
+            </dependency>
+            <dependency>
+                <groupId>org.apache.tinkerpop</groupId>
+                <artifactId>gremlin-driver</artifactId>
+                <version>3.4.6</version>
+            </dependency>
         </dependencies>
     </dependencyManagement>