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, 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.