IBM Tivoli Composite Application Agent for WebSphere Applications, Version 7.2

Defining iteration symbols

Within the <symbolDefinitions> tag, you can define an iteration symbol using the <iterationSymbol> tag. An iteration symbol represents a value that is acquired by iterating through a set of objects in a Java™ array, Enumeration, or Collection. For each of the members, Request Mapper evaluates one or more condition expressions. If an expression returns true, Request Mapper uses the member to calculate the return value. Once a member meets the condition expression, Request Mapper does not evaluate the rest of the members.

Within the <iterationSymbol> tag, use the following tags.

<name>: The name of the symbol. It is a string and must start with the $ character.

<type>: The type of the value that the symbol returns. Specify this value as a fully qualified Java class name or a Java primitive. Specifying the type for the symbol is optional. If it is not defined, the Request Mapper attempts to establish the field type based on the expression. If the Request Mapper is unable to determine the symbol type before evaluating the expression, performance is affected. Therefore, for best performance, it is better to specify the type.

<args>: The arguments for the symbol. This tag is optional; if it is specified, arguments must be supplied for evaluating the symbol. For more information, see Defining symbol arguments.

<iterate over="expression">

Defines the object (array, Enumeration, or Collection) that contains the members to iterate through. The expression must return such an object. Request Mapper iterates over its members until either one of them causes a condition expression to return true, or no more members remain. Define the set of iteration expressions in tags within this tag:

<test>

Define the condition and return expression within this tag. An <iterate> tag can contain several <test> tags. In this case, Request Mapper evaluates all of them. If any condition expression is true, the symbol returns a value using the result expression in the same <test> tag, and no further evaluation is performed.

<castTo>: Optional: If this tag is present, specify the name of a Java type within it, as a fully qualified Java class name or a Java primitive. Request Mapper casts the iterated element to this type before evaluating the condition and return expressions. If this tag is not present, Request Mapper casts a member of an array to the array base type, and a member of an Enumeration or Collection to java.lang.Object. For an array member, the array base type is usually the correct choice; therefore, use this tag when iterating over an Enumeration or Collection.

<condition>: An expression that must yield a Boolean value. Use $iterElement to refer to the element that is being iterated.

<return>: If the expression in the <condition> tag returns true, Request Mapper evaluates the expression in the <return> tag. The iteration symbol returns the value that this expression produces. Use $iterElement to refer to the element that is being iterated.

<defaultValue>: Optional. If Request Mapper has iterated over all members of the object, but no condition expression has returned true, Request Mapper evaluates the expression in the <defaultValue> tag. The iteration symbol returns the value that the expression produces. If this tag is not present, the default value is null.

Examples

<iterationSymbol>
  <name>$userNameCookieValue</name>
  <iterate over="$httpServletRequest.getCookies()">
     <test>
        <condition>$iterElement.getName().equals("userName")</condition>
        <return>$iterElement.getValue()</return>
     </test>
   </iterate>
</iterationSymbol>

This symbol finds the cookie named "username", and returns its value. $httpServletRequest.getCookies() returns an array, so there is no need for the <castTo> element.

<iterationSymbol>
  <name>$headerNameStartingWithA</name>
  <iterate over="$httpServletRequest.getHeaderNames()">
    <test>
       <castTo>java.lang.String</castTo>
       <condition>$iterElement.startsWith("A")</condition>
       <return>$iterElement</return>
    </test>
  </iterate>
</iterationSymbol>

This symbol finds the header with a name starting with "A", and returns its name. $httpServletRequest.getHeaderNames() returns an Enumeration, so the <castTo> element is required.

<iterationSymbol>
  <name>$determined_gender</name>
  <iterate over="$children">
    <test>
       <castTo>java.lang.String</castTo>
       <condition>$iterElement.equals("male")</condition>
       <return>"It's a boy"</return>
    </test>
    <test>
       <castTo>java.lang.String</castTo>
       <condition>$iterElement.equals("female")</condition>
       <return>"It's a girl"</return>
    </test>
  </iterate>
  <defaultValue>"unknown"</defaultValue>
</iterationSymbol>

This symbol iterates over $children, which must be an array, Enumeration, or Collection of strings. If any of the strings equals "male", it returns "it’s a boy". If any of the strings equals "female", it returns "it’s a girl". Finally, if no string in the $children object equals either "male" or "female", the symbol returns "unknown".

Feedback