Beginning execution of the ODA

When the ODA is started, the ODA runtime instantiates the associated ODA class (an extension of ODKAgentBase2) and then calls the class methods in Table 28.


Table 28. Beginning execution of the ODA

Initialization task ODKAgentBase2 method For more information
1. Obtain the configuration properties, including those that describe the data source to open. getAgentProperties() Obtaining configuration properties
2. Initialize the ODA meta-data so that Business Object Wizard can obtain information about the ODA (especially its supported content). getMetaData() Initializing ODA meta-data
3. Initialize the ODA to perform any necessary startup steps, such as opening a connection to the data source. init() Initializing the ODA execution

The following sections describe each of the steps in Table 28.

Obtaining configuration properties

To begin ODA initialization, Business Object Wizard calls the getAgentProperties() method of the ODA class. The getAgentProperties() method is part of the low-level ODA base class, ODKAgentBase. It is inherited by the ODA base class, ODKAgentBase2, then inherited in turn by your ODA class.

Important:
As part of the implementation of your ODA class, you must implement an getAgentProperties() method.

The getAgentProperties() method performs the following tasks:

Obtaining the handle to the ODKUtility object

Because getAgentProperties() is the first ODA method that Business Object Wizard calls, it is a good place to instantiate the ODKUtility object, which provides the ODA code with access to the following:

To obtain access to an ODKUtility object, use the getODKUtility() method. This method, defined in the ODKUtility class, returns a handle to the ODKUtility object.

odkUtil = ODKUtility.getODKUtility()

If you declare the handle to the ODKUtility object as global to the entire ODA class, all methods within this class can access the utility methods.

Note:
Instead of instantiating the ODKUtility object in its getAgentProperties() method, the sample Roman Army ODA provides a member variable named m_utility in its ODA class and initializes it as follows:
final ODKUtility m_utility = ODKUtility.getODKUtility();

Initializing the configuration-property array

As Obtaining ODA configuration properties describes, Business Object Wizard uses the configuration-property array that getAgentProperties() returns to initialize the Configure Agent dialog (Step 2). This dialog displays all ODA configuration properties and allows the user to enter or change their values. The configuration-property array is an array of AgentProperty objects. The AgentProperty class provides support for the configuration property to have the following features:

Note:
For more information, see Working with agent properties.

The purpose of getAgentProperties() is to send to Business Object Wizard an array of AgentProperty objects that describe the ODA configuration properties. To initialize the configuration-property array in getAgentProperties(), take the following steps:

  1. Instantiate an AgentProperty object for a configuration property, initializing it with the appropriate property information.

    The implementation of the getAgentProperties() method must instantiate agent-property objects for each configuration property that the Business Object Wizard is to display to the user. When you instantiate the agent-property object, you initialize some or all of its member variables (shown in Table 49).

  2. Store the initialized AgentProperty object in the configuration-property array.
  3. Return the initialized configuration-property array from the getAgentProperties() method.

Figure 58 shows the implementation of the getAgentProperties() method (defined in the ArmyAgent2 class of the sample Roman Army ODA).

Figure 58. Initializing the configuration-property array

public AgentProperties[] getAgentProperties()
   throws com.crossworlds.ODK.ODKException
{
   AgentProperty general = new AgentProperty("Army general", 
      AgentProperty.TYPE_STRING, true, false, false,
      "A general is a soldier at least 45 years old", true,
      ODKConstant.SINGLE_CARD, m_generals.toArray(), null);
   AgentProperty recAdop = new AgentProperty("Allow adoption", 
      AgentProperty.TYPE_BOOLEAN, true, false, false,
      "Select \"yes\" if adopted children can be business objects", true,
      ODKConstant.SINGLE_CARD, new Object[]{"true", "false"}, null);
   AgentProperty minAge = new AgentProperty("Minimum age for drafting", 
      AgentProperty.TYPE_INTEGER, true, false, false,
      "Drafted soldiers will be generable nodes", false,
      ODKConstant.SINGLE_CARD, null, new Object[] {"15"});
   AgentProperty maxAge = new AgentProperty("Maximum age for drafting", 
      AgentProperty.TYPE_INTEGER, true, false, false,
      "Drafted soldiers will be generable nodes", false,
      ODKConstant.SINGLE_CARD, null, new Object[] {"55"});
   AgentProperty minAdo = new AgentProperty("Minimum age for adopting", 
      AgentProperty.TYPE_INTEGER, true, false, true,
      "Drafted soldiers will be generable nodes", false,
      ODKConstant.SINGLE_CARD, null, new Object[] {"" + m_minAdoptionAge});
   AgentProperty[] props = new AgentProperty[]
      {general, minAge, maxAge, recAdop, minAdo});
   return props;
}

Figure 58 initializes the five ODA configuration properties for the sample Roman Army ODA. The actual properties you define depend on the specific data source your ODA is accessing.

When the user has specified values for the configuration properties, Business Object Wizard saves these properties in the memory of the ODA runtime. The ODA can access these properties through methods such as the getAgentProperty() method in the ODKUtility class. For more information, see Retrieving ODA configuration properties.

Initializing ODA meta-data

After Business Object Wizard calls the ODA's getAgentProperties() method, it calls the getMetaData() method to initialize the ODA meta-data. The getMetaData() method is defined in the ODA base class, ODKAgentBase2, then inherited by your ODA class. It returns an AgentMetaData object, which contains the ODA's meta-data, including the generated content it supports.

