4
EJB Entity Bean Deployment

TopLink Container-Managed Persistence provides container-managed persistence (CMP) for 1.1 and 2.0 Enterprise JavaBeans (EJBs). The deployment process generates CMP code that allows TopLink to handle persistence aspects of EJBs. To install entity beans within the BEA WebLogic Server and make them available for client applications, entity beans must be deployed within the server.

Overview of deployment

The goal of deployment is to make entity beans available to client applications.The process of deploying entity beans requires the use of several BEA WebLogic tools, the creation or editing of deployment descriptors and properties files, and ultimately running the BEA WebLogic Server to deploy the entity beans. For much of this process, BEA WebLogic tools and programs must be used. Consult your BEA WebLogic Server documentation for the most up-to-date information on these topics.

Understanding Deployment

The term "deployment" can sometimes cause confusion since there are actually a number of stages that occur between creating the bean classes and installing them in a running server.

Generally speaking the deployment process is three distinct steps:

1. Configuration - A number of properties are specified for the bean, including what persistence mechanism is being used and additional information required by the persistence mechanism.

2. Code generation - The information provided in the configuration stage is used by both BEA WebLogic and TopLink tools to generate the classes required for the bean. This includes helper classes related to transactions, persistence, and security, the EJBLocalHome, EJBLocalObject, EJBHome, and EJBObject implementations, and the stubs and skeletons required for RMI.

3. Installation - The server is started and instructed to make the bean available to clients.

Requirements before deployment

The following tasks must be completed prior to the deployment of TopLink persisted entity beans:

• Write and compile the various parts of each entity bean to be deployed, including the bean class, any required local and remote interfaces, home and local home interfaces, and the primary key class (if required).

• Map the entity beans to the appropriate database tables, and save the mapping information in a TopLink project class or project file (deployable XML file).

Steps in the deployment process

After the beans have been created and the mappings have been defined, the three deployment steps must be followed:

1. Configure the beans. Ensure that the XML deployment descriptors have all of the information that BEA WebLogic and TopLink require.

2. Generate the required run-time classes. Classes are generated using the weblogic.ejbc utility.

   Note: Generating the required run-time classes is optional when you are using WebLogic Server 6.1 (service Pack 3) or 7.0; if you deploy any uncompiled JAR files using WebLogic Server 6.1 (service Pack 3) or 7.0, the server runs ejbc for you automatically. Consult your WebLogic documentation for details.

3. Install the beans in the server.

This chapter describes setting up deployment descriptors, generating the run-time classes, and deploying your entity beans in the BEA WebLogic Server.

Configuring entity bean deployment descriptors

A TopLink project represents a single deployment unit. In other words, all related beans (beans that reference each other) and dependent objects within a given TopLink project must be deployed within a single EJB JAR.

There are three XML files to configure for every EJB JAR file that is to be deployed. These files can be created and edited using a text editor, or some other tool. These files must be properly specified to use container-managed persistence:

ejb-jar.xml

Contains standard EJB deployment properties

weblogic-ejb-jar.xml

Contains BEA WebLogic -specific properties

toplink-ejb-jar.xml

Contains TopLink-specific properties

Related beans share the same ejb-jar.xml, weblogic-ejb-jar.xml, and toplink-ejb-jar.xml files.

Configuring the ejb-jar.xml file

There is one ejb-jar.xml file for every JAR, although multiple beans may be specified in a single ejb-jar.xml file. The following information is stored in the ejb-jar.xml file:

persistence-type

Each entity specifies what type of persistence it is to use. To specify that an entity use container-managed persistence, the bean must have its <persistence-type> tag be set to Container.

Container managed fields

Each entity must list the bean fields which are to be persisted. The <cmp-field> tag is used for each field.

Finders

Finders are optional, and may be specified using the <query> tag and its subtags. An EJB-QL string is used to define the query. The finders found in the ejb-jar.xml file are read in by the Mapping Workbench. You can use the Mapping Workbench to further customize finders for your application.

Relationships

