Starting 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 30.


Table 30. Starting 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 metadata so that Business Object Wizard can obtain information about the ODA (especially its supported content). getMetaData() Initializing ODA metadata
3. Initialize the ODA to perform any necessary startup steps, such as opening a connection to the data source. init() Initializing the ODA start

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

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 box (Step 2). This dialog box displays all ODA configuration properties and allows users 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 users. When you instantiate the agent-property object, you initialize some or all of its member variables (shown in Table 51).

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

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

Figure 57. 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 57 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.

After values are specified 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 metadata

After Business Object Wizard calls the ODA's getAgentProperties() method, it calls the getMetaData() method to initialize the ODA metadata. 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 metadata, 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 31 to the ODA runtime when it needs to obtain metadata for the ODA.

Table 31. 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 metadata, you implement the getMetaData() method, which involves the following steps:

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

Figure 58. Initializing ODA metadata

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 58 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() starts 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 box (see Figure 48).

Initializing the ODA start

After Business Object Wizard calls the ODA's getMetaData() method, it calls the init() method to begin initialization of the ODAstart. 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. Users can update these properties as needed in the Configure Agent dialog box of Business Object Wizard. After configuration properties are updated, Business Object Wizard writes them to the memory of the ODA runtime.

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

Table 32. 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 32 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 59 shows the implementation of the init() method (defined in the ArmyAgent3 class from the sample Roman Army ODA).

Figure 59. 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 59, 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 one 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 runs 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 metadata).

Copyright IBM Corp. 1997, 2004