IBM ACEL 1.2, PMAC 1.2 Autonomic Computing User's Guide

Tivoli Software
ACEL User’s Guide
Autonomic Computing Expression
Language (ACEL) 1.2
User’s Guide
Issue Date: 02/28/2005
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 1 of 34
Tivoli Software
ACEL User’s Guide
Document Control Information
About this Document
User's guide for Autonomic Computing Expression Language (ACEL) describes the semantics of ACEL and user
interfaces exposed by the Policy Management for Autonomic Computing V1.2 ( PMAC 1.2) implementation of ACEL.
The user's guide documents enough of the language design and PMAC 1.2 implementation to allow its users to
understand overall language semantics and use PMAC 1.2 to parse and evaluate expressions written in ACEL.
Document Author: Dakshi Agrawal, Jim Giles, Kang-won Lee, Jorge Lobo
Document Owners: Dakshi Agrawal, Jorge Lobo
Summary of Changes:
To request a change to this document, contact a Document Owner.
Changes to this document are summarized in the following table in chronological order.
Version
1.0
Date
02/28/2005
Created by
Dakshi Agrawal
© IBM Corporation 2005. All rights reserved.
Short Description
Initial Version
Online version is the Master
Page 2 of 34
Tivoli Software
ACEL User’s Guide
Table of Contents
CHAPTER 1: INTRODUCTION......................................................................................................................................4
1.1 ACEL datatypes and functions.............................................................................................................................4
1.2 ACEL expressions in XML...................................................................................................................................5
1.3 PMAC 1.2 implementation of ACEL.....................................................................................................................6
CHAPTER 2: ACEL SEMANTICS.................................................................................................................................7
2.1
2.2
2.3
2.4
2.5
2.6
2.7
ACEL datatypes...................................................................................................................................................7
Boolean expressions............................................................................................................................................8
Numeric expressions..........................................................................................................................................11
String expressions..............................................................................................................................................15
Calendar expression..........................................................................................................................................17
Composite expression........................................................................................................................................17
References.........................................................................................................................................................17
CHAPTER 3: PMAC IMPLEMENTATION OF ACEL...................................................................................................19
3.1 Main interfaces provide by PMAC implementation.............................................................................................19
3.2 Typical steps in parsing and evaluating an ACEL expression............................................................................21
CHAPTER 4: BNF GRAMMAR OF ACEL...................................................................................................................24
4.1 Elements with substitution group Expression ....................................................................................................24
4.2 Elements with substitution group SensorElement...............................................................................................24
4.3 ExpressionReference element...........................................................................................................................24
4.4 Members of Argument group..............................................................................................................................24
4.5 Members of BooleanArgument group.................................................................................................................25
4.6 Members of NumericArgument group................................................................................................................25
4.7 Members of StringArgument group....................................................................................................................25
4.8 Members of CalendarArgument group...............................................................................................................25
4.9 Members of CompositeDataArgument group.....................................................................................................25
4.10 Members of CollectionArgument group............................................................................................................25
4.11 Members of URIArgument group......................................................................................................................25
4.12 Elements with substitution group BooleanExpression......................................................................................26
4.13 Elements with substitution group NumericExpression......................................................................................28
4.14 Elements with substitution group StringExpression..........................................................................................32
4.15 Elements with substitution group CalendarExpression.....................................................................................33
4.16 Elements with substitution group CollectionExpression....................................................................................33
4.17 Elements with substitution group CompositeDataExpression...........................................................................33
4.18 Elements with substitution group URIExpression.............................................................................................34
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 3 of 34
Tivoli Software
ACEL User’s Guide
Chapter 1: Introduction
Most programming languages, imperative or declarative, include an expression language to express calculation of a
new value from existing values. Initially, Autonomic Computing Expression Language was developed as a part of the
Autonomic Computing Policy Language. Later on, it was factored out in as an independent language since its use is
not limited to the Autonomic Computing Policy Language.
Autonomic Computing Expression Language (ACEL) is especially suited for use in an XML based declarative
language such as Autonomic Computing Policy Language or Web Services–Agreement1. In addition to simple
functions commonly found in imperative languages such as C and Java, ACEL includes a large number of functions
that can perform complex calculations to derive a new value from passed arguments. Among the existing expression
languages, the expression language embedded in XACML and “Xquery 1.0 and Xpath 2.0 Functions and Operators”
are closest in spirit to ACEL. Some distinguishing features of ACEL are as follows:
•
•
•
•
ACEL provides a rich set of datatypes and functions allowing a simple representation of most expressions
required for system management.
ACEL is a “strongly typed” expression language and its XML schema enforces most of the type constraints.
As a result, ACEL expressions can be validated to a large degree in plain XML editors to allow quick
authoring of ACEL expressions.
ACEL can be extended by a deployer in such a manner that it retains its “strongly typed” property with XML
schema enforcing the type constraints. Thus even the extended ACEL expressions can be rapidly authored in
a plain XML editor.
ACEL includes a comprehensive timezone specification with date and time values allowing unambiguous
treatment of time instances even in presence of daylight saving time.
Policy Management For Automatic Computing V1.2 (PMAC 1.2) provides a parser and evaluator for ACEL
expressions in as a user library (acexpressions.jar). The goal of this section is to briefly describe datatype and
functions provided by ACEL, XML form of ACEL expressions, and PMAC 1.2 implementation of ACEL parser and
evaluator.
1.1 ACEL datatypes and functions
ACEL provides nine primitive datatypes: Boolean, Short, Integer, Long, Float, Double, String, Calendar, URI. In
addition, it provides two composite datatypes: CompositeData and Collection. The first seven primitive datatypes
respectively correspond to XML schema datatypes of boolean, short, int, long, float, double, string. The Calendar
datatype is equivalent to the dateTime XML schema datatype except that it allows for a more generic timezone
specification (see Java TimeZone specifications). The URI datatype is equivalent the anyURI XML schema datatype.
The datatype CompositeData is equivalent to XML schema complex types. The datatype Collection represents a
possibly empty collection of expressions. Finally, ACEL supports a Reference element that contains a pointer or a
handle to an expression defined elsewhere.
ACEL supports a rich set of functions. In the following we list a subset of the supported standard functions:
•
•
•
Numeric functions: Type cast functions (ToInt, ToFloat, ToLong, etc.), Arithmetic operators (Plus, Product,
Remainder, Max, Log, Pow, Ceiling, etc.), Calendar field extraction functions (GetDayOfMonth, GetHour,
GetYear, etc.)
Boolean functions: Type cast function (ToBoolean), Logical functions (And, Or, Not, Xor), Relational functions
(Greater, Equal, GreaterEqual, etc.), String matching functions(Begins, Contains, Ends), Calendar comparison
functions (IsAfter,IsBefore, IsWithin), Set functions (Belongs)
String functions: Type cast functions (ToString), Substring extraction functions (LeftSubstring, RightSubstring,
ReplaceSubstring, etc.), Case conversion functions (ToUpper,ToLower)
A detailed description of ACEL datatypes and functions is given in Section 2.
1
Web Services Agreement Specification is an XML language from the Global Grid Forum for specifying an agreement
between a resource/service provider and a consumer, and a protocol for creation of an agreement using agreement
templates.
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 4 of 34
Tivoli Software
ACEL User’s Guide
1.2 ACEL expressions in XML
ACEL expressions have an intuitive form in their XML representation. For example, consider the simple expression
(2+3) rendered in ACEL:
<Plus>
<IntConstant><Value>2</Value></IntConstant>
<IntConstant><Value>3</Value></IntConstant>
</Plus>
Due to the type constraints imposed by ACEL XML schema, the following would be flagged as being in error by an
XML editor (using ACEL XML schema for validation):
<Plus>
<IntConstant><Value>2</Value></IntConstant>
<StringConstant><Value>3</Value></StringConstant>
</Plus>
The variables (quantities unknown at the time of writing expressions) in ACEL can be represented by the
PropertySensor element. Each PropertySensor element has a type associated with it. For example, an expression that
multiplies a Float constant 3.14159 to the PropertySensor “diameter” of type Float would be written as:
<Product>
<FloatConstant><Value>3.14159</Value></FloatConstant>
<PropertySensor propertyName="diameter" />
</Product>
In addition to PropertySensor, ACEL also provides OperationSensor element that can be used to represent a quantity
unknown at the time of writing expressions. OperationSensor element is specified by a “portType”, an
“operationName” and zero or more arguments. In general, the value of OperationSensor depends on the arguments
used to evaluate it. In that sense, it provides ability to invoke callout functions in ACEL.
<Product>
<FloatConstant><Value>2.5</Value></FloatConstant>
<OperationSensor portType="webServer" operationName="getAverageResponseTime">
<FloatConstant><Value>20.0</Value></FloatConstant>
</Product>
The OperationSensor used in above expression may provide average response time of a web server in last 20.0
seconds.
Each PropertySensor and OperationSensor is an ACEL expression with an associated type. An ACEL parser needs
the association of types with PropertySensor and OperationSensor to fully validate an ACEL expression. To evaluate
an expression containing PropertySensors or OperationSensors, an ACEL evaluator needs to be fed with the values
of PropertySensors and OperationSensors occuring in the expression. Section 3 describes how the values of
PropertySensors and OperationSensors can be provided as an input to the PMAC 1.2 ACEL evaluator.
Since all expressions return a value of predetermined type or type group, it is possible to use result of evaluating an
expression inside another expression. For example, consider
<ToString>
<Plus>
<IntConstant><Value>2</Value></IntConstant>
<IntConstant><Value>3</Value></IntConstant>
</Plus>
</ToString>
In general, a function f is represented as an XML element f with its arguments specified as its child elements. A few
function elements dealing with date and time have attributes to specify how certain ambiguities in the time specification
should be resolved.
Deployers can extend the expression schema by including it in their extension schema. Such an extension preserves
the type-checking by XML schema and readability attributes of the ACEL, while allowing more functions to be used.
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 5 of 34
Tivoli Software
ACEL User’s Guide
For example, a deployer may want to write a new function that returns standard deviation of specified arguments.
They can define a new expression element StandardDeviation in their own namespace (represented below by the
prefix deployer):
<deployer:StandardDeviation>
NumericArgument+
</deployer:StandardDeviation>
The deployer can use the new function along with functions defined in ACEL to compute standard deviation of {4,6,10}
and multiply the result by 4.
<Product>
<IntConstant><Value>4</Value></IntConstant>
<deployer:StandardDeviation>
<IntConstant><Value>4</Value></IntConstant>
<IntConstant><Value>6</Value></IntConstant>
<IntConstant><Value>10</Value></IntConstant>
</deployer:StandardDeviation>
</Product>
1.3 PMAC 1.2 implementation of ACEL
PMAC 1.2 provides a nearly complete implementation of ACEL (henceforth, referred to as ACEL user library) with the
following exceptions:
• The current implementation lacks support for ExpressionReference elements and URI datatype.
• The current implementation does not provide a method to validate ACEL expressions. Therefore, expression
authors have to rely on external tools to validate ACEL fragments with ACEL XML schema. As noted earlier,
even an ACEL fragment that passes schema validation may not be a correct expression as ACEL XML
schema does not fully capture ACEL specifications.
In near future, we expect to remove above restrictions. A detailed description of Application Programming Interfaces of
the ACEL implementation would be given in Chapter 3.
ACEL user library provides three main interfaces, Expression, SensorLookup, ExpressionFactory, representing
respectively a ACEL expression in Java, a lookup of PropertySensor and OperationSensor values, and a factory to
create ACEL expressions. A class ExpressionCreator in the user library can be used to create all ACEL Java
expressions from their XML representations. Typically, a deployer would create a Java ACEL expression:
Expression myExpression;
myExpression = ExpressionCreator.createExpression(org.w3c.dom.Element XMLExpression);
then at a later time, evaluate the expression by providing a suitably prepared SensorLookup as an input:
Object result;
SensorLookup s;
result = myExpression.evaluate(s);
A detailed description of Application Programming Interfaces of the ACEL implementation would be given in Chapter
3.
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 6 of 34
Tivoli Software
ACEL User’s Guide
Chapter 2: ACEL Semantics
The semantics of an expression language can be described with a mathematical rigor to ensure that all corner cases
have been addressed and there is no ambiguity left for implementors to interpret. Another style for describing the
semantics focuses on conveying the essential substance of a language without the distraction introduced by formal
notation. In this chapter we take the later approach. We describe the semantics of ACEL without formalism, focusing
on essential substance and a few important corner cases. In fact, the formal semantics of ACEL has not been
developed and corner cases are left for implementors to interpret.
2.1 ACEL datatypes
Every evaluation of an expression in ACEL results in a value belonging to one of the following types:
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
Boolean
Short
Long
Integer
Float
Double
String
URI
Calendar
Composite
Collection
The most basic expressions are constants from these types. The value they return is the constant itself.
Boolean constants: are the values true and false.
Short constants: any number from -32,768 to 32,767.
Long constants: any number from -9223,372,036,854,775,808 to 9,223,372,036,854,77,807.
Integer constants: any number from -2,147,483,648 to 2,147,483,647.
Float constants: any number that can be represented in exponential notation with eight digits of precision ranging
from 3.40282347E+38 as the largest positive number to 1.40239846E-45 as the smallest positive number plus 0.
Negative numbers range from -3.40282347E+38 to -1.40239846E-45.
Double constants: any number that can be represented in exponential notation with seventeen digits of precision
ranging from 1.79769313486231570E+308 as the largest positive number to 4.94065645841246544E-324 as the
smallest positive number plus 0. Negative numbers range from -1.79769313486231570E+308 to
-4.94065645841246544E-324.
String constants: any sequence of UNICODE characters. This set of characters includes the standard ASCII
symbols representing digits and Latin characters, blank, escape characters, etc. It also encompasses non-Latin
characters to cover many other languages. Detail description of this encoding can be found in ISO/IEC 10646.
URI constants: any string according to RFC 2396.
Calendar constants: are represented by tuples of nine fields (YYYY, MM, DD, hh, mm, ss, TZD, IsLenient, preferred
standard time), where YYYY is the year, MM is the month (from 01 to 12) , DD is the day of the month (from 01 to 31),
hh is the hour (from 00 to 23), mm is the minute (from 00 to 59), ss is the second (from 00 to 59), TZD is an optional
string representing a time zone using Java time zones IDs, or “UTC” (for universal time coordinated notation), or
“local” referring to the zone associated with the system evaluating the policy. If the TZD is not provided is assumed to
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 7 of 34
Tivoli Software
ACEL User’s Guide
be “local”. The IsLeneint argument is also optional and could be any of the strings "true" ,"1", "false" or "0". If the value
is "true" or "1", it means that if the input is not in the standard form but can still be parsed as a date, then the parse
succeeds. If the argument is not provided it is assumed "true". The preferred standard time is also one of the strings
"true", "1", "false", and "0" and optional. If the value is "true" or "1" it is assumed that the date is referring to the time
zone adjusted to Daylight Saving Time. This value is needed only to disambiguate the period of time that is repeated
when clocks are move from one time mode to the other. This usually happens in the Fall. If the argument is not
provided the value is assumed "false". Note that several calendar constants represent the same time instance and we
appeal to the reader intuition to determine equality and translation between different representations of the same time
instance.
Composite constants: are XML fragments in Element form. Unlike the scalar data types described above, Composite
data types have well-structured constituent parts that include XML element and attribute tags, and their related data.
Composite constants are essentially a way to describe complex data structures using an XML representation.
Collection constants: group constants of possibly different types into a single structure and are defined as follows:
1. {} is a collection constant.
2. {C1, ..., Cn} is a collection constant if each Ci is a constant.
Note that the above definition allows finite recursive construction of Collection constant. Thus, {1, 5.0, "IBM"} is a
Collection constant since 1, 5.0, "IBM" are respectively Integer, Float, and String constants. Furthermore, {3, {1, 5.0,
"IBM"}} is a Collection constant since 3 and {1, 5.0, "IBM"} are respectively Integer and Collection constants.
In addition to constants there is another set of elementary expressions called Variables.
Variables: are generic placeholders for constant values that are provided at execution time. The name and type of
each of these variables is known in advance and available for the policy author to write as an expression.
The rest of the expressions are built on top of these basic expressions using operators. Some of the operations
defined by these operators are typical operations over numbers such as addition and multiplication. Many times we
will apply these operations over multiple types of numbers, e.g. adding an Integer constant to a Float constant. The
evaluation of such operation will need to select a type for the resulting value. Most operators will follow the following
rules of conversion:
Rules of conversion for numeric operations
1.If no operand is a Float or a Double (integer arithmetic) and at least one operand is a Long the result is Long.
2.If no operand is a Float or a Double (integer arithmetic) and none of the operand is a Long the result is Integer.
3.The result is Double if at least one operand is a Double.
4.The result is Float if at least one operand is a Float and none is a Double.
Since any of the operations below that accepts a number as an argument will accept any expression that evaluates to
either Short, Long, Integer, Float or Double, we will collectively refer to all these types as numeric types.
Numeric expression: is any expression that results in a value that is a Short, a Long, an Integer, a Float or a Double
constant.
2.2 Boolean expressions
ToBoolean (String str)
Returns true if the string expression str evaluates to the string ″true″ or "1" ("true" is not case sensitive). If the
evaluation of str results in any other string it returns false. (See exceptions bellow)
ToBoolean (Numeric num)
Returns false if the numeric expression num evaluates to 0. If the evaluation of num returns any other numeric
constant the operation returns true.
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 8 of 34
Tivoli Software
ACEL User’s Guide
If neither of these two cases applies the operation throws an exception.
And (Boolean b1, Boolean b2, Boolean bn)
Returns true if the Boolean expressions b1 to bn evaluate to true, otherwise returns false as soon as it finds one of the
expressions evaluating to false.
The operation throws an exception if in the course of evaluating the b expression the evaluation results in a non
Boolean value before it finds an expression returning false.
Or (Boolean b1, Boolean b2, Boolean bn)
Returns true as soon as it finds that one of the Boolean expression evaluates to true. If all the expressions evaluate to
false it returns false.
The operation throws an exception if in the course of evaluating the b expression the evaluation results in a non
Boolean value before finding an expression returning true.
Not (Boolean b)
Returns true if the evaluation of b is false. Returns false if the evaluation of b is true. Otherwise the operation throws
an exception.
Xor (Boolean b1, Boolean b2)
Returns true if one of the two Boolean expressions evaluates to true and the other evaluates to false. If both
expressions are true or both expressions are false it returns false. Otherwise the operation throws an exception.
Greater (Numeric num1, Numeric num2)
Greater (String str1, String str2)
In the first instance, returns true if the evaluation of the first expression num1 returns a numeric value that is greater
than the value returned by the evaluation of num2. If the value returned by num1 is less than or equal to the numeric
value returned by num2 the result is false. In the second instance, returns true if the evaluation of the first expression
str1 returns a string that is greater than the string returned by the evaluation of str2 in the lexicographical order
induced by the Unicode code of the characters comprising the strings. If the string returned by str1 is less than or
equal to the string returned by str2 the result is false.
If both argument expressions do not result in values of the same type (string or numeric) the operation throws an
exception.
Less (Numeric num1, Numeric num2)
Less (String str1, String str2)
In the first instance, returns true if the evaluation of the first expression num1 returns a numeric value that is less than
the value returned by the evaluation of num2. If the value returned by num1 is greater than or equal to the numeric
value returned by num2 the result is false. In the second instance, returns true if the evaluation of the first expression
str1 returns a string that is less than the string returned by the evaluation of str2 in the lexicographical order induced
by the Unicode code of the characters comprising the strings. If the string returned by str1 is greater than or equal to
the string returned by str2 the result is false.
If both argument expressions do not result in values of the same type (string or numeric) the operation throws an
exception.
Equal (Boolean b1, Boolean b2)
Returns true if the evaluation of both Boolean expressions result in the same Boolean value. (See exception below).
Equal (Numeric num1, Numeric num2)
Returns true if the evaluation of both numeric expressions result in the same numeric value. (See exception below).
Equal (String str1, String str2)
Returns true if the evaluation of both string expressions result in the same string of characters. (See exception below).
Equal (Calendar cal1, Calendar cal2)
Returns true if the evaluation of both calendar expressions result in the same calendar value. (See exception below).
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 9 of 34
Tivoli Software
ACEL User’s Guide
Equal (Composite cmp1, Composite cmp2)
Returns true if the evaluation of both composite expressions result in identical XML documents.
If none of the four cases for Equal() applies the operation throws an exception.
GreaterEqual (Numeric num1, Numeric num2)
GreaterEqual (String str1, String str2)
In the first instance, returns true if the evaluation of the first expression num1 returns a numeric value that is greater
than or equal to the value returned by the evaluation of num2. If the value returned by num1 is less than the numeric
value returned by num2 the result is false. In the second instance, returns true if the evaluation of the first expression
str1 returns a string that is greater than or equal to the string returned by the evaluation of str2 in the lexicographical
order induced by the Unicode code of the characters comprising the strings. If the string returned by str1 is less than
the string returned by str2 the result is false.
If both argument expressions do not result in values of the same type (string or numeric) the operation throws an
exception.
LessEqual (Numeric num1, Numeric num2)
LessEqual (String str1, String str2)
In the first instance, returns true if the evaluation of the first expression num1 returns a numeric value that is less than
or equal to the value returned by the evaluation of num2. If the value returned by num1 is greater than the numeric
value returned by num2 the result is false. In the second instance, returns true if the evaluation of the first expression
str1 returns a string that is less than or equal to the string returned by the evaluation of str2 in the lexicographical order
induced by the Unicode code of the characters comprising the strings. If the string returned by str1 is greater than the
string returned by str2 the result is false.
If both argument expressions do not result in values of the same type (string or numeric) the operation throws an
exception.
Begins (String str1, String str2)
Returns true if the string returned by the evaluation of the string expression str1 begins with the string returned by the
evaluation of the string expression str2. If the str1 does not begin with str2 returns false.
If the evaluation of any of the expressions does not result in a string the operation throws an exception.
Contains (String str1, String str2)
Returns true if the string returned by the evaluation of the string expression str1 contains the string returned by the
evaluation of the string expression str2. If str1 does not contain str2 returns false.
If the evaluation of any of the expressions does not result in a string the operation throws an exception.
Ends (String str1, String str2)
Returns true if the string returned by the evaluation of the string expression str1 ends with the string returned by the
evaluation of the string expression str2. If str1 does not end with str2 returns false.
If the evaluation of any of the expressions does not result in a string the operation throws an exception.
IsAfter (Calendar cal1, Calendar cal2)
Returns true if the date returned by the evaluation of the calendar expression cal1 is after the date returned by the
evaluation of the calendar expression cal2. If cal1 is not after cal2 returns false.
If the evaluation of any of the expressions does not result in a calendar value the operation throws an exception.
IsBefore (Calendar cal1, Calendar cal2)
Returns true if the date returned by the evaluation of the calendar expression cal1 is before the date returned by the
evaluation of the calendar expression cal2. If cal1 is not before cal2 returns false.
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 10 of 34
Tivoli Software
ACEL User’s Guide
If the evaluation of any of the expressions does not result in a calendar value the operation throws an exception.
IsWithin (Calendar cal1, Calendar start, Calendar end)
Returns true if the evaluation of cal1 results in a time that is within time period specified by the result of evaluating the
calendar expression start and end. The start and end times are inclusive to the period. If the cal1 is outside this time
period it returns false.
If the evaluation of any of the expressions does not result in a calendar value the operation throws an exception.
Belongs (Expression exp, Collection col)
Returns true if the evaluation of exp returns a constant that belongs to the collection returned by the evaluation of the
collection expression col. It returns false if the constant returned by the evaluation of exp does not belong to collection
returned by the evaluation of col.
If exp does not evaluate to a constant or col does not evaluate to a collection value the operation throws an exception.
PolicyTimePeriodExpression (Calendar cal, Time Period)
Returns true if the calendar argument falls inside the Time Period. A time period is described by six arguments:
Calendar Expression: its evaluation represents the beginning of the period. This argument is optional. If it is not
provided it assumed that the beginning is open.
Calendar expression: its evaluation represents the end of the period. This argument is optional. If it is omitted it
assumed that the period has an open ending.
Month: this is a constant string of twelve characters from the set {"0", "1"}. Each position in the string corresponds to a
month of the year starting from January and ending in December. This string restricts the months considered in the
time period to only the months that are marked "1" in the string. This argument is optional. If it is omitted, no restriction
is applied.
Day: this is a constant string of 62 characters from the set {"0", "1"}. Each position in the string from one to 31
corresponds to a day in any month. Characters from 32 to 62 correspond to days in the month but starting from the
last day of the month (e.g. character 32 is the last day of the month, character 33 is the day before the last, etc.). This
string restricts the days considered in the time period to only those days of the months being considered in the time
period that are marked "1" in the string. This argument is optional. If it is omitted, no restriction is applied.
Day of Week: this is a constant string of 7 characters from the set {"0", "1"}. Each position in the string corresponds to
a day of the week. This string restricts the days considered in the time period to only those days that correspond to
days of the week that are marked "1" in the string. This argument is optional. If it is omitted, no restriction is applied.
Starting time: this restricts the time of each day included in the time period to only times after this starting time. This is
represented by a tuple of six elements, (hh, mm, ss, TZD, IsLenient, preferred standard time), and the arguments are
defined as in calendar constants. This is argument is optional and if it is omitted it means the time 0.
Ending time: this restricts the time of each day included in the time period to only times before this ending time. This is
represented by a tuple of six elements, (hh, mm, ss, TZD, IsLenient, preferred standard time), and the arguments are
defined as in calendar constants. This is argument is optional and if it is omitted it means the time 24.
The operation throws an exception if any of the calendar expressions does not return a calendar constant or the
syntax of the other arguments is violated.
XPathBooleanExpression (XPathLocation loc, Composite arg)
Returns ToBoolean(s) where s is the string extracted from arg using the XPathLocation loc.
If loc is not a string constant of a well formed XPath according to http://www.w3.org/TR/xpath or arg does not evaluate
to a composite value the operation throws an exception. Other exceptions behaves like ToBoolean().
2.3 Numeric expressions
ToShort (String str)
ToShort(Numeric num)
Returns the value of the specified expression as a Short. This may involve rounding or truncation.
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 11 of 34
Tivoli Software
ACEL User’s Guide
If num does not return a numeric expression or str does not return a string representing a number the operation
throws an exception.
ToLong (String str)
ToLong(Numeric num)
Returns the value of the specified expression as a Long. This may involve rounding or truncation.
If num does not return a numeric expression or str does not return a string representing a number the operation
throws an exception.
ToInt (String str)
ToInt(Numeric num)
Returns the value of the specified expression as an Integer. This may involve rounding or truncation.
If num does not return a numeric expression or str does not return a string representing a number the operation
throws an exception.
ToFloat (String str)
ToFloat(Numeric num)
Returns the value of the specified expression as a Float. This may involve rounding or truncation.
If num does not return a numeric expression or str does not return a string representing a number the operation
throws an exception.
ToDouble (String str)
ToDouble(Numeric num)
Returns the value of the specified expression as a Double. This may involve rounding or truncation.
If num does not return a numeric expression or str does not return a string representing a number the operation
throws an exception.
Plus (Numeric num1, Numeric num2, ..., Numeric numn)
Using the rules of conversion for numeric types it returns in the appropriate numeric type the sum of the numbers
resulting from the evaluation of each of the numeric expressions.
If any of the expressions does not return a numeric value the operation throws an exception.
Minus (Numeric num1, Numeric num2)
Using the rules of conversion for numeric types it returns the result of the evaluation of num1 minus the evaluation of
num2 in the appropriate type.
If any of the expressions does not return a numeric value the operation throws an exception.
Product (Numeric num1, Numeric num2, ..., Numeric numn)
Using the rules of conversion for numeric types it returns in the appropriate numeric type the product of the numbers
resulting from the evaluation of each of the numeric expressions.
If any of the expressions does not return a numeric value the operation throws an exception.
Division (Numeric num1, Numeric num2)
Using the rules of conversion for numeric types it returns the result of the evaluation of num1 divided by the evaluation
of num2 in the appropriate type.
If any of the two expressions does not return a numeric value the operation throws an exception. If the rules of
conversion result in Integer and num2 evaluates to 0 the operation also throws an exception.
Remainder (Numeric num1, Numeric num2)
Using the rules of conversion for numeric types it returns in the appropriate type the remainder of the result of the
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 12 of 34
Tivoli Software
ACEL User’s Guide
evaluation of num1 divided by the evaluation of num2.
If any of the two expressions does not return a numeric value the operation throws an exception. If the rules of
conversion result in Integer and num2 evaluates to 0 the operation also throws an exception.
Max (Numeric num1, Numeric num2, ..., Numeric numn)
Using the rules of conversion for numeric types it returns in the appropriate numeric type the largest of the numbers
resulting from the evaluation of each of the numeric expressions.
If any of the expressions does not return a numeric value the operation throws an exception.
Min (Numeric num1, Numeric num2, ..., Numeric numn)
Using the rules of conversion for numeric types it returns in the appropriate numeric type the smallest of the numbers
resulting from the evaluation of each of the numeric expressions.
If any of the expressions does not return a numeric value the operation throws an exception.
Log (Numeric num)
Returns the natural logarithm (base e) of the evaluation of num. The result is a Double.
If the evaluation of num does not return a numeric value the operation throws an exception.
Exp (Numeric num)
Returns the Euler’s number (e) raised to the power of the evaluation of num. The result is a Double.
If the evaluation of num does not return a numeric value the operation throws an exception.
Pow (Numeric num1, Numeric num2)
Returns the result of evaluating num1 raised to the power of the result of evaluating num2. The result is a Double.
If any of the two expressions does not return a numeric value the operation throws an exception.
Sqrt (Numeric num)
Returns the square root of the evaluation of num. The result is a Double.
If the evaluation of num does not return a numeric value the operation throws an exception.
Abs (Numeric num)
Returns the absolute value of the evaluation of num.
If the evaluation of num does not return a numeric value the operation throws an exception.
Round (Numeric num)
Returns the closest Integer value to the argument.
If the evaluation of num does not return a numeric value the operation throws an exception.
Rint (Numeric num)
Returns the Double value that is closest in value to the argument and is equal to a mathematical Integer.
If the evaluation of num does not return a numeric value the operation throws an exception.
Ceiling (Numeric num)
Returns the smallest whole number greater than or equal to the evaluation of num. The result is a Double.
If the evaluation of num does not return a numeric value the operation throws an exception.
Floor (Numeric num)
Returns the smallest whole number less than or equal to the evaluation of num. The result is a Double.
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 13 of 34
Tivoli Software
ACEL User’s Guide
If the evaluation of num does not return a numeric value the operation throws an exception.
StringLength (String str)
Returns the number of characters in the string str. The result is an Integer.
If the evaluation of str does not return a string the operation throws an exception.
GetDayOfMonth (Calendar cal)
Returns the day within the month of the specified Calendar expression. This is an Integer from 1 to 31.
If the evaluation of cal does not return a calendar value the operation throws an exception.
GetDayOfWeek (Calendar cal)
Returns the day within the week of the specified Calendar expression. This is an Integer from 1 to 7.
If the evaluation of cal does not return a calendar value the operation throws an exception.
GetDayOfWeekInMonth (Calendar cal)
Returns the number of the week in the month, in which the specified Calendar expression falls into. For instance, if the
day represented by the calendar is SUNDAY, GetDayOfWeekInMonth indicates whether this is the first, second, third,
fourth or fifth SUNDAY within the month.
If the evaluation of cal does not return a calendar value the operation throws an exception.
GetDayOfYear (Calendar cal)
Returns the day within the year of the specified Calendar expression. This is an Integer from 1 to 365.
If the evaluation of cal does not return a calendar value the operation throws an exception.
GetHour (Calendar cal)
Returns the hour of the morning or the afternoon (i.e. relative to a 12 hour clock) of the specified Calendar expression.
This is an Integer from 0-11.
If the evaluation of cal does not return a calendar value the operation throws an exception.
GetHourOfDay (Calendar cal)
Returns the hour of the day (i.e. relative to a 24 hour clock) of the specified Calendar expression. This is an Integer
from 0 to 23.
If the evaluation of cal does not return a calendar value the operation throws an exception.
GetMinute (Calendar cal)
Returns the minute within the hour of the specified Calendar expression. This is an Integer from 0 to 59.
If the evaluation of cal does not return a calendar value the operation throws an exception.
GetSecond (Calendar cal)
Returns the second within the minute of the specified Calendar expression. This is a number from 0 to 60 (leap
seconds can be 60).
If the evaluation of cal does not return a calendar value the operation throws an exception.
GetMilliSecond (Calendar cal)
Returns the millisecond within the second of the specified Calendar expression. This is an Integer from 0 to 999.
If the evaluation of cal does not return a calendar value the operation throws an exception.
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 14 of 34
Tivoli Software
ACEL User’s Guide
GetWeekOfMonth (Calendar cal)
Returns the week within the month of the specified Calendar expression. This is an Integer from 1 to 5.
If the evaluation of cal does not return a calendar value the operation throws an exception.
GetWeekOfYear (Calendar cal)
Returns the week within the month of the specified Calendar expression. This is an Integer from 1 to 52.
If the evaluation of cal does not return a calendar value the operation throws an exception.
GetMonth (Calendar cal)
Returns the month within the year of the specified Calendar expression. This is an Integer from 1 to 12.
If the evaluation of cal does not return a calendar value the operation throws an exception.
GetYear (Calendar cal)
Returns the year of the specified Calendar expression. This is an Integer from 0 to 9999.
If the evaluation of cal does not return a calendar value the operation throws an exception.
XPathShortExpression (XPathLocation loc, Composite cmp)
Returns ToShort(s) where s is the string extracted from cmo using the XPathLocation loc.
If loc is not a string constant of a well formed XPath according to http://www.w3.org/TR/xpath or cmp does not
evaluate to a composite value the operation throws an exception. Other exceptions behaves like ToShort().
XPathIntExpression (XPathLocation loc, Composite cmp)
Returns ToInt(s) where s is the string extracted from cmp using the XPathLocation loc.
If loc is not a string constant of a well formed XPath according to http://www.w3.org/TR/xpath or cmp does not
evaluate to a composite value the operation throws an exception. Other exceptions behaves like ToInt().
XPathLongExpression (XPathLocation loc, Composite cmp)
Returns ToLong(s) where s is the string extracted from cmp using the XPathLocation loc.
If loc is not a string constant of a well formed XPath according to http://www.w3.org/TR/xpath or cmp does not
evaluate to a composite value the operation throws an exception. Other exceptions behaves like ToLong().
XPathFloatExpression (XPathLocation loc, Composite cmp)
Returns ToFloat(s) where s is the string extracted from cmp using the XPathLocation loc.
If loc is not a string constant of a well formed XPath according to http://www.w3.org/TR/xpath or cmp does not
evaluate to a composite value the operation throws an exception. Other exceptions behaves like ToFloat().
XPathDoubleExpression (XPathLocation loc, Composite cmp)
Returns ToDouble(s) where s is the string extracted from cmp using the XPathLocation loc.
If loc is not a string constant of a well formed XPath according to http://www.w3.org/TR/xpath or cmp does not
evaluate to a composite value the operation throws an exception. Other exceptions behaves like ToDouble().
2.4 String expressions
Concatenate (String s1, String s2,... String n)
Concatenates two or more strings expressions.
If the evaluation of any of the expressions does not return a string the operation throws and exception.
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 15 of 34
Tivoli Software
ACEL User’s Guide
ToString (Numeric num)
Converts Numeric expressions into a string value.
If the evaluation of num does not return a numeric value the operation throws an exception.
ToUpper (String str)
Converts a string expression into uppercase.
If the evaluation of str does not return a string the operation throws an exception.
ToLower (String str)
Converts a string expression into lowercase.
If the evaluation of str does not return a string the operation throws an exception.
LeftSubstring (String s, Numeric n, String direction)
Extracts the n leftmost characters from the string resulting of the evaluation of s if direction is equal to "LeftToRight".
Skip the n rightmost characters of the result of evaluating s and returns the rest of the string if direction is equal to
"RightToLeft". The numeric value result of the evaluation of n is translated into an Integer using the ToInt() operation.
If the evaluation of s does not result in a string, or the evaluation of n does not result in a numeric value, or the
evaluation of direction does not result in neither "LeftToRight" nor "RightToLeft" the operation throws an exception.
LeftSubstring (String s, String subs, String direction)
Extracts the leftmost characters from a string up to a subs. The direction argument controls whether the subs search is
performed from left to right or from right to left.
If the evaluation of s or subs does not result in a string, or the evaluation of direction does not result in neither
"LeftToRight" nor "RightToLeft" the operation throws an exception.
MiddleSubstring (String s, Numeric offset, Numeric n, String direction)
Extracts n characters from a string s starting at an offset. The offset specifies a character position in string that
indicates where you want the middle to begin, counting either from left to right or right to left based on the direction
parameter. The middle begins one character after the offset.
If the evaluation of s does not result in a string, or the evaluation of offset or n does not result in a numeric value, or
the evaluation of direction does not result in neither "LeftToRight" nor "RightToLeft" the operation throws an exception.
MiddleSubstring (String s, String subs, Numeric n, String direction)
Extracts n characters from a string s starting at a subs. The direction argument controls whether the subs search is
performed from left to right or from right to left.
If the evaluation of s or subs does not result in a string, or the evaluation of offset does not result in a numeric value,
or the evaluation of direction does not result in neither "LeftToRight" nor "RightToLeft" the operation throws an
exception.
MiddleSubstring (String s, Numeric offset, String subs, String direction)
Extracts characters from a string starting at an offset and stopping at a subs. The direction argument controls whether
the subs search is performed from left to right or from right to left.
If the evaluation of s or subs does not result in a string, or the evaluation of offset does not result in a numeric value,
or the evaluation of direction does not result in neither "LeftToRight" nor "RightToLeft" the operation throws an
exception.
MiddleSubstring (String s, String subs1, String subs2, String direction)
Extracts characters from a string starting at subs1 and stopping at subs2. The direction argument controls whether the
substring search is performed from left to right or from right to left.
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 16 of 34
Tivoli Software
ACEL User’s Guide
If the evaluation of s, subs1 or subs2 does not result in a string, or the evaluation of direction does not result in neither
"LeftToRight" nor "RightToLeft" the operation throws an exception.
ReplaceSubstring (String source, String from, String to)
Replaces all the occurrences of ″from″ with ″to″ in source.
If the evaluation of source, from or to does not result in a string the operation throws an exception.
RightSubstring (String s, Numeric n, String direction)
Extracts the n rightmost characters from the string resulting of the evaluation of s if direction is equal to "RightToLeft".
Skip the n leftmost characters of the result of evaluating s and returns the rest of the string if direction is equal to
"LeftToRight". The numeric value result of the evaluation of n is translated into an Integer using the ToInt() operation.
If the evaluation of s does not result in a string, or the evaluation of n does not result in a numeric value, or the
evaluation of direction does not result in neither "LeftToRight" nor "RightToLeft" the operation throws an exception.
RightSubstring (String s, String subs, String direction)
Extracts the rightmost characters from a string up to a subs. The direction argument controls whether the subs search
is performed from left to right or from right to left.
If the evaluation of s or subs does not result in a string, or the evaluation of direction does not result in neither
"LeftToRight" nor "RightToLeft" the operation throws an exception.
Word (String s, String separator, Numeric n)
Extracts n words from a string where a word is the text of more than one charecter between the specified separators.
The numeric value result of the evaluation of n is translated into an Integer using the ToInt() operation.
If the evaluation of s or separator does not result in a string, or the evaluation of n does not result in a numeric value
the operation throws an exception.
XPathStringExpression (XPathLocation loc, Composite cmp)
Returns a string extracted from cmp using the XPathLocation loc.
If loc is not a string constant of a well formed XPath according to http://www.w3.org/TR/xpath or cmp does not
evaluate to a composite value the operation throws an exception.
2.5 Calendar expression
XPathCalendarExpression (XPathLocation loc, Composite cmp)
Returns the calendar value represented by the string extracted from cmp using the XPathLocation loc.
If loc is not a string constant of a well formed XPath according to http://www.w3.org/TR/xpath or cmp does not
evaluate to a composite value the operation throws an exception. If the string extracted does not correspond to date
time according to the XML dateTime datatype the operation throws an exception.
2.6 Composite expression
XPathCompositeDataExpression (XPathLocation loc, Composite cmp)
Returns the composite data value represented by the string extracted from cmp using the XPathLocation loc.
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 17 of 34
Tivoli Software
ACEL User’s Guide
If loc is not a string constant of a well formed XPath according to http://www.w3.org/TR/xpath or cmp does not
evaluate to a composite value the operation throws an exception. If the string extracted does not correspond to a well
formed XML expression the operation throws an exception.
2.7 Collection expressions
GenericCollection2 ()
Returns the empty collection constant value {}.
GenericCollection (Expression exp1, Expression exp2, ...,Expression expn)
Returns the collection constant value {const1, const2, ..., constn} obtained by evaluating exp1, exp2, ..., expn,
respectively.
The operation throws an exception if the evalution of any of the expressions throws an exception.
2.8 References
To simplify writing expressions ACEL provides a mechanism to write macros called references. In its basic form a
reference is an expression associated with a name:
Reference(RefID, Expression)
The RefID is a unique identifier for the reference and the expression is any well formed expression of any type. We
call the reference RefID and say that its type is the type of the Expression.
We extend the definition of expression by allowing the occurrence of any reference ID RefID in any place where an
expression of the same type of RefID is allowed to appear.
We also allow the occurrences of reference IDs in the expressions defining a reference as long as the reference
appearing in the expression has been already defined.
2In the current schema, GenericCollection function is represented by the CollectionConstant XML element. The tag of this XML element is
confusing and would be changed in future versions.
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 18 of 34
Tivoli Software
ACEL User’s Guide
Chapter 3: PMAC Implementation of ACEL
PMAC 1.2 provides a user library “acexpression.jar” that can be used to parse and evaluate ACEL. As discussed in
the introduction, acexpression.jar (henceforth referred to as the PMAC implementation) provides a nearly complete
parser and evaluator with the following exceptions:
• PMAC implementation does not validate ACEL expressions.
• PMAC implementation does not implement URI datatype and Reference element.
3.1 Main interfaces provide by PMAC implementation
The main interface provided by PMAC for ACEL is the Expression interface:
package com.ibm.autonomic.policy.expression;
/**
* Interface defining the abstract element Expression of the PMAC schema.
*
* @author Dakshi Agrawal, Jim Giles, Kang-won Lee
* @since
1.2
*/
public interface Expression {
....
....
/**
* Evaluates and returns the value of this Expression
* using the specified SensorLookup to obtain the
* values of indeterminates (quantities whose magnitude cannot be
* determined at the time of authoring the expression) occuring in
* this Expression.
*
* @param sensorData the specified SensorLookup
* @return the value of this Expression
* @throws EvaluationException if evaluation cannot be performed for some reason.
*/
public Object evaluate(SensorLookup sensorData) throws EvaluationException;
...
...
}
An instance of Expression interface can be evaluated by executing the evaluate method of the instance with a
SensorLookup instance as method argument. SensorLookup instance provides the value of variables (PropertySensor
and OperationSensor) to the evaluate method if necessary:
package com.ibm.autonomic.policy.expression;
/**
* SensorLookup provides values of variables (PropertySensors and OperationSensors)
* for evaluation of an Expression.
*
* @author Christina M. Cruz
* @since 1.2
*/
public interface SensorLookup {
...
...
...
/**
* This method returns the value of the
* specified variable.
*
* @param propertyName the name of the variable
*
* @return the value of the variable
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 19 of 34
Tivoli Software
ACEL User’s Guide
*/
public Object getSensorValue(String propertyName);
/**
* This method returns the value returned by the
* specified sensor operation.
*
* @param operation the SensorOperation parameter that includes the
* operationName, the portType, and the argument expressions
*
* @return the value returned by this SensorOperation
*/
public Object getSensorOperation(SensorOperation operation);
}
package com.ibm.autonomic.policy.expression;
import com.ibm.autonomic.policy.expression.*;
/**
* This object represents a sensor operation.
* @author Christina M. Cruz
* @since 1.2
*/
public interface SensorOperation {
/**
* This method returns the name of the port type of this
* sensor operation.
*
* @return the name of the port type of this
* sensor operation
*/
public String getPortType();
/**
* This method returns the operation name of this
* sensor operation.
*
* @return the operation name of this
* sensor operation
*/
public String getOperationName();
/**
* This method will return an ordered array of
* the the arguments that must be
* specified when calling this sensor operation.
*
* @return an ordered array of
* the arguments that must be
* specified when calling this sensor operation
*/
public Expression[] getArguments();
}
Expression instances can be created by using the ExpressionCreator class provided in the PMAC implementation:
/**
* Well known class that can be used
* to construct instances of Expression corresponding
* to a given Element object containing the XML representation of an ACEL
* expression.
*
* @author Dakshi Agrawal, Jim Giles, Kang-won Lee
* @since
1.2
*/
public class ExpressionCreator {
/**
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 20 of 34
Tivoli Software
ACEL User’s Guide
* Creates an expression based on the given element. Returns null if
* the expression cannot be created.
* @param e element
* @return expression, or null if none can be created.
* @throws ExpressionException if there is a problem creating the expression
*/
public static Expression createExpression(Element e) throws ExpressionException {
...
};
}
Finally, in order to extend ACEL by user-defined schema, the following interface is implemented by a deployer:
package com.ibm.autonomic.policy.expression;
/**
* Interface implemented by all providers of Expression.
* PMAC ships with an implementation of ExpressionFactory
* capable of creating Expression instances for all
* expression elements defined in PMAC schema. If a deployer wants to extend
* expression elements, they should do that in their own namespace and
* provide an implementation of this interface so that PMAC components can
* obtain Expression equivalent of their elements. Note that
* deployers would need to register their class with their namespace in a
* prescribed manner described elsewhere.<p>
*
* @author Dakshi Agrawal, James Giles, Kang-won Lee
* @since
1.1
*/
public interface ExpressionFactory {
/**
* Returns an Expression corresponding to the
* specified Element. <p>
*
* The usual steps in converting an Element into an
* Expression are as follows:
* <ul>
* <li> Check if the specified element is a known XML element that
* represents a known expression.
* <li> Parse element can create expressions corresponding to the
* arguments that the corresponding expression may take. This step
* may require a recursive call to this expression factory or to another
* expression factory via expression creator in the AML.
* <li>Create Expression corresponding to the specified element.
* </ul>
*
* @param element the specified Element
* @return corresponding instance of Expression
* @throws ExpressionException if there is a problem constructing the expression
*/
public Expression createExpression(Element element) throws ExpressionException;
}
3.2 Typical steps in parsing and evaluating an ACEL expression
Consider the following ACEL expression:
<Plus>
<IntConstant><Value>2</Value></IntConstant>
<IntConstant><Value>3</Value></IntConstant>
</Plus>
Typically this element would occur inside an XML document. In order to parse and evaluate this expression, following
steps needs to be performed:
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 21 of 34
Tivoli Software
•
•
•
•
ACEL User’s Guide
Parse XML document using a DOM parser and obtain an instance policyDocument of org.w3c.dom.Document.
Using the org.w3c.dom.* APIs, obtain the Element node xmlExpression from the policyDocument that corresponds
to the expression to be parsed and evaluated.
Create an Expression javaExpression instance by using ExpressionCreator Class.
Evaluate the expression using its evaluate method.
Java code performing above steps in the case of an XML document stored in a file would be as follows:
// read the XML document
String fileName;
InputSource xmlInputSource = new InputSource(new FileReader(fileName));
// obtain a DOM representation of the XML file
DocumentBuilderFactor dbf = DocumentBuilderFactory.newInstance();
dbf.setNamespaceAware(true);
DocumentBuilder = dbf.newDocumentBuilder();
Document policyDocument = db.parse(xmlInputSource);
/*
* fetch Plus element from the Document policyDocument. This step would be different for
different XML
* document structure.
*/
Element xmlExpression = (Element) policyDocument.getElementsByTagNameNS
("http://www.ibm.com/namespaces/autonomic/policy/expressions/1.2","Plus").item
(0);
// create Java expression
Expression javaExpression = ExpressionCreator.createExpression(xmlExpression);
// evaluate it
Object result = javaExpression.evaluate(null);
In this case, since the expression does not contain a variable, we can pass null to evaluate it. The result would be
Integer with value 5.
For expression containing variables, there is an additional step in which an instance of SensorLookup is prepared to
provide the evaluate method with variable values. If we are only using PropertySensor elements in ACEL expressions,
then a simple implementation of the interface SensorLookup can be done as follows:
/**
* A simple implementation of the SensorLookup interface
* that only provides values for PropertySensors.
* @author Dakshi Agrawal
*/
public class SensorLookupImpl extends HashMap implements SensorLookup{
public Object getSensorValue(String propertyName) {
return get(propertyName);
}
public Object getSensorOperation(SensorOperation operation) throws
UnsupportedOperationException{
throw new UnsupportedOperationException();
}
}
Now consider the following expression involving addition of three PropertySensors:
<Plus>
<PropertySensor propertyName="width"/>
<PropertySensor propertyName="height"/>
<PropertySensor propertyName="thickness"/>
</Plus>
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 22 of 34
Tivoli Software
ACEL User’s Guide
In order to parse and evaluate this expression with width, height, and thickness equal to 36, 24, 8, the following
example Java code can be used:
// read the XML document
String fileName;
InputSource xmlInputSource = new InputSource(new FileReader(fileName));
// obtain a DOM representation of the XML file
DocumentBuilderFactor dbf = DocumentBuilderFactory.newInstance();
dbf.setNamespaceAware(true);
DocumentBuilder = dbf.newDocumentBuilder();
Document policyDocument = db.parse(xmlInputSource);
/*
* fetch Plus element from the Document policyDocument. This step would be different for
different XML
* document structure.
*/
Element xmlExpression = (Element) policyDocument.getElementsByTagNameNS
("http://www.ibm.com/namespaces/autonomic/policy/expressions/1.2","Plus").item
(0);
// create Java expression
Expression javaExpression = ExpressionCreator.createExpression(xmlExpression);
// Prepare SensorLookup
SensorLookup s = new SensorLookupImpl();
s.put("width", new Integer(36));
s.put("height", new Integer(24));
s.put("thickness", new Integer(8));
// evaluate it
Object result = javaExpression.evaluate(s);
This case differs from the previous case only in the step of preparing a SensorLookup with appropriate values for
different variables and then passing it to the evaluate method. The result would be Integer with value 68.
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 23 of 34
Tivoli Software
ACEL User’s Guide
Chapter 4: BNF Grammar of ACEL3
Before we go into the details of elements defined in the Expressions schema V1.2, the following are some noteworthy
points:
5. Corresponding to datatypes defined in ACEL, the XML schema V1.2 defines the following groups of elements:
BooleanArgument, NumericArgument, StringArgument, CalendarArgument, URIArgument, CompositeDataArgument,
and CollectionArgument.
6.Expression schema V1.2 defines an abstract element SensorElement. Elements with substitution group
SensorElement represent variables in ACEL. The value of a variable is indeterminate at the time of authoring policies;
it is obtained at the runtime. The value of a variable could be of any type described above. A SensorElement element
does not contain information to determine the type of its value. SensorElement elements are members of all seven
argument groups BooleanArgument, NumericArgument, StringArgument, CalendarArgument, URIArgument,
CompositeDataArgument, and CollectionArgument.
7.In addition to SensorElement elements, BooleanArgument group contains all expression elements whose
substitution group is BooleanExpression. The expression elements with substitution group BooleanExpression have
the same value space as the XML schema type boolean.
8.The same is true for other data types. Elements in an argument group corresponding to a data type can be divided
into two categories: one corresponding to all expressions that have value of that type and another corresponding to
SensorElement elements.
9.All expression elements in Expressions schema V1.2 are grouped together as members of the group Argument.
Members of Argument group are: SensorElement elements and elements with substitution group BooleanExpression,
NumericExpression, StringExpression, CalendarExpression, URIArgument, CompositeDataArgument, or
CollectionArgument.
4.1 Elements with substitution group Expression
Elements with substitution group BooleanExpression, NumericExpression, StringExpression, CalendarExpression,
CompositeDataExpression, CollectionExpression, or URIExpression.
4.2 Elements with substitution group SensorElement
<PropertySensor
propertyName="xsd:QName">
</PropertySensor>
<OperationSensor portType="xsd:QName" operationName="xsd:NCName" >
Argument*
<OperationSensor />
4.3 ExpressionReference element
<ExpressionReference>
xsd:NCName
</ExpressionReference>
4.4 Members of Argument group
3 Conventions used in this representation are borrowed from WSDL Version 2.0 Part 1: Core Language Working Draft.
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 24 of 34
Tivoli Software
ACEL User’s Guide
Elements with substitution group SensorElement, elements with substitution group Expression, and
ExpressionReference element.
4.5 Members of BooleanArgument group
Elements with substitution group SensorElement, elements with substitution group BooleanExpression, and
ExpressionReference element.
4.6 Members of NumericArgument group
Elements with substitution group SensorElement, elements with substitution group NumericExpression, and
ExpressionReference element.
4.7 Members of StringArgument group
Elements with substitution group SensorElement, elements with substitution group StringExpression, and
ExpressionReference element.
4.8 Members of CalendarArgument group
Elements with substitution group SensorElement, elements with substitution group CalendarExpression, and
ExpressionReference element.
4.9 Members of CompositeDataArgument group
Elements with substitution group SensorElement, elements with substitution group CompositeDataExpression, and
ExpressionReference element.
4.10 Members of CollectionArgument group
Elements with substitution group SensorElement, elements with substitution group CollectionExpression, and
ExpressionReference element.
4.11 Members of URIArgument group
Elements with substitution group SensorElement, elements with substitution group URIExpression, and
ExpressionReference element.
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 25 of 34
Tivoli Software
ACEL User’s Guide
4.12 Elements with substitution group BooleanExpression
<BooleanConstant>
<Value>xsd:boolean</Value>
</BooleanConstant>
<ToBoolean>
StringArgument | NumericArgument
</ToBoolean>
<And>
BooleanArgument +
</And>
<Or>
BooleanArgument +
</Or>
<Not>
BooleanArgument
</Not>
<Xor>
BooleanArgument
</Xor>
BooleanArgument
<Greater>
[
NumericArgument
[
StringArgument
</Greater>
NumericArgument
StringArgument
]
]
|
<Less>
[
NumericArgument
[
StringArgument
</Less>
NumericArgument
StringArgument
]
]
|
<Equal>
[
BooleanArgument
BooleanArgument
] |
[
NumericArgument
NumericArgument
] |
[
StringArgument
StringArgument
]
[
CalendarArgument
CalendarArgument
] |
[
CompositeDataArgument CompositeDataArgument ]
</Equal>
<GreaterEqual>
[
NumericArgument
[
StringArgument
</GreaterEqual>
NumericArgument
StringArgument
]
]
|
<LessEqual>
[
NumericArgument
[
StringArgument
</LessEqual>
NumericArgument
StringArgument
]
]
|
<Begins>
StringArgument
</Begins>
<Contains>
StringArgument
StringArgument
StringArgument4
4 This function returns true if the first argument is a substring of the second argument and false otherwise. Ends works in an analogous
manner.
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 26 of 34
Tivoli Software
ACEL User’s Guide
</Contains>
<Ends>
StringArgument
</Ends>
StringArgument
<Like>
StringArgument
<StringTemplate>xsd:string</StringTemplate>
</Like>
<IsAfter>
CalendarArgument
</IsAfter>5
CalendarArgument
<IsBefore>
CalendarArgument
</IsBefore>6
CalendarArgument
<IsWithin>
CalendarArgument
</IsWithin>7
CalendarArgument
CalendarArgument
<Belongs>
Argument
CollectionArgument
</Belongs>
<PolicyTimePeriodExpression>
CalendarArgument
TimePeriodElement
</PolicyTimePeriodExpression>
<ContainsOnlyDigits>
StringArgument
</ContainsOnlyDigits>
<ContainsOnlyLetters>
StringArgument
</ContainsOnlyLetters>
<ContainsOnlyLettersOrDigits>
StringArgument
</ContainsOnlyLettersOrDigits>
<XPathBooleanExpression >8
<!--XPath 1.0 Location Path Expression
-->
<XPathLocation>XPath Location Path Expression specified as xsd:string</XPathLocation>
<!-- Context Node -->
CompositeDataArgument
</XPathBooleanExpression >
TimePeriodElement Element
<PolicyTimePeriod>
<TimeZone>
<tzID>"local" | "utc" | JavaTimeZoneIDs</tzID>
|
5 Returns true if the first calendar argument is after the second calendar argument.
6 Returns true if the first calendar argument is before the second calendar argument.
7 IsWithin checks to see if an instance of time is inside a time period including its start and end times. When taking three
CalendarExpressions, the first is the specified instance of time, and the remaining two define the start and end of the time period.
8 For a more detailed description of functions involving XPATH in Expressions1.2, see the accompanying "Composite Data FAQ" document.
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 27 of 34
Tivoli Software
ACEL User’s Guide
SensorElement9
<!-- TimeZoneID obtained from a sensor -->
</TimeZone> ?10
<TimePeriod>
<StartTime>
CalendarArgument
</StartTime>?
<EndTime>
CalendarArgument
</EndTime>?
</TimePeriod>?11
<MonthOfYearMask>
String matching the regular expression "(0|1){12}"
</MonthOfYearMask>?
<DayOfMonthMask>
String matching the regular expression "(0|1){62}"
</DayOfMonthMask>?
<DayOfWeekMask>
String matching the regular expression "(0|1){7}"
</DayOfWeekMask>?
<TimeOfDayMask>
<StartTime
preferStandardTime="xsd:boolean" ?
isLenient="xsd:boolean" ?>
<TimeZone>
<tzID>"local" | "utc" | JavaTimeZoneIDs</tzID>
</TimeZone>?12
<Value>
xsd:time restricted to exclude time zone information
</Value>
</StartTime>?
<EndTime
preferStandardTime="xsd:boolean" ?
isLenient="xsd:boolean" ?>
<TimeZone>
<tzID>"local" | "utc" | JavaTimeZoneIDs</tzID>
</TimeZone>?13
<Value>
xsd:time restricted to exclude time zone information
</Value>
</EndTime>?
</TimeOfDayMask>?
</PolicyTimePeriod>
4.13 Elements with substitution group NumericExpression
<ShortConstant>
<Value>xsd:short</Value>
</ShortConstant>
<IntConstant>
<Value>xsd:int</Value>
</IntConstant>
<LongConstant>
<Value>xsd:long</Value>
</LongConstant>
<FloatConstant>
<Value>xsd:float</Value>
</FloatConstant>
9 The SensorElement should return a valid value of tzID. At the time of authoring policies, this constraint cannot be imposed via schema. This
can only be checked at the runtime.
10 If TimeZone is not present, UTC is assumed.
11 If there is no TimePeriod element, then TimePeriod is assumed to be from THISANDPRIOR to THISANDFUTURE.
12 If there is no TimeZone element, UTC is assumed.
13 If there is no TimeZone element, UTC is assumed.
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 28 of 34
Tivoli Software
ACEL User’s Guide
<DoubleConstant>
<Value>xsd:double</Value>
</DoubleConstant>
<ToShort>
StringArgument | NumericArgument
</ToShort>
<ToInt>
StringArgument | NumericArgument
</ToInt>
<ToLong>
StringArgument | NumericArgument
</ToLong>
<ToFloat>
StringArgument | NumericArgument
</ToFloat>
<ToDouble>
StringArgument | NumericArgument
</ToDouble>
<Plus>
NumericArgument
NumericArgument
</Plus>
+
<Minus>
NumericArgument
NumericArgument
</Minus>
<Product>
NumericArgument
NumericArgument
</Product>
?
+
<Division>
NumericArgument
NumericArgument
</Division>
<Remainder>
NumericArgument
NumericArgument
</Remainder>
<Max>
NumericArgument
NumericArgument +
</Max>
<Min>
NumericArgument
NumericArgument +
</Min>
<Log>
NumericArgument
</Log>
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 29 of 34
Tivoli Software
ACEL User’s Guide
<Exp >
NumericArgument
</Exp>
<Pow>
NumericArgument
NumericArgument
</Pow>
<Sqrt>
NumericArgument
</Sqrt>
<Abs>
NumericArgument
</Abs>
<Round>
NumericArgument
</Round>
<Rint>
NumericArgument
</Rint>
<Floor>
NumericArgument
</Floor>
<Ceiling>
NumericArgument
</Ceiling>
<StringLength >
StringArgument
</StringLength>
<GetDayOfMonth>
CalendarArgument
</GetDayOfMonth>
<GetDayOfWeek>
CalendarArgument
</GetDayOfWeek>
<GetDayOfWeekInMonth>
CalendarArgument
</GetDayOfWeekInMonth>
<GetDayOfYear>
CalendarArgument
</GetDayOfYear>
<GetHour>
CalendarArgument
</GetHour>
<GetHourOfDay>
CalendarArgument
</GetHourOfDay>
<GetMinute>
CalendarArgument
</GetMinute>
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 30 of 34
Tivoli Software
ACEL User’s Guide
<GetSecond>
CalendarArgument
</GetSecond>
<GetMillisecond>
CalendarArgument
</GetMillisecond>
<GetWeekOfMonth>
CalendarArgument
</GetWeekOfMonth>
<GetWeekOfYear>
CalendarArgument
</GetWeekOfYear>
<GetMonth>
CalendarArgument
</GetMonth>
<GetYear>
CalendarArgument
</GetYear>
<ToMilliseconds>
CalendarArgument
</ToMilliseconds>
<XPathShortExpression >14
<!--XPath 1.0 Location Path Expression
-->
<XPathLocation>XPath Location Path Expression specified as xsd:string </XPathLocation>
<!-- Context Node -->
CompositeDataArgument
</XPathShortExpression >
<XPathIntExpression >15
<!--XPath 1.0 Location Path Expression
-->
<XPathLocation>XPath Location Path Expression specified as xsd:string </XPathLocation>
<!-- Context Node -->
CompositeDataArgument
</XPathIntExpression >
<XPathLongExpression >16
<!--XPath 1.0 Location Path Expression
-->
<XPathLocation>XPath Location Path Expression specified as xsd:string </XPathLocation>
<!-- Context Node -->
CompositeDataArgument
</XPathLongExpression >
<XPathFloatExpression >17
<!--XPath 1.0 Location Path Expression
-->
<XPathLocation>XPath Location Path Expression specified as xsd:string </XPathLocation>
<!-- Context Node -->
CompositeDataArgument
</XPathFloatExpression >
14 For
15 For
16 For
17 For
a
a
a
a
more
more
more
more
detailed
detailed
detailed
detailed
description of functions involving XPATH in Expressions1.2, see the accompanying "Composite Data FAQ" document.
description of functions involving XPATH in Expressions1.2, see the accompanying "Composite Data FAQ" document.
description of functions involving XPATH in Expressions1.2, see the accompanying "Composite Data FAQ" document.
description of functions involving XPATH in Expressions1.2, see the accompanying "Composite Data FAQ" document.
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 31 of 34
Tivoli Software
ACEL User’s Guide
<XPathDoubleExpression >18
<!--XPath 1.0 Location Path Expression
-->
<XPathLocation>XPath Location Path Expression specified as xsd:string </XPathLocation>
<!-- Context Node -->
CompositeDataArgument
</XPathDoubleExpression >
4.14 Elements with substitution group StringExpression
<StringConstant>
<Value>xsd:string</Value>
</StringConstant>
<ToString>
NumericArgument | BooleanArgument
</ToString>
<ToUpper>
StringArgument
</ToUpper>
<ToLower>
StringArgument
</ToLower>
<LeftSubstring>
[ StringArgument
|
[ StringArgument
</LeftSubstring>19
<MiddleSubstring>
[ StringArgument
"RightToLeft"/>
]
[ StringArgument
"RightToLeft"/>
]
[ StringArgument
"RightToLeft"/>
]
[ StringArgument
"RightToLeft"/>
</MiddleSubstring>
<RightSubstring>
[ StringArgument
] |
[ StringArgument
]
</RightSubstring>
NumericArgument <Direction direction="LeftToRight" | "RightToLeft"/>
StringArgument
]
NumericArgument NumericArgument <Direction direction="LeftToRight" |
|
StringArgument NumericArgument <Direction direction="LeftToRight" |
|
NumericArgument StringArgument <Direction direction="LeftToRight" |
|
StringArgument StringArgument <Direction direction="LeftToRight" |
]
NumericArgument
StringArgument
<ReplaceSubstring>
StringArgument
StringArgument
</ReplaceSubstring>
<Word>
StringArgument
</Word>
<Direction/>
]
StringArgument
<Direction direction="LeftToRight" | "RightToLeft"/>
<Direction direction="LeftToRight" | "RightToLeft"/>
StringArgument
NumericArgument
<Concatenate>
StringArgument StringArgument+
</Concatenate>
18 For a more detailed description of functions involving XPATH in Expressions1.2, see the accompanying "Composite Data FAQ" document.
19 Most of the StringExressions are suggested by Vaughn from Lotus. A description of these functions is in the Expressions1.2 SDD0.
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 32 of 34
Tivoli Software
ACEL User’s Guide
<Substring>
StringArgument NumericArgument NumericArgument?
</Substring>
<XPathStringExpression >20
<!--XPath 1.0 Location Path Expression
-->
<XPathLocation>XPath Location Path Expression specified as xsd:string </XPathLocation>
<!-- Context Node -->
CompositeDataArgument
</XPathStringExpression >
4.15 Elements with substitution group CalendarExpression
<DateTimeConstant
preferStandardTime="xsd:boolean" ?
isLenient="xsd:boolean" ?>
<TimeZone>
<tzID>"local" | "utc" | JavaTimeZoneIDs</tzID> |
SensorElement
<!-- TimeZoneID obtained from a sensor -->
</TimeZone> ?21
<Value>
xsd:dateTime restricted to exclude time zone information YYYY-MM-DDThh:mm:ss
</Value>
</DateTimeConstant>
<XPathCalendarExpression >22
<!--XPath 1.0 Location Path Expression
-->
<XPathLocation>XPath Location Path Expression specified as xsd:string</XPathLocation>
<!-- Context Node -->
CompositeDataArgument
</XPathCalendarExpression >
4.16 Elements with substitution group CollectionExpression
<CollectionConstant>
<Argument>*
</CollectionConstant>
4.17 Elements with substitution group CompositeDataExpression
<CompositeDataConstant>
XML element with no Expressions Schema V1.2 checking
</CompositeDataConstant>
<XPathCompositeDataExpression>
<!--XPath 1.0 Location Path Expression
-->
<XPathLocation>XPath Location Path Expression specified as xsd:string</XPathLocation>
<!-- Context Node -->
CompositeDataArgument
20 For a more detailed description of functions involving XPATH in Expressions1.2, see the accompanying "Composite Data FAQ" document.
21 If TimeZone is not present, UTC is assumed.
22 For a more detailed description of functions involving XPATH in Expressions1.2, see the accompanying "Composite Data FAQ" document.
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 33 of 34
Tivoli Software
ACEL User’s Guide
</XpathCompositeDataExpression>
4.18 Elements with substitution group URIExpression
<URIConstant>
<Value>xsd:string</Value>
</URIConstant>
© IBM Corporation 2005. All rights reserved.
Online version is the Master
Page 34 of 34
">