Bean-to-bean relationships are described under the <relationships> tag. Each relationship requires an <ejb-relation> tag and associated subtags. The Mapping Workbench uses these relationship descriptions as a starting point for defining the reference mappings between beans. Note that the Mapping Workbench can be used to define other relationships between beans or between beans and regular Java objects which are not described in the ejb-jar.xml file.

Updating the ejb-jar.xml file

The ejb-jar.xml may either be manually updated as you develop your application or modified by the Mapping Workbench after mapping the TopLink project. The ejb-jar.xml file and the Mapping Workbench project should be synchronized as follows:

• When manual changes are made directly in the ejb-jar.xml file, refresh the Mapping Workbench project by re-importing the ejb-jar.xml file into the project.

• When changes to the project are made in the Mapping Workbench, the ejb-jar.xml file is automatically updated when the project is saved.

For more information on managing the ejb-jar.xml file in the Mapping Workbench, see the Oracle9iAS TopLink Mapping Workbench Reference Guide.

Configuring the weblogic-ejb-jar.xml file

The weblogic-ejb-jar.xml file allows you to configure WebLogic-specific information for your beans.

Persistence descriptor

Within the weblogic-ejb-jar.xml file, each bean must have a <persistence-descriptor> entry with subentries indicating that TopLink is available and should be used.

• If you are deploying to WebLogic 6.1 (service Pack 3), there must be a <persistence-type> entry, which indicates that TopLink is available and a <persistence-use> entry that specifies that TopLink is to be used.

• If you are deploying to WebLogic 7.0, the entries under <persistence-use> includes both of the required pieces of information.

The persistence descriptor includes settings for specifying the EJB version supported by the bean. Set <type-identifier> to

• TopLink_CMP_2_0 to indicate support for EJB 2.0

• TopLink_CMP_1_1 to indicate support for EJB 1.1

The persistence descriptor also includes settings for specifying the WebLogic version supported by the bean. Set <type-version> to

• 4.5 to indicate support for WebLogic 7.0

• 4.0 to indicate support for WebLogic 6.1 (service Pack 3)

  Note: The deprecated <type-version> setting of version 3.5 will also function correctly with WebLogic 6.1 (service Pack 3) if used with EJB 1.1.

Persistence descriptors and WebLogic 6.1 (service Pack 3)

A typical persistence descriptor for WebLogic 6.1 (service Pack 3) is shown below:

<persistence>
   <persistence-type>
      <type-identifier>TopLink_CMP_2_0</type-identifier>
      <type-version>4.0</type-version>
      <type-storage>META-INF\toplink-ejb-jar.xml</type-storage>
   </persistence-type>
   <persistence-use>
      <type-identifier>TopLink_CMP_2_0</type-identifier>
      <type-version>4.0</type-version>
   </persistence-use>
</persistence>

There may be several entries for the persistence type, but exactly one persistence use entry must be specified for a given entity bean.

Persistence descriptors and WebLogic 7.0

A typical persistence descriptor for WebLogic 7.0 is shown below:

<persistence>
   <persistence-use>
      <type-identifier>TopLink_CMP_2_0</type-identifier>
      <type-version>4.5</type-version>
      <type-storage>META-INF\toplink-ejb-jar.xml</type-storage>
   </persistence-use>
</persistence>

It is very important that the <type-version> entry is consistent with the installed version of TopLink (TopLink_CMP_2_0 for 2.0 entity beans and TopLink_CMP_1_1 for 1.1 entity beans). The <type-version> must be correct in order to use BEA WebLogic tools, and to deploy the bean in the BEA WebLogic Server.

Within the persistence type, the <type-storage> should be set to META-INF\toplink-ejb-jar.xml. The toplink-ejb-jar.xml contains TopLink-specific information and is stored in the META-INF directory in the deployable JAR file.

Enabling Call by Reference

To allow TopLink to manage relationships between beans, call-by-reference must be enabled for all beans managed by TopLink. To enable call-by-reference for beans you must set the entry <enable-call-by-reference> to True in the weblogic-ejb-jar.xml file.

