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.
You need the following tools to develop and deploy enterprise beans for the
EJB server (CB):
- An ASCII text editor. (You can use also use a Java development tool
that does not support enterprise bean development.)
- The SDK Java compiler (javac) and Java Archiving tool
(jar).
- The following tools available in the WebSphere Application Server,
Enterprise Edition:
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:
- 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).
- 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.
- Write and compile the components of the enterprise bean. For more
information, see Creating the components of an enterprise bean.
- 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).
- 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.
- Deploy the enterprise bean by doing one of the following:
- To automatically deploy the enterprise bean from a JAR file, use the
CBDeployJar tool. For more information, see Deploying an enterprise bean with the CBDeployJar tool.
- To automatically deploy the enterprise bean from a J2EE EAR file, use the
CBDeployEar tool. For more information, see Deploying an enterprise bean with the CBDeployEar tool.
- To manually deploy the enterprise bean from a JAR file, do the
following:
- Use the cbejb command to deploy the enterprise bean. For
more information, see Using the cbejb tool to deploy enterprise beans.
- Build a data object (DO) implementation for use by the enterprise bean by
using Object Builder. For more information, see Building a data object during CMP entity bean deployment.
- Install the deployed enterprise bean and configure its EJB server
(CB). For more information, see Installing an enterprise bean and configuring its EJB server (CB).
- Start the EJB server (CB). For more information see the Component
Broker System Administration Guide.
- 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.) For more information,
see Binding the JNDI name of an enterprise bean into the JNDI namespace.
For more information on manual deployment, see Manually deploying an enterprise bean.
- 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:
- CB Server
- CB Tools (including the Object Builder, VisualAge Component Development
toolkit, samples, the Server SDK, and (PAO only) CICS and IMS
Application Adapter SDK
- (PAO only) CICS/IMS Application run time
- (PAO only) CICS/IMS Application client
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:
- Developing an enterprise bean or an EJB client: no additional
files.
- Deploying an EJB JAR file:
- somojor.zip
- The EJB JAR file being deployed and any JAR or ZIP files on which it
depends
- Running an EJB server (CB) managing an enterprise bean named
beanName. These JAR files are automatically added to the
CLASSPATH environment variable.
- beanNameS.jar
- The EJB JAR file used to create beanNameS.jar and any
JAR or ZIP files on which it depends
- Running a pure Java EJB client using an enterprise bean named
beanName:
- beanNameC.jar
- somojor.zip
- Running an EJB server (CB) that contains an enterprise bean named
clientBeanName that accesses another enterprise bean named
beanName as a client. These JAR files are automatically
added to the CLASSPATH environment variable.
- clientBeanNameS.jar
- The EJB JAR file used to create clientBeanNameS.jar and
any JAR or ZIP files on which it depends
- beanNameC.jar
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.
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);
}
}
|
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.
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
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:
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
To generate an EJB JAR file with the jetace tool, do the
following:
- 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.
- If you do not want to include a listed enterprise bean in the resulting
EJB JAR file, highlight that enterprise bean's deployment descriptor and
click Delete. This action removes the deployment descriptor
from the list box.
- If you want to create a duplicate of an enterprise bean, highlight its
deployment descriptor and click Copy. This action adds a new
default deployment descriptor to the list box. Copying can be useful if
you want to create a deployment descriptor for one enterprise bean that is
similar to the deployment descriptor of the copied bean. You must then
edit the new deployment descriptor.
- 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.
- 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.
- Set the transaction attributes for the enterprise bean's deployment
descriptor on the Transactions page. For information, see Setting transaction attributes.
- Set the security attributes for the enterprise bean's deployment
descriptor on the Security page. For information, see Setting security attributes.
- 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.
- 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.
- 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).
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
In the Basic page, you must select or confirm values for the following
fields:
- Deployed Name--The pathname of the deployment descriptor
file to be created. It is recommended that this directory name match
the full package name of the enterprise bean class. For the Account
bean, the full name is
com/ibm/ejs/doc/account/Account.ser.
- Enterprise Bean Class--Specify the full package name of
the bean class. For the Account bean, the full name is
com.ibm.ejs.doc.account.AccountBean.
- Home Interface--Specify the full package name of the
bean's home interface. For the Account bean, the full name is
com.ibm.ejs.doc.account.AccountHome.
- Remote Interface--Specify the full package name of the
bean's remote interface. For the Account bean, the full name is
com.ibm.ejs.doc.account.Account.
- JNDI Home Name--Specify the JNDI home name of the
bean's home interface. This the name under which the enterprise
bean's home interface is registered and therefore is the name that must
be specified when an EJB client does a lookup of the home interface.
For the Account bean, the JNDI home name is Account.
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
In the Entity page, you must select or confirm values for the
following fields:
- Primary Key Class--Specify the full package name of the
bean's primary key class. For the example Account bean, the full
name is
com.ibm.ejs.doc.account.AccountKey.
- Container-Managed Fields--Check the check boxes of the
variables in the bean class for which the container needs to handle
persistence management. This is required for entity beans with CMP
only, and must not be done for entity beans with BMP. For
the Account bean, the type, balance, and accountId variables are container
managed, so each box is checked.
- Re-entrant?--Check this check box if the bean is
reentrant. By default, an entity bean is not reentrant. If an
instance of a non-reentrant entity bean is executing a client request in a
transaction context and it receives another request using the same transaction
context, the EJB container throws the java.rmi.RemoteException
exception to the second request. Since a container cannot distinguish
between a legal loopback call from another bean and an illegal concurrent call
from another client or client thread, a client must take care to prevent
concurrent calls to a reentrant bean. The example Account bean is
not reentrant.
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
On the Session page, you must select or confirm values for the
following fields:
- Session Timeout (seconds)--Specify the idle timeout value
for this bean in seconds; a 0 (zero) indicates that idle bean
instances timeout after the maximum allowable timeout period has
elapsed. For the Transfer bean, the value is left at 0 to
indicate that the default timeout is used.
- Note:
- In the EJB server (CB) environment, this attribute is not used.
- State Management Attribute--Specify whether the bean is
stateless or stateful. The example Transfer bean is
STATELESS_SESSION. For more information, see Stateless versus stateful session beans.
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
On the Transactions page, you must select or confirm values for
the following fields in the Defaults group box:
- Transaction Attribute--Set a value for the transaction
attribute. The values for this attribute are described in Enabling transactions and security in enterprise beans. For the Account bean, the value
TX_MANDATORY is used because the methods in this bean must be
associated with an existing transaction when invoked; as a result, the
Transfer bean must use the value that begins a new transaction or passes on an
existing one.
- Isolation Level--Set a value for the transaction isolation
level attribute. The values for this attribute are described in Enabling transactions and security in enterprise beans. For the Account bean, the value
REPEATABLE_READ is used.
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.
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
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.
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
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:
- JNDIName--The JNDI name of the Account bean, which is accessed by the
Transfer bean. For more information, see Figure 11.
- javax.naming.Context.INITIAL_CONTEXT_FACTORY--The
name of the initial context factory used by the Transfer bean to look up the
JNDI name of the Account bean
- javax.naming.Context.PROVIDER_URL--The location
of the naming service used by the Transfer bean to look up the JNDI name of
the Account bean.
For more information on how these environment variables are used by the
Transfer bean, see Implementing the ejbCreate methods.
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
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.
The CBDeployJar tool automates the tasks associated with
deploying an enterprise bean. It can be used to do the following:
- Deploy enterprise beans from JAR files
- Verify whether enterprise beans have been deployed from a JAR file
- Undeploy enterprise beans associated with a JAR file
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:
- Session beans
- Entity beans with BMP
- Entity beans with CMP that use top-down mapping or have mapping
information from VisualAge for Java
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:
- 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.
- It runs the cbejb tool on the JAR file, using any options
specified by the user.
- It runs the make command for the platform, using any options
specified by the user.
- It maps the persistent fields in entity beans with CMP to database
tables.
- 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.
- 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:
- ejb-jarFile -- The name of the JAR file (required).
This must be the first parameter.
- hostname -- The fully-qualified host name of the machine
where the enterprise beans are being deployed (required). This must be
the second parameter.
- -cbejb options -- Specifies the desired options for the
cbejb command, which is run by the CBDeployJar tool as
part of the deployment process. If this flag is not set, the
command's default options are used. For a complete list of
cbejb command-line options, see Using the cbejb tool to deploy enterprise beans.
- Note:
- Use double quotes ("") for options passed to the -cbejb and -make flags that
contain spaces.
- -make options -- Specifies the desired options for the
make command for the platform, which is run by the
CBDeployJar tool as part of the deployment process. If this
flag is not set, the command's default options are used. For a
complete list of make options, see the documentation for your
compiler.
- -noTables -- Prevents the CBDeployJar tool from creating
tables for persistent fields in entity beans with CMP. You must specify
this flag if you are using entity beans with CMP that are backed by a database
other than DB2. (The CBDeployJar tool only creates DB2
database tables.)
- -prepJarOnly -- Stops the process after converting a version
1.1-compatible JAR file to the version 1.0 format (step
1).
- -cbejbOnly -- Stops the process after running the cbejb
tool (step 2).
- -makeOnly -- Stops the process after running the make
command (step 3).
- -isDeployed -- Verifies whether a specific JAR file has been
deployed. This option can be specified only with the
ejb-jarFile and hostname parameters.
- -undeploy -- Undeploys a JAR file that had previously been deployed
with the CBDeployJar tool. This option can be specified only
with the ejb-jarFile and hostname parameters. The
-undeploy option removes all of the files generated by the cbejb
and make commands, deletes the Data Object implementations for
entity beans with CMP, deletes the server configuration and associated
information, stops the EJB server, and deletes any references to EJB
1.1-compatible enterprise beans from the JNDI namespace.
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
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:
- earFile -- The name of the J2EE EAR file (required).
This must be the first parameter.
- hostname -- The fully-qualified host name of the machine
where the enterprise beans are being deployed (required). This must be
the second parameter.
- -cbejb options -- Specifies options for the cbejb
command, which is run when the CBDeployEar tool calls the
CBDeployJar tool. See Deploying an enterprise bean with the CBDeployJar tool for more information.
- -make options -- Specifies options for the make
command, which is run when the CBDeployEar tool calls the
CBDeployJar tool. See Deploying an enterprise bean with the CBDeployJar tool for more information.
- -noTables -- Stops the tool from creating tables for persistent
fields in entity beans with CMP. You must specify this flag if you are
using entity beans with CMP that are backed by a database other than
DB2.
- -prepJarOnly -- Stops the process after converting a version
1.1-compatible JAR file to the version 1.0 format.
- -cbejbOnly -- Stops the process after running the cbejb
tool.
- -makeOnly -- Stops the process after running the make
command.
- -bindEJBRefs -- Binds references to EJB 1.1-compatible
enterprise beans into the JNDI namespace. This option is specified by
default. However, there are situations when it is convenient to skip
the cbejb and make steps and perform the JNDI binding
step when running the CBDeployEar tool-- for example, if the
EJB server was not started when you first ran the CBDeployEar tool
and you want to save time when running the tool again.
- -isDeployed -- Verifies whether a JAR file has been deployed from a
specific EAR file. This option can be specified only with the
earFile and hostname parameters.
- -undeploy -- Undeploys a JAR file that had previously been deployed
from an EAR file with the CBDeployEar tool. This option can
be specified only with the earFile and hostname
parameters.
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
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:
- Use the cbejb command to deploy the enterprise bean.
- Build a data object (DO) implementation for use by the enterprise bean by
using Object Builder (This step is part of the deployment process).
- Install the deployed enterprise bean and configure its EJB server
(CB).
- Start the EJB server (CB) as described in the Component Broker System Administration Guide.
- 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.
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:
- Deployment options, which govern the generation and compilation of
code.
- Storage options, which govern persistent storage.
- Execution options, which govern the run time environment.
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.
- Deployment options
- -ob projDir -- Specifies the relative or full path of the
project directory in which the generated files are stored. If this
option is not specified, the current working directory is used as the project
directory.
- Compilation modifiers -- By default, the cbejb tool does
the following for each enterprise bean contained in the EJB JAR file:
- Generate and import XML.
- Generate code--Creates a DDL file, makefile, and other source files
for each enterprise bean contained in the EJB JAR file. These files are
placed in the specified project directory.
- Compile and link--Invokes the generated makefile to compile an
application. Each application file is placed in the specified project
directory. While the Dynamic Link Libraries (DLLs) are being linked,
numerous duplicate symbol warnings appear; these warnings are harmless
and can be ignored.
The following command options modify the default compilation
behavior:
- -nm -- Suppresses the XML-processing step.
- -ng -- Suppresses the code-generation step.
- -nc -- Suppresses the compilation-and-linking step.
- -cc -- Removes previously compiled and linked code by invoking the
generated makefile to remove non-source files. This option must be used
if you specify either of these combinations:
- -bean beanNames -- Identifies the enterprise beans in the
EJB JAR file to be deployed. By default, all enterprise beans in the
EJB JAR file are deployed. To deploy multiple enterprise beans, delimit
the bean names with a : (colon). For example,
Account:Transfer.
- -platform -- Specifies the platform for which to generate
code. This also sets the deployment platform in the Object Builder
tool, but it does not set the platform for viewing, generating, or applying
development constraints. You must set these manually by using the
choices on the Platform menu.
- -guisg -- Directs the tool to present the Object Builder graphical
user interface (GUI), which enables the tool to collect options from the user
rather than from the command line.
- -usecurdopo -- Directs the tool to use the current mapping between
the data object and the persistent object in the existing model rather than
bringing up the Object Builder interface to build a mapping. Use this
option when redeploying beans for which a satisfactory mapping already
exists. The deployment will proceed automatically.
When you first deploy CMP entity beans, you must not use this
option. The tool will then build the default mapping between the data
and persistent objects and, if you specify the -guisg option, launch the
Object Builder interface.
- -nousraction -- Directs the tool to use only the information on the
command line after building the mapping between data objects and persistent
objects. Otherwise, if you have also specified the -guisg option, the
tool prompts you for the next action.
- -polymorphichome -- Specifies the beans that use polymorphic home
interfaces.
- -queryable -- Directs the tool to generate a queryable CB home
object. This option can be used only for entity beans with CMP that
store their persistent data in a relational database. This option must
be used if the finder helper class, which is used to implement the finder
methods in a CMP entity bean, uses the CB query service. This option
must not be used if an entity bean uses CICS or IMS to store its
persistent data.
By default, the interface definition language (IDL) interface of an
enterprise bean's CB home extends the IManagedClient::IHome
class, and the home implementation extends the
IManagedAdvancedServer::ISpecializedHome class. An IDL
interface of a queryable home extends the
IManagedAdvancedClient::IQueryableIterableHome class, and the home
implementation extends the
IManagedAdvancedServer::ISpecializedQueryableIterableHome
class.
In addition, the generated BO interface is marked as queryable. For
queryable homes, the EJB client programming model remains unchanged;
however, a Common Object Request Broker Architecture (CORBA) EJB client can
treat the EJB home as an
IManagedAdvancedClient::IQueryableIterableHome object.
For more information on queryable homes, see the Advanced Programming Guide.
- Storage options
- -dbname DBName -- Specifies the name of the database for
beans with CMP.
- Database choices--The default database for persistent storage of
container-managed beans is DB2 version 5.2 with embedded SQL.
You can override this default by using:
- -cacheddb2v52 -- Identifies entity beans with CMP that require DB2
version 5.2 used with the Cache Service to store persistent
data.
- -cacheddb2v61 -- Identifies entity beans with CMP that require DB2
version 6.1 used with the Cache Service to store persistent
data.
- -db2v61 -- Identifies entity beans with CMP that require DB2 version
6.1 used with embedded SQL to store persistent data.
- -oracle -- Identifies entity beans with CMP that require Oracle to
store persistent data. If you specify this option, you must also use
the -queryable option.
- -informix -- Identifies entity beans with CMP that require Informix
to store persistent data. A given transaction cannot access more than
one Informix database from a CB server. To access two Informix
databases in one transaction, you must access each from a different CB
server. If you specify this option, you must also use the -queryable
option.
- -jdbcaa -- Identifies entity beans with BMP that require JDBC to
store persistent data. This option enables the beans to join
distributed transactions by allowing the bean implementation to connect to the
Transaction Service. Beans with BMP that do not use this option will
handle transactions in an implementation-dependent manner.
- -hod -- Identifies entity beans with CMP that use Host-on Demand
(HOD) to store persistent data. These beans will use the Session
Service. This option must not be used for enterprise beans
generated from the PAOToEJB tool.
- -eci -- Identifies entity beans with CMP that use the external call
interface (ECI) to store persistent data. These beans will use the
Session Service. This option must not be used for enterprise
beans generated from the PAOToEJB tool.
- -appc -- Identifies entity beans with CMP that use advanced
program-to-program communications (APPC) to store persistent data.
These beans will use the Transaction Service. This option must
not be used for enterprise beans generated from the
PAOToEJB tool.
- -exci -- Identifies entity beans with CMP that use the EXCI to store
persistent data. These beans will use the Transaction Service.
This option must not be used for enterprise beans generated from
the PAOToEJB tool.
- -otma -- Identifies entity beans with CMP that use the OTMA to store
persistent data. These beans will use the Transaction Service.
This option must not be used for enterprise beans generated from
the PAOToEJB tool.
- -ccf -- Identifies entity beans with CMP that use the SAP interface,
which is a common connector framework (CCF) back end. These beans will
use the Transaction Service.
- Execution options
- -family familyName -- Specifies the application family
name to be generated. By default, this name is set to the name of the
EJB JAR file with the word Family appended. This option can be
specified more than once, as long as the values are unique.
- -finderHelper finderHelperClassName
remoteInterface-- Specifies the finder helper class name
(finderHelperClassName) and remote interface name
(remoteInterface) for entity beans with CMP. If unspecified,
it is assumed that no finder helper class is provided by the deployer.
This option can be specified more than once, as long as the values are
unique. For more information on finder helper classes, see Defining finder methods.
- -usewstringindo -- Directs the tool to map the container-managed
fields of an entity bean to the wstring IDL type (rather than the string type)
on the DO. It is preferable to map to the string IDL type if the data
source contains single-byte character data; it is preferable to map to
the wstring IDL type if the data source contains double-byte or Unicode
character data.
- -workloadmanaged -- Directs the tool to configure a CMP entity bean
or a stateless session bean into a workload managing container and with a
workload managed home interface. For a BMP entity bean or a stateful
session bean it directs the tool to configure the bean only with a workload
managed home interface.
- -clientdep deployed-jarFile -- Specifies the name of a
dependent JAR required by an EJB client that uses the enterprise bean being
deployed. You must specify the full path of the file. To create
multiple client JAR files, you must specify this option for each JAR
file. This option can be specified more than once, as long as the
values are unique.
- -serverdep deployed-jarFile -- Specifies the name of a
dependent JAR required by the EJB server (CB) that runs the deployed
enterprise bean. You must specify the full path of the file. To
create multiple dependent JAR files, you must specify this option for each JAR
file. This option can also be used to identify existing JAR files that
contain classes required by the enterprise bean being deployed; when this
is done, the EJB server's CLASSPATH environment variable is automatically
updated to include this specified JAR file. This option can be
specified more than once, as long as the values are unique.
- -sentinel sentinelValue -- Specifies an value for a Java
type or container-managed field for the deployed beans. If you set a
value for a Java type, do not put spaces around the = (equals) sign.
- -strbehavior -- Specifies how the tool should determine the behavior
of the strings for a container-managed string fields in deployed beans.
The corba value indicates that strings should be handled as CORBA
strings; the strip value directs the tool to remove trailing spaces from
strings.
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:
- AccountS.jar and (Windows NT and Windows 2000)
AccountS.dll or (AIX or Solaris)
libAccountS.so--The files required by the EJB server (CB) that
contains this enterprise bean. The AccountS.jar file contains
the code generated from the Account EJB JAR file. The
AccountS.dll and libAccountS.so files contain the required C++
classes.
(Windows NT and Windows 2000) To run the Account enterprise bean
in an EJB server (CB), the AccountS.jar file must be defined in the
server's CLASSPATH environment variable, and the AccountS.dll file
must be defined in the server's PATH environment variable.
Typically, the System Management End User Interface (SM EUI) sets these
environment variables during installation of the deployed enterprise bean into
an EJB server (CB).
(AIX or Solaris) To run the Account enterprise bean
in an EJB server (CB), the AccountS.jar file must be defined in the
server's CLASSPATH environment variable, and the libAccountS.so
file must be defined in the server's LD_LIBRARY_PATH environment
variable. Typically, the SM EUI sets these environment variables during
installation of the deployed enterprise bean into an EJB server (CB).
- AccountC.jar--The file required by an EJB client, including
enterprise beans that access other enterprise beans. This JAR file
contains everything in the original EJB JAR file except the enterprise bean
implementation class. To use the Account enterprise bean, a Java EJB
client must have the AccountC.jar and the IBM Java ORB defined in its
CLASSPATH environment variable.
- (PAO only) paotoejbName.jar--This file
is created by the PAOToEJB tool and is used to wrap an existing
procedural adapter object (PAO) in an enterprise bean.
- EJBAccountFamily.DDL--This file is used during installation of
the Account family into an EJB server (CB) to update the database used by the
SM EUI. Its name is composed of the EJB JAR file name with the string
Family.DDL appended.
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).
- EJBObject or EJBHome variables--Objects of classes that implement the
EJBObject or EJBHome interface map to the Object IDL type. At run time,
this DO attribute contains the CORBA proxy for the EJBObject or EJBHome
object. The CB EJB run time automatically converts between the
EJBObject or EJBHome object (stored in the bean's container-managed
field) and the CORBA::Object attribute (stored in the C++
DO). It is possible to deploy container-managed beans that have
container-managed fields of the same type, for example, a linked list
implementation where each node of the list is a container-managed bean that
has a reference to the next node. It is also possible to have circular
references in a container-managed field, for example, a container-managed Bean
A can have a container-managed field of type Bean B, which in turn has a
container-managed field of type Bean A. When defining the DO-to-PO
mapping in Object Builder, you can use either a predefined Component Broker
mapping of CORBA::Object to the data source, or implement a C++
DO-to-PO mapping helper (in the standard Component Broker way) to invoke
methods on the C++ proxy to obtain the persistent data. For more
information on creating a C++ DO-to-PO mapping, see the Component Broker Programming Guide.
- Note:
- Although Component Broker allows an entity bean's container-managed
fields to be EJBObject or EJBHome objects, the Enterprise JavaBeans 1.0
specification does not.
- Primary key variables--Do not map an enterprise bean's primary
key variables to the SQL type long varchar in a DB2, Informix or Oracle
database. Instead, use either a varchar or a char type and set the
length appropriately.
- java.lang.String variables--Objects of this class are
mapped to a DO IDL attribute of type string or wstring, depending on the
command-line options used when the entity bean was deployed by using the
cbejb tool (see Manually deploying an enterprise bean). By default, a variable of type
java.lang.String is mapped to a DO IDL attribute of type
string; however, the -usewstringindo option of the cbejb tool
can be used to map java.lang.String variables to DO IDL
attributes of type wstring. (Mapping some of a bean's String
fields to the IDL string type and others to the IDL wstring type is not
supported.) It is preferable to map to the string IDL type if the data
source contains single-byte character data; it is preferable to map to
the wstring IDL type if the data source contains double-byte or Unicode
character data.
- java.io.Serializable variables--Objects of classes that
implement this interface are mapped to a DO IDL attribute of type ByteString
(which is a typedef for sequence of octet defined in the
IManagedClient.idl file). The EJB server (CB) automatically
converts serializable objects (stored in the entity bean's
container-managed fields) to the C++ sequence of octets containing the
serialized form of the object (stored in the DO). Use the Component
Broker default DO-to-PO mapping for ByteString to store the serialized object
directly in the data source.
Unless you implement a C++ DO-to-PO mapping helper that passes the C++
ByteString to a Java implementation by way of the interlanguage object model
(IOM), it is not possible to manipulate the serialized Java object contained
in a ByteString from within a C++ DO implementation. Therefore, if you
are doing top-down enterprise bean development and you don't want to
store a serialized Java object in the data source, it is recommended that you
avoid defining container-managed fields of type Serializable. Instead,
make the Serializable variable a nonpersistent variable, define primitive type
container-managed fields to capture the state of the Serializable variable,
and convert between the Serializable variable and the primitive variable in
the ejbLoad and ejbStore methods of the enterprise bean.
- Array variables--These variables are mapped to a DO IDL sequence of
the corresponding type in the same way that the individual types are mapped to
DO IDL attributes. For example, an array of the
java.lang.String class is mapped to a DO IDL attribute that is a
sequence of type string (or a sequence of type wstring, if the -usewstringindo
option of the cbejb tool is used). The EJB server (CB)
automatically converts between the array (stored in the entity bean's
container-managed fields) and the C++ sequence (stored in the DO). You
can store the entire sequence in the data source as a whole, or you can write
a C++ DO-to-PO mapping helper (in the standard Component Broker way) to
iterate through the sequence and store individual elements in the data source
separately. For more information on creating a C++ DO-to-PO mapping,
see the Component Broker Programming Guide.
- Date/Time fields--The cbejb tool maps container-managed
fields of type java.util.Date and its subclasses
(java.sql.Date, java.sql.Time,
java.sql.Timestamp only) differently from other
Serializable fields. The following mapping rules are used:
- java.util.Date: ISO-formatted timestamp string
(yyyy-mm-dd-hh.mm.ss.mmmmmm)
- java.sql.Date: ISO-formatted date string
(yyyy-mm-dd)
- java.sql.Time: ISO-formatted time string
(hh.mm.ss)
- java.sql.Timestamp: ISO-formatted timestamp string
(yyyy-mm-dd-hh.mm.ss.mmmmmm)
Therefore a container-managed field of one of the above types should be
mapped to either a string or a database-specific date/time field that can take
an ISO-formatted string as input. (For example, both DB2 and Oracle
Date/Time/Timestamp column types can take ISO strings as input values.)
If a deployer chooses to map a Date/Time container-managed field to something
other than the types mentioned above, then a special data mapping code should
be written in the DO implementation. The mapping code must be able to
convert an ISO-formatted string to a backend-specific type and vice
versa.
The java.sql.Timestamp class has a precision of nanoseconds,
whereas ISO timestamp format has a precision of microseconds.
Therefore, precision is compromised (by rounding nanoseconds to nearest
microseconds) when a Timestamp CMP field is mapped. Users should be
particularly aware of this when they use the java.sql.Timestamp
class as one of the attributes of bean's primary key.
While mapping java.sql.Date to ISO Date format, the time
field values are ignored. Similarly while mapping
java.sql.Time to ISO Time, the date field values are
ignored.
- Note:
- For DB2 only: If an existing database outputs date/time in a non-ISO
format, then the deployer must rebind DB2 packages using the "DATETIME ISO"
option.
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.
- When Object Builder starts, it presents the Open Project dialog.
Choose the location of the project directory for your enterprise bean and
click Finish.
- To import an existing relational database schema, click DBA-Defined
Schemas and right-click the appropriate database type.
- On the pop-up menu, click Import and SQL.
- On the Import SQL dialog box, click Find and browse
for your SQL file.
- Double-click your SQL file.
- Change the name in the Database Name text field from
Database to the actual name of the database.
- Select the appropriate database type and click Finish.
- To create a persistent object (PO) from the database schema, expand
DBA-Defined Schemas and expand your group.
- Highlight your schema and then right-click it to display a pop-up
menu. Click Add->Persistent Object.
- On the Names and Attributes dialog box, accept the defaults and
click Finish.
- Create a DO implementation as follows:
- 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.
- On the DO Implementation pop-up menu, select
Properties.
- On the Name and Platform page, select the Deployment
Platform (for example, NT, AIX, or Solaris) and click
Next.
- 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.
- 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
- Accept the defaults for the Attributes, Methods, and
Key and Copy Helper pages by clicking Next on each
page.
- On the Associated Persistent Objects page, click Add
Another. Accept the default for the instance name (iPO) and
select the correct type. Click Next.
- 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.
- 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.
- Exit from Object Builder by clicking File->Exit; save any
changes if prompted.
- 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:
- The entity bean's transaction attribute must be set to TX_MANDATORY
if you want to map the bean to a HOD- or ECI-based application. The
transaction attribute must be set to either the TX_MANDATORY or TX_REQUIRED if
you want to map it to an APPC-based application.
- The existing CICS or IMS application must be represented as a procedural
adapter object (PAO). See the Procedural Application Adaptor Development Guide for more information
on creating PAOs.
- The PAO class files must be specified in the CLASSPATH environment
variable.
- The entity bean must implement all enterprise bean logic; the only
remaining requirement is to map the entity bean's container-managed
fields to the PAO. Pushdown methods on the PAO cannot be utilized from
the enterprise bean. (PAO pushdown methods can be used from an entity
bean with CMP generated by using the PAOToEJB tool as described in Creating an enterprise bean from an existing CICS or IMS application.)
- The cbejb tool must be run as follows, where the
ejb-jarFile is the EJB JAR file containing the entity bean:
# cbejb ejb-jarFile [-hod | -eci | -appc
[beanNames]]
For a description of the cbejb tool's syntax, see Manually deploying an enterprise bean.
If you have met the prerequisites, use Object Builder to create the mapping
between the entity bean and the CICS or IMS application:
- When Object Builder starts, it presents the Open Project dialog.
Choose the location of the project directory for your enterprise bean and
click Finish.
- From the main menu, click Platform and then
Target. Uncheck the 390 platform.
- Click User-Defined PA Schemas and right-click the
selection.
- 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.
- Select the appropriate connector type and click Next.
- Select the primary key attribute name from the Properties
list.
- Click >> to move the primary key to the Key
Attributes list and click Finish.
- For HOD and ECI only, do the following for both the MO and the
HomeMO:
- 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.
- Change the Service to use property from Transaction
Service to Session Service.
- Create a DO implementation as follows:
- On the Tasks and Object panel, expand the User-Defined
DOs, expand the DO File from the menu, and click the DO
Interface.
- On the DO Interface pop-up menu, select Add
Implementation.
- 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.
- Click Next on the Implementation Inheritance page,
the Attributes page, the Methods page, and the Key
and Copy Helper page.
- On the Associated Persistent Object page, click Add
Another, verify that the PO that you previously created is selected, and
click Next.
- 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.
- 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.
- 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.
- 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.
- 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.
- Select Caching for Business Object.
- Select Delegating for Data Object.
- Click Finish.
- 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:
- 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.
- Create the database and database tables. For more information, see Creating the database and database table.
- Compile the code generated in phase 1; compilation fails if the database and database tables
do not exist.
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.
Follow these instructions to create a database and database table by using
the Object Builder GUI:
- When Object Builder starts, it presents the Open Project dialog.
Choose the location of the project directory for your enterprise bean and
click Finish.
- Create a DO implementation as follows:
- Expand the User-Defined DOs, expand the DO File from
the menu, and click the DO Interface.
- 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.
- On the Name and Platform page, select the platform and click
Next.
- 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.
- 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
- Accept the defaults for the Attributes, Methods, and
Key and Copy Helper pages by clicking Next on each
page.
- On the Associated Persistent Objects page, click Add
Another. Accept the default for the instance name (iPO) and
select the correct type. Click Next.
- 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.
- 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.
- Exit from Object Builder by clicking File->Exit; save any
changes if prompted.
- 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
After both the database and database table are created, compile the
enterprise bean code by using the following commands:
Follow these steps to install an enterprise bean and configure the resulting
EJB server (CB):
- (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).
- 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:
- Load the application into a host image.
- Add the application to a configuration.
- Associate the EJB application with a server group or server. (If
the server group or server does not already exist, you must create it.)
- (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.
- Configure the EJB server (CB) with a host.
- Set the ORB request timeout for both clients and servers to 300
seconds.
- 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.
- Activate the EJB server configuration.
- Start the EJB server.
- 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:
- The JNDI name can be bound into the local root. Under this binding
approach, EJB clients use the JNDI name in the enterprise bean's
deployment descriptor. The approach restricts the visibility of the EJB
home to EJB clients using the same name server (the same bootstrap host) and
can cause collisions with other names in the tree.
- The JNDI name can be bound into the host name tree (at
host/resources/factories/EJBHomes). Under this binding approach, EJB
clients must prefix the string host/resources/factories/EJBHomes to
the JNDI name given in the bean's deployment descriptor. This
approach minimizes collisions with other names in the tree, but restricts
visibility of the enterprise bean home to clients using the same name
server.
- The JNDI name can be bound into the workgroup name tree (at
workgroup/resources/factories/EJBHomes). Under this binding approach,
EJB clients must prefix the string
workgroup/resources/factories/EJBHomes to the JNDI name given in
the enterprise bean's deployment descriptor, and the EJB home is visible
to all EJB clients using a name server that belongs to the same preferred
workgroup.
- The JNDI name can be bound into the cell name tree (at
cell/resources/factories/EJBHomes). Under this binding approach, EJB
clients must prefix cell/resources/factories/EJBHomes to the JNDI
name in the bean's deployment descriptor, and the EJB home is visible
throughout the cell.
Before running the ejbbind tool, do the following:
- Deploy your enterprise bean for Component Broker by using the
cbejb tool. For more information, see Manually deploying an enterprise bean.
- Install the Component Broker application that cbejb tool
generates, and configure it on a specific EJB server (CB) by using the SM
EUI. For more information, see Installing an enterprise bean and configuring its EJB server (CB).
- Start the CBConnector Service and a name server, if they are not already
running. For more information, see the Component Broker System Administration Guide.
- Activate the configuration containing the EJB server (CB) that runs the
application.
- Determine the IP address (the bootstrap host name) and port number (the
bootstrap port) of the machine running the name server.
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:
- -f -- Force the bind, even if the JNDI name is already bound in the
namespace; this option is not valid with the unbind command
options.
- -BindLocalRoot -- Bind the JNDI name into the local root's name
tree.
- -BindHost -- Bind the JNDI name into the host name tree.
- -BindWorkgroup -- Bind the JNDI name into the workgroup name
tree.
- -BindCell -- Bind the JNDI name into the cell name tree.
- -BindAllTrees -- Bind the JNDI name into the host, the workgroup, and
the cell name trees.
- -ORBInitialHost hostName -- Identify the bootstrap host (the
default is the local host).
- -ORBInitiallPort portNumber -- Identify the bootstrap port
(the default is port 900).
- -u -- Unbind the JNDI name; this option is not valid with bind
command options.
- -UnbindLocalRoot -- Unbind the JNDI name from the local root's
name tree.
- -UnbindHost -- Unbind the JNDI name from the host name tree.
- -UnbindWorkgroup -- Unbind the JNDI name from the workgroup name
tree.
- -UnbindCell -- Unbind the JNDI name from the cell name tree.
- -UnbindAllTrees -- Unbind the JNDI name from the host, the workgroup,
and the cell name trees.
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:
- You modify the JNDI name of an enterprise bean. You can modify the
JNDI name by using the jetace tool. For more information,
see Creating an EJB module.
- You reconfigure Component Broker. In this case, you must rebind
every enterprise bean served by this configuration.
- You move the enterprise bean to a different EJB server (CB) or a different
machine.
To enable lazy enumeration (see Creating finder logic in the EJB server (CB)), follow these steps:
- From the System Management End User Interface (SM EUI), go to the View
menu, and set the View Level to Control.
- Expand Host Images
- Expand the name of your host.
- Expand Server Images.
- Expand the name of your server.
- Expand Container Images.
- Right-click iIteratorSysObjsNoPRef. From the pop-up
menu, select Properties. Change the following
properties:
- Change the Default transaction policy to
throwException.
- Change the Memory management policy to passivate at end of
transaction.
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.
- 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.
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:
- com.ibm.ejb.cb.runtime.CBCtxFactoryHostDefault
- com.ibm.ejb.cb.runtime.CBCtxFactoryHostWidenedDefault
- com.ibm.ejb.cb.runtime.CBCtxFactoryHostServerDefault
- com.ibm.ejb.cb.runtime.CBCtxFactoryHostServerWidenedDefault
- com.ibm.ejb.cb.runtime.CBCtxFactoryWorkGroupDefault
- com.ibm.ejb.cb.runtime.CBCtxFactoryWorkGroupWidenedDefault
- com.ibm.ejb.cb.runtime.CBCtxFactoryWorkGroupServerDefault
- com.ibm.ejb.cb.runtime.CBCtxFactoryWorkGroupServerWidenedDefault
- com.ibm.ejb.cb.runtime.CBCtxFactoryCellDefault
- com.ibm.ejb.cb.runtime.CBCtxFactoryCellServerDefault
- com.ibm.ejb.cb.runtime.CBCtxFactoryCellServerWidenedDefault
resolve EJB home lookup operations with the corresponding factory
finders:
- host/resources/factory-finders/host-scope
- host/resources/factory-finders/host-scope-widened
- host/resources/factory-finders/server-server-scope
- host/resources/factory-finders/server-server-scope-widened
- workgroup/resources/factory-finders/workgroup-scope
- workgroup/resources/factory-finders/workgroup-scope-widened
- workgroup/resources/factory-finders/server-server-scope
- workgroup/resources/factory-finders/server-server-scope-widened
- cell/resources/factory-finders/host-scope
- cell/resources/factory-finders/server-server-scope
- 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.
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:
- host/applications/initial-contexts
- workgroup/applications/initial-contexts
- cell/applications/initial-contexts
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
- host/applications/initial-contexts
- workgroup/applications/initial-contexts
- cell/applications/initial-contexts
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:
- -u--This flag is used to perform an unbind operation. An
unbind operation unbinds the context specified with the -name option and the
-sc option, if specified. If the -sc option is specified, only the
subcontexts corresponding to the JNDI home names in the JAR's deployment
descriptors are removed. If the -sc option is not used, the context
specified by the -name option and all of its subcontexts are unbound.
To help keep the name tree manageable, once a context or subcontext is
unbound, parent contexts are recursively unbound up to the context name stem
(see the -name option above) or until a non-empty parent is
encountered.
- -sc--This option is used to specify subcontexts, where file
jarFileName is the name of an EJB JAR file that contains deployment
descriptors with EJB home names. Each of the EJB home names, not
including the leaf-name component, is treated as a subcontext name. For
example, if the name for a home is com/mycom/myapp/MyHome, the subcontext name
is com/mycom/myapp.
When binding, the subcontext names are created under the
application-specific context specified by the -name flag. When
unbinding, the contexts which are unbound are restricted to the subcontext
names identified by the JAR file. Whether binding or unbinding, other
subcontexts are not affected.
- -host, -workgroup, -cell--These flags control the scope of the
application context being bound or unbound. Each scope has a
corresponding context name stem, as described in the -name flag section
above. The -host, -workgroup, and -cell flags specify a scope of host,
workgroup, or cell, respectively, for the context. The default scope is
host scope. Only one scope can be specified per bind or unbind
operation.
- -factoryfinder--This option is used to specify which factory finder
to associate with the application-specific context being bound, where
factoryFinderPath is the name of the factory finder. The
default factory finder is
host/resources/factory-finders/host-scope-widened.
This option does not apply to unbind operations.
- -genctxfactory--Typically, when an application-specific context is
bound, it is desirable to have an initial context factory for the
application-specific context. This option directs the
appbind tool to create a Java source file for an initial context
factory, where factoryClassName is the fully-qualified class name of
the context factory. All package prefix subdirectories are created, if
necessary. If the source file already exists, it is replaced.
The file and its containing subdirectories are created relative to the
directory specified with the -o option or, by default, relative to the current
directory.
This option does not apply to unbind operations.
- -o--This option is used to specify the target directory for the
initial context factory file (see the -genctxfactory option), where
targetDir is the directory path (not including package prefix
directories). The default target directory is the current
directory.
This option does not apply to unbind operations.
If the -o option is used, use of the -genctxfactory flag is
required.
- -boothost--This option is used to override the default host and port
used for ORB initialization, where bootstrapHostUrl is the URL of
the bootstrap host. The bootstrap host URL has the form
iiop:// hostName [: portNumber]
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:
- Change to the directory where your PAO class file exists.
- Add the PAO class file's directory, or the JAR file containing the
class, to your CLASSPATH environment variable.
- 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:
- -hod --This indicates that the PAO class is for Host On-Demand
(HOD). HOD is a browser-based 3270 telnet connection.
- -eci --This indicates that the PAO class is for External Call
Interface (ECI). ECI is a proprietary protocol that provides a remote
procedure call (RPC)-like interface into CICS.
- -appc --This indicates that the PAO class is for advanced
program-to-program communications (APPC), which is the System Network
Architecture (SNA) for LU 6.2 communications.
- 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.
- 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.
- Compile the Java source files of the newly created enterprise bean:
javac ejbName*.java
- 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.
- Deploy the EJB JAR file by using the cbejb tool as described in
Manually deploying an enterprise bean.
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:
- Create a Java properties file that contains these
items:
- 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:
- The Java source files (and the corresponding compiled class files) that
compose the enterprise bean in the subdirectory corresponding to the package
name.
- A JAR file containing the Java source files and compiled files that
compose the enterprise bean.
- An XML file containing the enterprise bean's deployment
descriptor.
- Run the jetace tool as follows to generate an EJB JAR file for
the enterprise bean:
# jetace -f beanName.xml
- 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.
The following restrictions apply when developing enterprise beans for the EJB
server (CB) environment: