Sun Identity Manager Deployment Reference

Chapter 6 XML Object Language

The XML Object Language is a collection of XML elements that you can use to represent common Java objects such as strings, lists, and maps.

See Chapter 5, XPRESS Language for information about using expressions to include logic in your forms.

Understanding XML Object Language

XML Objects are often used in forms, but you can also use them in workflows and rules. One common use is to create a list of allowed values for a Select or MultiSelect field in a form, as shown below.

Example

<Field name=’global.state’>

    <Display class=’Select’>

       <Property name=’title’ value=’State’/>

       <Property name=’allowedValues’>

         <List>

            <String>Alabama</String>

            <String>Alaska</String>

            <String>Arizona</String>

            <String>Arkansas</String>

            <String>California</String>

            <String>Washington</String>

            <String>Washington D.C.</String>

            <String>West Virginia</String>

            <String>Wisconsin</String>

            <String>Wyoming</String>

         </List>

       </Property>

    </Display>

</Field>

Elements in the XML Object language are similar to elements in the XPRESS language, but it is more efficient to use the XML Object language if the values are static.

These two languages differ primarily in that XML Object language does not allow the contents of an object to be computed with an expression. This restriction allows the system to construct the object more efficiently, which will result in faster processing if the object is large.

When defining lists with XML Object language, the list is created once when the form is read from the repository and reused thereafter. When defining lists with XPRESS, a new list is created every time the form is displayed.

XML Object Language and Corresponding XPRESS

The following table lists several basic XML objects and the equivalent XPRESS expressions, if available.

Table 6–1 Basic XML Objects and Equivalent XPRESS Expressions


XML Object Language	XPRESS Language
`<String>cat</String>`	`<s>cat</s>`
`<Integer>10</Integer>`	`<i>10</i>`
`<Boolean>true</Boolean>` `<Boolean>false</Boolean`	`<i>1</i>` `<i>0</i>`
`<null/>`	`<null/>`
`<Map>` `<MapEntry key=’name’ value=’neko’/>` `<MapEntry key=’ID’ value=’123’/>` `</Map>`	`<map>` `<s>name</s>` `<s>neko</s>` `<s>ID</s>` `<i>123</i>` `</map>`
`<List>` `<String>cat</String>` `<String>dog</String>` `<integer>673</Integer>` `</List>`	`<list>` `<s>cat</s>` `<s>dog</s>` `<i>673</i>` `</list>`
`<Long>123456789</Long>`	`N/A`
`<Date>20020911 09:15:00</Date>`	`N/A`

You cannot use XPRESS statements within an XML object.

Using XML Objects in XPRESS

You can use XML objects within XPRESS anywhere an expression is allowed. In the example below, a map is passed as an argument to an invoked method.

<invoke name=’printTheMap’>

    <ref>mapPrinter</ref>

       <Map>

       </Map>

</invoke>

In releases prior to 2.0, XPRESS required that all XML Objects be wrapped in an <o> element. While this is no longer required, you may still encounter its use in older files containing XPRESS.

When to Use XML Object Language Instead of XPRESS

Although both XML Object Language and XPRESS provide ways of representing lists in forms, XML Object syntax is more efficient than XPRESS if the list is long and contains static data. The list is built in memory once and it is reused every time it is referenced. In contrast, XPRESS list syntax is re-evaluated on every reference and a new list is created each time.

The XML object language is most typically used when creating lists of the information described in the following table.

Table 6–2 XML Use for Information Lists


Type of Information Lists	Where Used
Machine names	forms
Business sites	forms
Approver names	workflow

Representing Lists in XML Object Language and XPRESS

Both XML Object Language and XPRESS provide ways of representing lists in forms.

Using XPRESS to Represent a List

You use the <list> element when representing lists in XPRESS. The contents of the <list> element can be any XPRESS expression.

Note –

Use only the <list> XPRESS element in forms if the list must contain calculated elements. Using the <list> element can slow the execution of the form in which it is included. This degradation in performance is typically not noticeable unless the list contains many elements. It is permissible and common for forms to use <list>.

The following example uses the <s> string constants in the XPRESS list, but you can also use the <invoke> or <concat> elements to dynamically build the list elements.

Example

<list>

   <s>cat</s>

   <s>dog</s>

</list>

Using XML Object Language to Represent a List

The XML Object language uses the <List> element to represent lists. The contents of the <List> element can be only other XML Objects. In the following example, the content of the <List> element are <String> elements.

Example

<List>

   <String>cat</String>      

   <String>dog</String>    

</List>

Example Form Using Both Types of Syntax

The following form incorporates fields containing lists defined by both XML Object syntax and XPRESS.

<Form>

    <Field name=’department’>

      <Display class=’Select’>

        <Property name=’allowedValues’>

          <List>

           <String>Engineering</String>

           <String>Marketing</String>

           <String>Sales</String>

          </List>

        </Property>

      </Display>

    </Field>

 

    <Field name=’department2’>

      <Display class=’Select’>

        <Property name=’allowedValues’>

          <expression>

            <list>

              <s>Engineering</s>

              <s>Marketing</s>

              <s>Sales</s>

            </list>

          </expression>

        </Property>

      </Display>

    </Field>

</Form>

The allowedValues list in the department field is defined as a static list built with <List>. No matter how many times this form is used, only one list is created. In contrast, the allowedValues list in the department2 field is defined with a <list> expression. A new list is created every time this form is used.

Defining Map Objects with XML Object Syntax and XPRESS

You can use either the XML Object syntax or XPRESS to dynamically construct Map objects. Using the XPRESS <map> element is similar to using the XML Object language <Map> and <MapEntry> elements. These elements differ in that the contents of <map> can be calculated using expressions. In contrast, the <Map> element can only define static maps.

Note –

Maps are sometimes used as arguments to methods that are called with an <invoke> expression. For example, certain methods in the FormUtil class require maps as arguments.

Using XPRESS to Represent a Map

The contents of the XPRESS <map> element are pairs of name/value expressions. The even-numbered expressions define map keys, and odd-numbered expressions define map values. If any key expression evaluates to null, the entry is ignored.

You can use the XPRESS <map> element to dynamically construct java.util.HashMap objects:

 <map>

   <s>name</s>

   <s>Jeff</s>

   <s>phone</s>

   <s>338-1818</s>

</map>

Using XML Object Syntax to Map Objects

You can use XML Object syntax to define map objects as follows:

<Map>

   <MapEntry key=’name’ value=’Jeff’/>

   <MapEntry key=’phone’ value=’338-1818’/>

</Map>