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.The TopLink descriptor can also be modified through a Session amendment class because the TopLink descriptors are available through the session. 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 value for the <project-class> element is the fully-qualified Project class name. 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.

The following example illustrates how TopLink projects can be specified in code.

/**
* The class EmployeeProject is an example of a TopLink project defined in Java
code. The individual parts of the project - the Login and the descriptors, are
built inside of methods that are called by the constructor. Note that
EmployeeProject extends the class oracle.toplink.sessions.Project.
*/

public class EmployeeProject extends oracle.toplink.sessions.Project {
   /**
   * Supply a zero argument constructor that initializes all aspects of the
   project. Make sure that the login and all the descriptors are initialized and
   added to the project.
   */
   public EmployeeProject() {
      applyPROJECT();
      applyLOGIN();
      buildAddressDescriptor();
      buildEmployeeDescriptor();
      // other methods to build all descriptors for the project

      /**
      * Project-level properties, such as the name of the project, should be specified here.
      */
      protected void applyPROJECT() {
         setName("Employee");
      }

      protected void applyLOGIN() {      
         oracle.toplink.sessions.DatabaseLogin login = new oracle.toplink.sessions.DatabaseLogin();
         
         // use platform appropriate for underlying database
         login.setPlatformClassName("oracle.toplink.internal.databaseaccess.OraclePlatform");
         
         // if no sequencing is used, setLogin() will suffice
         setLoginAndApplySequenceProperties(login);
      }
      
      /**
      * Descriptors are built by defining table info, setting properties (caching,
      etc.) and by adding mappings to the descriptor.
      */
      protected void buildEmployeeDescriptor() {
         oracle.toplink.publicinterface.Descriptor descriptor = new oracle.toplink.publicinterface.Descriptor();
         
         // SECTION: DESCRIPTOR
         // specify the class to be made persistent
         descriptor.setJavaClass(examples.ejb.cmp11.advanced.EmployeeBean.class);
         
         // specify the tables to be used and primary key
         Vector tables = new Vector();
         tables.addElement("EJB_EMPLOYEE");
         descriptor.setTableNames(tables);
         descriptor.addPrimaryKeyFieldName("EJB_EMPLOYEE.EMP_ID");
         
         // SECTION: PROPERTIES
         descriptor.setIdentityMapClass(oracle.toplink.internal.identitymaps. FullIdentityMap.class);
         descriptor.setExistenceChecking("Check cache");
         descriptor.setIdentityMapSize(100);
         
         // SECTION: COPY POLICY
         descriptor.createCopyPolicy("constructor");
         
         // SECTION: INSTANTIATION POLICY
         descriptor.createInstantiationPolicy("constructor");
         
         // SECTION: DIRECTTOFIELDMAPPING
         oracle.toplink.mappings.DirectToFieldMapping firstNameMapping = new
            oracle.toplink.mappings .DirectToFieldMapping();
         firstNameMapping.setAttributeName("firstName");
         firstNameMapping.setIsReadOnly(false);
         firstNameMapping.setFieldName("EJB_EMPLOYEE.F_NAME");
         descriptor.addMapping(firstNameMapping);
         
         // ... Additional mappings are added to the descriptor using the addMapping() method.
      } // end buildEmployeeDescriptor
   } // end EmployeeProject
} // end EmployeeProject class

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.

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

• You want to define custom finder queries on one or more TopLink descriptors.

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

You can register a session listener class that extends oracle.toplink.sessions.SessionEventAdaptor to listen for various session events, such as pre_login, post_commit_unit_of_work, and so on. The listener is registered to the TopLink session by defining the <event_listener_class> tag in the toplink-ejb-jar.xml file. For example:

<session>
   <event_listener_class>
      oracle.toplink.ejb.cmp.demos.sessionlistener
   </event_listener_class>
</session>