<weblogic-ejb-jar>
   <weblogic-enterprise-bean>
      <ejb-name>AccountBean</ejb-name>
      ...
      <enable-call-by-reference>True</enable-call-by-reference>
      ...
   </weblogic-enterprise-bean>
</weblogic-ejb-jar>

Unsupported tags in the weblogic-ejb-jar.xml file

There are a number of tags included in the weblogic-ejb-jar.xml that are either not supported or not required by TopLink, as follows:

concurrency-strategy

In BEA WebLogic Server 6.1 (service Pack 3) and 7.0, the weblogic-ejb-jar.xml includes a <concurrency-strategy> tag that does not apply to entity beans deployed with TopLink for WebLogic. TopLink supports concurrent access to entities through the use of several locking options, including no locking, optimistic database-level locking, and pessimistic database-level locking. For more information please refer to the TopLink documentation.

db-is-shared

TopLink does not require this tag because TopLink does not make any assumptions about the exclusivity of database access. Issues arising from multi-user access can be addressed through various locking and refreshing policies.

delay-updates-until-end-of-tx

TopLink always delays updates until the end of a transaction, and so does not require this tag. This optimization allows for minimal write calculations.

finders-load-bean

TopLink always loads the bean upon execution of the finder. This optimization eliminates excessive select calls during the ejbLoad sequence.

pool

TopLink for WebLogic does not use a pooling strategy for entity beans. This avoids object-identity problems that can occur due to pooling.

lifecycle

This element applies to beans that follow a pooling strategy. As TopLink does not use a pooling strategy, this tag is not required.

is-modified-method-name

TopLink does not require a bean developer-defined method to detect changes in object state. This is handled automatically.

isolation-level

Isolation level settings for the cache or database transactions can be specified in the TopLink project.

cache

TopLink caching properties are defined using the TopLink Mapping Workbench.

Configuring the toplink-ejb-jar.xml file

The toplink-ejb-jar.xml file is similar to the session.xml file used by non-CMP beans. The toplink-ejb-jar.xml file specifies all TopLink-related information. The DTD for this XML file is located in the tl_wlsx.jar file, and is documented in Appendix B, "The toplink-ejb-jar DTD".

<?xml version="1.0" ?>
<!DOCTYPE toplink-ejb-jar (View Source for full doctype...)>
<toplink-ejb-jar>
   <session>
      <name>ejb_AccountDemo</name>
      <project-xml>Account.xml</project-xml>
      <login>
         <datasource>jdbc/ejbJTSDataSource</datasource>
         <non-jts-datasource>jdbc/ejbNonJTSDataSource</non-jts-datasource>
      </login>
   </session>
</toplink-ejb-jar>

Defining required project options: the Session Section

The session section is used to define those settings that apply to an entire project, and must be included in the toplink-ejb-jar.xml file. The xml elements that are defined in the session section are as follows:

name

A string that provides a unique name for the project. No two projects deployed within the same server instance are permitted to have the same name.

project-class

The fully qualified name of the TopLink project class. The source code for this class may be created using the TopLink Mapping Workbench and included in the deployed JAR.

project-xml

The fully qualified name of the deployable TopLink project file. This file may be included in the deployed JAR or located on the CLASSPATH

Note: Use either project-xml or project-class but do not use both.

login

A section in which the following entries are provided:

• connection-pool A string identifying the JDBC pool that is to be used by TopLink. The name of the pool should correspond to a JDBC connection pool specified in the WebLogic administration console.

• datasource A string identifying the name of the data source to use for this project. datasource must be used in conjunction with non-jts-datasource. The combination is intended as an alternative to using a connection-pool.

  datasource is intended to map to a Jts data source, and non-jts-datasource is intended to map to a non-Jts data source.

  For more information about data sources, see your user documentation for BEA WebLogic Server.

• non-jts-datasource A string identifying the name of the read only data source to use for this project. non-jts-datasource must be used in conjunction with datasource. The combination is intended as an alternative to using a connection-pool. See "datasource" earlier for more information.

• should-bind-all-parameters (optional) A string value that indicates whether all queries should use parameter binding. Valid values are True or False. Default is False.

• uses-byte-array-binding (optional) A string value that indicates whether byte arrays should be bound. Valid values are True or False. Default is False.

• uses-string-binding (optional) A string value that indicates whether strings should be bound. Valid values are True or False. Default is False.

cache-synchronization (optional)

When provided, indicates that changes made to one TopLink cache in a cluster should be automatically propagated to all other server caches. The following elements may also be provided:

• is-asynchronous (optional) Set to True if synchronization should not wait until all sessions have been synchronized before returning. Valid values are True or False. Default is True.

• should-remove-connection-on-error (optional) Set to True if a synchronization connection should be removed from the session if a communication error occurs. Valid values are True or False. Default is True.

use-remote-relationships (optional)

TopLink goes beyond the EJB 2.0 specification and allows you to define relationships between beans in terms of their remote interfaces. This may be especially useful when porting EJB 1.1 applications to EJB 2.0. When this option is specified, all relationships in the JAR must be defined using remote interfaces. Valid values are True or False. Default is False.

Note: If you use remote relationships, you must run the weblogic.ejbc tool with the -nocompliance flag set.

customization-class (optional)

This fully qualified name of a DeploymentCustomization class is optional. For more information, see Chapter 7, "Customization".

Generating the run-time classes

After creating the deployment descriptors, generate the run-time classes from the deployment descriptors using of the ejbc tool.

Note: Generating the required run-time classes is optional when you are using WebLogic Server 6.1 (service Pack 3) and 7.0; if you deploy any uncompiled JAR files using WebLogic Server, the server runs ejbc for you automatically. Consult your WebLogic documentation for details.

Running the Weblogic EJB Compiler

When TopLink is used to provide container-managed persistence for BEA WebLogic entity beans, the standard BEA WebLogic EJB Compiler (ejbc) is used. For more information about this tool and its use, refer to the BEA WebLogic Server documentation.

There are two stages involved in running ejbc:

1. Create a "standard" EJB JAR file containing all bean classes and all required XML files (ejb-jar.xml, weblogic-ejb-jar.xml, toplink-ejb-jar.xml). The XML files should be placed in the META-INF directory within the JAR.

2. Run ejbc with the JAR file created in step one as command line arguments. ejbc creates an EJB JAR containing the original classes as well as all required generated classes and files.

Several things happen when ejbc is run:

• A partial EJB conformance check is performed on the beans and their associated interfaces

• A number of internal BEA WebLogic classes that manage security, transactions, and so on, are generated and compiled

• Concrete bean subclasses are generated by TopLink and compiled

• RMI stubs and skeletons are generated for client access of the beans

Running ejbc can take some time because of the number of the processes involved. If errors occur while running ejbc, attempt to determine which stage is causing the problem. Problems encountered running this tool may be related to one of the following areas:

• Errors or problems in the bean classes caused by non-conformance with the EJB specification

• Problems due to not having all required classes on the CLASSPATH, which should include all domain classes, all required TopLink classes, and all required BEA WebLogic classes

• A problem encountered when running the Java compiler (javac), potentially caused by using an incorrect version of the JDK

• A failure encountered when generating the RMI stubs and skeletons (a failure of rmic)

  Note: Use a command script (for example, a batch or ant script) to run ejbc. This enables you to pre-configure all of the required variables for the command line and helps to prevent typing errors. Sample build scripts are provided with the TopLink for BEA WebLogic example applications.

Installing the beans in the server

Installing entity beans that use TopLink for BEA WebLogic container-managed persistence follows the same steps as installing other EJBs in the BEA WebLogic Server. For information on installing entity beans, consult the BEA WebLogic documentation.

Connection pools and data sources

BEA WebLogic can provide TopLink with either a connection pool or a data source.

Creating JDBC connection pools

A BEA WebLogic JDBC connection pool must be defined for the entity beans that are to be deployed. Examples of how connection pools are defined and used can be found in your BEA WebLogic Server documentation.

