7
Customization

With container-managed persistence (CMP), many aspects of persistence are handled transparently by the EJB "container". Other properties may be configured, as required, in the bean deployment descriptors (see "Configuring entity bean deployment descriptors"). The intent is to minimize the amount of persistence code that the EJB developer has to write.

However, there are cases where a bean developer or deployer wants to take advantage of advanced features that require additional customization and configuration of bean deployment.

TopLink Container-Managed Persistence provides a number of entry points for advanced customization of mappings, logins, and other aspects of persistence. These can be used to take advantage of advanced TopLink features, JDBC driver features, or to gain "low-level" access to TopLink for Java APIs that are normally masked in the container-managed persistence layer.

Note: For basic information about TopLink descriptors and mappings, see the Oracle9iAS TopLink Mapping Workbench Reference Guide.

Customizing TopLink descriptors and mappings

TopLink projects and descriptors are normally created using the TopLink Mapping Workbench. The output of the TopLink Mapping Workbench tool is an XML file that contains all of the mapping information required to store beans and persistent objects in the database.

Some customizations available to the TopLink descriptors that make up the project cannot be configured using the Mapping Workbench. In these situations, customize the mapping information by specifying an amendment method to be run at deployment time.. Each TopLink descriptor can have an amendment method. For more information, see "Customizing TopLink descriptors with amendment methods".

Alternatively, the TopLink Mapping Workbench can be bypassed entirely, and create all the mappings directly in Java code. With this approach, any customizations can be made directly in the source code.

Creating projects and TopLink descriptors in Java

Creating mappings and TopLink descriptors directly in Java code provides access to features that are not available in TopLink Mapping Workbench.

To define a project using Java code:

1. Implement a project class that extends the oracle.toplink.sessions.Project class.

2. Compile the project class.

3. Edit the toplink-ejb-jar.xml deployment descriptor so that the <project-class> element is used. For more about creating project classes, see the Oracle9iAS TopLink Mapping Workbench Reference Guide.

   Note: The TopLink Mapping Workbench can be used to create a Java Project class from an existing project which can be used as a starting point for a custom project class. See the Oracle9iAS TopLink Mapping Workbench Reference Guide for more information. Also note that the TopLink Mapping Workbench has an Export Project to Java Source... option which can be used as starting point for coding the project class manually.

After the TopLink project is written and compiled, it can be used in deployment. You can specify the project class to be used instead of a project file by filling in the project-class element in the toplink-ejb-jar.xml deployment descriptors for your entity beans.

The next example shows the session portion of a deployment descriptor that specifies a session class.

<session>
   <name>EmployeeDemo</name>
   <project-class>oracle.toplink.demos.ejb.cmp.wls.employee.EmployeeProject
   </project-class>
   <login>
      <connection-pool>ejbPool</connection-pool>
   </login>
</session>

Customizing TopLink descriptors with amendment methods

The TopLink descriptor of any persistent class can be modified when the descriptor is first instantiated. For container-managed persistence, this happens when the entity beans are deployed into the EJB server.

Amendment methods are static methods that are run at deployment time and allow for arbitrary descriptor customization code to be run.

For more information on amendment methods, see the Oracle9iAS TopLink Mapping Workbench Reference Guide.

Working with TopLink ServerSession and Login

TopLink interacts with databases using two key components:

• The ServerSession is a TopLink component that interacts with the underlying database on behalf of the application.

• The DatabaseLogin contains connection information and settings that are specific to the underlying database.

Understanding ServerSession

In TopLink container-managed persistence support, the ServerSession is normally hidden from the EJB developer because interaction with the database is performed transparently by the EJB container (via TopLink). The ServerSession is still present "behind-the-scenes", but plays a lesser role in its direct interaction with the EJB application.

The ServerSession handles all aspects of persistence, such as caching, reading and writing.

Understanding DatabaseLogin

Databases typically require a valid username and password to login successfully. In a TopLink application, this login information is stored in the DatabaseLogin class. All sessions must have a valid DatabaseLogin instance before logging in to the database.

For more information on DatabaseLogin, see "Database Sessions" in the Oracle9iAS TopLink Foundation Library Guide.

Customizing ServerSession and DatabaseLogin

A session amendment class can be used to configure the ServerSession and DatabaseLogin in ways not available through the deployment descriptor file.

