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 Summary

Fields

Modifier and Type	Field and Description
static boolean	cancelFunction$UPDATES
static boolean	continueFunction$UPDATES
static boolean	evaluateExpression$UPDATES
static boolean	evaluateExpressionType$UPDATES
static boolean	getDefaultFormat$UPDATES
static boolean	getDisplayFormatForLocale$UPDATES
static boolean	getDisplayFormatsForLocales$UPDATES
static boolean	prepareExpression$UPDATES
static boolean	prepareModifyExpression$UPDATES
static boolean	setDefaultFormat$UPDATES
static boolean	setDisplayFormatForLocale$UPDATES
static boolean	setDisplayFormatsForLocales$UPDATES
static boolean	validateExpression$UPDATES

Fields inherited from interface com.appiancorp.services.ContextSensitiveService

SET_SERVICE_CONTEXT_METHOD_NAME

Method Summary

Modifier and Type	Method and Description
void	cancelFunction(java.lang.Long expressionId_, java.lang.String reason_) Deprecated. see ProcessDesignService.evaluateExpression; it handles the full expression lifecycle
void	continueFunction(java.lang.Long expressionId_, TypedVariable result_) Deprecated. see ProcessDesignService.evaluateExpression
PartialResult	evaluateExpression(java.lang.Long expressionId_, TypedVariable[] parameters_) Deprecated. see ProcessDesignService.evaluateExpression; it handles the full expression lifecycle
PartialResult	evaluateExpressionType(java.lang.Long expressionId_, TypedVariable[] parameters_, int resultType_) Deprecated. see ProcessDesignService.evaluateExpression; it handles the full expression lifecycle
java.lang.String	getDefaultFormat(java.lang.String name_) Retrieves the default display format for a given format name.
LocaleDisplayFormat	getDisplayFormatForLocale(LocaleDisplayFormat ldf_) Retrieves the display format information for the locale set in the LocaleDisplayFormat parameter object.
LocaleDisplayFormat[]	getDisplayFormatsForLocales(LocaleDisplayFormat[] ldf_) Receives an array of LocaleDisplayFormat objects that have only the locale field set for each object.
java.lang.Long	prepareExpression(java.lang.String textToEvaluate_) Deprecated. see ProcessDesignService.evaluateExpression; it handles the full expression lifecycle
java.lang.Long	prepareModifyExpression(java.lang.String variable_, java.lang.String operator_, java.lang.String textToEvaluate_) Deprecated. see ProcessDesignService.evaluateExpression; it handles the full expression lifecycle
void	setDefaultFormat(java.lang.String name_, java.lang.String format_) Sets the default display format for a given format name.
void	setDisplayFormatForLocale(LocaleDisplayFormat ldf_) Sets a display format for the locale set in the LocaleDisplayFormat parameter object.
void	setDisplayFormatsForLocales(LocaleDisplayFormat[] ldf_) Receives an array of LocaleDisplayFormat objects and sets a display format for the locale set in each of the LocaleDisplayFormat objects.
void	validateExpression(java.lang.String textToEvaluate_) Validates the expression.

Methods inherited from interface com.appiancorp.services.ContextSensitiveService

setServiceContext

Field Detail

prepareExpression$UPDATES

static final boolean prepareExpression$UPDATES

See Also:

Constant Field Values

prepareModifyExpression$UPDATES

static final boolean prepareModifyExpression$UPDATES

See Also:

Constant Field Values

evaluateExpression$UPDATES

static final boolean evaluateExpression$UPDATES

See Also:

Constant Field Values

evaluateExpressionType$UPDATES

static final boolean evaluateExpressionType$UPDATES

See Also:

Constant Field Values

validateExpression$UPDATES

static final boolean validateExpression$UPDATES

See Also:

Constant Field Values

continueFunction$UPDATES

static final boolean continueFunction$UPDATES

See Also:

Constant Field Values

cancelFunction$UPDATES

static final boolean cancelFunction$UPDATES

See Also:

Constant Field Values

getDefaultFormat$UPDATES

static final boolean getDefaultFormat$UPDATES

See Also:

Constant Field Values

setDefaultFormat$UPDATES

static final boolean setDefaultFormat$UPDATES

See Also:

Constant Field Values

getDisplayFormatForLocale$UPDATES

static final boolean getDisplayFormatForLocale$UPDATES

See Also:

Constant Field Values

setDisplayFormatForLocale$UPDATES

static final boolean setDisplayFormatForLocale$UPDATES

See Also:

Constant Field Values

getDisplayFormatsForLocales$UPDATES

static final boolean getDisplayFormatsForLocales$UPDATES

See Also:

Constant Field Values

setDisplayFormatsForLocales$UPDATES

static final boolean setDisplayFormatsForLocales$UPDATES

See Also:

Constant Field Values

Method Detail

prepareExpression

@Deprecated
java.lang.Long prepareExpression(java.lang.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
java.lang.Long prepareModifyExpression(java.lang.String variable_,
                                                   java.lang.String operator_,
                                                   java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.Long expressionId_,
                                java.lang.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

java.lang.String getDefaultFormat(java.lang.String name_)
                           throws java.security.InvalidParameterException,
                                  java.lang.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:

java.security.InvalidParameterException

java.lang.NullPointerException

setDefaultFormat

void setDefaultFormat(java.lang.String name_,
                      java.lang.String format_)
               throws java.security.InvalidParameterException,
                      java.lang.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:

java.security.InvalidParameterException

java.lang.NullPointerException

getDisplayFormatForLocale

LocaleDisplayFormat getDisplayFormatForLocale(LocaleDisplayFormat ldf_)
                                       throws java.security.InvalidParameterException,
                                              java.lang.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:

java.lang.NullPointerException - if LocaleDisplayFormat parameter is null

java.security.InvalidParameterException - if the locale field for the parameter is invalid

setDisplayFormatForLocale

void setDisplayFormatForLocale(LocaleDisplayFormat ldf_)
                        throws java.security.InvalidParameterException,
                               java.lang.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:

java.lang.NullPointerException - if LocaleDisplayFormat parameter is null

java.security.InvalidParameterException - if a parameter set in the LocaleDisplayFormat object is invalid

getDisplayFormatsForLocales

LocaleDisplayFormat[] getDisplayFormatsForLocales(LocaleDisplayFormat[] ldf_)
                                           throws java.security.InvalidParameterException,
                                                  java.lang.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:

java.lang.NullPointerException - if LocaleDisplayFormat array parameter is null

java.security.InvalidParameterException - if the locale set in one of the LocaleDisplayFormat objects invalid

setDisplayFormatsForLocales

void setDisplayFormatsForLocales(LocaleDisplayFormat[] ldf_)
                          throws java.security.InvalidParameterException,
                                 java.lang.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:

java.lang.NullPointerException - if LocaleDisplayFormat array parameter is null

java.security.InvalidParameterException - if a parameter set in one of the LocaleDisplayFormat objects is invalid