Running an ODA

At runtime, execution of an ODA involves the following components:

Figure 55 shows the components of the ODA runtime architecture.

Figure 55. Object Discovery Agent Architecture


To generate the business object definitions, the ODA must take the following steps:

  1. Obtain from the user values for the ODA configuration properties (such as user name and database type) that the ODA requires to connect to the data source (such as an application, database, or filesystem).
  2. Use these configuration properties to connect to the data source.
  3. Obtain from the user the list of source nodes for which business object definitions are to be created.
  4. Discover the requirements for the data-source entity underlying the source node (as defined by an application, database table, filesystem, or DTD).
  5. Generate business object definitions that meet the requirements of theWebSphere business integration system and the component that processes the business object, and return the business object definitions to the user.

Note:
In addition to business object definitions, an ODA can also generate files as content. For more information, see Generating content.

Table 16 summarizes the steps in the execution of an ODA and the steps in Business Object Wizard that initiate them.


Table 16.

Execution of the Object Discovery Agent
Execution task Step in Business Object Wizard For more information
1. Select the desired ODA to execute. Step 1: Select Agent Selecting the ODA
2. Obtain the ODA configuration properties, including those that describe the data source to open. Step 2: Configure Agent Obtaining ODA configuration properties
3. Obtain the source data for which to generate the ODA content. Step 3: Select Source Selecting and confirming source data
4. Confirm the source data that the user has selected. Step 4: Confirm Source Nodes Selecting and confirming source data
5. Generate the business object definitions. Step 5: Generating Business Objects Generating content


Business Object Properties Obtaining business-object properties
6. Save the business object definitions. Step 6: Save Business Objects Saving content

Selecting the ODA

When you choose the File->New Using ODA menu item, Business Object Designer invokes Business Object Wizard to run the ODA. Step 1 of Business Object Wizard displays the Select Agent dialog, which provides graphical access to all available Object Discovery Agents. From this dialog, the user selects the desired ODA to run. To display the names of all ODAs that are running on the current machine, click the Find Agents button.

Once the user has selected an ODA, Business Object Wizard connects to this ODA with the following steps:

Note:
An ODA must already be launched for Business Object Wizard to list it as an ODA you can run. For more information, see Before using an ODA.

For more information on how to create the ODA class, see Extending the ODA base class.

Obtaining ODA configuration properties

Step 2 of Business Object Wizard displays the Configure Agent dialog, which shows the ODA's configuration properties. Configuration properties are those properties that the ODA needs to be able to begin its execution. The ODK API represents a configuration property as an agent-property (AgentProperty) object. In this step, the wizard displays the configuration properties, allows the user to update them, and then writes the user-initialized properties into the ODA-runtime memory.

Figure 56. Configure Agent (Step 2) of Business Object Wizard


As Figure 56 shows, Business Object Wizard takes the following actions:

  1. Obtain the configuration properties from the selected ODA and display them in the Configure Agent dialog.

    To obtain the configuration properties from the ODA, the wizard calls the getAgentProperties() method, which is defined in the ODA base class, ODKAgentBase2. This method is an abstract method that the ODA developer must implement as part of the ODA class. It returns the ODA's configuration properties to Business Object Wizard as an array of AgentProperty objects. These configuration properties can include the names, types, any valid values, descriptions, input restrictions, and any default values.

    In addition to the configuration properties that getAgentProperties() provides, Business Object Wizard always provides a set of standard configuration properties, which are common to all ODAs:

    For more information, see Obtaining configuration properties.

  2. From the Configure Agent dialog, accept values that the user enters or changes for the configuration properties. Once the user clicks Next, the wizard sends the user-initialized configuration properties to the ODA.

    Business Object Wizard saves these properties in the ODA-runtime memory. Within the ODA, you can access these properties through an instance of the ODKUtility class, which provides the getAgentProperty() and getAllAgentProperties() methods for this purpose.

  3. Initialize the ODA's meta-data, which provides information about the ODA and its capabilities.

    After it calls getAgentProperties(), Business Object Wizard calls the getMetaData() method of the ODA base class, ODKAgentBase2. This method is an abstract method that the ODA developer must implement as part of the ODA class. It returns an initialized AgentMetaData object that contains the ODA meta-data.

  4. Initialize the ODA based on the user-initialized startup properties.

    To initialize the ODA, the wizard calls the init() method of the ODA base class, ODKAgentBase2. This method is an abstract method that the ODA developer must implement as part of the ODA class. It performs initialization tasks such as resource allocation and creating a connection to the data source.

