001package org.hl7.fhir.dstu2.utils;
002
003import org.hl7.fhir.dstu2.model.Base;
004import org.hl7.fhir.dstu2.model.ExpressionNode;
005import org.hl7.fhir.dstu2.model.ExpressionNode.TypeDetails;
006import org.hl7.fhir.dstu2.model.Type;
007import org.hl7.fhir.exceptions.PathEngineException;
008import org.hl7.fhir.utilities.fhirpath.FHIRPathConstantEvaluationMode;
009
010import java.util.List;
011
012// if the fhir path expressions are allowed to use constants beyond those
013// defined in the specification
014// the application can implement them by providing a constant resolver
015public interface IHostApplicationServices {
016  public class FunctionDetails {
017    private String description;
018    private int minParameters;
019    private int maxParameters;
020
021    public FunctionDetails(String description, int minParameters, int maxParameters) {
022      super();
023      this.description = description;
024      this.minParameters = minParameters;
025      this.maxParameters = maxParameters;
026    }
027
028    public String getDescription() {
029      return description;
030    }
031
032    public int getMinParameters() {
033      return minParameters;
034    }
035
036    public int getMaxParameters() {
037      return maxParameters;
038    }
039
040  }
041
042
043  /**
044   * A constant reference - e.g. a reference to a name that must be resolved in context.
045   *
046   * resolveConstant is invoked under 3 different circumstances, which are reflected in the mode parameter:
047   *  * an explicit constant of the form %{token}, where the token isn't a known internal constant
048   *  * 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
049   *  * at the start of evaluating an expression if the focus provided by the application when invoking the expression is {}
050   *
051   * The return value is a List<Base> - a collection, though most constants are singleton values
052   *
053   * note that variables created using defineVariable() in the FHIRPath expressions will not be processed by resolveConstant (or resolveConstantType)
054   *
055   * @param appContext - application context passed into the FHIRPath engine when first executed
056   * @param name - name reference to resolve. if mode = EXPLICIT, the % will NOT be in the name
057   * @param mode - what situation the reference comes from - see the documentation for @FHIRPathConstantEvaluationMode
058   * @return the value of the constant , or an empty list, though the host application can choose to throw an exception
059   */
060  public List<Base> resolveConstant(FHIRPathEngine engine, Object appContext, String name, FHIRPathConstantEvaluationMode mode) throws PathEngineException;
061
062
063  /**
064   * Compile time support for a constant reference - e.g. a reference to a name that must be resolved in context.
065   *
066   * resolveConstant is invoked under 3 different circumstances, which are reflected in the mode parameter:
067   *  * an explicit constant of the form %{token}, where the token isn't a known internal constant
068   *  * 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
069   *  * at the start of evaluating an expression if the focus provided by the application when invoking the expression is {}
070   *
071   * The return value is a TypeDetails - a collection, though most constants are singleton values
072   *
073   * note that variables created using defineVariable() in the FHIRPath expressions will not be processed by resolveConstant (or resolveConstantType)
074   *
075   * @param appContext - application context passed into the FHIRPath engine when first executed
076   * @param name - name reference to resolve. if mode = EXPLICIT, the % will NOT be in the name
077   * @param mode - what situation the reference comes from - see the documentation for @FHIRPathConstantEvaluationMode
078   * @return the type of the constant, or null, though the host application can choose to throw an exception
079   */
080  public TypeDetails resolveConstantType(FHIRPathEngine engine, Object appContext, String name, FHIRPathConstantEvaluationMode mode) throws PathEngineException;
081
082
083  public boolean Log(String argument, List<Base> focus);
084
085  // extensibility for functions
086
087  /**
088   * @param functionName
089   * @return null if the function is not known
090   */
091  public FunctionDetails resolveFunction(String functionName);
092
093  /**
094   * Check the function parameters, and throw an error if they are incorrect, or
095   * return the type for the function
096   *
097   * @param functionName
098   * @param parameters
099   * @return
100   */
101  public ExpressionNode.TypeDetails checkFunction(Object appContext, String functionName, List<ExpressionNode.TypeDetails> parameters)
102    throws PathEngineException;
103
104  /**
105   * @param appContext
106   * @param functionName
107   * @param parameters
108   * @return
109   */
110  public List<Base> executeFunction(Object appContext, String functionName, List<List<Base>> parameters);
111}