Path Expressions

A path expression is a string that is interpreted at runtime by the GenericObject class to traverse an object hierarchy and retrieve or assign the value of an attribute. Waveset uses a system of dots and brackets to represent objects and attributes in the hierarchy.

You use path expressions as the value of the name attribute in form fields when customizing a form (for example, <Field name=’user.waveset.roles’/>).

Traversing Objects

The following simple example illustrates a GenericObject with two attributes:

• name (String)

• address (GenericObject) The address object, in turn, has an attribute named street, which is a string.

To create a path expression to the street attribute of the address object, use address.street.

Path expressions use the dot character (.) to indicate traversal from one object to another. This is similar to the way dot is used in Java or the ’->’ operator is used in C. Paths can be long, as illustrated by this example:

user.role.approver.department.name

Traversing Lists

You can also use path expressions to traverse values that are lists. Consider an object that has an attribute children whose value is a java.util.List. Each object in the list is itself a GenericObject with a name attribute and an age attribute. Write the path to the name of the first child as:

children[#0].name

Path expressions use square brackets to indicate the indexing of a list. The token between brackets is the index expression. In the simplest case, this is a positive integer that is used to index the list by element position.

Typically, the position of an object in a list is arbitrary. Index expressions can also specify simple search criteria to identify one object in the list. Objects in a list typically have a name attribute, which serves to uniquely identify this object among its peers. Path expressions support an implicit reference to an object’s name attribute within the index expression.

For example

children[hannah].age

The preceding path expression obtains the list of objects stored under the children attribute. This list is searched until an object with a name attribute equal to hannah is found. If a matching object is found, Waveset returns the value of the age attribute.

Example: Using the = Operator

<ref>accountInfo.accounts[type=vms].name</ref>

accountInfo.accounts[type=vms].name returns a list of names for VMS resources. It returns a list of only one element if only one exists.

Using the == Operator

children[hannah].age is equivalent to children[name==hannah].age. If you search using type=LDAP for example, you would get a list of names of LDAP resources. However, if you use the == operator, the result is a single object. For example, children[parent=hannah].occupation returns a list of occupations for all of hannah’s children, but children[parent==hannah].occupation returns a single occupation (not in a list) for whichever child was found first.

Example

<index i=’0’>
<   ref>accountInfo.accounts[type=vms].name</ref>
</index>

is equivalent to

<ref>accountInfo.accounts[type==vms].name</ref>

If more than one account with type vms exists, then either example will return the first account found with no particular guaranteed ordering.

Calculating Lists

You can also write path expressions that calculate List values that are not stored in the object. For example:

accounts[*].name

When an asterisk is found as an index expression, it implies an iteration over each element of the list. The result of the expression is a list that contains the results of applying the remaining path expression to each element of the list. In the previous example, the result would be a list of String objects. The strings would be taken from the name attribute of each object in the accounts list.

Path expressions with * (asterisk) are used with the FieldLoop construct in forms to replicate a collection of fields.