Package com.appiancorp.suiteapi.expression

Interface ExpressionService

All Superinterfaces:
com.appiancorp.services.ContextSensitiveService, Service
public interface ExpressionService extends com.appiancorp.services.ContextSensitiveService
Defines service methods related to the use of expressions within the application.

Expressions are configured at design-time within the process application to perform execution-time calculations. For instance, it may be useful to append a timestamp to a process name when it is started - this can be accomplished using the following expression for the process display name at design time: "concatenate("MyProcessName_", now())", where "now()" is a function which returns the current time, and "concatenate" is a function which appends a list of arguments.

Java will call prepareExpression(java.lang.String) or prepareModifyExpression(java.lang.String, java.lang.String, java.lang.String) to register an expression to be evaluated with the expression engine. Java should then call evaluateExpression(java.lang.Long, com.appiancorp.suiteapi.process.TypedVariable[]) or evaluateExpressionType(java.lang.Long, com.appiancorp.suiteapi.process.TypedVariable[], int) to attempt evaluation of the expression. If the expression engine encounters a sub-expression within the expression that it does not recognize, these methods will return a PartialResult that specifies 1) the name of the function that could not be identified (via the function field) and 2) the parameters that were passed to the expression engine for the unidentified function (via the functionParameters field). This allows Java to specify and evaluate its own custom expressions, which are not known to the expression engine. After evaluation of the sub-expression (see ExpressionEvaluationService), the expression engine can continue evaluating the entire expression via a call to continueFunction(java.lang.Long, com.appiancorp.suiteapi.process.TypedVariable), passing as an argument the result which was evaluated in Java. Or, if evaluation of the sub-expression fails, Java can discontinue evaluation of the expression by calling cancelFunction(java.lang.Long, java.lang.String). If the expression engine recognizes all elements of the expression that is passed via evaluateExpression(java.lang.Long, com.appiancorp.suiteapi.process.TypedVariable[]) or evaluateExpressionType(java.lang.Long, com.appiancorp.suiteapi.process.TypedVariable[], int), these methods will return a PartialResult with the result field populated. This represents the result of the expression evaluation.

Methods of service classes can all throw the unchecked exception ServiceException if any system-level error (for example, server failure) occurs, and will in general throw a checked exception (InvalidXXXException) when an entity to be retrieved is inaccessible, instead of returning null. Exceptions to this paradigm (including the use of ResultList as described below) are noted. All checked exceptions extend AppianException.

It may be necessary to retrieve a subset of results as opposed to an entire collection, and also to sort the subset by some property of the returned object. "Paging" methods which return a ResultPage are provided in certain instances for this purpose. The ResultPage will contain the sorted subset of results (via Result.getResults()), and the total number of items in the available result set (via ResultPage.getAvailableItems()).

It may also be necessary to retrieve some results, even if all results cannot be retrieved (for instance, some of the entities corresponding to a list of entity IDs may no longer exist). Methods which return a ResultList are provided for this purpose. The Result.getResults() method in this case will return all results which can be retrieved. In addition, there will be a list of result codes (ResultList.getResultCodes()) that represent the successful retrieval of an entity, or, if the entity could not be retrieved, the reason for the failure. See the CODE_XXX constants in ResultList for details.

