Generating business object definitions

This section describes how to use the EJB ODA in Business Object Designer to generate business object definitions. For information on launching and using Business Object Designer, see IBM WebSphere Business Integration Adapters Business Object Development Guide.

Starting the ODA

The ODA can be run from any machine that can mount the file system on which the metadata repository (the JAR files) resides, using the ODA startup file. This file contains start parameters, including the paths to certain required EJB and connector JAR files. These JAR files must also be accessible from the machine on which you are running the ODA.

The ODA for EJB has a default name of EJBODA. The name can be changed by changing the value of the AGENTNAME variable in the start script.

To start the ODA, run this command:

The CLIENT JARPATH variable of the startup file contains no default value, so before running the start command, set the value to the directory and filename of the client JAR path, so as to allow the ODA to include the file in its Java class path. For example:

set CLIENTJARPATH=C:\BIA_MusicBeanSample.jar

Running Business Object Designer

Business Object Designer provides a wizard that guides you through the steps to generate a business object definition using the ODA. The steps are as follows:

Select the agent

To select the agent, follow these steps.

  1. Start Business Object Designer.
  2. Click File > New Using ODA. The Business Object Wizard - Step 1 of 6 - Select Agent screen appears.
  3. Select the ODA/AGENTNAME in the Located agents list and click Next. (You may have to click Find Agents if the desired agent is not listed.)



    Figure 5. Select Agent screen

Configure the agent

After you click Next on the Select Agent screen, the Business Object Wizard - Step 2 of 6 - Configure Agent screen appears. Figure 6 illustrates this screen with sample values.



Figure 6. Configure Agent screen

The properties you set on this screen are described in Table 9. You can save all the values you enter on this screen to a profile. Instead of retyping the property data the next time you run the ODA, you simply select a profile from the Current profile drop-down menu and re-use the saved values. You can save multiple profiles, each with a different set of specified values.


Table 9. Configure Agent properties

Property name Default value Type Description
EJBJarFilePath None String (required) The fully qualified path to the EJB JAR file. This is the file that the ODA reads as input to generate business objects.
DefaultBOPrefix None String The prefix that the ODA will add to the names of the business objects it generates
TraceFileName <agentname>trace.txt String The name of the trace message file; for example, BIA_EJBODAtrace.txt. Note that the connector supports globalized values for this property, which means that the file path and name can be globalized, though the file content cannot.
TraceLevel 0 Integer (required) The tracing level (from 0 to 5) for the Agent. For details about tracing levels, see Tracing.
MessageFile <agentname>Agent.txt String The name of the message file that contains all the messages displayed by the ODA. For the connector for EJB, the name of this file is BIA_EJBODAAgent.txt. If you do not correctly specify the name of the message file, the ODA will run without messages. Note that the connector supports globalized values for this property, which means that the file path and name can be globalized, though the file content cannot.

  1. Type the value of the property in the Value column of the Configure Agent screen, illustrated in Figure 6.
  2. Use the New and Save buttons in the Profiles group box to create a new profile. When you use the ODA again, you can select an existing profile.
    Note:
    If you use an existing profile, the property values are filled in for you, though you can modify the values as needed.

Select an EJB object

The Business Object Wizard - Step 3 of 6 - Select Source screen appears, as illustrated in Figure 7. The screen lists the objects that have been defined in the EJB JAR file. Use this screen to select any number of EJB objects for which the ODA will generate business object definitions.

Notice that the list contains a total of eight methods. The first two objects in the list are the creator methods from the home interface. The remaining six methods are remote interface business methods.



Figure 7. Select Source screen

  1. If necessary, expand an EJB object to see a list of methods of the object.
  2. Select the EJB object(s) you want to use. For example, you can select the following:

    In Figure 7, the MusicCartHome and MusicCart class are selected. Although only the class names are selected, the ODA will also create objects of the associated methods of each selected class.

  3. Click Next.

Confirm the object selection

The Business Object Wizard - Step 4 of 6 - Confirm source nodes for business object definitions screen appears. It shows the object(s) you selected.



Figure 8. Confirm source node screen

Click Back to make changes or Next to confirm that the list is correct.

The Business Object Wizard - Step 5 of 6 - Generating business objects... screen appears with a message stating that the wizard is generating the business objects.

Select verbs and assign the JNDI name

After you click Next, the Enter JNDI name for this Enterprise Java Bean screen appears. It appears for each selected EJB source object. Use this screen to select the supported verbs for this object and to assign a JNDI name.

In the example provided in Figure 9, the JNDI name assigned is MusicCartJNDI.



Figure 9. Enter JNDI Name for Enterprise Java Bean screen

