3
Working with Enterprise JavaBeans

Enterprise JavaBeans (EJB) is a component architecture for creating scalable, multi-tier, distributed applications. EJB makes it possible to create dynamically-extensible applications.

This chapter describes TopLink features that provide support for Enterprise JavaBeans. It discusses

In summary, TopLink can be used in conjunction with session beans and bean-managed persistence entity beans designed in accordance with versions 1.0, 1.1, or 2.0 of the Enterprise JavaBean specification.

Container-managed persistence (CMP) for entity beans is provided by specialized products such as TopLink CMP for BEA WebLogic Server and TopLink CMP for IBM WebSphere Server. For information on additional support for other EJB servers, please contact Oracle Support.

The EJB specification

Enterprise JavaBeans (EJBs) represent a standard in enterprise computing developed by Sun Microsystems and its partners. EJB provides a component-based architecture for developing and deploying distributed object-oriented applications in Java. It is important to note the EJB is not itself a product. Enterprise JavaBeans is a specification that describes a framework for developers to use to create distributed business applications and for vendors to use to design application servers. Sun Microsystems has partnered with industry to specify the EJB framework and many vendors have responded with widespread support for EJB.

Additional information

The EJB home page can be found at www.java.sun.com/products/ejb.

The specification in PDF format is available at www.javasoft.com/products/ejb/docs.html.

Additional information about EJB can also be found at www.javasoft.com/products/ejb/white_paper.html.

Using the session bean model

Session beans are intended to model a process, operation, or service and as such are not themselves persistent. To perform the service they model, session beans can use persistence mechanisms. Under the session bean model, a client application invokes methods on a session bean that in turn performs operations on TopLink-enabled Java objects. All TopLink-related operations are carried out on behalf of the client by the session beans.

Figure 3-1 Basic view of TopLink Session bean architecture

Text description of tlsessbn.gif follows.

Text description of the illustration tlsessbn.gif

The EJB specification describes session beans as either stateless or stateful.

Stateful beans maintain a "conversational" state with a client; that is, they retain information between method calls issued by a particular client. Manipulation of persistent objects can occur across multiple method calls. In between those invocations, the EJB Server may decide to passivate (or serialize) the session bean out of the Java VM's memory-space to satisfy some run-time characteristic: performance, memory-footprint, maximum number of beans, and so on. Later, the bean can be activated (un-serialized) and brought back into memory.
Stateless beans, on the other hand, retain no data between method calls. For stateless session beans, any manipulation of persistent objects must be fully completed within a single method-call.

For more information about Session Beans, activation and passivation, please consult the EJB specification.

Session beans and DatabaseSessions

Both stateful session beans and stateless session beans can be used with a TopLink DatabaseSession. However, the way in which TopLink DatabaseSessions are handled may be different depending on which type of bean is used.

For stateless beans, no information is stored between method calls from the client, so the bean's connection to the DatabaseSession must be re-established for each client method call. Each method call that would require use of TopLink would consist of first obtaining a DatabaseSession, making the appropriate calls, and then releasing the reference to the DatabaseSession.

For stateful beans, the DatabaseSession could be considered a part of the conversational state associated with the bean, and could be retained between calls. However, DatabaseSession instances are not fully serializable and will not survive passivation. If the DatabaseSession is to be maintained between method calls, it must be released during the passivation process and re-obtained during the activation process.

There are a variety of strategies available for managing session bean access to DatabaseSessions. One option available is to make use of the SessionManager class which is described in the following sections.

Interactions with JTS

Many EJB Servers provide a Java Transaction Service (JTS) compliant JDBC driver for use with EJBs. TopLink now has the ability to use such a JTS service. The DatabaseLogin must be configured correctly in order to support JTS and session beans.

Please see Chapter 2, "Developing Enterprise Applications" for more information on how to configure TopLink sessions for JTS.

Example 3-1 Configuring DatabaseLogin for interoperability with JTS and EJB

DatabaseLogin login = null;
project = null;

//note that useExternalConnectionPooling and useExternalTransactionController 
must be set before Session is created
project = new SomeProject();
login = project.getLogin();
login.useExternalConnectionPooling(); 
login.useExternalTransactionController();

// usually, other login configuration such as user, password, JDBC URL comes 
from the project but these can also be set here
session = new Session(project);

// other session configuration, as necessary: logging, ETC
session.SetExternalTransactionController(new 
SomeJTSExternalTransactionController());
session.login();

Using session beans with TopLink's three-tier application model

There are several ways to design and implement session beans that make use of TopLink. Here we describe one possible model that uses TopLink's three-tier feature to allow efficient use of database connections. Please refer to Chapter 2, "Developing Enterprise Applications" for a general overview of the TopLink client and server session.

Essentially, the three-tier model can be used to create a ServerSession that is to be shared among the various session beans. When the session bean needs to access a TopLink Session, the bean obtains a ClientSession from the shared ServerSession. Using the TopLink three-tier feature provides several benefits:

Reduction of overhead: TopLink project, descriptor, and login information is shared amongst beans
Future compatibility with other servers: all login information is isolated from the beans, which contain no EJB Server-specific information
Shared read cache: efficiency is increased by using a shared cache for reading objects

Using the Session Manager

The TopLink Session Manager is a static utility class that provides developers with any easy way to build a series of sessions that are maintained under a single entity. Use the Session Manager to ensure that a ServerSession is always available for any session bean.

The SessionManager class, oracle.toplink.tools.sessionmanagement. SessionManager, is contained in the tl_tools.jar and can be used to create and manage TopLink sessions defined in an external XML file.

The SessionManager supports the following session types:

ServerSession (for more information, see "Client and server sessions" )
DatabaseSession (for more information, see "Understanding Database sessions" )
SessionBroker (for more information, see "Session broker"

The Session Manager has two main functions: to create instances of these classes, and to ensure that only a single instance of a session with a particular name is returned to the application for any single instance of a SessionManager.

TopLink offers a managed approach for the developer by providing static methods to make a single instance of the SessionManager available globally.

To use this method, instantiate a SessionManager as follows:

SessionManager.getManager().

Retrieving a session from a SessionManager

The following call is simplest way to retrieve a session from a session manager:

getSession(String sessionName)

Retrieving a session this way uses all defaults. If no session exists within the current instance of SessionManager, the Session Manager attempts to load a session from an XML file called sessions.xml. This file, which must be on the root of the class path, contains all of the configuration information for the named session. This allows developers to update the configuration of a session without modifying application code.

Note:

While this is the simplest way to retrieve a session, it is not the only way. A session can also be loaded by specifying an XMLLoader to use, the name of the session, the class loader and some flags as defined in the Java Docs. Refer to the Java Docs for specifics on the API that supports this type of custom call.

Using the default configuration file: sessions.xml

By default, SessionManager attempts to create a new session using the specifications contained in a file called sessions.xml. This file can define one or more session configurations by name that the SessionManager makes available at runtime. This XML file has a DTD provided that can be found in the installation at <INSTALL_DIR>\TopLink\core\sessions_4_5.dtd. The DTD is also documented in Appendix A, "Sessions.xml DTD".

The following is an example sessions.xml file. Although it does not show all of the configuration options available it does highlight the most common ones.

<?xml version = "1.0" encoding = "US-ASCII"?>
<!DOCTYPE toplink-configuration PUBLIC "-//Oracle Corp.//DTD TopLink for 
JAVA//EN" >
<toplink-configuration>

   <session>

      <name>default</name>
      <project-class>MyProject</project-class>
      <session-type><server-session/></session-type>
      <connection-pool>

         <is-read-connection-pool>false</is-read-connection-pool>
         <name>BopPool</name>
         <login>
         <user-name>user</user-name>
         <password>password</password>
         </login>

      </connection-pool>
      <enable-logging>true</enable-logging>
      <logging-options>

         <log-debug>true</log-debug>
         <log-exceptions>true</log-exceptions>
         <log-exception-stacktrace>true</log-exception-stacktrace>
         <print-thread>true</print-thread>
         <print-session>true</print-session>
         <print-connection>true</print-connection>
         <print-date>true</print-date>

      </logging-options>

   </session>

</toplink-configuration>

Note that the DOC_TYPE indicator is a specific reference to the DTD packaged in the core tl_core.jar. If this entry is not exactly as listed the DTD may not be found.

Using the XMLLoader

The XMLLoader is a mechanism that offers two important features:

It enables a developer to specify a custom session configuration to be loaded rather than the standard default configuration.
It enables a developer to control whether or not the session configuration file is re-read when successive sessions are created.

The XMLLoader also enables different sessions, and even different class loaders, to be loaded from different configuration files.

Specifying a custom session configuration file

Developers can store customized session configuration information in XML files other than sessions.xml. XMLLoader enables the developer to specify this custom configuration file rather than the default sessions.xml file. For example:

XMLLoader loader = new XMLLoader("MySession.xml");

This code creates a new XMLLoader that loads the session configuration from the specified, MySession.xml. Note that the file must exist before the getSession(...) call is invoked on the SessionManager. By default, the XML file is opened using a ClassLoader's ability to lookup resources as streams. The ClassLoader used for this is the one returned from the default ConversionManager.

Reusing the XML file

If the XMLLoader instance is maintained, the configuration file is read the first time the get session () call is made but is not reparsed with each subsequent get session () call. If either a different XMLLoader is used to call a session or the API to refresh the configuration file is invoked, the configuration file is be re-parsed, but sessions already in the SessionManager do not change.

Loading Session Broker

Using the XMLLoader method to load SessionBroker enables several different sessions from different files to be combined under a single SessionBroker. The developer can make repeated calls to getSession(XMLLoader, String sessionBrokerName, Class anyObjectClass), passing in a different XMLLoader for each file required for the session broker. When all required sessions are loaded in this manner, a completed SessionBroker is returned.

Note:

If the developer attempts to load a SessionBroker without all required sessions loaded in to the SessionManager, null is returned.

Example 3-2 Retrieving a named ServerSession

SessionManager.getManager().getSession( "employeeSession"); !

Example 3-3 A complex call using XMLLoader

XMLLoader loader = new XMLLoader("Sessions.xml");
SessionManager.getManager().getSession(loader, "SessionName", SessionBeanClass);

Using the entity bean model

Entity beans represent a "business entity." Entity beans may be shared by many users and are long-lived, able to survive a server failure. Essentially, entity beans are persistent data objects - objects with durable state that exist from one moment in time to the next.

TopLink provides a extensive framework for providing developers with Bean Managed Persistence enabled beans. Within the enterprise package TopLink provides a class oracle.toplink.ejb.bmp.BMPEntityBase. This class provides developers with a starting point when developing beans. The BMPEntityBase class provides implementation for all EJB spec required methods except ejbPassivate(). ejbPassivate() is excluded because of special requirements. By sub classing the BMPEntityBase, developers have a TopLink enabled entity bean.

To use the BMPEntityBase, developers must create the sessions.xml file as explained in "Using the Session Manager" . The second requirement is to add a oracle.toplink.ejb.bmp.BMPWrapperPolicy to each descriptor that represents an EntityBean. This BMPWrapperPolicy provides TopLink with the information to create Remote objects for entity beans and to extract the data out of a Remote object. After this is done, the user must create the home and remote interfaces, create deployment descriptors, and deploy the beans.

If a more customized approach is required, TopLink provides a hook into its functionality through the oracle.toplink.ejb.bmp.BMPDataStore class. With this class it is possible to easily translate EJB required functionality into simple calls. The BMPDataStore provides implementations of load, store, multiple finders and remove functionality. When using the BMPDataStore, a sessions.xml file is required for use with the SessionManager. A single instance of BMPDataStore should exist for each bean type that is deployed within a session. When creating a BMPDataStore, pass in the session name of the session that the BMPDataStore should use to persist the beans and the class of the Bean type being persisted. Store the BMPDataStore in a global location so that each instance of a Bean type uses the correct Store.

If using a customized implementation, the full functionality of the ServerSession and the UnitOfWork is available to developers.

TopLink and container-managed persistent entity beans

Because entity beans represent persistent data, bean developers must have some mechanism for making their beans persistent. In most cases this means mapping beans to a relational database. The EJB specification describes a type of entity bean -- container-managed persistent entity bean. For this type of bean, the designer does not have to include calls to any particular persistence mechanism in the bean itself. The EJB Server and its tools use meta-information in the deployment descriptor to describe how the bean is to be persisted to a database. This is commonly referred to as automatic persistence.

Also available from Oracle are:

TopLink CMP for BEA WebLogic Server, a separate product based upon TopLink for Java, that provides container-managed persistent entity beans for the BEA WebLogic Server.
TopLink CMP for IBM WebSphere Application Server, a separate product based upon TopLink for Java, that provides container-managed persistent entity beans for the IBM WebSphere server.

Please contact Oracle for more information concerning our support of EJB and the use of TopLink for container-managed persistent entity beans.

3Working with Enterprise JavaBeans