001/*-
002 * #%L
003 * HAPI FHIR - Core Library
004 * %%
005 * Copyright (C) 2014 - 2025 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.fhirpath;
021
022import jakarta.annotation.Nonnull;
023import jakarta.annotation.Nullable;
024import org.hl7.fhir.instance.model.api.IBase;
025import org.hl7.fhir.instance.model.api.IIdType;
026
027import java.util.List;
028
029public interface IFhirPathEvaluationContext {
030
031        /**
032         * The is an adapter for org.hl7.fhir.utilities.fhirpath.FHIRPathConstantEvaluationMode. At present, it matches
033         * org.hl7.fhir.core 1-to-1.
034         * </br>
035         * Comments are provided here for convenience, but org.hl7.fhir.utilities.fhirpath.FHIRPathConstantEvaluationMode
036         * should be considered the source of truth.
037         *
038         */
039        public enum ConstantEvaluationMode {
040                EXPLICIT, // the FHIRPathEngine has encountered an explicit reference to a constant e.g. %{token} that it does
041                // not recognise internally
042                NOVALUE, // the FHIRPathEngine was invoked with no focus provided
043                IMPLICIT_BEFORE, // The FHIRPath engine is about to evaluate a named property reference, but the Host
044                // Application is being offered an opportunity to provide it's own value first
045                IMPLICIT_AFTER // The FHIRPath engine has evaluated a property and found nothing, and perhaps the Host
046                // Application wants to offer a value (constant fall through). This only happens if
047                // checkWithHostServicesBeforeHand is true on the FHIRPath engine
048        }
049
050        /**
051         * Evaluates the <code>resolve()</code> function and returns the target
052         * of the resolution.
053         *
054         * @param theReference The reference
055         * @param theContext The entity containing the reference. Note that this will be <code>null</code> for FHIR versions R4 and below.
056         */
057        default IBase resolveReference(@Nonnull IIdType theReference, @Nullable IBase theContext) {
058                return null;
059        }
060
061        /**
062         *
063         * @param theAppContext
064         * @param theName The name of the constant(s) to be resolved
065         * @param theConstantEvaluationMode
066         * @return
067         */
068        default List<IBase> resolveConstant(
069                        Object theAppContext, String theName, ConstantEvaluationMode theConstantEvaluationMode) {
070                return null;
071        }
072}