See Also:
  • ExpressionEvaluationService

  • Field Details

    • prepareExpression$UPDATES

      static final boolean prepareExpression$UPDATES
      See Also:

    • prepareModifyExpression$UPDATES

      static final boolean prepareModifyExpression$UPDATES
      See Also:

    • evaluateExpression$UPDATES

      static final boolean evaluateExpression$UPDATES
      See Also:

    • evaluateExpressionType$UPDATES

      static final boolean evaluateExpressionType$UPDATES
      See Also:

    • validateExpression$UPDATES

      static final boolean validateExpression$UPDATES
      See Also:

    • continueFunction$UPDATES

      static final boolean continueFunction$UPDATES
      See Also:

    • cancelFunction$UPDATES

      static final boolean cancelFunction$UPDATES
      See Also:

    • getDefaultFormat$UPDATES

      static final boolean getDefaultFormat$UPDATES
      See Also:

    • setDefaultFormat$UPDATES

      static final boolean setDefaultFormat$UPDATES
      See Also:

    • getDisplayFormatForLocale$UPDATES

      static final boolean getDisplayFormatForLocale$UPDATES
      See Also:

    • setDisplayFormatForLocale$UPDATES

      static final boolean setDisplayFormatForLocale$UPDATES
      See Also:

    • getDisplayFormatsForLocales$UPDATES

      static final boolean getDisplayFormatsForLocales$UPDATES
      See Also:

    • setDisplayFormatsForLocales$UPDATES

      static final boolean setDisplayFormatsForLocales$UPDATES
      See Also:

  • Method Details

    • prepareExpression

      @Deprecated Long prepareExpression(String textToEvaluate_) throws ExpressionException
      Deprecated.
      see ProcessDesignService.evaluateExpression; it handles the full expression lifecycle
      Constructs an expression and returns the ID of the expression constructed from the text argument. The expression can then be evaluated by evaluateExpression(java.lang.Long, com.appiancorp.suiteapi.process.TypedVariable[]) or evaluateExpressionType(java.lang.Long, com.appiancorp.suiteapi.process.TypedVariable[], int)
      Parameters:
      textToEvaluate_ - the expression to be evaluated
      Returns:
      expression ID to be passed to the one of the evaluate methods
      Throws:
      ExpressionException - if the expression is invalid.
      ServiceException - if any system-level error occurs

    • prepareModifyExpression

      @Deprecated Long prepareModifyExpression(String variable_, String operator_, String textToEvaluate_) throws ExpressionException
      Deprecated.
      see ProcessDesignService.evaluateExpression; it handles the full expression lifecycle
      Constructs an expression and returns the ID of the expression constructed from the String arguments. The method differs from prepareExpression(java.lang.String) in that the variable and operator are already separated from the rest of the expression. E.g. a:1+2, a is the assignment variable, : the assignment operator and a will be set to be 3. "a:1+2" would be the argument passed to prepareExpression(java.lang.String), but "a", ":", "1+2" would be the respective arguments to prepareModifyExpression Supported operators are:
      • : Direct Modification
      • +: Addition Modification
      • -: Subtraction Modification
      • *: Multiplication Modification
      • /: Division Modification
      • ^: Exponentiation Modification
      • &: Concatenation Modification
      Parameters:
      variable_ - the name of the variable that will be assigned.
      operator_ - the assignment operator for the expression
      textToEvaluate_ - the expression to be evaluated in String format.
      Returns:
      expression ID to be passed to the one of the evaluate methods
      Throws:
      ExpressionException - if the expression is invalid.
      ServiceException - if any system-level error occurss

    • evaluateExpression

      @Deprecated PartialResult evaluateExpression(Long expressionId_, TypedVariable[] parameters_) throws ExpressionException, InvalidExpressionException
      Deprecated.
      see ProcessDesignService.evaluateExpression; it handles the full expression lifecycle
      Evaluates the expression with the given ID, and returns a final result or a function for Java to evaluate.

      This method must always be preceded by a call to prepareExpression(java.lang.String) or prepareModifyExpression(java.lang.String, java.lang.String, java.lang.String)

      NOTE: This function should be called first with parameters_ as an empty array. If the result field of the returned PartialResult is null, then this method should be called again with parameters_ set to be the functionParameters field of the returned PartialResult.

      Parameters:
      expressionId_ - the unique id of expression being evaluated
      parameters_ - the array of parameters to the expression with the given ID
      Returns:
      a PartialResult that may contain a final result or a function for Java to evaluate
      Throws:
      ExpressionException - if the expression is invalid.
      InvalidExpressionException - if the expression with the given ID does not exist
      ServiceException - if any system-level error occurs

    • evaluateExpressionType

      @Deprecated PartialResult evaluateExpressionType(Long expressionId_, TypedVariable[] parameters_, int resultType_) throws ExpressionException, InvalidExpressionException
      Deprecated.
      see ProcessDesignService.evaluateExpression; it handles the full expression lifecycle
      Evaluates the expression with the given ID, and returns a final result or a function for Java to evaluate.

      This method is the same as evaluateExpression(java.lang.Long, com.appiancorp.suiteapi.process.TypedVariable[]) except the result (if any) within the PartialResult returned will be cast to the given resultType.

      NOTE: This function should be called first with parameters_ as an empty array. If the result field of the returned PartialResult is null, then this method should be called again with parameters_ set to be the functionParameters field of the returned PartialResult.

      Parameters:
      expressionId_ - the unique id of expression being evaluated
      parameters_ - the array of parameters to the expression with the given ID
      resultType_ - the type for the returned PartialResult. This is one of the object types in TypedVariable
      Returns:
      a PartialResult of the given type that may contain a final result or a function for Java to evaluate
      Throws:
      ExpressionException - if the expression is invalid.
      InvalidExpressionException - if the expression with the given ID does not exist
      ServiceException - if any system-level error occurs

    • validateExpression

      void validateExpression(String textToEvaluate_) throws ExpressionException
      Validates the expression. If the expression is not valid, an exception will be thrown.
      Parameters:
      textToEvaluate_ - the expression to validate
      Throws:
      ExpressionException - if the expression is invalid.
      ServiceException - if any system-level error occurs

    • continueFunction

      @Deprecated void continueFunction(Long expressionId_, TypedVariable result_) throws InvalidExpressionException
      Deprecated.
      see ProcessDesignService.evaluateExpression
      Continue the evaluation of an expression.

      After Java successfully evaluates a sub-expression, it returns the result and calls continueFunction to carry on evaluation of the expression with the given ID.

      NOTE: This method should only be used from within the ExpressionEvaluationService

      Parameters:
      expressionId_ - the unique ID of expression being evaluated
      result_ - the result of the sub-expression that Java has evaluated
      Throws:
      InvalidExpressionException - if the expression does not exist
      ServiceException - if any system-level error occurs

    • cancelFunction

      @Deprecated void cancelFunction(Long expressionId_, String reason_) throws InvalidExpressionException
      Deprecated.
      see ProcessDesignService.evaluateExpression; it handles the full expression lifecycle
      Cancel the evaluation of an expression

      If Java evaluation of the sub-expression fails, it returns an appropriate message as the reason and calls cancelFunction to terminate the evaluation of the expression with the given ID.

      NOTE: This method should only be used from within the ExpressionEvaluationService

      Parameters:
      expressionId_ - the unique ID of expression being evaluated
      reason_ - the error that Java encountered while evaluating the expression
      Throws:
      InvalidExpressionException - if the expression does not exist
      ServiceException - if any system-level error occurs

    • getDefaultFormat

      String getDefaultFormat(String name_) throws InvalidParameterException, NullPointerException
      Retrieves the default display format for a given format name.
      Parameters:
      name_ - A string identifying the type of display format, one of: "date", "time", or "timezone".
      Returns:
      Returns the display format for the given format name.
      Throws:
      InvalidParameterException
      NullPointerException

    • setDefaultFormat

      void setDefaultFormat(String name_, String format_) throws InvalidParameterException, NullPointerException
      Sets the default display format for a given format name.
      Parameters:
      name_ - A string identifying the type of display format, one of: "date", "time", or "timezone".
      format_ - The display format to use for the given format name.
      Throws:
      InvalidParameterException
      NullPointerException

    • getDisplayFormatForLocale

      LocaleDisplayFormat getDisplayFormatForLocale(LocaleDisplayFormat ldf_) throws InvalidParameterException, NullPointerException
      Retrieves the display format information for the locale set in the LocaleDisplayFormat parameter object. Only the locale field should be set on the ldf_ parameter. If a previously set LocaleDisplayFormat object exists with the specified locale, the object will be returned with all of the LocaleDisplayFormat object's fields set.
      Parameters:
      ldf_ - A LocaleDisplayFormat object that has only the locale field set
      Throws:
      NullPointerException - if LocaleDisplayFormat parameter is null
      InvalidParameterException - if the locale field for the parameter is invalid

    • setDisplayFormatForLocale

      void setDisplayFormatForLocale(LocaleDisplayFormat ldf_) throws InvalidParameterException, NullPointerException
      Sets a display format for the locale set in the LocaleDisplayFormat parameter object. All fields of the ldf_ parameter must be set and may not be null.
      Parameters:
      ldf_ - A LocaleDisplayFormat object that has all fields set
      Throws:
      NullPointerException - if LocaleDisplayFormat parameter is null
      InvalidParameterException - if a parameter set in the LocaleDisplayFormat object is invalid

    • getDisplayFormatsForLocales

      LocaleDisplayFormat[] getDisplayFormatsForLocales(LocaleDisplayFormat[] ldf_) throws InvalidParameterException, NullPointerException
      Receives an array of LocaleDisplayFormat objects that have only the locale field set for each object. For each object in the array, the remaining fields are set if a previously set LocaleDisplayFormat object matches the locale set in the array object. An array of the same length is returned with all fields set instead of just the locale.
      Parameters:
      ldf_ - An array of LocaleDisplayFormat objects that have only the locale field set
      Throws:
      NullPointerException - if LocaleDisplayFormat array parameter is null
      InvalidParameterException - if the locale set in one of the LocaleDisplayFormat objects invalid

    • setDisplayFormatsForLocales

      void setDisplayFormatsForLocales(LocaleDisplayFormat[] ldf_) throws InvalidParameterException, NullPointerException
      Receives an array of LocaleDisplayFormat objects and sets a display format for the locale set in each of the LocaleDisplayFormat objects. All fields of each of the LocaleDisplayFormat objects in the ldf_ parameter must be set and may not be null.
      Parameters:
      ldf_ - An array of LocaleDisplayFormat objects that have all fields set
      Throws:
      NullPointerException - if LocaleDisplayFormat array parameter is null
      InvalidParameterException - if a parameter set in one of the LocaleDisplayFormat objects is invalid