001package org.hl7.fhir.r4.fhirpath;
002
003import org.hl7.fhir.exceptions.FHIRException;
004import org.hl7.fhir.exceptions.PathEngineException;
005import org.hl7.fhir.r4.model.Base;
006import org.hl7.fhir.r4.model.ValueSet;
007import org.hl7.fhir.utilities.fhirpath.FHIRPathConstantEvaluationMode;
008
009import java.util.List;
010
011/**
012 * This interface allows the application making use of a FHIRPathEngine to provide
013 * additional services that can be used in the FHIRPath statements. The services fall into
014 * two categories: extending the FHIRPath engine with types, constants and functions, and
015 * performing work that the FHIRPath engine doesn't know how to do itself
016 *
017 * Functionality:
018 *  * resolveConstant()/resolveConstantType() - register constants
019 *  * log() - do something when .log() is used in the FHIRPath statement
020 *  * resolveFunction() / checkFunction() / executeFunction() - allow the application to define FHIRPath functions of it's own
021 *  * resolveReference() - called when a FHIRPath statement uses 'resolve()' so the host application can attempt to resolve the reference
022 *  * resolveValueSet() - called when memberOf() is used
023 *  * conformsToProfile() - check that the content conforms to the stated profile. Used by the ValidationEngine - not generally suitable for applications to provide their own interface
024 *  * paramIsType() - used when the FHIRPath statement
025 *
026 *  Note that his used to be called IEvaluationContext in the FHIRPathEngine class, but was renamed
027 *  due to a broken interface - see comments at https://github.com/hapifhir/org.hl7.fhir.core/releases/tag/6.6.0
028 */
029
030public interface IHostApplicationServices {
031
032
033  /**
034   * A constant reference - e.g. a reference to a name that must be resolved in context.
035   *
036   * resolveConstant is invoked under 3 different circumstances, which are reflected in the mode parameter:
037   *  * an explicit constant of the form %{token}, where the token isn't a known internal constant
038   *  * every evaluation of any expression to allow the Host Application to decide whether to interpret the expression as a constant even if it is not explicitly a constant
039   *  * at the start of evaluating an expression if the focus provided by the application when invoking the expression is {}
040   *
041   * The return value is a List<Base> - a collection, though most constants are singleton values
042   *
043   * note that variables created using defineVariable() in the FHIRPath expressions will not be processed by resolveConstant (or resolveConstantType)
044   *
045   * @param appContext - application context passed into the FHIRPath engine when first executed
046   * @param name - name reference to resolve. if mode = EXPLICIT, the % will NOT be in the name
047   * @param mode - what situation the reference comes from - see the documentation for @FHIRPathConstantEvaluationMode
048   * @return the value of the constant , or an empty list, though the host application can choose to throw an exception
049   */
050  public List<Base> resolveConstant(FHIRPathEngine engine, Object appContext, String name, FHIRPathConstantEvaluationMode mode) throws PathEngineException;
051
052
053  /**
054   * Compile time support for a constant reference - e.g. a reference to a name that must be resolved in context.
055   *
056   * resolveConstant is invoked under 3 different circumstances, which are reflected in the mode parameter:
057   *  * an explicit constant of the form %{token}, where the token isn't a known internal constant
058   *  * every evaluation of any expression to allow the Host Application to decide whether to interpret the expression as a constant even if it is not explicitly a constant
059   *  * at the start of evaluating an expression if the focus provided by the application when invoking the expression is {}
060   *
061   * The return value is a TypeDetails - a collection, though most constants are singleton values
062   *
063   * note that variables created using defineVariable() in the FHIRPath expressions will not be processed by resolveConstant (or resolveConstantType)
064   *
065   * @param appContext - application context passed into the FHIRPath engine when first executed
066   * @param name - name reference to resolve. if mode = EXPLICIT, the % will NOT be in the name
067   * @param mode - what situation the reference comes from - see the documentation for @FHIRPathConstantEvaluationMode
068   * @return the type of the constant, or null, though the host application can choose to throw an exception
069   */
070  public TypeDetails resolveConstantType(FHIRPathEngine engine, Object appContext, String name, FHIRPathConstantEvaluationMode mode) throws PathEngineException;
071
072  /**
073   * when the .log() function is called
074   *
075   * @param argument
076   * @param focus
077   * @return
078   */
079  public boolean log(String argument, List<Base> focus);
080
081  // extensibility for functions
082
083  /**
084   * @param functionName
085   * @return null if the function is not known
086   */
087  public FHIRPathUtilityClasses.FunctionDetails resolveFunction(FHIRPathEngine engine, String functionName);
088
089  /**
090   * Check the function parameters, and throw an error if they are incorrect, or return the type for the function
091   *
092   * @param functionName
093   * @param parameters
094   * @return
095   */
096  public TypeDetails checkFunction(FHIRPathEngine engine, Object appContext, String functionName, TypeDetails focus, List<TypeDetails> parameters) throws PathEngineException;
097
098  /**
099   * @param appContext
100   * @param functionName
101   * @param parameters
102   * @return
103   */
104  public List<Base> executeFunction(FHIRPathEngine engine, Object appContext, List<Base> focus, String functionName, List<List<Base>> parameters);
105
106  /**
107   * Implementation of resolve() function. Passed a string, return matching resource, if one is known - else null
108   *
109   * @param url the reference (Reference.reference or the value of the canonical
110   * @return
111   * @throws FHIRException
112   * @appContext - passed in by the host to the FHIRPathEngine
113   */
114  public Base resolveReference(FHIRPathEngine engine, Object appContext, String url, Base refContext) throws FHIRException;
115
116  public boolean conformsToProfile(FHIRPathEngine engine, Object appContext, Base item, String url) throws FHIRException;
117
118  /*
119   * return the value set referenced by the url, which has been used in memberOf()
120   */
121  public ValueSet resolveValueSet(FHIRPathEngine engine, Object appContext, String url);
122
123  /**
124   * For the moment, there can only be one parameter if it's a type parameter
125   *
126   * @param name
127   * @return true if it's a type parameter
128   */
129  public boolean paramIsType(String name, int index);
130}