The ServerSession and DatabaseLogin may need to be customized for any of the following reasons:

• You need to specify special settings for the JDBC driver, such as to use parameter binding or to use a different data conversion routine to work with an incompatible driver

• You wish to directly access regular TopLink for Java features, such as database connections or caching

Other settings that can be applied to the ServerSession and DatabaseLogin are:

• Native SQL support -- required if your JDBC bridge does not support the JDBC standard SQL syntax

• Binding and parameterized SQL -- these options determine whether values are inlined directly into the generated SQL or are parameterized

• Batch writing -- allows groups of insert/update/delete statements to be sent to the database in a single batch

• Optimizing data conversion

Additional configuration changes

To make additional configuration changes, one must obtain access to the ServerSession or DatabaseLogin that exists on the server. This access enables direct method invocation on the session or login.

There are currently two supported methods of obtaining the session and login objects and configuring them:

• Use the Deployment Customization interface

• Use a BEA WebLogic Startup class

Using the DeploymentCustomization interface

A DeploymentCustomization class is one that implements the oracle.toplink.ejb.cmp.DeploymentCustomization interface. A class implementing this interface must be specified in the toplink-ejb-jar.xml bean deployment descriptor for the project. If a class is specified, an instance of the class is created during deployment, and the code provided by the class is run.

The DeploymentCustomization interface defines the following methods:

public String beforeLoginCustomization(Session session) throws Exception;
public String afterLoginCustomization(Session session) throws Exception;

These methods are invoked immediately before and after TopLink logs into the database for the first time (during bean deployment). This gives developers the chance to invoke methods on the ServerSession as required.

The DatabaseLogin can be obtained by invoking the getLogin() method on the Session that is passed in as a parameter to each method. The following example illustrates how the beforeLoginCustomization() method configures TopLink to use parameter binding:

public String beforeLoginCustomization(Session session)
throws Exception {
   session.getLogin().useBinding();
   return "beforeLogin customization successful";
}

The class implementing the DeploymentCustomization interface should have a zero argument constructor. The Strings returned from each of the methods are output to the BEA WebLogic Server console.

To supply a class to be used for this purpose, the fully-qualified name of the class must be supplied in the customization-class element of the toplink-ejb-jar.xml deployment descriptor.

The following example shows the project portion of the toplink-ejb-jar.xml deployment descriptor that specifies a customization class

<session>
   <name>EmployeeDemo</name>
   <project-class>
   oracle.toplink.demos.ejb.cmp.wls
   .employee.EmployeeProject.class
   </project-class>
   <login>
      <connection-pool>ejbPool</connection-pool>
   </login>
   <customization-class>
   oracle.toplink.demos.ejb.cmp.wls
   .employee.EmployeeCustomizer
   </customization-class>
</session>

Using a BEA WebLogic Startup class

When a project is deployed, the TopLink Session is placed in a static Hashtable keyed on the project identifier (the value of name in the toplink-ejb-jar.xml deployment descriptor).

This can be retrieved at startup-time by using a BEA WebLogic Startup class (an implementor of the interface weblogic.common.T3StartupDef) to:

• Call SessionManager.getManager().getSession(String) to look up the Session under the name supplied by the name parameter

• Invoke methods on the Session

For example:

import weblogic.common.*;
import oracle.toplink.threetier.ServerSession
import oracle.toplink.tools.sessionmanagement.SessionManager

public class BindingStartup implements T3StartupDef {
   // Define project identifier here
      static final String PROJECT_IDENTIFIER = "EmployeeDemo";
   public T3ServicesDef services;
   public BindingStartup() {}
   public String startup(String theName, Hashtable properties) {
      System.out.println(theName + " startup" );
      try{
         ServerSession session = SessionManager.getManager().getSession(PROJECT_IDENTIFIER);
         If (session == null) return name + " startup could not find project" + PROJECT_IDENTIFIER;
         session.getLogin().useBinding();
      } catch(Exception e) {
         return name + " startup failed: " + e.getMessage();
      }
      return name + " startup successful";
   }
   public void setServices(T3ServicesDef theServices) {
      services = theServices;
   }
}

For more information on BEA WebLogic Startup classes, see your BEA WebLogic Server documentation.