Tools for developing and deploying enterprise beans in the EJB server (CB) environment

The following are the basic approaches to developing and deploying enterprise beans in the EJB server (CB) environment:

Before beginning development of enterprise beans in the EJB server (CB) environment, review the list of development restrictions contained in Restrictions in the EJB server (CB) environment.

Note:
Deployment and use of enterprise beans for the EJB server (CB) environment must take place on the Microsoft Windows NT or Windows 2000 operating system, the IBM AIX operating systems, or the Sun Solaris operating system.

For information on developing and deploying enterprise beans in the EJB server (AE) environment, see Tools for developing and deploying enterprise beans in the EJB server (AE) environment.


Developing and deploying enterprise beans with EJB server (CB) tools

You need the following tools to develop and deploy enterprise beans for the EJB server (CB):

This section describes the steps you must follow to develop and deploy enterprise beans by using the EJB server (CB) tools. The following tasks are involved:

  1. Ensure that you have the prerequisite software to develop and deploy enterprise beans in the EJB server (CB). For more information, see Prerequisite software for the EJB server (CB).

  2. Set the CLASSPATH environment variable required by different components of the EJB server (CB) environment. For more information, see Setting the CLASSPATH environment variable in the EJB server (CB) environment.

  3. Write and compile the components of the enterprise bean. For more information, see Creating the components of an enterprise bean.

  4. Create a finder helper class for each entity bean with CMP that contains specialized finder methods (other than the findByPrimaryKey method). For more information, see Creating finder logic in the EJB server (CB).

  5. Use the jetace tool to create an EJB JAR file to contain the enterprise bean. For more information, see Creating an EJB JAR file for an enterprise bean.

  6. Deploy the enterprise bean by doing one of the following:

Prerequisite software for the EJB server (CB)
Note:
Any items marked PAO only are needed only if you intend to use the PAOToEJB tool and need the CICS- or IMS-related support.
You must configure the tools provided with the EJB server (CB) environment; however, before you can configure the tools, you must ensure that you have installed and configured the following prerequisite software products contained in the Enterprise Application Server:

Setting the CLASSPATH environment variable in the EJB server (CB) environment
To do any of the tasks listed below, make sure that the classes.zip file contained in the Java Development Kit is included in the CLASSPATH environment variable. In addition, make sure that the following files are identified by the CLASSPATH environment variable to perform the associated task:

Creating the components of an enterprise bean

If you use an ASCII text editor or a Java development tool that does not support enterprise bean development, you must create each of the components that compose the enterprise bean you are creating. You must ensure that these components match the requirements of the EJB specification. These components are described in Developing enterprise beans.

To manually develop a session bean, you must write the bean class, the bean's home interface, and the bean's remote interface. To manually develop an entity bean, you must write the bean class, the bean's primary key class, the bean's home interface, and the bean's remote interface. After you have properly coded these components, use the Java compiler to create the corresponding Java class files. For example, since the components of the example Account bean are stored in a specific directory, you can compile the bean components by issuing the following command:

C:\MYBEANS\COM\IBM\EJS\DOC\ACCOUNT> javac *.java

This command assumes that the CLASSPATH environment variable contains all of the packages used by the Account bean.

Creating finder logic in the EJB server (CB)
In the EJB server (CB), finder logic is contained in a finder helper class. The enterprise bean deployer must implement the finder helper class before deploying the enterprise bean and then specify the name of the class with the -finderhelper option of the cbejb tool.

For each specialized finder method in the home interface (other than the findByPrimaryKey method), the finder helper class must have a corresponding method with the same name and parameter types. When an EJB client invokes a specialized finder method, the generated CB home that implements the enterprise bean's home interface invokes the corresponding finder helper method to determine what to return to the EJB client.

The finder helper class must also have a constructor that takes a single argument of type com.ibm.IManagedClient.IHome. When the CB home instantiates the finder helper class, the CB home passes a reference to itself to the finder helper constructor. This allows the finder helper to invoke methods on the CB home within the implementation of the finder helper methods, which is particularly useful when the CB home is an IQueryableIterableHome because the finder helper can narrow the IHome object passed to the constructor and invoke query service methods on the CB home.

The names of the entity bean's container-managed fields are mapped to interface definition language (IDL) attributes of the same name, except that an underscore (_) is appended, in the business object (BO) interface, the CB key class, and the CB copy helper class. These names are mapped exactly to IDL attributes in the DO interface. For example, in the AccountBean class, the accountId variable is mapped to accountId_ in the BO interface, the CB key class, and the CB copy helper class, but is mapped to accountId in the DO interface.

This renaming is necessary, and relevant to finder helper classes implemented by using the Component Broker Query Service, because the entity bean's remote interface can also have a property named accountId (of potentially a different type) that must also be exposed through the BO interface. If that is the case, then a query over the BO attribute accountId is done in object space, whereas a query over the BO attribute accountId_ is done directly against the underlying data source, which is typically more efficient.

If a home interface's specialized finder method returns a single entity bean, then the corresponding method in the finder helper class must return the java.lang.Object type. When invoked, the finder helper method can return the EJB object, the CB key object, the entity bean's primary key object, or a CB managed object framework (MOFW) object. If the finder helper method returns a CB object or a primary key object, the CB home determines the corresponding EJB object to return to the EJB client.

If a home interface's specialized finder method returns a java.util.Enumeration type, the corresponding finder helper method must also return java.util.Enumeration. When invoked, the finder helper method can return an Enumeration of EJB objects, CB key objects, CB MOFW objects, enterprise bean primary key objects, or a heterogeneous mix of one or more of the four. The CB home then constructs a serializable Enumeration object containing the corresponding EJB objects, which is returned to the EJB client.

If a home interface's specialized finder method returns a java.util.Collection type, the corresponding finder helper method must also return java.util.Collection. When invoked, the finder helper method can return a Collection of EJB objects, CB key objects, CB MOFW objects, enterprise bean primary key objects, or a heterogeneous mix of one or more of the four. The CB home then constructs a serializable Collection object containing the corresponding EJB objects, which is returned to the EJB client.

An optional base class, named com.ibm.ejb.cb.runtime.FinderHelperBase, is provided with the EJB server (CB) environment to assist in the development of a finder helper class. This class encapsulates the Component Broker Query Service, so that the deployer does not need to write any CB-specific code. The FinderHelperBase base class contains the methods listed in Table 1. These methods generally take an Object-Oriented Structured Query Language (OOSQL) predicate as a parameter and return an object or an Enumeration or Collection of objects that meet the conditions of the query.

Table 1. FinderHelperBase class methods

Method Parameter Return type Notes
evaluate OOSQL where clause Enumeration Desired objects instantiated immediately
extendedEvaluate Full OOSQL statement Enumeration Desired objects instantiated immediately
lazyEvaluate OOSQL where clause Enumeration Desired objects instantiated as needed
extendedLazyEvaluate Full OOSQL statement Enumeration Desired objects instantiated as needed
singleEvaluate OOSQL where clause Object Throws ObjectNotFoundException if not found
extendedSingleEvaluate Full OOSQL statement Object Throws ObjectNotFoundException if not found
evaluateCollection OOSQL where clause Collection Desired objects instantiated immediately
extendedEvaluateCollection Full OOSQL statement Collection Desired objects instantiated immediately
lazyEvaluateCollection OOSQL where clause Collection Desired objects instantiated as needed
extendedLazyEvaluateCollection Full OOSQL statement Collection Desired objects instantiated as needed

