Session Types

Three-Tier Architecture Overview

In an OracleAS TopLink three-tier architecture, client sessions and server sessions both reside on the server. Client applications access the OracleAS TopLink application through a client session, and the client session communicates with the database using the server session.

Figure 4-6 Server Session and Client Session Usage

Description of the illustration cliserv.gif

EJBs and Server Session

The Enterprise JavaBean (EJB) container manages interaction with the database and OracleAS TopLink. The server session manages all aspects of persistence, such as caching, reading, and writing, but does so behind the scenes.

General Concepts for the OracleAS TopLink Three-Tier Design

Although the server session and the client session are two different session types, you can treat them as a single unit in most cases, because they are both required to provide three-tier functionality to the application. The server session provides the client session to client applications, and also supplies the bulk of the session functionality. This section discusses some of the advantages and general concepts associated with the OracleAS TopLink three-tier design.

Providing Read Access

To read objects from the database the client must first acquire a client session from the server session. Acquiring a client session gives the client access to the session cache and the database through the server session.

Example 4-33 Acquiring a Client Session

ClientSession myClientSession = myServerSession.acquireClientSession();

After the client acquires a client session, it can send read requests to the server. The server session responds to these requests as follows:

• If the object or data is in the session cache, then the server session returns the information back to the client.

• If the object or data is not in the cache, then the server session reads the information from the database and stores the object in the session cache. The objects are then available for retrieval from the cache.

Because a server session processes each client request in a separate thread, this enables multiple clients to access the database connection pool concurrently.

Figure 4-7 illustrates how multiple clients read from the database using the server session.

Figure 4-7 Multiple Client Sessions Reading the Database Using the Server Session

Description of the illustration mltiread.gif

To read objects from the database using a Client Session:

1. Start the application server.

2. Create a ServerSession object and call login().

3. Call acquireClientSession() to acquire a ClientSession from the ServerSession.

4. Execute read operations on the ClientSession object.

   
   

   Note: Do not use the ServerSession object directly to read objects from the database.

   
   

Providing Write Access

Because the client session disables all database modification methods, a client session cannot create, change, or delete objects directly. Instead, the client must obtain a Unit of Work from the client session to perform database modification methods.

To write to the database, the client acquires a client session from the server session and then acquires a UnitOfWork within that client session. The Unit of Work acts as an exclusive transactional object space, and ensures that any changes that are committed to the database also occur in the session cache.

Note: Although client sessions are thread-safe, do not use them to write across multiple threads. Multi-thread writes from the same client session can result in errors and a loss of data.

To write to the database using a Unit of Work:

1. Start the application server.

2. Create a ServerSession object and call login().

3. Call acquireClientSession() to acquire a ClientSession from the ServerSession.

4. Acquire a UnitOfWork object from the ClientSession object.

   For more information about the Unit of Work, see Chapter 7, "Transactions".

5. Perform the required updates, and then commit the UnitOfWork.

Figure 4-8 Writing with Client Sessions and Server Sessions

Description of the illustration uowwrite.gif

Reference

Table 4-10 and Table 4-11 summarize the most common public methods for ClientSession and ServerSession. For more information about the available methods for ClientSession and ServerSession, see the Oracle Application Server TopLink API Reference.

Customizing Server Session and Database Login

You can use a session amendment class to configure the server session and database login in ways not available through the deployment descriptor file. For example, you can:

• Specify special settings for the JDBC driver. For example, if you are working with an incompatible database driver, you can implement parameter binding, to enable a different data conversion routine.

• Access regular OracleAS TopLink features, such as database connections or caching, directly.

• Define custom finder queries on one or more OracleAS TopLink descriptors (under EJB 1.1).

• Enable native SQL support if your JDBC bridge does not support the JDBC standard SQL syntax.

• Enable binding and parameterized SQL, to specify whether values are inlined directly into the generated SQL or are parameterized.

• Enable batch writing, forcing the application to send groups of insert, update, and delete statements to the database in a single batch.

• Optimize data conversion.

Working with Login

Databases usually require a valid user name and password to log in successfully. OracleAS TopLink applications maintain this information in the DatabaseLogin class. All sessions must have a valid DatabaseLogin instance before logging in to the database.

For more information about the DatabaseLogin, see "Database Session".

Registering Event Listeners for EJB 1.1

To customize an EJB 1.1 application, register a session listener class that extends oracle.toplink.sessions.SessionEventAdaptor. Configure the listener to listen for various session events, such as pre_login and post_commit_unit_of_work. To register the OracleAS TopLink session, define the event_listener_class tag in the toplink-ejb-jar.xml file, as follows:

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

Enabling Direct Method Invocation for EJB 2.0