This chapter provides the following information on how to implement the methods involved in the initialization of an ODA:

Initialization method For more information
getAgentProperties() Obtaining configuration properties
getMetaData() Initializing ODA meta-data
init() Initializing the ODA execution

Selecting and confirming source data

Step 3 of Business Object Wizard displays the Select Source dialog, which displays the source nodes of the data source. The source nodes are arranged in the source-node hierarchy, through which the user can move. Each source node is the name of an object that the ODA has "discovered" in the data source. It can either be expanded to display other child nodes or selected by the user for generation into content. The user can expand this source-node hierarchy as desired to choose objects in the data source for conversion to content. For information on how to move through the source-node hierarchy, see Moving through the source-node hierarchy.

In Step 3, the wizard takes the following actions:

  1. Obtain the source-node hierarchy from the selected ODA and display is top level in the Select Source dialog.

    To obtain the source-node hierarchy, the wizard calls the getTreeNodes() method of the IGeneratesBoDefs interface. The ODA developer must implement this method as part of the ODA class's implementation of the IGeneratesBoDefs interface. It searches the data source to "discover" source nodes and returns these source nodes to Business Object Wizard as an array of TreeNode objects. When the user expands a node for the first time, the wizard calls getTreeNodes() to display to the user that particular level in the source-node hierarchy. The user can traverse this hierarchy to select the level of detail. For more information, see Moving through the source-node hierarchy.

  2. From the Select Source dialog, keep track of the names of the source nodes in the hierarchy that the user selects for content generation. Once the user clicks the Next key, the wizard generates an array that contains the names of the user-selected source nodes.

Step 4 of Business Object Wizard displays the Confirm Source Nodes dialog, which displays the source nodes that the user has selected. The user can either confirm the selections or go back to the Select Source dialog to reselect source nodes. Once the user clicks the Next key, the wizard begins the content generation.

For information on how to implement the getTreeNodes() method, see Generating source nodes.

Generating content

You can write an ODA to generate one or both of the content types listed in Table 17. The content type determines the structure of the data that the ODA generates. For an ODA to support a particular content, it must implement the appropriate content-generation interface for the ODA. Table 17 lists the content types that an ODA can support as well as the associated content-generation interface the ODA must implement.

Table 17. Content types for an ODA

Content type Description Content-generation interface
Business object definitions The ODA generates business object definitions to represent the objects in the data source. IGeneratesBoDefs
Binary files The ODA generates file objects to hold information about the generated content. IGeneratesBinFiles

Note:
With this release, an ODA must support the generation of business object definitions as its content. Therefore, it must implement the IGeneratesBoDefs interface. Additionally, the ODA can support the generation of files as its content by implementing the IGeneratesBinFiles interface.

Once the user has selected and confirmed the desired source nodes, Business Object Wizard enters Step 5 of the content generation. It displays the Generating Business Objects screen and passes the array of user-selected source nodes (from Step 4) to the ODA by calling the content-generation method for business object definitions, generateBoDefs(). This method generates the corresponding business object definitions for the user-selected source nodes. Because an ODA must support the generation of business object definitions in the on-request content protocol, Business Object Wizard always calls the generateBoDefs() method. Therefore, the ODA developer must implement this method as part of the ODA's implementation of the IGeneratesBoDefs interface.