All of these methods throw a javax.ejb.FinderException if any errors occur. The finder helper class does not need to catch this exception; instead, the class can pass it on to the EJB client. A utility class, named com.ibm.ejb.cb.emit.cb.FinderHelperGenerator (contained in the developEJB.jar file), is also provided to further assist the deployer in the development of a finder helper class. This utility takes the name of an entity bean's home interface and generates a Java source file containing a class that extends com.ibm.ejb.cb.runtime.FinderHelperBase and that contains skeleton methods for each specialized finder method in the home interface. In addition, each finder helper method contains a call to invoke the appropriate FinderHelperBase method listed in Table 1.

By using ejbfhgen, the FinderHelperGenerator utility, the deployer can easily implement the finder helper class. You can use a batch file to run the utility. For example, to generate a finder helper class for the example AccountHome interface, enter the following command:

# ejbfhgen com.ibm.ejs.doc.account.AccountHome

This command generates the finder helper class shown in Figure 8.

Figure 8. Code example: Generated AccountFinderHelper class for the EJB server (CB)


...
public class AccountFinderHelper extends FinderHelperBase {
     ...
     AccountFinderHelper(IManagedClient.IHome iHome) {
          ...
     }
     public Enumeration findLargeAccounts(float amount) {
          return evaluate("replace with appropriate code");
     }
 }

To enable the helper class for use in a deployed enterprise bean, the deployer makes a few simple edits to the parameters of the evaluate invocations. For example, for the AccountFinderHelper class, the "replace with appropriate code" String is replaced with "balance_>" + amount as shown in Figure 9. The generated finder helper class can be used only with an enterprise bean that is deployed to have a queryable home by using the -queryable option of the cbejb tool.

Figure 9. Code example: Completed AccountFinderHelper class for the EJB server (CB)


...
public class AccountFinderHelper extends FinderHelperBase {
     ...
     AccountFinderHelper(IManagedClient.IHome iHome) {
          ...
     }
     public Enumeration findLargeAccounts(float amount) {
          return evaluate("balance_>" + amount);
     }
 }

Using VisualAge for Java-style finder-helper interfaces

The VisualAge for Java finder-helper interfaces (described in Creating finder logic in the EJB server (AE)) support suffixes that map to the FinderHelperBase methods as shown in Table 2.

Table 2. FinderHelperBase method suffixes

Suffix Return type Method
CBWhereClause Enumeration evaluate
CBQueryString Enumeration extendedEvaluate
CBWhereClause Collection evaluateCollection
CBQueryString Collection extendedEvaluateCollection
CBWhereClause Object singleEvaluate
CBQueryString Object extendedSingleEvaluate
CBLazyWhereClause Enumeration lazyEvaluate
CBLazyQueryString Enumeration extendedLazyEvaluate
CBLazyWhereClause Collection lazyEvaluateCollection
CBLazyQueryString Collection extendedLazyEvaluateCollection

VisualAge for Java will automatically create a CB finder-helper class when you export an EJB JAR file to CB with the CBWhereClause, CBQueryString,CBLazyWhereClause, or CBLazyQueryString specified in the finder-helper interface.

Alternatively, you can manually create a CB finder-helper class by passing the VisualAge for Java-style finder-helper interface as the second parameter to the ejbfhgen utility. For example, you could issue the following command:

ejbfhgen com.ibm.ejs.doc.account.AccountHome 
     com.ibm.ejs.doc.account.AccountBeanFinderHelper

When this command is invoked with a VisualAge for Java-style finder-helper interface as input, it fills in the OOSQL statements instead of emitting the "replace with appropriate code" string and compiles the code. There is no need to manually edit the code when passing a VisualAge for Java-style finder-helper interface that contains all of the OOSQL strings. The deployer needs to add the compiled CB finder-helper class to an EJB JAR file; alternatively, it can be packaged in a separate JAR file by using the cbejb tool with the -serverdep parameter.

Using lazy enumeration
The Enumeration returned by the evaluate method is called eager, because all the enterprise bean references that match the query are brought into memory and stored in the enumeration before being passed from the server to the client. If the number of references returned by the query is large, the deployer can use lazy enumeration; that is, it incrementally fetches more enterprise bean references only when the client calls the nextElement method on the Enumeration.

To use lazy enumeration, change the call to the evaluate method in the FinderHelper to a call to the lazyEvaluate method. A transaction must already be started before the home's finder method is called. The caller must not call the nextElement method on the Enumeration after the completion of the transaction.

At configuration time, the System Management End User Interface must be used to enable the settings for lazy Enumerations. Refer to Configuring systems management to enable lazy enumeration

Creating an EJB JAR file for an enterprise bean
Once the bean components are built, the next step is package them into an EJB JAR file. The WebSphere Application Server jetace tool can be used to create an EJB JAR file for one or more enterprise beans and generate a deployment descriptor file for each enterprise bean. The resulting EJB JAR file contains each enterprise bean's class files and deployment descriptor and an EJB-compliant manifest file.
Note:
The jetace tool can only be used to create JAR files that are compatible with version 1.0 of the EJB specification. If you need to create JAR files compatible with version 1.1, use the Application Assembly tool. See Using the Application Assembly Tool.
Before you create an EJB JAR file for one or more enterprise beans, you must do one of the following:

Running the jetace tool

To run the jetace tool, type jetace on the command line. The window shown in Figure 10 is displayed.

Figure 10. The initial window of jetace tool



The initial window of jetace tool

To generate an EJB JAR file with the jetace tool, do the following:

  1. Click the File->Load item, and select the JAR or ZIP file or the directory containing one or more enterprise beans. Use the Browse button to obtain the file or directory.
    Note:
    To specify the current directory as the input source, type an = (equals character) in the File Name field of the browser window and click Open.

    If you are creating a new EJB JAR file, click New and a default name for the deployment descriptor (for example, UNAMED_BEAN_1.ser) appears in the Current Enterprise Beans list box. (You can edit this name on any of the remaining tabbed pages of the jetace GUI by editing the Deployed Name field at the top of each tabbed page. This field is described in Specifying the enterprise bean components and JNDI home name.)

    If you are editing an existing EJB JAR file, the name of the deployment descriptor for each enterprise bean in the EJB JAR file is displayed in the Current Enterprise Beans list box, as shown in Figure 10.

  2. To create a new deployment descriptor or edit an existing one, highlight the deployment descriptor and press the Edit button. This action causes the Basic page to display. On this page, set or confirm the names of the deployment descriptor file, the enterprise bean class, the home interface, and the remote interface and specify the JNDI name of the enterprise bean. For information, see Specifying the enterprise bean components and JNDI home name.

  3. Set the entity bean or session bean attributes for the enterprise bean's deployment descriptor on the Entity or Session page, respectively. For information on setting deployment descriptor attributes for entity beans, see Setting the entity bean-specific attributes. For information on setting deployment descriptor attributes for session beans, see Setting the session bean-specific attributes.

  4. Set the transaction attributes for the enterprise bean's deployment descriptor on the Transactions page. For information, see Setting transaction attributes.

  5. Set the security attributes for the enterprise bean's deployment descriptor on the Security page. For information, see Setting security attributes.

  6. Set any environment variables to be associated with the enterprise bean on the Environment page. For information, see Setting environment variables for an enterprise bean.

  7. Set any class dependencies to be associated with the enterprise bean on the Dependencies page. For information, see Setting class dependencies for an enterprise bean.

  8. After you have set the appropriate deployment descriptor attributes for each enterprise bean, click File->Save As to create an EJB JAR file. (If desired, a ZIP file can be created instead of a JAR file.)
