Defining the property value

Business Object Wizard displays the agent-property value in the Value column of the Configure Agent (configuration property) or BO Properties dialog box. As part of the process of initializing an agent property, you must address the following tasks:

Choosing the type of display control

Business Object Wizard uses the following AgentProperty metadata to determine the type of control for displaying the property value:

Table 51 illustrates the possible combinations for displaying the property-value control.

Table 51. Possible property-value control types.

Cardinality Displays multiple values (isMultiple) Are valid values
(all ValidValues) provided?
Explanation
1
 
false
 
No The property value displays as a plain edit control; that is, a simple box in which users can enter and edit one value.
1
 
true
 
Yes The property value displays as a drop-down list that displays the specified valid values (see Figure 71). From this list, users can choose only one value.
n
 
true
 
Yes The property value displays as a drop-down list that contains the specified valid values. Each value in this list displays with a check box that, if selected, allows the value to be included in the property's value set (see Figure 71).
n
 
true
 
No The property value displays as a grid control that contains no displaying values. Initially, this grid displays a sub-grid with one empty row. If users enter text in that row, Business Object Wizard inserts another empty row. This process continues until users finish entering new rows. To delete a value, users delete the value's text. Business Object Wizard includes only non-empty rows in the property's value set.

When Business Object Wizard displays a single-cardinality property that does not have valid values, it just leaves the property's Value field empty. You can, however, define a default value for the property. In this case, Business Object Wizard displays the default value in the Value field. For more information, see Specifying default values.

Figure 71 illustrates two controls that display multiple values (isMultiple = true) in Business Object Wizard.

Figure 71. Single- and multiple-cardinality controls for properties with multiple values.

Figure 71 shows single- and multiple-cardinality controls, both of which display multiple values in a drop-down list:

Specifying default values

To specify a default value for an agent property, you provide its default value (or values) in the its allDefaultValues member variable. This member variable is an array of Object values. The number of elements in this array must correspond to the cardinality of the property, as follows:

Business Object Wizard assigns the default value to the property before it displays the property. If users do not override this default by specifying a property value, this default value remains as the property value.

Note:
Any valid values specified for the property are not automatically its default values. You must explicitly specify default values.

Table 52 summarizes the behavior of default values.

Table 52. Default values for agent properties

Cardinality Contents of allDefaultValues Display
Single One element

With valid values (isMultiple=true):
default value displays as a "checked" item in the drop-down list of valid values.

With no valid values (isMultiple=false): default value displays in the property's Value field.

Multiple One or more elements Default values display as "checked" items in the drop-down list of valid values.

Initializing a single-cardinality property

To initialize a single-cardinality agent property, take the following steps:

The following code fragment initializes a single-cardinality agent property that does not provide a list of values to choose from, and has a default value of 256:

defaultVal[0] = 256;
 AgentProperty("Property1", AgentProperty.TYPE_INTEGER, "Description of property",
    false, false, ODKConstant.SINGLE_CARD, null, defaultVal); 
 

Initializing a multiple-cardinality property

To initialize a multiple-cardinality agent property, take the following steps:

The code fragment in Figure 65 initializes a multiple-cardinality agent property named Verbs, which has a list of valid values and default values.

Copyright IBM Corp. 1997, 2004