001package org.hl7.fhir.r5.fhirpath;
002
003import org.hl7.fhir.exceptions.FHIRException;
004import org.hl7.fhir.exceptions.PathEngineException;
005import org.hl7.fhir.r5.model.Base;
006import org.hl7.fhir.r5.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   * A constant reference - e.g. a reference to a name that must be resolved in context.
034   *
035   * resolveConstant is invoked under 3 different circumstances, which are reflected in the mode parameter:
036   *  * an explicit constant of the form %{token}, where the token isn't a known internal constant
037   *  * 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
038   *  * at the start of evaluating an expression if the focus provided by the application when invoking the expression is {}
039   *
040   * The return value is a List<Base> - a collection, though most constants are singleton values
041   *
042   * note that variables created using defineVariable() in the FHIRPath expressions will not be processed by resolveConstant (or resolveConstantType)
043   *
044   * @param appContext - application context passed into the FHIRPath engine when first executed
045   * @param name - name reference to resolve. if mode = EXPLICIT, the % will NOT be in the name
046   * @param mode - what situation the reference comes from - see the documentation for @FHIRPathConstantEvaluationMode
047   * @return the value of the constant , or an empty list, though the host application can choose to throw an exception
048   */
049  public List<Base> resolveConstant(FHIRPathEngine engine, Object appContext, String name, FHIRPathConstantEvaluationMode mode) throws PathEngineException;
050
051
052  /**
053   * Compile time support for a constant reference - e.g. a reference to a name that must be resolved in context.
054   *
055   * resolveConstant is invoked under 3 different circumstances, which are reflected in the mode parameter:
056   *  * an explicit constant of the form %{token}, where the token isn't a known internal constant
057   *  * 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
058   *  * at the start of evaluating an expression if the focus provided by the application when invoking the expression is {}
059   *
060   * The return value is a TypeDetails - a collection, though most constants are singleton values
061   *
062   * note that variables created using defineVariable() in the FHIRPath expressions will not be processed by resolveConstant (or resolveConstantType)
063   *
064   * @param appContext - application context passed into the FHIRPath engine when first executed
065   * @param name - name reference to resolve. if mode = EXPLICIT, the % will NOT be in the name
066   * @param mode - what situation the reference comes from - see the documentation for @FHIRPathConstantEvaluationMode
067   * @return the type of the constant, or null, though the host application can choose to throw an exception
068   */
069  public TypeDetails resolveConstantType(FHIRPathEngine engine, Object appContext, String name, FHIRPathConstantEvaluationMode mode) throws PathEngineException;
070
071  /**
072   * when the .log() function is called
073   *
074   * @param argument
075   * @param focus
076   * @return
077   */
078  public boolean log(String argument, List<Base> focus);
079
080  // extensibility for functions
081
082  /**
083   * @param functionName
084   * @return null if the function is not known
085   */
086  public FHIRPathUtilityClasses.FunctionDetails resolveFunction(FHIRPathEngine engine, String functionName);
087
088  /**
089   * Check the function parameters, and throw an error if they are incorrect, or return the type for the function
090   *
091   * @param functionName
092   * @param parameters
093   * @return
094   */
095  public TypeDetails checkFunction(FHIRPathEngine engine, Object appContext, String functionName, TypeDetails focus, List<TypeDetails> parameters) throws PathEngineException;
096
097  /**
098   * @param appContext
099   * @param functionName
100   * @param parameters
101   * @return
102   */
103  public List<Base> executeFunction(FHIRPathEngine engine, Object appContext, List<Base> focus, String functionName, List<List<Base>> parameters);
104
105  /**
106   * Implementation of resolve() function. Passed a string, return matching resource, if one is known - else null
107   *
108   * @param url the reference (Reference.reference or the value of the canonical
109   * @return
110   * @throws FHIRException
111   * @appContext - passed in by the host to the FHIRPathEngine
112   */
113  public Base resolveReference(FHIRPathEngine engine, Object appContext, String url, Base refContext) throws FHIRException;
114
115  public boolean conformsToProfile(FHIRPathEngine engine, Object appContext, Base item, String url) throws FHIRException;
116
117  /*
118   * return the value set referenced by the url, which has been used in memberOf()
119   */
120  public ValueSet resolveValueSet(FHIRPathEngine engine, Object appContext, String url);
121
122  /**
123   * For the moment, there can only be one parameter if it's a type parameter
124   *
125   * @param name
126   * @return true if it's a type parameter
127   */
128  public boolean paramIsType(String name, int index);
129}