001/*
002 * #%L
003 * HAPI FHIR JPA Server
004 * %%
005 * Copyright (C) 2014 - 2024 Smile CDR, Inc.
006 * %%
007 * Licensed under the Apache License, Version 2.0 (the "License");
008 * you may not use this file except in compliance with the License.
009 * You may obtain a copy of the License at
010 *
011 *      http://www.apache.org/licenses/LICENSE-2.0
012 *
013 * Unless required by applicable law or agreed to in writing, software
014 * distributed under the License is distributed on an "AS IS" BASIS,
015 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
016 * See the License for the specific language governing permissions and
017 * limitations under the License.
018 * #L%
019 */
020package ca.uhn.fhir.jpa.term.api;
021
022import ca.uhn.fhir.context.support.ConceptValidationOptions;
023import ca.uhn.fhir.context.support.IValidationSupport;
024import ca.uhn.fhir.context.support.ValidationSupportContext;
025import ca.uhn.fhir.context.support.ValueSetExpansionOptions;
026import ca.uhn.fhir.jpa.api.dao.IFhirResourceDaoCodeSystem;
027import ca.uhn.fhir.jpa.entity.TermConcept;
028import ca.uhn.fhir.jpa.entity.TermValueSet;
029import ca.uhn.fhir.jpa.model.entity.ResourceTable;
030import ca.uhn.fhir.jpa.term.IValueSetConceptAccumulator;
031import ca.uhn.fhir.rest.api.server.RequestDetails;
032import ca.uhn.fhir.util.FhirVersionIndependentConcept;
033import jakarta.annotation.Nonnull;
034import jakarta.annotation.Nullable;
035import org.hl7.fhir.instance.model.api.IBaseCoding;
036import org.hl7.fhir.instance.model.api.IBaseDatatype;
037import org.hl7.fhir.instance.model.api.IBaseResource;
038import org.hl7.fhir.instance.model.api.IIdType;
039import org.hl7.fhir.instance.model.api.IPrimitiveType;
040import org.hl7.fhir.r4.model.CodeSystem;
041import org.hl7.fhir.r4.model.ValueSet;
042import org.springframework.transaction.annotation.Transactional;
043
044import java.util.List;
045import java.util.Optional;
046import java.util.Set;
047
048/**
049 * This interface is the "read" interface for the terminology service. It handles things like
050 * lookups, code validations, expansions, concept mappings, etc.
051 * <p>
052 * It is intended to only handle read operations, leaving various write operations to
053 * other services within the terminology service APIs.
054 * (Note that at present, a few write operations remain here- they should be moved but haven't
055 * been moved yet)
056 * </p>
057 */
058public interface ITermReadSvc extends IValidationSupport {
059
060        ValueSet expandValueSet(
061                        @Nullable ValueSetExpansionOptions theExpansionOptions, @Nonnull String theValueSetCanonicalUrl);
062
063        ValueSet expandValueSet(
064                        @Nullable ValueSetExpansionOptions theExpansionOptions, @Nonnull ValueSet theValueSetToExpand);
065
066        void expandValueSet(
067                        @Nullable ValueSetExpansionOptions theExpansionOptions,
068                        ValueSet theValueSetToExpand,
069                        IValueSetConceptAccumulator theValueSetCodeAccumulator);
070
071        /**
072         * Version independent
073         */
074        IBaseResource expandValueSet(
075                        @Nullable ValueSetExpansionOptions theExpansionOptions, IBaseResource theValueSetToExpand);
076
077        void expandValueSet(
078                        @Nullable ValueSetExpansionOptions theExpansionOptions,
079                        IBaseResource theValueSetToExpand,
080                        IValueSetConceptAccumulator theValueSetCodeAccumulator);
081
082        List<FhirVersionIndependentConcept> expandValueSetIntoConceptList(
083                        ValueSetExpansionOptions theExpansionOptions, String theValueSetCanonicalUrl);
084
085        Optional<TermConcept> findCode(String theCodeSystem, String theCode);
086
087        List<TermConcept> findCodes(String theCodeSystem, List<String> theCodes);
088
089        Set<TermConcept> findCodesAbove(
090                        Long theCodeSystemResourcePid, Long theCodeSystemResourceVersionPid, String theCode);
091
092        List<FhirVersionIndependentConcept> findCodesAbove(String theSystem, String theCode);
093
094        List<FhirVersionIndependentConcept> findCodesAboveUsingBuiltInSystems(String theSystem, String theCode);
095
096        Set<TermConcept> findCodesBelow(
097                        Long theCodeSystemResourcePid, Long theCodeSystemResourceVersionPid, String theCode);
098
099        List<FhirVersionIndependentConcept> findCodesBelow(String theSystem, String theCode);
100
101        List<FhirVersionIndependentConcept> findCodesBelowUsingBuiltInSystems(String theSystem, String theCode);
102
103        CodeSystem fetchCanonicalCodeSystemFromCompleteContext(String theSystem);
104
105        void deleteValueSetAndChildren(ResourceTable theResourceTable);
106
107        void storeTermValueSet(ResourceTable theResourceTable, ValueSet theValueSet);
108
109        IFhirResourceDaoCodeSystem.SubsumesResult subsumes(
110                        IPrimitiveType<String> theCodeA,
111                        IPrimitiveType<String> theCodeB,
112                        IPrimitiveType<String> theSystem,
113                        IBaseCoding theCodingA,
114                        IBaseCoding theCodingB);
115
116        void preExpandDeferredValueSetsToTerminologyTables();
117
118        /**
119         * Version independent
120         */
121        @Transactional()
122        CodeValidationResult validateCodeIsInPreExpandedValueSet(
123                        ValidationSupportContext theValidationSupportContext,
124                        ConceptValidationOptions theOptions,
125                        IBaseResource theValueSet,
126                        String theSystem,
127                        String theCode,
128                        String theDisplay,
129                        IBaseDatatype theCoding,
130                        IBaseDatatype theCodeableConcept);
131
132        boolean isValueSetPreExpandedForCodeValidation(ValueSet theValueSet);
133
134        /**
135         * Version independent
136         */
137        boolean isValueSetPreExpandedForCodeValidation(IBaseResource theValueSet);
138
139        String invalidatePreCalculatedExpansion(IIdType theValueSetId, RequestDetails theRequestDetails);
140
141        /**
142         * Version independent
143         */
144        Optional<TermValueSet> findCurrentTermValueSet(String theUrl);
145
146        /**
147         * Version independent
148         */
149        Optional<IBaseResource> readCodeSystemByForcedId(String theForcedId);
150
151        /**
152         * Version independent
153         * Recreates freetext indexes for TermConcept and nested TermConceptProperty
154         */
155        ReindexTerminologyResult reindexTerminology() throws InterruptedException;
156}