Under EJB 2.0, you can invoke the DeploymentCustomization interface, which implements the oracle.toplink.ejb.cmp.DeploymentCustomization interface. You must also specify any class that implements this interface in the toplink-ejb-jar.xml file. If you specify a class, then OracleAS TopLink instantiates the class during deployment and runs the code provided by the class.

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 OracleAS TopLink logs into the database for the first time (during bean deployment).

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

<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>

Creating a Database Session

An application opens a database session by creating an instance of the DatabaseSession class, and initializing the project with the appropriate database login parameters. After initialization, the session:

• Registers the OracleAS TopLink descriptors (see "Registering Descriptors")

• Connects to the database

• Establishes the session cache

Connecting to the Database

After you register the descriptors, use the DatabaseSession class to connect to the database, using the login() method. If the log in parameters in the DatabaseLogin class are incorrect, or if the connection cannot be established, OracleAS TopLink throws a DatabaseException.

After a connection is established, the application can use the session to access the database. To test the connection, invoke the isConnected() method. If the connection works, that method returns TRUE.

To interact with the database, the application uses the session querying methods or executes query objects. The interactions between the application and the database are collectively known as the query framework. For more information about querying, see Chapter 6, "Queries".

Although session query methods work well with database sessions, concurrency issues make the database session unsuited for three-tier applications.

Logging Out of the Database

To log out the session, use the logout() method. To disconnect the session from the relational database and flush the session identity maps, call the logout() method.

Because logging in to the database can be time-consuming, log out only when all database interactions are complete.

Applications that log out from the database do not have to reregister their descriptors if they log back in to the database.

Using Manual Transaction Control

Certain versions of Sybase JConnect prevent the execution of stored procedures with JDBC auto-commit. If you use OracleAS TopLink with a version of JConnect that causes this problem, use the handleTransactionsManuallyForSybaseJConnect() method to handle the transactions manually.

To add transaction processing to a set of database operations:

1. At the start of the transaction set, call beginTransaction().

2. Specify a try-catch block that calls rollbackTransaction() if a database exception is thrown.

3. At the end of the transaction set, call commitTransaction().

   
   

   Note: The Unit of Work is already transaction bound and does not require these calls.

   
   

/** Update a group of employee records*/
void writeEmployees(Vector employees, Session session)
{
    Employee employee;
    Enumeration employeeEnumeration = employees.elements();
    try {
        session.beginTransaction();
        while (employeeEnumeration.hasMoreElements())
        {
            employee=(Employee) employeeEnumeration.nextElement();
            session.writeObject(employee);
        }
        session.commitTransaction();
    } catch (DatabaseException exception) {
    // If a database exception has been thrown, roll back the transaction.
        session.rollbackTransaction();
    }
}

Creating Database Sessions: Examples

import oracle.toplink.tools.workbench.*;
import oracle.toplink.sessions.*

// Create the project object
Project project = XMLProjectReader.read("C:\TopLink\example.xml");
DatabaseLogin loginInfo = project.getLogin();
loginInfo.setUserName("scott"); 
loginInfo.setPassword("tiger"); 

//Create a new instance of the session and login
DatabaseSession session = project.createDatabaseSession();
try {
    session.login();
    } catch (DatabaseException exception) {
    throw new RuntimeException("Database error occurred at login: " +     exception.getMessage());
    System.out.println("Login failed");
    }

/* Do any database interaction using the query framework, transactions or Units of Work */
...

// Log out when database interaction is over
session.logout();
Creating and using a session from coded descriptors 
import oracle.toplink.sessions.*;

//Create the project object. 
DatabaseLogin loginInfo = new DatabaseLogin();
loginInfo.useJDBCODBCBridge();
loginInfo.useSQLServer();
loginInfo.setDataSourceName("MS SQL Server");
loginInfo.setUserName("scott"); 
loginInfo.setPassword("tiger");
Project project = new Project(loginInfo);

//Create a new instance of the session, register the descriptors, and login
DatabaseSession session = project.createDatabaseSession();
session.addDescriptors(this.buildAllDescriptors());
try {
    session.login();
} catch (DatabaseException exception) {
    throw new RuntimeException("Database error occurred at login: " +
    exeption.getMessage());
    System.out.println("Login failed");
    }

//Do any database interaction using the query framework, transactions or Units of Work
...
//Log out when database interaction is over
session.logout(); 
}

Reference

Table 4-12 summarizes the most common public methods for the DatabaseSession class. For more information about the available methods for the DatabaseSession class, see the Oracle Application Server TopLink API Reference.

Multiple Sessions

The session broker is a powerful tool that enables you to use data that is split across multiple databases for a given application. An alternative to the session broker is to use multiple sessions to work with multiple databases:

• If the data on each database is unrelated to data on the other databases, and relationships do not cross database boundaries, then you can create a separate session for each database. For example, you may have individual databases and associated sessions dedicated to each cost center.

  This arrangement requires that you to manage each session manually and ensure that the class descriptors for your project reside in the correct session.

• You can use additional sessions to house a regular batch job. In this case, you can create two or more sessions on the same database. In addition to the main session that supports client queries, you can create other sessions that support batch inserts at low-traffic times in your system. This enables you to maintain the client cache.

Configuring the Session Broker in Code

After the session broker is set up and logged in, it functions like a session, making multiple database access transparent. Because a session broker is more complex than a regular database session, it requires more work to create and configure.

Project p1 = ProjectReader.read(("C:\Test\Test1.project"));
Project p2 = ProjectReader.read(("C:\Test\Test2.project"));

/* modify the user name and password if they are not correct in the .project file */
p1.getLogin().setUserName("User1");
p1.getLogin().setPassword("password1");
p2.getLogin().setUserName("User2");
p2.getLogin().setPassword("password2");
DatabaseSession session1 = p1.createDatabaseSession();
DatabaseSession session2 = p2.createDatabaseSession();

SessionBroker broker = new SessionBroker();
broker.registerSession("broker1", session1);
broker.registerSession("broker2", session2);

broker.login();

UnitOfWork uow = broker.acquireUnitOfWork();
Test test = (Test) broker.readObject(Test.class);
Test testClone = uow.registerObject(test);
. . .
//change and manipulate the clone and any of its references
. . .
uow.commit();

//log out when finished
broker.logout();

Committing a Transaction with a Session Broker

If you use a session broker, incorporate a JTA external transaction controller wherever possible. The external transaction controller provides a two-phase commit, which passes the SQL statements that are required to commit the transaction to the JTA driver. The JTA driver handles the entire commit process.

JTA guarantees that the transaction commits or rolls back completely, even if the transaction involves more than one database. If the commit to any one database fails, then all database transactions roll back. The two-phase commit is the safest method available to commit a transaction to the database.

Two-phase commit support requires integration with a JTA-compliant driver.

For more information about the JTA drivers, see "JTA".

Using the Session Broker in a Three-tier Architecture

The session broker operates in a seamless manner in a tree-tier environment. To use the session broker in a three-tier application, configure server sessions for the session broker.

Although you can configure your session broker in code, as illustrated in Example 4-40, we recommend you use the OracleAS TopLink Sessions Editor to specify a session broker in the sessions.xml file.

For more information, see the Oracle Application Server TopLink Mapping Workbench User's Guide.

Project p1 = ProjectReader.read(("C:\Test\Test1.project"))

Project p2 =
ProjectReader.read(("C:\Test\Test2.project"));

/* Create Sessions for the SessionBroker */
Server sSession1 = p1.createServerSession();
Server sSession2 = p2.createServerSession();


/* Create the SessionBroker and assign the sessions to it */
SessionBroker broker = new SessionBroker();
broker.registerSession("broker1", sSession1);
broker.registerSession("broker2", sSession2);
broker.login();

Session clientBroker = broker.acquireClientSessionBroker();

Limitations

Using the session broker is not the same as linking databases at the database level. If your database allows linking, use that functionality to provide multiple database access.

The session broker has the following limitations:

• You cannot split multiple table descriptors across databases.

• Each class must reside on only one database.

• You cannot use joins through expressions across databases.

• Many-to-many join tables and direct collection tables must reside on the same database as the source object.

  
  

  Note: The "Advanced Use" section describes a workaround for this limitation. It uses an amendment to the descriptor.

  
  

Advanced Use

Many-to-many join tables and direct collection tables must be on the same database as the source object, because reading these tables requires a join that spans both databases. To get around this problem, use the setSessionName(String sessionName) method on ManyToManyMapping and DirectCollectionMapping. This method indicates that the join table or direct collection table is on the same database as the target table.

Descriptor desc = session1.getDescriptor(Employee.class);
((ManyToManyMapping)desc.getObjectBuilder().getMappingForAttributeName("projects")).setSessionName("broker2");

DatabaseQuery offers a similar method that supports nonobject queries.

Reference

Table 4-13 summarizes the most common public methods for SessionBroker. For more information about the available methods for SessionBroker, see the Oracle Application Server TopLink API Reference.

Architectural Overview

The remote session model comprises of the following layers (also see Figure 4-11):

• The application layer—a client side application talking to a remote session

• The transport layer—a communication layer, RMI, or RMI-IIOP

• The server layer—an OracleAS TopLink session communicating with a database

