Interface ExpressionService
- All Superinterfaces:
com.appiancorp.services.ContextSensitiveService
,Service
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
Modifier and TypeFieldDescriptionstatic final boolean
static final boolean
static final boolean
static final boolean
static final boolean
static final boolean
static final boolean
static final boolean
static final boolean
static final boolean
static final boolean
static final boolean
static final boolean
Fields inherited from interface com.appiancorp.services.ContextSensitiveService
SET_SERVICE_CONTEXT_METHOD_NAME
-
Method Summary
Modifier and TypeMethodDescriptionvoid
cancelFunction
(Long expressionId_, String reason_) Deprecated.see ProcessDesignService.evaluateExpression; it handles the full expression lifecyclevoid
continueFunction
(Long expressionId_, TypedVariable result_) Deprecated.see ProcessDesignService.evaluateExpressionevaluateExpression
(Long expressionId_, TypedVariable[] parameters_) Deprecated.see ProcessDesignService.evaluateExpression; it handles the full expression lifecycleevaluateExpressionType
(Long expressionId_, TypedVariable[] parameters_, int resultType_) Deprecated.see ProcessDesignService.evaluateExpression; it handles the full expression lifecyclegetDefaultFormat
(String name_) Retrieves the default display format for a given format name.Retrieves the display format information for the locale set in theLocaleDisplayFormat
parameter object.Receives an array ofLocaleDisplayFormat
objects that have only the locale field set for each object.prepareExpression
(String textToEvaluate_) Deprecated.see ProcessDesignService.evaluateExpression; it handles the full expression lifecycleprepareModifyExpression
(String variable_, String operator_, String textToEvaluate_) Deprecated.see ProcessDesignService.evaluateExpression; it handles the full expression lifecyclevoid
setDefaultFormat
(String name_, String format_) Sets the default display format for a given format name.void
Sets a display format for the locale set in theLocaleDisplayFormat
parameter object.void
Receives an array ofLocaleDisplayFormat
objects and sets a display format for the locale set in each of theLocaleDisplayFormat
objects.void
validateExpression
(String textToEvaluate_) Validates the expression.Methods inherited from interface com.appiancorp.services.ContextSensitiveService
setServiceContext
-
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.see ProcessDesignService.evaluateExpression; it handles the full expression lifecycleConstructs an expression and returns the ID of the expression constructed from the text argument. The expression can then be evaluated byevaluateExpression(java.lang.Long, com.appiancorp.suiteapi.process.TypedVariable[])
orevaluateExpressionType(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 lifecycleConstructs an expression and returns the ID of the expression constructed from the String arguments. The method differs fromprepareExpression(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 toprepareExpression(java.lang.String)
, but "a", ":", "1+2" would be the respective arguments toprepareModifyExpression
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 expressiontextToEvaluate_
- 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 lifecycleEvaluates 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)
orprepareModifyExpression(java.lang.String, java.lang.String, java.lang.String)
NOTE: This function should be called first with
parameters_
as an empty array. If theresult
field of the returnedPartialResult
isnull
, then this method should be called again withparameters_
set to be thefunctionParameters
field of the returnedPartialResult
.- Parameters:
expressionId_
- the unique id of expression being evaluatedparameters_
- 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 existServiceException
- 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 lifecycleEvaluates 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 theresult
(if any) within thePartialResult
returned will be cast to the givenresultType
.NOTE: This function should be called first with
parameters_
as an empty array. If theresult
field of the returnedPartialResult
isnull
, then this method should be called again withparameters_
set to be thefunctionParameters
field of the returnedPartialResult
.- Parameters:
expressionId_
- the unique id of expression being evaluatedparameters_
- the array of parameters to the expression with the given IDresultType_
- the type for the returnedPartialResult
. This is one of the object types inTypedVariable
- 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 existServiceException
- if any system-level error occurs
-
validateExpression
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.evaluateExpressionContinue 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 evaluatedresult_
- the result of the sub-expression that Java has evaluated- Throws:
InvalidExpressionException
- if the expression does not existServiceException
- 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 lifecycleCancel the evaluation of an expressionIf 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 evaluatedreason_
- the error that Java encountered while evaluating the expression- Throws:
InvalidExpressionException
- if the expression does not existServiceException
- if any system-level error occurs
-
getDefaultFormat
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 theLocaleDisplayFormat
parameter object. Only the locale field should be set on theldf_
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_
- ALocaleDisplayFormat
object that has only the locale field set- Throws:
NullPointerException
- if LocaleDisplayFormat parameter is nullInvalidParameterException
- 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 theLocaleDisplayFormat
parameter object. All fields of theldf_
parameter must be set and may not be null.- Parameters:
ldf_
- ALocaleDisplayFormat
object that has all fields set- Throws:
NullPointerException
- ifLocaleDisplayFormat
parameter is nullInvalidParameterException
- if a parameter set in theLocaleDisplayFormat
object is invalid
-
getDisplayFormatsForLocales
LocaleDisplayFormat[] getDisplayFormatsForLocales(LocaleDisplayFormat[] ldf_) throws InvalidParameterException, NullPointerException Receives an array ofLocaleDisplayFormat
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 ofLocaleDisplayFormat
objects that have only the locale field set- Throws:
NullPointerException
- if LocaleDisplayFormat array parameter is nullInvalidParameterException
- if the locale set in one of theLocaleDisplayFormat
objects invalid
-
setDisplayFormatsForLocales
void setDisplayFormatsForLocales(LocaleDisplayFormat[] ldf_) throws InvalidParameterException, NullPointerException Receives an array ofLocaleDisplayFormat
objects and sets a display format for the locale set in each of theLocaleDisplayFormat
objects. All fields of each of theLocaleDisplayFormat
objects in theldf_
parameter must be set and may not be null.- Parameters:
ldf_
- An array ofLocaleDisplayFormat
objects that have all fields set- Throws:
NullPointerException
- ifLocaleDisplayFormat
array parameter is nullInvalidParameterException
- if a parameter set in one of theLocaleDisplayFormat
objects is invalid
-