On this screen you also specify the verbs that the business object supports. The ODA allows you to specify the four supported verbs (Create, Retrieve, Delete, and Update) and assign as actions of each verb n methods, where n equals the number of methods in the corresponding EJB object. To specify additional verbs beyond the supported four, or to edit verb information after you create a business object, use Business Object Designer.

For details about business object verbs for the EJB connector, see Verb ASI.

  1. In the Value list for the Verbs property, select the verbs that you want the business object to support. You can select one or more verbs. You can also deselect a verb at any time.

  2. In the JNDI name for <className> property, enter the JNDI name of the enterprise bean. This name is defined at the time when the bean is deployed onto the application server.
  3. Click OK.

Specify the verb ASI

For each verb you select, a separate window appears where you specify the method sequence that must be executed for the verb.

Figure 10 illustrates this screen for the Create verb of the MusicCart business object created in Figure 7 and Figure 8.



Figure 10. Setting the verb method sequence

  1. In the Value list for the MethodSequence property, click the method that you want the business object to execute first for the verb. In Figure 10, the method sequence is as follows:

    By specifying a method sequence for the verb, you are creating the verb ASI that is associated with that verb. If necessary, this verb ASI can be modified later using Business Object Designer.

  2. Click OK.

Opening or saving the business object

The Business Object Wizard - Step 6 of 6 - Save business objects screen appears.



Figure 11. Save business objects screen

You can optionally open the new business objects in separate windows within Business Object Designer, or (after specifying a key for the top-level business object) you can save the generated business object definitions to a file.

To open the business objects in separate windows

  1. Select Open the new BOs in separate windows.
  2. Click Finish. Each business object appears in a separate window where you can view and set the ASI information for the business objects and business object verbs you just created. For details, see Select verbs and assign the JNDI name and Specify the verb ASI.

To save the business objects to a file (only after you specify a key for the parent-level business object):

  1. Select Save a copy of the business objects to a separate file. A dialog box appears.
  2. Type the location in which you want the copy of the new business object definitions to be saved.

Business Object Designer saves the files to the specified location.

If you have finished working with the ODA, you can shut it down by checking "Shutdown ODA EJBODA" before clicking Finish.

Specifying the attribute-level ASI

After you define the verb ASI (by specifying a method sequence that must be executed for each verb), Business Object Designer displays the attributes for the business object. For details about the attribute-level ASI in the EJB connector, see Attribute-level ASI.

The attributes are listed on the Attributes tab in the order in which they appear in the EJB object structure, as defined by the numeric value in the Pos column. Simple EJB object attributes are represented as simple attributes and their ASI contains the original EJB attribute name and type.

For each attribute, the screen provides the name of the attribute, its type, and the ASI information. Figure 12 illustrates the method (complex) attributes. The getAllRecordsInfo attribute of the business object has an ASI that maps the attribute to the original EJB object method. In this example, the original method is indicated under the App Spec Info column, by the method_name=getAllRecordInfo ASI.

The getCustomer attribute of the business object has an ASI that maps the attribute to the original EJB object method. In this example, the original method is indicated under the App Spec Info column, by the method_name=getCustomer ASI.

In addition, getCustomer (a child business object) has the child object attribute Return_Value, which is used to capture the return value of the getCustomer method. In the EJB JAR file, the method is defined as having a return value of type CustomerHelper, which itself is a method. The attribute ASI of CustomerHelper is set to type=proxy because the object type is a return value. Note that if a method in the EJB JAR file does not return a value, the Return_Value attribute is not included in the list of business object attributes.

Notice also that the Return_Value attribute of type CustomerHelper has three non-method child object attributes: name, password, and email. In the original EJB JAR file where the MusicCartBean class is defined, these are all defined as parameters of type String of the CustomerHelper method. In the business object, the attribute ASI of these parameters indicates the Java property name and type (String) of each in the original JAR file.



Figure 12. Setting the attribute ASI

On this screen, you should specify whether or not a parent-level object is a key (which is required by the ODA for saving the business objects to a separate file). You can also use this screen to set child object keys as needed and to specify the following information:

Note:
While you can create a business object through the ODA (running in Business Object Designer) and set the parent level key(s), do not configure the foreign key in this manner. The foreign key is non-ASI metadata and therefore must always be configured without the ODA (in Business Object Designer, click File > New to create a new business object without using the ODA).

Specifying the business object-level ASI

You can view and modify the business object-level ASI. For details about business object-level ASI, see Business object-level ASI.

The business object-level ASI is listed on the General tab. The ASI value that appears in the field Business Object Level Application-specific information contains the name of the remote interface that corresponds to this business object. The connector uses this information to map a remote object to a business object.

The General tab also lists all the verbs that are supported by the business object and provides the ASI for each verb, as it was defined in Specify the verb ASI. If a verb is blank, then a method sequence will not be executed for that verb.

Copyright IBM Corp. 1997, 2004