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.ValueSetExpansionOptions;
025import ca.uhn.fhir.jpa.api.dao.IFhirResourceDaoCodeSystem;
026import ca.uhn.fhir.jpa.entity.TermConcept;
027import ca.uhn.fhir.jpa.entity.TermValueSet;
028import ca.uhn.fhir.jpa.model.entity.ResourceTable;
029import ca.uhn.fhir.jpa.term.IValueSetConceptAccumulator;
030import ca.uhn.fhir.rest.api.server.RequestDetails;
031import ca.uhn.fhir.util.FhirVersionIndependentConcept;
032import jakarta.annotation.Nonnull;
033import jakarta.annotation.Nullable;
034import org.hl7.fhir.instance.model.api.IBaseCoding;
035import org.hl7.fhir.instance.model.api.IBaseDatatype;
036import org.hl7.fhir.instance.model.api.IBaseResource;
037import org.hl7.fhir.instance.model.api.IIdType;
038import org.hl7.fhir.instance.model.api.IPrimitiveType;
039import org.hl7.fhir.r4.model.CodeSystem;
040import org.hl7.fhir.r4.model.ValueSet;
041import org.springframework.transaction.annotation.Transactional;
042
043import java.util.List;
044import java.util.Optional;
045import java.util.Set;
046
047/**
048 * This interface is the "read" interface for the terminology service. It handles things like
049 * lookups, code validations, expansions, concept mappings, etc.
050 * <p>
051 * It is intended to only handle read operations, leaving various write operations to
052 * other services within the terminology service APIs.
053 * (Note that at present, a few write operations remain here- they should be moved but haven't
054 * been moved yet)
055 * </p>
056 */
057public interface ITermReadSvc extends IValidationSupport {
058
059        ValueSet expandValueSet(
060                        @Nullable ValueSetExpansionOptions theExpansionOptions, @Nonnull String theValueSetCanonicalUrl);
061
062        ValueSet expandValueSet(
063                        @Nullable ValueSetExpansionOptions theExpansionOptions, @Nonnull ValueSet theValueSetToExpand);
064
065        void expandValueSet(
066                        @Nullable ValueSetExpansionOptions theExpansionOptions,
067                        ValueSet theValueSetToExpand,
068                        IValueSetConceptAccumulator theValueSetCodeAccumulator);
069
070        /**
071         * Version independent
072         */
073        IBaseResource expandValueSet(
074                        @Nullable ValueSetExpansionOptions theExpansionOptions, IBaseResource theValueSetToExpand);
075
076        void expandValueSet(
077                        @Nullable ValueSetExpansionOptions theExpansionOptions,
078                        IBaseResource theValueSetToExpand,
079                        IValueSetConceptAccumulator theValueSetCodeAccumulator);
080
081        List<FhirVersionIndependentConcept> expandValueSetIntoConceptList(
082                        ValueSetExpansionOptions theExpansionOptions, String theValueSetCanonicalUrl);
083
084        Optional<TermConcept> findCode(String theCodeSystem, String theCode);
085
086        List<TermConcept> findCodes(String theCodeSystem, List<String> theCodes);
087
088        Set<TermConcept> findCodesAbove(
089                        Long theCodeSystemResourcePid, Long theCodeSystemResourceVersionPid, String theCode);
090
091        List<FhirVersionIndependentConcept> findCodesAbove(String theSystem, String theCode);
092
093        List<FhirVersionIndependentConcept> findCodesAboveUsingBuiltInSystems(String theSystem, String theCode);
094
095        Set<TermConcept> findCodesBelow(
096                        Long theCodeSystemResourcePid, Long theCodeSystemResourceVersionPid, String theCode);
097
098        List<FhirVersionIndependentConcept> findCodesBelow(String theSystem, String theCode);
099
100        List<FhirVersionIndependentConcept> findCodesBelowUsingBuiltInSystems(String theSystem, String theCode);
101
102        CodeSystem fetchCanonicalCodeSystemFromCompleteContext(String theSystem);
103
104        void deleteValueSetAndChildren(ResourceTable theResourceTable);
105
106        void storeTermValueSet(ResourceTable theResourceTable, ValueSet theValueSet);
107
108        IFhirResourceDaoCodeSystem.SubsumesResult subsumes(
109                        IPrimitiveType<String> theCodeA,
110                        IPrimitiveType<String> theCodeB,
111                        IPrimitiveType<String> theSystem,
112                        IBaseCoding theCodingA,
113                        IBaseCoding theCodingB);
114
115        void preExpandDeferredValueSetsToTerminologyTables();
116
117        /**
118         * Version independent
119         */
120        @Transactional()
121        CodeValidationResult validateCodeIsInPreExpandedValueSet(
122                        ConceptValidationOptions theOptions,
123                        IBaseResource theValueSet,
124                        String theSystem,
125                        String theCode,
126                        String theDisplay,
127                        IBaseDatatype theCoding,
128                        IBaseDatatype theCodeableConcept);
129
130        boolean isValueSetPreExpandedForCodeValidation(ValueSet theValueSet);
131
132        /**
133         * Version independent
134         */
135        boolean isValueSetPreExpandedForCodeValidation(IBaseResource theValueSet);
136
137        String invalidatePreCalculatedExpansion(IIdType theValueSetId, RequestDetails theRequestDetails);
138
139        /**
140         * Version independent
141         */
142        Optional<TermValueSet> findCurrentTermValueSet(String theUrl);
143
144        /**
145         * Version independent
146         */
147        Optional<IBaseResource> readCodeSystemByForcedId(String theForcedId);
148
149        /**
150         * Version independent
151         * Recreates freetext indexes for TermConcept and nested TermConceptProperty
152         */
153        ReindexTerminologyResult reindexTerminology() throws InterruptedException;
154}