Important:
The getMetaData() method is an abstract method. As part of the implementation of your ODA class, you must implement a getMetaData() method.

The AgentMetaData object provides the information in Table 29 to the ODA runtime when it needs to obtain meta-data for the ODA.

Table 29. Contents of an AgentMetaData object

Member variable Description

agentVersion

The version of the ODA

searchableNodes, searchPatternDesc

Information to specify the ODA search pattern, which the user can specify to reduce the number of tree nodes from the data source that are displayed


supportedContent

A description of the generated content that the ODA can support

To initialize the ODA meta-data, you implement the getMetaData() method, which involves the following steps:

Figure 59 shows the implementation of the getMetaData() method (defined in the ArmyAgent2 class from the sample Roman Army ODA).

Figure 59. Initializing ODA meta-data

public AgentMetaData getMetaData(){
   odkUtil.trace(TRACELEVEL1, XRD_TRACE, "Entering getMetaData()...");
   AgentMetaData amdObj = new AgentMetaData(this, "Sample ODA v1.0.0");
   //Initialize search-pattern feature for tree nodes
   amd.searchableNodes = true;
   amd.searchPatternDesc = "Enter the first letter to search by. For example, " +
      "\"A\", \"k\", "\Z\". Only names that start with this letter will be " +
      "returned."
   return amd;
}

Because the getMetaData() method in Figure 59 is inherited by the ArmyAgent3 class (which implements the IGeneratesBoDefs interface), the call to the AgentMetaData() constructor in this code fragment initializes the content type and its associated content protocol for the ODA. After getMetaData() executes in ArmyAgent3, the ODA's content type is initialized to ContentType.BusinessObject and its content protocol to "on request". For more information, see Determining the ODA generated content.

This getMetaData() method also provides support for the search-pattern feature by initializing the searchableNodes and searchPatternDesc member variables. The searchPatternDesc variable contains the text that displays in the Enter the Search Pattern dialog, which displays to the user (see Figure 49).

Initializing the ODA execution

After Business Object Wizard calls the ODA's getMetaData() method, it calls the init() method to begin initialization of the ODA execution. Business Object Wizard. The init() method is part of the low-level ODA base class, ODKAgentBase. It is inherited by the ODA base class, ODKAgentBase2, then inherited in turn by your ODA class. This method performs initialization steps for the ODA.

Important:
The init() method is an abstract method. As part of the implementation of your ODA class, you must implement an init() method.

The main tasks of the init() method include:

Retrieving ODA configuration properties

The init() method can retrieve any of the user-initialized configuration properties it needs to complete the initialization of the ODA. The ODA initializes its configuration properties in its getAgentProperties() method. The user then updates these properties as needed in the Configure Agent dialog of Business Object Wizard. Once the user has updated configuration properties, Business Object Wizard writes them to the memory of the ODA runtime.

The ODK API provides the methods in Table 30 for retrieving the value of an ODA configuration property from the ODA-runtime memory.

Table 30. Methods to retrieve the value of an ODA configuration property

ODK library method Description
getAgentProperty()
Retrieves the value of a specified ODA configuration property
getAllAgentProperties()
Retrieves the values of all ODA configuration properties as a Java Hashtable object

All methods in Table 30 are defined in the ODKUtility class. Therefore, you must obtain a handle to the singleton object of this class before you can access any configuration properties. For more information, see Obtaining the handle to the ODKUtility object.

Figure 60 shows the implementation of the init() method (defined in the ArmyAgent3 class from the sample Roman Army ODA).

Figure 60. Initializing the ODA

public void init() throws com.crossworlds.ODK.ODKException
{
   Hashtable h = m_utility.getAllAgentProperties();
// Obtain values of ODA configuration properties
   AgentProperty property = (AgentProperty) h.get("Army general");
   m_general = property.allValues[0].toString();
   property = (AgentProperty) h.get("Minimum age for drafting");
   m_minAge = Integer.parseInt(property.allValues[0].toString());
   property = (AgentProperty) h.get("Maximum age for drafting");
   m_maxAge = Integer.parseInt(property.allValues[0].toString());
   property = (AgentProperty) h.get("Allow adoption");
   m_allowAdoption = new Boolean(
      property.allValues[0].toString()).booleanValue();
// Clear the generated-content structure
   m_generatedBOs.clear();
}

In Figure 60, the init() method uses the following to obtain configuration-property values:

The configuration properties that this init() method obtains are all single-cardinality properties. Therefore, the allValues member variable contains only a single value. For an example of using multiple-cardinality properties, see Creating the business-property array. This init() method also initializes the ODA's generated-content structure, a vector called m_generatedBOs. This vector will hold the generated business object definitions.

Establishing a connection

The main task of the init() initialization method is usually to establish a connection to the data source. The ODA searches the data source to "discover" objects for potential conversion to business object definitions. To establish the connection, the init() method can perform the following tasks:

The init() method executes successfully if the ODA succeeds in opening a connection and the ODA is ready to begin processing data in the data source. If the ODA cannot open a connection, the init() method should throw an ODKException exception to indicate the cause of the failure.

Checking the ODA version

The getVersion() method returns the version of the ODA runtime. This method is part of the low-level ODA base class, ODKAgentBase. It is inherited by the ODA base class, ODKAgentBase2, then inherited by your ODA class. It is called in both of the following contexts:

Note:
The getVersion() method returns the version of the ODA runtime, not the version of the ODA (which is stored as part of the ODA's meta-data).

Copyright IBM Corp. 1997, 2003