The jetace tool can also be used to read and generate an XML version of an enterprise bean's deployment descriptor. To read an XML file, click the File->Read XML item. To generate an XML file from an existing enterprise bean (after saving the output EJB JAR file) click the File->Write XML item.

The jetace tool can also be run from the command line to create an EJB JAR file. The syntax of this command follows, where xmlFile is the name of an XML file containing the enterprise bean's deployment descriptor:

% jetace -f xmlFile

For more information on the syntax of the XML file required for this command, see Appendix C, Using XML in enterprise beans (CB Only).

Specifying the enterprise bean components and JNDI home name
The Basic page is used to set the full pathname of the deployment descriptor file and the Java package name of the enterprise bean class, home interface, and remote interface and to set the enterprise bean's JNDI home name. To access this page, which is shown in Figure 11, click the Basic tab.

Figure 11. The Basic page of the jetace tool



The Basic page of the jetace tool

In the Basic page, you must select or confirm values for the following fields:

Setting the entity bean-specific attributes
To set the deployment descriptor attributes associated specifically with an entity bean, click the Entity tab in the jetace tool to display the Entity page shown in Figure 12. This tab is disabled if the highlighted enterprise bean in the initial jetace window is a session bean.

Figure 12. The Entity page of the jetace tool



The Entity page of the jetace tool

In the Entity page, you must select or confirm values for the following fields:

Setting the session bean-specific attributes
To set the deployment descriptor attributes associated specifically with a session bean, click the Session tab in the jetace tool to display the Session page shown in Figure 13. This tab is disabled if the highlighted enterprise bean in the initial jetace window is an entity bean.

Figure 13. The Session page of the jetace tool



The Session page of the jetace tool

On the Session page, you must select or confirm values for the following fields:

Setting transaction attributes
The Transactions page is used to set the transaction and transaction isolation level attributes for all of the methods in an enterprise bean and for individual methods in an enterprise bean. If an attribute is set for an individual method, that attribute overrides the default attribute value set for the enterprise bean as a whole.
Note:
In the EJB server (CB), the transactional attribute can be set only for the bean as a whole; the transaction attribute cannot be set on individual methods in a bean.

To access the Transaction page, click the Transactions tab in the jetace tool. Figure 14 shows an example of this page.

Figure 14. The Transactions page of the jetace tool



The Transactions page of the jetace tool

On the Transactions page, you must select or confirm values for the following fields in the Defaults group box:

If necessary, you can also set these attributes on individual methods by highlighting the appropriate method and setting one or both of the attributes in the Specified Methods group box.

Setting security attributes
The Security page is used to set the security attributes for all of the methods in an enterprise bean and for individual methods in an enterprise bean. If an attribute is set for an individual method, that attribute overrides the default attribute value set for the enterprise bean as a whole.

To access the Security page, click the Security tab in the jetace tool. Figure 15 shows an example of this page.

Figure 15. The Security page of the jetace tool



The Security page of the jetace tool

On the Security page, you must select or confirm values for the Run-As Mode field in the Defaults group box. This field must be set to one of the values described in Setting the security attribute in the deployment descriptor. The run-as identity attribute is not used by the EJB server (CB environment), so you cannot set the value for the corresponding field in the jetace tool.

If necessary, you can also set the run-as mode attribute on individual methods by highlighting the appropriate method and setting the attribute in the Specified Methods group box.

Setting environment variables for an enterprise bean
The Environment page is used to associate environment variables (and their corresponding values) with an enterprise bean. To access the Environment page, click the Environment tab in the jetace tool. Figure 16 shows an example of this page.

Figure 16. The Environment page of the jetace tool



The Environment page of the jetace tool

To set an environment variable to its value, specify the environment variable name in the Name field and specify the environment variables value in the Value field. If desired, use the Comment field to further identify the environment variable. Press the Set button to set the value. To delete an environment variable, highlight the variable in the Environment Settings window and press the Delete button.

For the example Transfer bean, the following environment variables are required:

For more information on how these environment variables are used by the Transfer bean, see Implementing the ejbCreate methods.

Setting class dependencies for an enterprise bean
The Dependencies page is used to specify classes on which the enterprise bean depends. To access the Dependencies page, click the Dependencies tab in the jetace tool. Figure 17 shows an example of this page.

Figure 17. The Dependencies page of the jetace tool



The Dependencies page of the jetace tool

Generally, the jetace tool discovers class dependencies automatically and sets them here. If there are other class dependencies required by an enterprise bean, you must set them here by entering the fully-qualified Java class name in the Classname field. If desired, use the Comment field to further identify the dependency. Press the Add button to set the value. To remove a dependency, highlight it in the Class Dependencies window and press the Delete button.

For the example Account bean, the jetace tool set the dependencies shown in Figure 17.

Deploying an enterprise bean with the CBDeployJar tool

The CBDeployJar tool automates the tasks associated with deploying an enterprise bean. It can be used to do the following:

The CBDeployJar tool can be run on JAR files that are compatible with both version 1.0 and version 1.1 of the EJB specification. It can be used to deploy the following types of enterprise beans:

It cannot be used to deploy entity beans with CMP that use meet-in-the-middle mapping and were not created using VisualAge for Java. These enterprise beans must be manually deployed as described in Manually deploying an enterprise bean.

When it deploys an enterprise bean from a JAR file, the CBDeployJar tool performs the following tasks:

  1. If the JAR file is compatible with version 1.1 of the EJB specification, it parses the XML of the version 1.1 deployment descriptor and generates a new JAR file with version 1.0-style serialized deployment descriptors. (This is necessary because other Component Broker EJB tools only work with version 1.0 JAR files.) It also registers all EJB 1.1 deployment descriptor environment variables in the JNDI namespace under java:comp/env/environVarName, where environVarName is the name of the environment variable.

  2. It runs the cbejb tool on the JAR file, using any options specified by the user.

  3. It runs the make command for the platform, using any options specified by the user.

  4. It maps the persistent fields in entity beans with CMP to database tables.

  5. It configures and starts a Component Broker EJB server by running a series of wscmd commands that load the application family into Component Broker systems management; create a new management zone, configuration, and EJB server; configure the deployed enterprise beans onto the EJB server; and start the EJB server.

  6. For enterprise beans written to version 1.1 of the EJB specification, it registers references to these beans in the appropriate place in the JNDI namespace under java:comp/env/ejb. (This is necessary to prevent naming collisions between enterprise beans.)

The syntax of the CBDeployJar command is as follows:

CBDeployJar ejb-jarFile hostname [-cbejb options] [-make options] [-noTables] 
     [-prepJarOnly] [-cbejbOnly] [-makeOnly]
CBDeployJar ejb-jarFile hostname  -isDeployed
CBDeployJar ejb-jarFile  hostname  -undeploy

where:

Note:
Use double quotes ("") for options passed to the -cbejb and -make flags that contain spaces.

The following are examples of using the CBDeployJar command:

CBDeployJar EJBsavingsAccount.jar test.netbank.ibm.com
CBDeployJar EJBcalculator.jar trident.ibm.com -make IVB_COMBINE_SOURCE=0
CBDeployJar EJBportfolio.jar bringup.ibm.com -cbejb "-dbname Investors"
CBDeployJar EJBhello.jar tasmania.ibm.com -noTables
CBDeployJar EJBtest.jar trip.ibm.com -isDeployed
CBDeployJar EJBtest.jar trip.ibm.com -undeploy

Deploying an enterprise bean with the CBDeployEar tool

The CBDeployEar tool automatically deploys enterprise beans from JAR files encapsulated in J2EE EAR files. This tool extracts a JAR file from the specified EAR file, then runs the CBDeployJar tool on the extracted file to deploy the enterprise bean.

The syntax of the CBDeployEar command is as follows:

CBDeployEar earFile hostname [-cbejb options] [-make options] [-noTables] 
[-prepJarOnly] [-cbejbOnly] [-makeOnly] [-bindEJBRefs]
CBDeployEar earFile hostname  -isDeployed
CBDeployEar earFile  hostname  -undeploy

where:

The following are examples of using the CBDeployEar command:

CBDeployEar EJB11Big3.ear greenland.ibm.com
CBDeployEar EJB11Big3.ear greenland.ibm.com -bindEJBRefs
CBDeployEar EJB11Big3.ear greenland.ibm.com -isDeployed
CBDeployEar EJB11Big3.ear greenland.ibm.com -undeploy

Manually deploying an enterprise bean

You can manually deploy JAR files that contain any type of enterprise bean, regardless of which tool was used to create the files. The following steps summarize the tasks that you must complete to manually deploy enterprise beans onto a Component Broker EJB server:

  1. Use the cbejb command to deploy the enterprise bean.

  2. Build a data object (DO) implementation for use by the enterprise bean by using Object Builder (This step is part of the deployment process).

  3. Install the deployed enterprise bean and configure its EJB server (CB).

  4. Start the EJB server (CB) as described in the Component Broker System Administration Guide.

  5. Bind the JNDI name of the enterprise bean into the JNDI namespace by using the ejbbind tool. (This step is not necessary on the AIX, Windows NT, Windows 2000 or Solaris platforms.)

This section describes how to perform steps 1, 2, 3 and 5.

Using the cbejb tool to deploy enterprise beans

During deployment, a deployed JAR file is generated from an EJB JAR file. Use the cbejb tool to deploy enterprise beans in the EJB server (CB) environment. The deployed JAR file contains classes required by the EJB server. The cbejb tool also generates the data definition language (DDL) file used during installation of the enterprise bean into the EJB server (CB).

If you want to use an enterprise bean on a different machine from the one on which it was developed (and on which you ran cbejb), follow the guidelines for installing applications in the Component Broker document entitled System Administration Guide. If an enterprise bean uses additional files (such as other JAR files) that need to be copied with the enterprise bean, specify these files in the properties notebook of the application (not the family).

Note:
The cbejb tool can only be used to deploy JAR files that are compatible with version 1.0 of the EJB specification. To manually deploy a version 1.1-compatible JAR file, you must first run the CBDeployJar tool with the -prepJarOnly option to convert the JAR file to the version 1.0 format. See Deploying an enterprise bean with the CBDeployJar tool for more information.

The cbejb tool has the following syntax:

cbejb ejb-jarFile [-rsp responseFile][-ob projDir] [-nm] [-ng] [-nc] [-cc] 
[-bean beanNames] [-platform [NT | AIX | OS390 | Solaris | HP]]
[-guisg] [-usecurdopo] [-nousraction] [-dllname DLLName beanName]
[-polymorphichome [beanNames]]  [-queryable [beanNames]]
[-dbname DBName [beanName]]
[-cacheddb2v52 | -cacheddb2v61 | -db2v61 |-oracle | -informix |
-jdbcaa [beanNames]]
[-hod | -eci | -appc | -exci | -otma | -ccf [beanNames]] 
[-family familyName [beanNames]] 
[-finderhelper finderHelperClassName [beanNames]] 
[-usewstringindo [beanNames]]  [-workloadmanaged [beanNames]]
[-clientdep deployed-jarFile [beanNames]] 
[-serverdep deployed-jarFile [beanNames]]
[-sentinel [JavaPrimitiveObjectType=]sentinelValue [beanNames[+CMFieldNames]]
[-strbehavior [strip | corba] [beanNames[+CMFieldNames]]

The ejb-jarFile parameter is required; it must be the first argument and it must specify a valid EJB JAR file. If the -ob option is used, it must come second on the command line. The other options can be specified in any order. The beanNames argument is a list of one or more fully qualified enterprise bean names delimited by colons (:) (for example, com.ibm.ejs.doc.transfer.Transfer:com.ibm.ejs.doc.account.Account). For the enterprise bean name, specify either the bean's remote interface name or the name of its deployment descriptor. If the beanNames argument is not specified for a particular option, then the effect of that option is applied to all enterprise beans in the EJB JAR file for which the option is valid.

Note:
The relative file name of the JAR files specified by the ejb-jarFile variable and by the two deployed-jarFile variables must be different from each other. JAR file names that have the same relative file names but different paths are not valid.

The rest of the command parameters are optional and can be specified in any order. For explanation purposes, the options can be grouped by function into three general categories:

The -rsp option does not fit into these categories. This option allows you to create a file containing some or all of the other options and their values (except the ejb-jarFile parameter). You can then submit the file to the cbejb command. This allows the common setting to be saved and makes commands easier to issue.

For session beans or entity beans with BMP, the code generation process runs without additional user intervention. For entity beans with CMP, the Object Builder GUI is displayed during execution of the command, and you must create a DO implementation to manage the entity bean's persistent data. For more information, see Building a data object during CMP entity bean deployment.

The cbejb tool deploys enterprise beans by generating extensible markup language (XML) files and importing those files into Object Builder. If the XML import fails, you can view any error messages generated by Object Builder in the import_model.log file located in the project directory.

If your CLASSPATH environment variable is too long, the cbejb command file fails. If this happens, shorten your CLASSPATH by removing any unnecessary files. The cbejb tool generates the following files for an EJB JAR file containing an enterprise bean named Account:

Building a data object during CMP entity bean deployment

When deploying an entity bean with CMP in the EJB server (CB), you must create a DO implementation by using Component Broker's Object Builder. This DO implementation manages the entity bean's persistent data. To build a DO implementation, you must map the entity bean's container-managed fields to the appropriate data source as described in Guidelines for mapping the container-managed fields to a data source. Then, you must do one of the following:

Guidelines for mapping the container-managed fields to a data source When you deploy enterprise beans with the cbejb tool, a Component Broker DO IDL interface is created. The IDL attributes of this interface correspond to the entity bean's container-managed fields. You must then define the DO implementation by using Object Builder to map the DO attributes to the attributes of a Persistent Object (PO) or Procedural Adapter Object (PAO), which correspond to the data types found in the data source.

This section contains information on how the cbejb tool maps the container-managed fields of entity beans to DO IDL attributes, and how the enterprise bean deployer maps DO IDL attributes to the entity bean's data source. These guidelines apply whether you are using an existing data source (also known as meet-in-the-middle deployment) or defining a new one (also known as top-down deployment).

Using an existing DB2 or Oracle data source to store persistent data To use an existing DB2 or Oracle database to store a CMP entity bean's persistent data, follow these steps. The end result is a PO with attributes that correspond to the items in the database schema.

  1. When Object Builder starts, it presents the Open Project dialog. Choose the location of the project directory for your enterprise bean and click Finish.

  2. To import an existing relational database schema, click DBA-Defined Schemas and right-click the appropriate database type.

    1. On the pop-up menu, click Import and SQL.

    2. On the Import SQL dialog box, click Find and browse for your SQL file.

    3. Double-click your SQL file.

    4. Change the name in the Database Name text field from Database to the actual name of the database.

    5. Select the appropriate database type and click Finish.

  3. To create a persistent object (PO) from the database schema, expand DBA-Defined Schemas and expand your group.

    1. Highlight your schema and then right-click it to display a pop-up menu. Click Add->Persistent Object.

    2. On the Names and Attributes dialog box, accept the defaults and click Finish.

  4. Create a DO implementation as follows:

    1. Expand the User-Defined DOs, expand the DO File (for example CBAccountDO), expand the DO Interface (for example, com_ibm_ejs_doc_account_AccountDO), and select the DO Implementation.

    2. On the DO Implementation pop-up menu, select Properties.

    3. On the Name and Platform page, select the Deployment Platform (for example, NT, AIX, or Solaris) and click Next.

    4. On the Behavior page, make the appropriate selections and click Next:

      • For DB2, select BOIM with any Key for Environment, select Embedded SQL for Form of Persistent Behavior and Implementation, select Delegating for Data Access Pattern, and select Home name and key for Handle for Storing Pointers.

      • For Oracle, select BOIM with any Key for Environment, select Oracle Caching services for Form of Persistent Behavior and Implementation, select Delegating for Data Access Pattern, and select Home name and key for Handle for Storing Pointers.

    5. On the Implementation Inheritance page, make the appropriate selections for the parent class and click Next:

      • For DB2, select IRDBIMExtLocalToServer::IDataObject

      • For Oracle, select IRDBIMExtLocalToServer::ICachingServiceDataObject

    6. Accept the defaults for the Attributes, Methods, and Key and Copy Helper pages by clicking Next on each page.

    7. On the Associated Persistent Objects page, click Add Another. Accept the default for the instance name (iPO) and select the correct type. Click Next.

    8. On the Attribute Mapping page, map the container-managed fields of the entity bean to the corresponding items in the database schema. Object Builder creates default mappings for the data object attributes for which it can identify corresponding persistent object attributes. The default mapping is generally suitable for everything except for the primary key variable, which you must map to a varchar or char type rather than a long varchar type. For more information, see Guidelines for mapping the container-managed fields to a data source. After you finish mapping the attributes, click Finish.

    9. Oracle only. When mapping an entity bean with CMP to an Oracle database, expand the Container Definition folder and right-click the EJB container. From the pop-up menu, click Properties. In the wizard, click Next until you reach the Data Access Patterns; on that page, check the Cache Service checkbox and click Finish.

    10. Exit from Object Builder by clicking File->Exit; save any changes if prompted.

    11. Create the database specified by the Database text field and use the SQL file specified by the Schema File text field to create a database table. For more information on creating a database and database table with an SQL file, consult your DB2 or Oracle documentation. The SQL file can be found in the following directory, where projDir is the project directory created by the cbejb tool:

      • On Windows NT and Windows 2000, projDir\Working\NT

      • On AIX, projDir/Working/AIX

      • On Solaris, projDir/Working/Solaris

Using an existing CICS or IMS application to store persistent data To use CICS or IMS for Persistent Adaptor Object (PAO) storage, following these instructions. Note that if the persistent store uses a CICS or IMS application (by way of a PAO), only application data is used; the methods on the CICS or IMS application are pushdown methods, which run application-specific logic rather than storing and loading data.

The following prerequisites must be met to map an entity bean with CMP to an existing CICS or IMS application:

If you have met the prerequisites, use Object Builder to create the mapping between the entity bean and the CICS or IMS application:

  1. When Object Builder starts, it presents the Open Project dialog. Choose the location of the project directory for your enterprise bean and click Finish.

  2. From the main menu, click Platform and then Target. Uncheck the 390 platform.

  3. Click User-Defined PA Schemas and right-click the selection.

  4. From the pop-up menu, click Import and then Bean. On the Import Bean dialog box, type the class name of the PAO bean and click Next.

  5. Select the appropriate connector type and click Next.

  6. Select the primary key attribute name from the Properties list.

  7. Click >> to move the primary key to the Key Attributes list and click Finish.

  8. For HOD and ECI only, do the following for both the MO and the HomeMO:

    1. In the Tasks and Object panel, expand the User-Defined Business Objects, expand the object, and expand the object's BO. From the MO file's pop-up menu, click Properties.

    2. Change the Service to use property from Transaction Service to Session Service.

  9. Create a DO implementation as follows:

    1. On the Tasks and Object panel, expand the User-Defined DOs, expand the DO File from the menu, and click the DO Interface.

    2. On the DO Interface pop-up menu, select Add Implementation.

    3. On the Behavior page, select BOIM with any Key for Environment, select Procedural Adapters for Form of Persistent Behavior and Implementation, select Delegating for Data Access Patterns, and select Default for Handle for Storing Pointers. Click Next.

    4. Click Next on the Implementation Inheritance page, the Attributes page, the Methods page, and the Key and Copy Helper page.

    5. On the Associated Persistent Object page, click Add Another, verify that the PO that you previously created is selected, and click Next.

    6. On the Attribute Mapping page, designate how the container-managed fields of the entity bean correspond to the items in the existing PAO. This designation is done by defining a mapping between the attributes of the DO (which match the entity bean's container-managed fields) to the attributes of the PO (which match the existing PAO). In the Attributes list, there is a DO attribute corresponding to each of the bean's container-managed fields.

      For each DO attribute in the Attributes list, right-click the attribute and click Primitive from the menu. From the Persistent Object Attribute drop-down menu, select the PO attribute (the item from the existing database schema) that corresponds to the DO attribute. For more information, see Guidelines for mapping the container-managed fields to a data source. After you have processed all container-managed fields, click Next.

    7. On the Methods Mapping page, for each method in the list of Special Framework Methods, right-click a method and click Add Mapping. From the Persistent Object Method drop-down menu, select the PO method with the same name as the selected DO method. If there are more methods than available mappings, map methods to similarly named methods. For example, map update to update(). After you have processed all of the methods, click Finish.

    8. Expand the Container Definition folder and right-click the EJB container. From the pop-up menu, click Properties. In the wizard, click Next until you reach the Data Access Patterns page.

    9. On the Data Access Patterns page, select one of the following items and then click Next:

      • For HOD or ECI, select Use PAA Session services.

      • For APPC, select Use PAA Transaction services.

    10. On the Service Details page, do the following and then click Next:

      • For HOD or ECI, select Throw an exception and abandon the call for Behavior for Methods Called Outside a Transaction; define a connection name, for example, MY_PAA_Connection; select Host on Demand or ECI connection, respectively, for the Type of connection.

      • For APPC, select Throw an exception and abandon the call for enterprise beans with the TX_MANDATORY transaction attribute, or select Start a new transaction and complete the call for enterprise beans with the TX_REQUIRED transaction attribute.

    11. Select Caching for Business Object.

    12. Select Delegating for Data Object.

    13. Click Finish.

  10. Exit from Object Builder by clicking File->Exit; save any changes if prompted.

Defining a new DB2 or Oracle database to store persistent data When you use a top-down development approach to enterprise bean development, enterprise bean deployment must occur in three phases:

  1. Define the database schema, map the container-managed fields of the entity bean with CMP to the database schema, and generate the code to encapsulate this mapping. For more information, see Mapping the database schema.

  2. Create the database and database tables. For more information, see Creating the database and database table.

  3. Compile the code generated in phase 1; compilation fails if the database and database tables do not exist.

Mapping the database schema

After you have defined the manner in which the entity bean maps to a database, create the mapping by running the cbejb tool with the -nc option to prevent automatic compilation after code generation. For example, to create a mapping for an Account bean stored in an EJB JAR file named EJBAccount.jar, enter the following command:

# cbejb EJBAccount.jar -nc -queryable [-oracle | -cacheddb2]

Note:
If the database being used to store the persistent data is either Oracle or DB2, those options must also be specified.

Creating the database and database table

Follow these instructions to create a database and database table by using the Object Builder GUI:

  1. When Object Builder starts, it presents the Open Project dialog. Choose the location of the project directory for your enterprise bean and click Finish.

  2. Create a DO implementation as follows:

    1. Expand the User-Defined DOs, expand the DO File from the menu, and click the DO Interface.

    2. On the DO Interface pop-up menu, select Add Implementation. If the implementation is already present, you can modify it by selecting the implementation, invoking the pop-up menu, and selecting Properties.

    3. On the Name and Platform page, select the platform and click Next.

    4. On the Behavior page, make the appropriate selections and click Next:

      • For DB2: select BOIM with any Key for Environment, select Embedded SQL for Form of Persistent Behavior and Implementation, select Delegating for Data Access Pattern, and select Home name and key for Handle for Storing Pointers.

      • For Oracle: select BOIM with any Key for Environment, select Oracle Caching services for Form of Persistent Behavior and Implementation, select Delegating for Data Access Pattern, and select Home name and key for Handle for Storing Pointers.

    5. On the Implementation Inheritance page, make the appropriate selections for the parent class and click Next:

      • For DB2, select IRDBIMExtLocalToServer::IDataObject

      • For Oracle, select RDBIMExtLocalToServer::ICachingServiceDataObject

      • For CICS or IMS PAO, select IRDBIMExtLocalToServer::IDataObject

    6. Accept the defaults for the Attributes, Methods, and Key and Copy Helper pages by clicking Next on each page.

    7. On the Associated Persistent Objects page, click Add Another. Accept the default for the instance name (iPO) and select the correct type. Click Next.

    8. On the Attribute Mapping page, map the container-managed fields of the entity bean to the corresponding items in the database schema. The default mapping is generally suitable for everything except for the primary key variable, which you must map to a varchar or char type rather than a long varchar type. Object Builder creates default mappings for the data object attributes for which it can identify corresponding persistent object attributes. For more information, see Guidelines for mapping the container-managed fields to a data source. After you finish mapping the attributes, click Finish.

    9. Oracle only. When mapping an entity bean with CMP to an Oracle database, expand the Container Definition folder and right-click the EJB container. From the pop-up menu, click Properties. In the wizard, click Next until you reach the Data Access Patterns; on that page, check the Cache Service checkbox and click Finish.

    10. Exit from Object Builder by clicking File->Exit; save any changes if prompted.

    11. Create the database specified by the Database text field and use the SQL file specified by the Schema File text field to create a database table. For more information on creating a database and database table with an SQL file, consult your DB2 or Oracle documentation. The SQL file can be found in the following directory, where projDir is the project directory created by the cbejb tool:

      • On Windows NT, projDir\Working\NT

      • On AIX, projDir/Working/AIX

      • On Solaris, projDir/Working/Solaris

Compiling the generated code

After both the database and database table are created, compile the enterprise bean code by using the following commands:

Installing an enterprise bean and configuring its EJB server (CB)
Follow these steps to install an enterprise bean and configure the resulting EJB server (CB):

  1. (Entity bean with CMP using DB2 only) Use the bind file, which Object Builder generates as a side effect of using the cbejb tool, to bind the enterprise bean to the database (for example, db2 bind AccountTblPO.bnd).

  2. Using the SM EUI, install the application generated by cbejb. In general, this installation is the same as installing a Component Broker application generated by Object Builder:

    1. Load the application into a host image.

    2. Add the application to a configuration.

    3. Associate the EJB application with a server group or server. (If the server group or server does not already exist, you must create it.)

    4. (Entity bean with CMP only) Associate the entity bean's data source (DB2, Oracle, CICS, or IMS PAA) with the EJB application:

      • DB2: associate the DB2 services (iDB2IMServices) with the EJB server.

      • Oracle: associate the Oracle services (iOAAServices) with the EJB server.

      • CICS or IMS PAA: associate the PAA services (iPAAServices) with the EJB server.

    5. Configure the EJB server (CB) with a host.

    6. Set the ORB request timeout for both clients and servers to 300 seconds.

    7. If the EJB server requires Java Virtual Machine (JVM) properties to be set, edit the JVM properties. Do this in the server model instead of the server image. For instance, if the enterprise bean performs a JNDI lookup to access other enterprise beans, the server hosting the enterprise bean must have its JVM properties set to include values for JNDI properties.

    8. Activate the EJB server configuration.

    9. Start the EJB server.

Binding the JNDI name of an enterprise bean into the JNDI namespace
Note:
This section does not apply to servers running on the AIX, Windows NT, Windows 2000, or Solaris platforms.
An enterprise bean's JNDI home name is defined within its deployment descriptor as described in The deployment descriptor. This name is used by EJB clients (including other enterprise beans) to find the home interface of an enterprise bean.

The ejbbind tool locates the CB home that implements the enterprise bean's EJBHome interface in the Component Broker namespace. It also rebinds the home name into the namespace, using the JNDI home name specified in the enterprise bean's deployment descriptor. This binding enables an EJB client to look up the EJB home by using the JNDI name specified in the bean's deployment descriptor. An enterprise bean can be bound on a different machine from the one on which the bean was deployed.

The subtree of the Component Broker namespace in which the JNDI name is bound can be controlled by the command-line options used with the ejbbind tool. The manner in which the name is bound (the subtree chosen) affects the JNDI name that EJB clients must use to look up the enterprise bean's EJB home and also affects the visibility of the enterprise bean's EJB home. Specifically, the JNDI name can be bound in one of the following ways:

Before running the ejbbind tool, do the following:

Invoke the ejbbind command with the following syntax:

ejbbind ejb-jarFile [beanParm] [-f] 
[-BindLocalRoot ] [-BindHost]  [-BindWorkgroup] [-BindCell] [-BindAllTrees] 
[-ORBInitialHost hostName] [-ORBInitialPort portNumber] 
[-u] [-UnbindLocalRoot] [-UnbindHost] [-UnbindWorkgroup] [-UnbindCell] 
[-UnbindAllTrees]

The ejb-jarFile is the fully-qualified path name of the EJB JAR file containing the enterprise bean to be bound or unbound. The optional beanParm argument is used to bind a single enterprise bean in the EJB JAR file; you can identify this bean by supplying a fully qualified name (for example, com.ibm.ejs.doc.account.Account, where Account is the bean name) or the name of the enterprise bean's deployment descriptor file without the .ser extension. If an enterprise bean has multiple deployment descriptors in the same EJB JAR file, you must supply the deployment descriptor file name rather than the enterprise bean name.

When no options are specified, the JNDI name is bound into the local root's name tree, using the local host and port 900 for the bootstrap host (the name server).

The other options do the following:

If the command is successful, it issues a message similar to the following:

Name AccountHome was bound to CB Home

You must run the ejbbind tool again if any of the following occurs:

Configuring systems management to enable lazy enumeration

To enable lazy enumeration (see Creating finder logic in the EJB server (CB)), follow these steps:

  1. From the System Management End User Interface (SM EUI), go to the View menu, and set the View Level to Control.

  2. Expand Host Images

  3. Expand the name of your host.

  4. Expand Server Images.

  5. Expand the name of your server.

  6. Expand Container Images.

  7. Right-click iIteratorSysObjsNoPRef. From the pop-up menu, select Properties. Change the following properties:

The transaction policy ensures that the caller starts a transaction. The memory management policy ensures that the lazy enumerations are passivated when the transaction completes.


Resolving to EJB homes using lifecycle services in CBConnector

Note:
This section applies only to servers running on the AIX, Windows NT, Windows 2000, or Solaris platforms.
When an EJB client performs a simple JNDI lookup, a 1-to-1 mapping is made between the name and the particular EJB home instance. In a distributed environment, this model can be limiting. In such an environment, for example, there may be many EJB homes supporting the same type of enterprise bean. It is better to have an approach that does not require an application to request a specific instance of that home. In addition, as changes are made to the system, it is important that applications not have to be changed or redeployed to specify a different instance of an EJB home. The CBConnector LifeCycle Service provides a level of indirection and abstraction that allows the application to request a home that is within a particular scope of location within the distributed environment, yet be isolated from the specifics of the exact configuration of the environment. For more info on lifecycle factory finders, see the LifeCycle section in the Advanced Programming Guide.

Using CBConnector, a JNDI context can be associated with a LifeCycle Service factory finder so that the associated factory finder is used to resolve EJB home lookup operations from the context. Contexts such as these enable deployers of EJB applications to take advantage of the power of factory finders in a manner that is transparent to clients of these applications.

To resolve EJB home lookups with factory finders, the application deployer can use pre-defined default application contexts associated with the various CBConnector-supplied default factory finders or use the appbind tool to create application-specific contexts and associate them with any given factory finder. For more information on each approach, see Default context-to-finder associations and Application-specific contexts and the appbind tool.

Note:
Default application contexts and application-specific contexts eliminate the need for the ejbbind tool, which creates a simple 1-to-1 mapping of a JNDI name and an EJB home instance. Clients must use one of the default initial context factories or an application-specific context factory generated by the appbind tool.

Default context-to-finder associations
There are several default factory finders built into CBConnector, each of which searches particular scopes of location when finding a factory. When an EJB application is deployed on a CBConnector server, the EJB homes for the application are bound in the LifeCycle repository using the names for the EJB homes as specified by the deployment descriptors contained in the application's EJB jar file. A factory finder can find any EJB home within the scope of its particular search rules.

An EJB client can use a particular built-in CBConnector default factory finder simply by using the initial context factory that corresponds to that factory finder. The initial context returned by the context factory will use its corresponding factory finder to resolve EJB home lookup requests.

Contexts returned by the following initial context factories:

  1. com.ibm.ejb.cb.runtime.CBCtxFactoryHostDefault

  2. com.ibm.ejb.cb.runtime.CBCtxFactoryHostWidenedDefault

  3. com.ibm.ejb.cb.runtime.CBCtxFactoryHostServerDefault

  4. com.ibm.ejb.cb.runtime.CBCtxFactoryHostServerWidenedDefault

  5. com.ibm.ejb.cb.runtime.CBCtxFactoryWorkGroupDefault

  6. com.ibm.ejb.cb.runtime.CBCtxFactoryWorkGroupWidenedDefault

  7. com.ibm.ejb.cb.runtime.CBCtxFactoryWorkGroupServerDefault

  8. com.ibm.ejb.cb.runtime.CBCtxFactoryWorkGroupServerWidenedDefault

  9. com.ibm.ejb.cb.runtime.CBCtxFactoryCellDefault

  10. com.ibm.ejb.cb.runtime.CBCtxFactoryCellServerDefault

  11. com.ibm.ejb.cb.runtime.CBCtxFactoryCellServerWidenedDefault

resolve EJB home lookup operations with the corresponding factory finders:

  1. host/resources/factory-finders/host-scope

  2. host/resources/factory-finders/host-scope-widened

  3. host/resources/factory-finders/server-server-scope

  4. host/resources/factory-finders/server-server-scope-widened

  5. workgroup/resources/factory-finders/workgroup-scope

  6. workgroup/resources/factory-finders/workgroup-scope-widened

  7. workgroup/resources/factory-finders/server-server-scope

  8. workgroup/resources/factory-finders/server-server-scope-widened

  9. cell/resources/factory-finders/host-scope

  10. cell/resources/factory-finders/server-server-scope

  11. cell/resources/factory-finders/server-server-scope-widened

Server-based context factories can only be used by a client that is running as a CBConnector server, in which case, server is the name of the CBConnector server.

Default context factories can only be used by client applications that issue fully qualified EJB home lookups. If a client traverses to a subcontext and then performs a partially qualified EJB home lookup, you must run the appbind tool to create an application-specific context with home subcontexts and to generate an application-specific initial context factory. For more information, see Application-specific contexts and the appbind tool.

Application-specific contexts and the appbind tool
If a CBConnector-supplied default factory finder is being used to locate an EJB home, CBConnector supplies a default mapping between application contexts and default factory finders (for more information, see Default context-to-finder associations). For added flexibility, an enterprise bean deployer can create an application-specific context with optional EJB home subcontexts and associate it with any factory finder. The factory finder association can be changed at a later time if desired. To isolate clients from the actual context name, the enterprise bean deployer generates an initial context factory for the application-specific context by using the appbind tool.

The appbind tool allows deployers to create an application-specific naming context and associate it with a selected factory finder so that lookup operations are resolved with that factory finder. These application-specific contexts are designed to be initial JNDI contexts for EJB clients so that JNDI lookup calls on EJB homes are transparently resolved with the associated factory finder. The appbind tool enables users to create, modify, and delete such application-specific contexts. Note that the application's EJB home instances are not actually bound under the application-specific context. Instead, they are bound to the LifeCycle repository. The associated factory finder will resolve the EJB home lookups using the lifecycle rules defined for it.

Using the appbind tool also helps to avoid naming collisions for enterprise beans that are written to version 1.1 of the EJB specification. It can be used to create separate JNDI namespaces for enterprise beans that have the same JNDI name but are deployed with initial context factories located at different places in the namespace. This prevents naming conflicts between these beans.

All application-specific contexts must have one of the following context name stems:

depending on whether a scope of host, workgroup, or cell is specified when the context is created.

By default, the factory finder host/resources/factory-finders/host-scope-widened is associated with an application-specific context created with the appbind tool. However, the user can specify another factory finder. The factory finder can be one of the other default factory finders, one created by an administrator using System Management, or one created by an application program you write. For more information, see the LifeCycle section in the Advanced Programming Guide.

Under an application-specific context, subcontexts for EJB home names optionally can be created. For example, if the name for a home is com/mycom/myapp/MyHome, the subcontext com/mycom/myapp can be created. These subcontexts provide additional transparency to the client. They allow a client to traverse the JNDI name space from the application-specific context down to any subcontext that corresponds to a non-leaf component of an EJB home name. The factory finder associated with the application-specific context is also used to resolve EJB home lookup operations from these subcontexts. The appbind tool creates a subcontext for each home name in the deployment descriptors within a specified EJB JAR file.

The appbind tool can optionally create a Java source file for an initial context factory for the application-specific context being created. This initial context factory can be used as the initial context factory by clients. The appbind tool also allows the user to override the default bootstrap host to use for ORB initialization. Invoke the appbind tool with the following syntax:

appbind [-u] -name  contextName [-sc jarFileName] [-host | -workgroup | -cell]
[-factoryfinder factoryFinderPath]
[-genctxfactory  factoryClassName [-o  targetDir]]
[-boothost  bootstrapHostUrl]

The context being bound or unbound is specified with the required -name option, where contextName is the name of the JNDI application-specific context to bind or unbind. All application context names are relative to one of the following context name stems

depending on whether a scope of host, workgroup, or cell was specified. (See the -host, -workgroup, and -cell options below.)

A bind operation is performed unless the -u option is specified, in which case, an unbind operation is performed. If a bind operation is performed on an existing context, the current factory finder association is added or replaced. The context cannot be a child or parent of a context which already has a factory finder association.

The other options do the following:


Creating an enterprise bean from an existing CICS or IMS application

You can create an enterprise bean from an existing CICS or IMS application by using the PAOToEJB tool. The application must be mapped into a PAO prior to creating the enterprise bean. For more information on creating PAOs, see the Component Broker document entitled Procedural Application Adaptor Development Guide and the VisualAge for Java, Enterprise Edition documentation.

The PAOToEJB tool runs independently of the other tools described in this chapter. To create an enterprise bean from a PAO class, do the following:

  1. Change to the directory where your PAO class file exists.

  2. Add the PAO class file's directory, or the JAR file containing the class, to your CLASSPATH environment variable.

  3. Invoke the PAOToEJB command with the following syntax:
    PAOToEJB -name [ejbName] paoClass -hod |  -eci | -appc
    

    The ejbName argument is optional and specifies the enterprise bean's name (for example, Account). If this name is not supplied, the enterprise bean is named by using the short name of the PAO class. The paoClass argument is required and specifies the fully qualified Java name of the PAO class without the .class extension; the PAO class is always a subclass of com.ibm.ivj.eab.paa.EntityProceduralAdapterObject. You must also specify one of the following options:

    Note:
    EJB clients that access entity beans with CMP that use HOD or ECI for CICS or IMS applications must begin a transaction before invoking a method on these entity beans. This is necessary because these types of entity beans must use the TX_MANDATORY transaction attribute.

  4. If the paoClass is part of a Java package, then you must create the corresponding directory structure and move the generated Java files into this directory.

  5. Compile the Java source files of the newly created enterprise bean:
    javac ejbName*.java
    

  6. Place the compiled class components of the enterprise bean into a JAR or ZIP file and use the jetace tool to create an EJB JAR file for the bean, as described in Creating an EJB module.

  7. Deploy the EJB JAR file by using the cbejb tool as described in Manually deploying an enterprise bean.

Creating an enterprise bean that communicates with MQSeries

Component Broker contains tools for developing BOs that send or receive MQSeries messages. It also allows access to MQSeries queues within distributed transactions. The EJB server (CB) builds on this MQSeries support and allows you to create an enterprise bean that wraps an MQSeries-based BO.

The MQSeries EJB support enables an EJB client application to indirectly interact with MQSeries through an EJB client interface. Both the Component Broker support for MQSeries BOs and the EJB support described here require you to modify the DO implementation generated by Object Builder. The main difference between these two supported approaches is that when Component Broker MQSeries-based BOs are built, the MQSeries message content is specified through Object Builder, whereas the EJB support requires the MQSeries message content to be specified in a Java properties file.

For more information on the MQSeries support in Component Broker, see the MQSeries Application Adaptor Development Guide document.

The mqaaejb tool generates a session bean that wraps a Component Broker BO based on the MQSeries Application Adaptor. The resulting session bean implementation is specific to the EJB server (CB) and is not portable to other EJB servers. To deploy the generated session bean, use the cbejb tool. The mqaaejb tool runs independently of other EJB server (CB) tools.

To create a session bean for a particular MQSeries queue, do the following:

  1. Create a Java properties file that contains these items:

  2. Run the mqaaejb command with the following syntax:
    # mqaaejb -f propertiesFile -n baseBeanName [-p packageName] 
      [-i existingInboundBOInterfaceName]
      [-o existingOutboundBOInterfaceName]
      [-c existingOutboundCopyName
    

    The -f and -n options are required. The propertiesFile specifies the name of the properties file created in Step 1, and the baseBeanName argument specifies the base name of the enterprise bean or beans to be generated. For example, if the base name is Account and the properties file specifies that it is for both an inbound and an outbound message, then the mqaaejb command generates session beans, related interfaces, and artifacts with the following names:

    AccountInboundBean

    AccountEJBObject

    AccountInboundEJBHome

    AccountOutboundBean

    AccountOutboundEJBObject

    AccountOutboundEJBHome

    AccountMsgTemplate

    The -p option specifies the package name of the enterprise bean; if not specified, the package name defaults to mytest.ejb.mqaa.

    Unless the -i option or the -o and -c options are specified, the mqaaejb command makes a mark for the cbejb command; later, when the cbejb command is run over the beans, it generates the required backing message BOs for the session beans. If you have already created and tested MQSeries Application Adaptor-based BOs (following the procedure described in the MQSeries Application Adaptor Development Guide), you now need only wrap them in session beans. You can specify the names of these BOs and the Copy object to the mqaaejb command. The mqaaejb command then creates session beans that use the specified BOs. The names of these objects must be fully qualified. For example:

    mqaaejb -f mymsg.properties -n Account -i TextMessage::TMInbound \
       -o TextMessage::TMOutbound -c TextMessageCopy::TMOutboundCopy
    

    You still must specify the base bean name with the -n option independently of the existing BOs. You also must provide a properties file; the message format specified in this file must be consistent with the existing BOs. The correct mapping between the C++ field types in the BOs and the Java types in the properties file can be established by referring to the IDL C++/Java binding documentation.

    The following items are generated in the working directory on successful completion of the mqaaejb command:

  3. Run the jetace tool as follows to generate an EJB JAR file for the enterprise bean:

    # jetace -f beanName.xml

  4. Run the cbejb tool to deploy the enterprise bean contained in the EJB JAR file. For more information, see Manually deploying an enterprise bean. When the cbejb command is complete, unless you are using existing BOs, you possibly need to follow the steps in the MQSeries Application Adaptor Development Guide to modify the DO implantation.

Restrictions in the EJB server (CB) environment

The following restrictions apply when developing enterprise beans for the EJB server (CB) environment: