There are two situations in which an ODA provides agent properties to Business Object Wizard:
To represent an agent property, the ODK API defines an agent-property
object, which is an instantiation of the
AgentProperty class. When you instantiate the agent-property
object, you initialize some or all of its member variables, shown in Table 51.
To instantiate an agent-property object, use one of the forms of the AgentProperty() constructor:
Table 52 shows the basic information about an agent property that the
agent-property object contains.
Table 52. Basic information for an agent property
Basic property information | AgentProperty member variable | Description |
---|---|---|
Name |
propName
|
Identifies the agent property. Business Object Wizard displays this value in the Property column of the
Configure Agent (configuration property) or BO Properties (business-object
property) dialog box. You can initialize the agent property's name
with any of the forms of the AgentProperty() constructor.
|
Description
|
description
|
Provides additional information to describe the purpose of the agent property. Business Object Wizard displays this value in the Description column of the
Configure Agent (configuration property) or BO Properties (business-object
property) dialog box. You must use either the second or third form of
the AgentProperty() constructor to initialize the agent
property's description.
|
Data type |
type
|
Defines the data type of the values that the agent property holds. Business Object Wizard displays this value in the Type column of the
Configure Agent (configuration property) or BO Properties (business-object
property) dialog box. If you use the first form of the
AgentProperty() constructor to initialize the agent property (which
specifies only the property name), the agent property's type defaults to
String. To specify a type, use the second or third form of the
AgentProperty() constructor to initialize the agent
property. Represent the agent property's type with one of the
property-type constants shown in Table 69.
|
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:
Business Object Wizard uses the following AgentProperty metadata to determine the type of control for displaying the property value:
Table 53 illustrates the possible combinations for displaying the
property-value control.
Table 53. 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 73). 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 73). |
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 73 illustrates two controls that display multiple values (isMultiple = true) in Business Object Wizard.
Figure 73. Single- and multiple-cardinality controls for properties with multiple values.
Figure 73 shows single- and multiple-cardinality controls, both of which display multiple values in a drop-down list:
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.
Table 54 summarizes the behavior of default values.
Table 54. Default values for agent properties
Cardinality | Contents of allDefaultValues | Display |
---|---|---|
Single | One element |
With valid values (isMultiple=true):
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. |
To initialize a single-cardinality agent property, take the following steps:
If you do not provide a list of valid values, set the isMultiple variable as false and do not pass in a valid-value array.
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);
To initialize a multiple-cardinality agent property, take the following steps:
If you do not provide a list of valid values, Business Object Wizard provides a sub-grid for users to specify each property value.
The code fragment in Figure 67 initializes a multiple-cardinality agent property named Verbs, which has a list of valid values and default values.
The AgentProperty class provides the ability to define
conditions on an agent property. A condition can restrict
the values of one agent property, called a dependent property,
based on the value of another agent property. A condition has two
parts, each part a particular kind of subcondition, as Table 55 shows.
Table 55. Parts of an agent-property condition
To represent a condition, the ODK API defines a complete-condition object,
which is an instantiation of the
CompleteCondition class. Table 56 shows the member variables that a complete-condition object
contains.
Table 56. Contents of a complete-condition object
A complete-condition object contains the information that describes a single condition on an agent property. An agent property can have many conditions defined on it. Each condition's complete-condition object is stored in the allDependencies member variable of the agent property's AgentProperty object.
To create one condition on an agent property, take the following steps:
The
InputCondition class represents an input condition,
which describes a condition on the current agent property's value.
When an input condition evaluates to true, the associated dependent conditions
are applied to the dependent agent property. Table 57 shows the information needed to define an input
condition.
Table 57. Information for an input condition
To create an input condition, use one of the forms of the InputCondition() constructor. The code fragment in Figure 76 creates input conditions that compare the agent-property value with two constant string values, "optionA" and "optionB". You can also compare the agent-property value with some other property's value. The code fragment in Figure 74 creates an input condition to compare an agent property's value with the value currently in the Property2 agent property.
Figure 74. Input condition to compare a property value with another property's value
// Instantiate a complete-condition object condition1 = new CompleteCondition();
// Input condition to compare property value with // Property2's value condition1.allInputConditions[0] = new InputCondition( CompleteCondition.OP_NOT_EQUAL, true, AgentProperty.TYPE_INTEGER, "Property2");
In Figure 74, the isDynamic member variable is set to true so that Business Object Wizard knows to first obtain the current value of the Property2 property before comparing the user-specified value with this value. In addition, the specificValue is set to "Property2", the name of the property against which the comparison is made. As a result of this input condition, the dependent conditions for the property apply only if this property's value is not the same as Property2's value.
The
DependentCondition class represents a dependent
condition, which describes a restriction on the value a particular
dependent property. A dependent property is a property whose value in
some way depends on the current property's value. When the
associated input condition (or conditions) evaluates to true, the dependent
property's value must meet the restriction that the dependent condition
specifies. Table 58 shows the information needed to define a dependent
condition.
Table 58. Information for a dependent condition
To create a dependent condition, use one of the forms of the DependentCondition() constructor. The code fragment in Figure 76 creates the following dependent conditions:
You can also compare the dependent-property value with some other property's value. The code fragment in Figure 75 creates a dependent condition to compare a dependent property's value with the value currently in the Property2 agent property.
Figure 75. Dependent condition to compare a property value with another property's value
// Dependent condition to compare property value // with Property2's value condition1.allDependentConditions[0] = new DependentCondition( CompleteCondition.OP_EQUAL, true, AgentProperty.TYPE_INTEGER, "Property2");
In Figure 75, the isDynamic member variable is set to true so that Business Object Wizard knows to first obtain the current value of the Property2 property before comparing the dependent property's value with this value. In addition, the specificValue is set to "Property2", the name of the property against which the comparison is made.
Suppose that you want to define conditions on an agent property (Property1) that specifies restrictions on two dependent properties, based on values of Property1, as follows:
Figure 76 shows the code that implements these two conditions.
Figure 76. Defining two agent-property conditions
// 1. Instantiate the complete-condition object condition1 = new CompleteCondition();
// 2. Create the condition on the "optionA" value // a) Instantiate the input condition on "optionA" condition1.allInputConditions[0] = new InputCondition( CompleteCondition.OP_EQUAL, false, AgentProperty.TYPE_STRING, "optionA");
// b) Instantiate the dependent conditions for DepProperty1 condition1.allDependentConditions[0] = new DependentCondition( "DepProperty1", CompleteCondition.OP_EQUAL, false, AgentProperty.TYPE_INTEGER, "0");
condition1.allDependentConditions[1] = new DependentCondition( "DepProperty1", CompleteCondition.OP_EQUAL, false, AgentProperty.TYPE_INTEGER, "1");
condition1.allDependentConditions[2] = new DependentCondition( "DepProperty1", CompleteCondition.OP_EQUAL, false, AgentProperty.TYPE_INTEGER, "256");
condition1.allDependentConditions[3] = new DependentCondition( "DepProperty1", CompleteCondition.OP_EQUAL, false, AgentProperty.TYPE_INTEGER, "512");
// 3. Instantiate the next complete-condition object condition2 = new CompleteCondition();
// 4. Create the condition on the "optionB" value // a) Instantiate the input condition on "optionB" condition2.allInputConditions[0] = new InputCondition( CompleteCondition.OP_EQUAL, false, AgentProperty.TYPE_STRING, "optionB");
// b) Instantiate the dependent conditions for DepProperty2 condition2.allDependentConditions[0] = new DependentCondition( "DepProperty2", CompleteCondition.OP_GREATER_THAN_EQUAL, false, AgentProperty.TYPE_INTEGER, "1");
condition2.allDependentConditions[1] = new DependentCondition( "DepProperty2", CompleteCondition.OP_LESS_THAN_EQUAL, false, AgentProperty.TYPE_INTEGER, "5");
// Save conditions in the agent-property object agentProp.allDependencies[0] = condition1; agentProp.allDependencies[1] = condition2;