The request from the client application to the server travels down through the layers of a distributed system. A client that makes a request to the server session uses the remote session as a conduit to the server session. The client references the remote session, and the remote session forwards a request to the server session through the transport layer.

At runtime, the remote session builds its knowledge base by reading descriptors and mappings from the server side as they are needed. These descriptors and mappings are lightweight, because not all information is passed on to the remote session. The information needed to traverse an object tree and to extract primary keys from the given object is passed with the mappings and descriptors.

Figure 4-11 An Architectural Overview of the Remote Session

Description of the illustration remarch.gif

Securing Remote Session Access

The remote session represents a potential security risk, because it requires you to register a remote session controller dispatcher as a service that anyone can access. This can expose the entire database.

To reduce this threat, run a server manager as a service to hold the remote controller session dispatcher. All the clients must then communicate through the server manager, which implements the security model for accessing the remote session controller dispatcher.

On the client side, the user requests the remote session controller dispatcher. The manager returns a remote session controller dispatcher only if the user has access rights according to the security model built into the server manager.

To access the system, the remote session controller dispatcher on the client side creates a remote connection, and acquires a remote session from the remote connection. The API for the remote session is the same as for the session, and there is no user-visible difference between working on a session or a remote session.

Queries

Read queries are publicly available on the client side, but queries that modify objects must be performed using the Unit of Work.

Refreshing

Calling refresh methods on the remote session causes database reads, and may also cause cache updates if the data being refreshed is modified in the database. This can lead to poor performance.

To improve performance, configure refresh methods to run against the server session cache, by configuring the descriptor to always remotely refresh the objects in the cache on all queries. This technique ensures that all queries against the remote session refresh the objects from the server session cache, without the database access.

Cache hits on remote sessions still occur on read object queries based on the primary keys. If you want to avoid this, disable the remote session cache hits on read object queries based on the primary key.

// Get the PolicyHolder descriptor
Descriptor holderDescriptor = remoteSession.getDescriptor(PolicyHolder.class);

// Set refresh on the ServerSession cache
holderDescriptor.alwaysRefreshCachedOnRemote();

// Disable remote cache hits, ensure all queries go to the ServerSession cache
holderDescriptor.disableCacheHitsOnRemote();

Indirection

The remote session supports indirection objects. An indirection object is a valueholder that can be invoked remotely on the client side. When invoked, the valueholder first checks to see if the requested object exists on the remote session. If not, then the associated valueholder on the server is instantiated to get the value that is then passed back to the client. Remote valueholders are used automatically; the code of the application does not change.

Cursored Streams

Remote session supports cursored streams, but not scrollable cursors.

For more information about enabling cursored streams, see "Java Streams".

Unit of Work

Use a Unit of Work acquired from the remote session to modify objects on the database. A Unit of Work acquired from the remote session offers the user the same functionality as a Unit of Work acquired from the client session or the database session.

Creating a Remote Connection Using RMIConnection

Example 4-43 and Example 4-44 demonstrate how to create a remote OracleAS TopLink session on a client that communicates with a remote session controller on a server that uses RMI. After creating the connection, the client application uses the remote session as it does with any other OracleAS TopLink session.

These examples assume that a class called RMIServerManager exists on the server. It is not an OracleAS TopLink-enabled class. This class has a method that instantiates and returns an RMIRemoteSessionController (an OracleAS TopLink server side interface).

RMIServerManager serverManager = null;
// Set the client security manager
try {
    System.setSecurityManager(new RMISecurityManager());
    } catch(Exception exception) {
    System.out.println("Security violation " + exception.toString());
}
// Get the remote factory object from the Registry
try {
    serverManager = (RMIServerManager) Naming.lookup("SERVER-MANAGER");
    } catch (Exception exception) {
    System.out.println("Lookup failed " + exception.toString());
}
// Start RMIRemoteSession on the server and create an RMIConnection
RMIConnection rmiConnection = null;
try {
    rmiConnection = new     RMIConnection(serverManager.createRemoteSessionController());
    } catch (RemoteException exception) {
    System.out.println("Error in invocation " + exception.toString());
}
// Create a remote session which we can then use as a normal OracleAS TopLink Session
Session session = rmiConnection.createRemoteSession();

RMIRemoteSessionController controller = null;
try {
    /* Create instance of RMIRemoteSessionControllerDispatcher which implements 
    RMIRemoteSessionController. The constructor takes an OracleAS TopLink     session as a parameter */
    controller = new RMIRemoteSessionControllerDispatcher (localTopLinkSession);
} 
catch (RemoteException exception) {
    System.out.println("Error in invocation " + exception.toString());
}
return controller;