Creating JTS and non-JTS data sources

To work with data sources, TopLink requires both a JTS and a non-JTS data source. When working with a connection pool, Toplink configures the connection automatically, and only needs a single connection pool to operate properly

Please consult the BEA WebLogic Server user documentation for more information about data sources.

Using the defined connection pool

The pool name is supplied to TopLink using the toplink-ejb-jar.xml file. The name is specified using the <connection-pool> tag (see "login").

Using the defined data source

Instead of connecting through a connection pool directly, it is possible to instruct TopLink to use a defined data source. If data sources are to be used, both JTS and non-JTS data sources must be used together.

The toplink-ejb-jar.xml file has data-source options in the form of the tags <datasource> and <non-jts-data-source>. These tags correspond to JTS and non-JTS data sources respectively.

The values for these data source tags correspond directly to the names of the data sources as defined in WebLogic Server. Following is an example of a partial toplink-ejb-jar.xml file listing using data sources:

...
<datasource>myJtsDataSource</datasource>
<non-jts-data-source>myNonJtsDataSource</non-jts-data-source>
...

Problems with deployment

Various configuration errors can cause problems with entity bean deployment. Be sure that you have followed the steps outlined in the relevant BEA WebLogic Server documentation.

Message Logging

The logging facilities are configured at the server level and affect all TopLink-enabled CMP entity beans deployed in that server. The granularity and destination of TopLink's logging can be configured by using two system properties. These properties can be set at the command line of the server start script.

toplink.log.level

Determines the granularity of log messages that TopLink will generate. Possible values include INFO (default), NONE and DEBUG. When set to DEBUG, TopLink trace statements will be generated. For example:

-Dtoplink.log.level=DEBUG

toplink.log.destination

Determines where TopLink log messages get logged. Possible values include SYSOUT (default), SERVER or the name of a file.

When set to SYSOUT log messages are sent to System.out.

When set to SERVER, logging is integrated with the WebLogic logging streams. If this mode is in effect then the WebLogic logging levels must be considered since logging may be filtered by the server log level settings.

When neither of the above is selected, the value is assumed to be the name of a file (relative or fully qualified). Consider these examples:

-Dtoplink.log.destination=SERVER

-Dtoplink.log.destination=c:\toplink.log

Hot deployment of EJBs

Hot deployment is a feature in BEA's WebLogic Server product that allows for the deployment of EJBs on a running server. It is useful for situations where rebooting the BEA WebLogic Server is not feasible.

The BEA WebLogic Server hot deployment feature allows:

• Newly-developed EJBs to be deployed to a running production system

• Deployed EJBs to be removed from a running server (undeployment)

• The behavior of deployed EJBs to be modified by updating the bean class definition (redeployment)

For detailed information on hot deployment, see the BEA WebLogic documentation.

Consider the following points when deploying a newly-created EJB JAR or redeploying an existing JAR:

• All related beans (all beans that share a common TopLink project) must be deployed within the same EJB JAR file. TopLink for BEA WebLogic views deployment on a project level. If one bean is to be deployed or updated, then all of the project's beans should be deployed or updated to maintain consistency across the project.

• When a bean is redeployed, its TopLink project is reset. This process flushes all object caches and rolls back any active object transactions that are associated with the project.

The client receives deployment exceptions when attempting to access bean instances that have been undeployed or re-deployed. The client side is responsible for catching and handling those exceptions.

Running an EJB Client

After the beans have been deployed, an EJB client can be run to access them. The client can either be a SessionBean or a Java program running outside the server.

The EJB client requires the following bean classes in its CLASSPATH: remote interface, home interface, and primary key classes for all the beans accessed. In addition, if the client is a session bean running on the same server as the entity beans and you want to access the local interfaces of the entity beans, you must also include their local and home interfaces on the CLASSPATH.

To lookup a bean's home interface a JNDI InitialContext must be setup. Setting up the initial context requires that the server's URL be supplied.