Whether the ODA generates file content depends on whether it implements the IGeneratesBinFiles interface. If the ODA class implements this interface, the method that actually provides the generated content depends on the content protocol that the ODA uses for the file content type, as follows:

Therefore, whether Business Object Wizard calls the content-generation method for files, generateBinFiles(), depends on the following:

Note:
For more information on content protocols, see Choosing the ODA content protocol.

Regardless of the content protocol uses, the generation of content involves the following steps:

  1. Optionally, obtain from the user any additional information, such as verb values, as business-object properties.
  2. Generate the requested content and save it in the generated-content structure in ODA memory.

The following sections summarize these steps. For a more detailed overview of the content-generation process, Table 18 shows where to find more information for each of the supported content types.

Table 18. Content-generation process

Content type For more information
Business object definitions Generating business object definitions
Binary files Generating files

Obtaining business-object properties

Often the ODA needs additional information from the user before it can generate the business object definitions. The ODA can request this additional information by defining business-object properties. The ODK API represents a business-object property as an agent-property (AgentProperty) object. To collect business-object properties, the ODA can have Business Object Wizard display the BO Properties dialog. In this dialog, the wizard displays the business-object properties, allows the user to update them, and writes the user-initialized properties into the ODA-runtime memory, as Figure 54 shows.

To display the BO Properties dialog to the user, the content-generation method of the ODA calls the getBOSpecificProps() method (defined in the ODKUtility class).

Figure 57. Obtaining business-object properties


As Figure 57 shows, the getBOSpecificProps() method takes the following steps:

  1. Send the business-object properties to Business Object Wizard, which displays them in the BO Properties dialog.

    To send the business-object properties, the getBOSpecificProps() method sends as an argument the initialized array of agent-property (AgentProperty) objects, one object for each business-object property to display.

  2. From the BO Properties dialog, the user can enter or change values for the business-object properties. Once the user clicks the Next key, the wizard sends the user-initialized business-object properties back to the getBOSpecificProps() method in the ODA.

    You can access these business-object properties within the ODA through the Java Hashtable object that getBOSpecificProps() returns. Alternatively, you can access these properties through an instance of the ODKUtility class, which provides the getBOSpecificProperty() and getAllBOSpecificProperties() methods.

The ODA can call getBOSpecificProps() repeatedly to obtain different sets of business-object properties. For more information on how to use the getBOSpecificProps() method, see Requesting business-object properties.

Providing generated content

The ODA provides its generated content to Business Object Wizard in two parts:

The method that provides the generated content depends on the content protocol that the ODA uses for a particular content type, as follows:

Note:
For more information on content protocols, see Choosing the ODA content protocol.

The following table shows where to find more information on how to provide generated content:

Content type For more information
Business object definitions Providing generated business object definitions
Binary files Providing generated files

To retrieve the generated content, Business Object Wizard calls the appropriate content-retrieval method as Table 19 shows.


Table 19. Content-retrieval methods

Content type Content-retrieval method For more information
Business object definitions IGeneratesBoDefs.getBoDefs()
Providing access to generated business object definitions
Binary files IGeneratesBinFiles.getBinFile()
Providing access to generated files

The content-retrieval method accesses the generated-content structure within the ODA object and returns specified content in an array to Business Object Wizard. Business Object Wizard must have access to the generated content before it can process the user's request to save the content in Step 6. For more information, see Saving content.

Saving content

Step 6 of Business Object Wizard displays the Save Business Objects dialog, which provides the user with options for saving the generated business object definitions. As Figure 45 shows, Business Object Wizard provides the user with the ability to save generated content to an ICL project or a file, or to open each business object definition in Business Object Designer. To save the generated business object definitions in the format that the user specifies, Business Object Wizard must access the generated content. It has retrieved this content in the previous step (Step 5), using the ODA's content-retrieval method listed in Table 19.

Copyright IBM Corp. 1997, 2003