16
Managing Sessions and Transactions

Chapter 4, "Creating an Oracle Internet File System Document" enables developers to get started building custom applications by introducing how to establish a session with Oracle 9iFS and use the session to create objects. This chapter discusses session management in more detail by covering the following advanced topics:

Managing Sessions

When you build a custom application, such as an agent, a protocol server, or a Web client, the first thing it must do is establish a session with Oracle 9iFS. The session enables the application to authenticate the user, cache information that the user is working with, and perform operations in the repository, such as searching for information, browsing folders, creating, updating, and deleting objects.

How Oracle 9iFS Session Management Works

Oracle 9iFS provides a highly scalable and performant framework for managing sessions. The framework enables applications to horizontally scale by distributing the application's processing load across multiple middle-tier machines. The framework also enables applications to optimize memory usage and performance by caching information and pooling database resources.

The framework employs two Java objects to manage sessions:

Figure 16-1 Session Management Object Model

Text description of sesobmod.gif follows.

Text description of the illustration sesobmod.gif

LibraryServices

LibraryServices (service) are responsible for:

Connecting to the Database

Each LibraryService is responsible for connecting to the Oracle9i database and pooling database resources. The service connects to the database via Net8, enabling connections to be made locally on the machine running the database or remotely from a middle-tier machine. Consequently, services enable you to scale your application by distributing its processing load and memory demands across multiple host machines. Distributing your application in this manner also allows you to manage the accessibility of your applications by placing them on host machines that are accessible to different types of users. For example, you can place a Web application on a host machine outside of the corporate firewall to make it accessible to Internet users. You can place an SMB-based application on a host machine that is accessible to corporate users via an internal network. If your company is distributed across several worldwide sites, you can distribute an Intranet application across host machines at each site.

Authenticating Users

Applications use services to obtain a session with Oracle 9iFS. To establish a session for the application, the service first authenticates the user. If the user credentials are valid, the service provides a session that the application can use to interact with Oracle 9iFS.

Managing Sessions

Each service manages a set of sessions. The service is responsible for timing out inactive sessions, tracing session activity, maintaining a cache of information accessed by the sessions, and publishing events incurred by operations performed by sessions.

Caching Information

Oracle 9iFS services also allow you to optimize the performance, network demand and memory usage of your application. Each service maintains a cache of information accessed by the sessions. By caching information, the service decreases the number of Java objects that would be constructed by sessions and the number of calls that would retrieve data from the database.

Event Handling

Oracle 9iFS services are also used to handle events. The services publish events that occur in Oracle 9iFS so that sessions can process the events.

NOTE:

For instructions on handling events, see Chapter 13, "Creating Custom Servers". For instructions on configuring services, consult the Oracle 9iFS Setup and Administration Guide.

LibrarySessions

LibrarySessions (sessions) are responsible for:

Managing the State of the Session

he Oracle 9iFS session maintains its own state. For example, the session keeps track of the current user and whether administration mode is enabled.

Performing Operations

The session acts as a factory for all operations performed by the application. The application uses the session to create, modify, and delete objects. The application also uses the session to execute queries for information in Oracle 9iFS, and to get collections of frequently used objects, such as the DirectoryUser collection, ClassObject collection, and SystemAccessControlList collection.

Managing Transactions

The Oracle 9iFS session is also used to perform operations synchronously within transactions. The application uses the session to begin a transaction, during which all operations are reflected only within the session's cache. Subsequently, the application can use the session to abort the transaction, effectively rolling back all changes, or commit the transaction, effectively making the changes in the repository.

Caching Uncommitted Changes to Information

The session maintains a cache of information that is being processed by the session. The session's cache reflects the session-specific state of the information. For example, all operations performed during a transaction are visible in the session's cache, but are not visible to other sessions until the transaction is committed. When the session commits the changes to Oracle 9iFS, the service informs all other sessions of the changes so that they can properly update their caches.

Session Management Classes

Oracle 9iFS Java API provides two Java classes that your application can use manage sessions: LibraryService and LibrarySession. These classes are supported by a few other classes, located in the oracle.ifs.common package, that are used to authenticate session users.

LibraryService

Services are represented as instances of the LibraryService class. The LibraryService class provides methods that the application can use to connection to the Oracle database and establish a session with Oracle 9iFS.

Table 16-1 lists the most commonly used methods on LibraryService.

Table 16-1 LibraryService Methods

connect()

Establishes a connection to Oracle 9iFS. It receives an instance of ConnectionOption that holds the user's credentials and other connection information.

LibrarySession

Sessions are represented by instances of the LibrarySession class. The LibrarySession class provides methods that the application can use to perform operations in Oracle 9iFS, such as creating, modifying, and deleting Oracle 9iFS objects, and searching the repository.

Table 16-2 lists the most commonly used methods on LibrarySession.

Table 16-2 LibrarySession Methods

`abortTransaction()` `beginTransaction()` `completeTransaction()` `disconnect()`	Manages transaction state.
`createPublicObject()` `createSchemaObject()` `createSystemObject()`	Creates new persistent objects.
`createView()`	Creates custom SQL views against Oracle 9iFS classes.
`getClassAccessControlListCollection()` `getClassDomainCollection()` `getClassObjectCollection()` `getDirectoryUserCollection()` `getExtendedPermissionCollection()` `getExtendedUserProfileCollection()` `getFormatCollection()` `getFormatExtensionCollection()` `getPermissionBundleCollection()` `getPolicyCollection()` `getSharedAccessControlListCollection()` `getSystemAccessControlListCollection()` `getValueDefaultCollection()` `getValueDomainCollection()`	Gets collections for certain classes of objects.
`getDefaultFolderRelationshipClassname()` `getDefaultFolderSortSpecification()` `getFolderPathDelimiter()` `getRootFolder()` `getWorldDirectoryGroup()` `setDefaultFolderRelationshipClassname()` `setDefaultFolderSortSpecification()` `setFolderPathDelimiter()`	Determines and manipulates system defaults.
`getDirectoryObject()` `getPublicObject()` `getSchemaObject()` `getSystemObject()` `lookupInverseInstanceLabel()`	Finds objects by their identifiers.
`getId()` `getSchemaVersionNumber()` `getSchemaVersionString()` `getServerName()` `getServerProperty()` `getServerVersionNumber()` `getServerVersionString()` `getServiceId()` `getVersionNumber()` `getVersionString()`	Determines server configuration and version information.
`grantAdministration()` `isAdministrationMode()` `setAdministrationMode()`	Gets and sets administration modes for the session.
`getObjectsLockedForSession()` `unlockForSession()` `getUser()` `impersonateUser()` `isConnected()`	Gets information about the connected user.
`deregisterClassEventHandler()` `deregisterEventHandler()` `invokeServerMethod()` `processEvents()` `registerClassEventHandler()` `registerEventHandler()`	Processes events.

Common Classes

When the LibraryService establishes a connection, it must be passed a set of connection options, including the Oracle 9iFS server being connected to, and the user's credentials. The ConnectOptions class in the oracle.ifs.common package holds the connection information that is passed to the LibraryService, including the Locale, Service name, and Service password. In addition, the class CleartextCredential is used by an application to pass the user credentials to the LibraryService, which uses the credentials to authenticate the user.

Table 16-3 lists the most commonly used methods on ConnectOptions.

Table 16-3 ConnectOptions Methods

getLocale()

setLocale()

Determines the locale for the session to be created.

getServiceName()

setServiceName()

Determines which LibraryService will be used to establish a connection to Oracle 9iFS.

getServicePassword()

setServicePassword()

Determines the password that is required for the LibraryService to connect to the Oracle 9iFS database schema (the ifssys database user password).

Table 16-4 lists the most commonly used methods on ClearTextCredential.

Table 16-4 ClearTextCredential Methods

getName()

setName()

Determines the name of the user.

getPassword()

setPassword()

Determines the user's password. The password is passed unencrypted.

Using the Session Management Framework

When applications use the Session Management Classes to establish a session with Oracle 9iFS, they inherently benefit from the caching, database resource pooling, and session management capabilities of the Oracle 9iFS service. In addition, the application can explicitly call the session management classes to perform fundamental tasks in Oracle 9iFS.

Table 16-5 lists the various tasks that an application can perform with the session management classes. It also references the section or chapter that describes how to perform these tasks in detail.

Table 16-5 Session Management Tasks

Task	Chapter / Section
Connecting to the Database and Authenticating Users	Chapter 4, "Creating an Oracle Internet File System Document" describes how the session management classes can be used to connect to the database, authenticate the user's credentials, and establish a session with Oracle 9iFS.
Creating Objects	Chapter 4, "Creating an Oracle Internet File System Document" discusses how to use the LibrarySession and Definition classes to create documents.
Querying the Repository	Chapter 8, "Building Search Applications" discusses how the LibrarySession class can be used to construct Selectors and Searches which are used to query the repository.
Managing Transactions	The "Managing Transactions" section discusses how the application can call methods on the session to perform operations synchronously in transactions.
Handling Events	Chapter 13, "Creating Custom Servers"discusses how applications can use the session management classes to post and process events.
Tracing	The Oracle 9iFS Developer's Reference does not currently cover this topic.

Managing Transactions

When an application performs an operation in Oracle 9iFS, such as creating, modifying, or deleting an object, the changes are immediately committed to the database. However, in some cases the application may need to commit a set of dependent operations together. That is, the application needs to ensure that if all operations cannot be successfully performed, none of the operations are performed. That is, the operations must be atomically committed or rolled back. The Oracle 9iFS session management framework enables applications to wrap operations in a transaction block that can be used to control when the changes are committed to the database.

Beginning, Aborting, and Committing Transactions

The LibrarySession class in the Oracle 9iFS Java API provides methods that are used to manage transactions: beginTransaction(), abortTransaction(), and completeTransaction(). These methods enable applications to define the boundaries of a transaction block, test the feasibility of the operations in the transaction, and commit or rollback the changes made by the operations based on their success or failure.

Transactions are managed in the following steps:

Begin the Transaction. The application calls the beginTransaction() on the LibrarySession to start the transaction.
Perform Operations. Within the transaction, any operations that manipulate Oracle 9iFS objects are performed in the session's cache, but are not actually performed in the repository. This allows the session to ensure that the operations can all be performed successfully.
Abort the Transaction. If an operation fails, the application can call the abortTransaction() method to rollback the changes made to the session's cache.
Complete the Transaction. If all operations succeed, the application can call the completeTransaction() method to commit the changes in the repository. When the changes are committed to the repository, the service will propagate the changes to the service cache for other sessions to access.

Example 16-1 illustrates how an application can use the LibrarySession to manage a transaction.

Example 16-1 Using a LibrarySession to Manage Transactions

/* 
 * The following example illustrates how to delete a group 
 * and all of its members in a single transaction.  
 * If a member cannot be removed, the group will not be deleted.
 */

Assume that the application has already obtained the group.

DirectoryGroup dg = ....
DirectoryObject[] members = dg.getAllMembers();
DirectoryObject m;

Begin a transaction.

Transaction transaction = session.beginTransaction();

Start a try block to test the operations and catch any exceptions.
```
try 
{
```

Loop through the group and remove each user.

  int count = (members == null) ? 0 : members.length;
  for (int i = 0; i < size; i++) 
  {
    m = members[i];
    dg.removeMember(m); 
  }

If the transaction reaches the end of the for loop without throwing an exception, complete the transaction to commit the changes to the database.
```
  session.completeTransaction(transaction); 
}
catch (IfsException e) 
{
```
If an exception was thrown while trying to remove a member, abort the transaction to rollback the changes in the session cache.
```
  session.abortTransaction(transaction); 
  throw e; 
} 
```

DDL Operations in Transactions

Oracle 9iFS operations in the transaction that perform Data Definition Language (DDL) operations in the database (e.g., creating tables, views, and columns) will still be immediately committed to the database. Calling the abortTransaction() method will not rollback the database changes. The following Java API methods perform DDL operations in the database:

LibrarySession.createSchemaObject(ClassObjectDefinition def) creates tables and views for new ClassObjects.
ClassObject.free() drops tables and views for ClassObjects.
ClassObject.addAttribute(AttributeDefinition def) creates a column for an Attribute in a ClassObject's table and view.
ClassObject.removeAttribute(Attribute attr) removes the column for an Attribute in a ClassObject's table and view.

Availability of Changed LibraryObjects

The following are the rules for how changed LibraryObjects become available to sessions:

Uncommitted changes to LibraryObjects are only visible to the session making those changes (the originating session). Until the transaction is completed, the session holds a lock on the LibraryObjects being changed to prevent other sessions from changing them.
Committed changes are propagated synchronously to the originating session, making them immediately visible to that session.
Committed changes are propagated asynchronously to all other sessions in the service that manages the originating session. They are visible to all other sessions in that service within EventPollerPeriod seconds, where EventPollerPeriod is the value specified in the service properties file.
Committed changes are propagated asynchronously by the service to all other sessions in all other services. The changes are visible to sessions in those services within a period of time that can be configured for the service. The period of time can be calculated from properties in the service's properties file, as follows:
```
1000 * (PollForEventsFromOtherServicesPeriod  + 

TransportEventsToOtherServicesPeriod) + 

EventPollerPeriod milliseconds
```

Embedding Java Database Calls (JDBC) in Transactions

Some custom application may need to use Oracle 9iFS transaction management capabilities not only to manage operations performed in Oracle 9iFS, but to manage operations performed in an external database schema. For example, you might build an application that integrates Oracle 9iFS with another database schema that stores product data. Whenever a design document is updated in Oracle 9iFS, the custom application must also update the status of the corresponding product in the other database schema. If the product cannot be updated successfully, then the changes to the design document must be rolled back.

Oracle 9iFS Java API provides a set of server-side Java classes, included in the oracle.ifs.server.sql package, that allow custom applications to implement overrides that perform operations against Oracle 9iFS objects and external databases in a single transaction. The classes allow an application to connect to an external database schema, construct a SQL statement, and execute the statement. The classes encapsulate the JDBC calls that perform these tasks against the external database so that Oracle 9iFS maintains control of how the operations are committed and rolled back.

The following are the Java classes package, that are used to perform JDBC operations on the server:

IfsConnection. The IfsConnection class is used to establish a JDBC connection to the external database. It encapsulates java.sql.Connection.
IfsStatement. The IfsStatement class is used to construct and execute static SQL statements. It encapsulates java.sql.Statement.
IfsPreparedStatement. The IfsPreparedStatement is used to construct and execute pre-compiled SQL statements containing parameter variables. It encapsulates java.sql.PreparedStatement.
IfsCallableStatement. The IfsCallableStatement class is used to construct and execute SQL stored procedures. It encapsulates java.sql.CallableStatement.

IfsConnection

To represent a session with a database schema, the custom application would instantiate the IfsConnection class. IfsConnection is instantiated by calling the getIfsConnection() method on the server-side representation of the application's session (e.g., S_LibrarySession).

Example 16-2 Using IfsConnection to Connect to a Database Schema

Use the S_LibrarySession to construct an IfsConnection object.

IfsConnection conn = m_Session.getIfsConnection();

The IfsConnection instance is subsequently used to construct the Java objects used to represent SQL statement: IfsStatement, IfsPreparedStatement, and IfsCallableStatement. Example 16-3, Example 16-4, and Example 16-5 illustrate how the IfsConnection is used to construct these objects.

IfsStatement

Once an IfsConnection object is constructed, it can be used obtain an IfsStatement. IfsStatement is used to construct SQL statements that are static, that is statements that don't use bind variables. To uses an IfsStatement, follow these steps:

Construct an IfsConnection to connect to the external database schema.
Construct an IfsStatement object by calling the createStatement() method on the IfsConnection.
Construct a string to hold the SQL statement.
Pass the SQL statement to the execute() or to the executeUpdate() method on the IfsStatement object to execute the SQL.
Catch any SQLExceptions thrown. Catching SQLExceptions allows the server-side override to handle the impact they have on a transaction that contains the JDBC operations.
Finally, call the dispose() method on the IfsStatement.

Example 16-3 Using IfsStatement to Construct and Execute Static SQL Statements

protected void extendedPreInsert(OperationState opState, 
  S_LibraryObjectDefinition def) throws IfsException 
{ 
  super.extendedPreInsert(opState, def);

Use the S_LibrarySession to construct the IfsConnection.

  IfsConnection conn = m_Session.getIfsConnection(); 

  try 
  {

Use the IfsConnection to construct an IfsStatement.

    IfsStatement stmt = conn.createStatement();

Construct a string to hold the SQL statement.

   AttributeValue av = def.getAttribute("NAME"); 
   String recipe = av.getString(m_Session); 

   S_DirectoryUser user = m_Session.getUser(); 
   String name = user.getName(); 

   String sqlstmt = "insert into your_custom_table (chef, recipe) " 
                     + "values ('wtalman','Curry Lamb')";

Pass the SQL statement to the IfsStatement object to execute the SQL.
```
    stmt.execute(sqlstmt); 
  }
```

Catch any SQLExceptions thrown.

  catch (SQLException e) 
  { 
    throw new IfsException(98765, e); 
  }

Finally, close the IfsStatement.

  finally 
  { 
    if (stmt != null) 
    { 
      stmt.dispose();
    } 
  } 
}

IfsPreparedStatement

As an alternative to IfsStatements, IfsPreparedStatements can be used to call pre-compiled SQL statement. To use an IfsPreparedStatement, follow these steps:

Construct an IfsConnection to connect to the external database schema.
Construct a string to hold the SQL statement with placeholders for the bind variables.
Pass the SQL statement to the prepareStatement() method on the IfsConnection object to construct an IfsPreparedStatement object.
Pass the bind variables to the setString() method on the IfsPreparedStatement object.
Call the execute() method on the IfsPreparedStatement method to execute the SQL statement.
Catch any SQLExceptions thrown. Catching SQLExceptions allows the server-side override to handle the impact they have on a transaction that contains the JDBC operations.
Finally, call the dispose() method on the IfsPreparedStatement.

Example 16-4 Using IfsPreparedStatements to Call Pre-Compiled SQL Statements

protected void extendedPreUpdate(OperationState opState,
  S_LibraryObjectDefinition def) throws IfsException
{
  super.extendedPreUpdate(opState, def);

Use the S_LibrarySession to construct the IfsConnection.

  IfsConnection conn = m_Session.getIfsConnection();

  try
  {

Construct a string to hold the SQL statement.

    AttributeValue av = def.getAttribute("NAME");
    String recipe = av.getString(m_Session);
    S_DirectoryUser user = m_Session.getUser();
    String name = user.getName();
    String sqlstmt = "insert into your_custom_table (chef, recipe) " +
                     "values (?, ?)";

Pass the SQL statement to the IfsConnection object to construct an IfsPreparedStatement object.
```
    IfsPreparedStatement pstmt = conn.prepareStatement(sqlstmt); 
```

Pass in the bind variables.

    pstmt.setString(1, name); 
    pstmt.setString(2, recipe);

Execute the SQL statement.
```
    pstmt.execute(sqlstmt); 
  } 
```

Catch any SQLExceptions.

  catch (SQLException e) 
  { 
    throw new IfsException(98765, e); 
  }

Finally, close the IfsPreparedStatement.

  finally 
  { 
    if (pstmt != null) 
    { 
       pstmt.dispose();
    } 
  } 
}

IfsCallableStatement

The IfsConnection can also be used to construct an IfsCallableStatement to execute a SQL stored procedure. To use an IfsCallableStatement, follow these steps:

Construct an IfsConnection to connect to the external database schema.
Construct a string to hold the SQL procedure call with placeholders for the arguments.
Pass the SQL statement to the prepareCall() method on the IfsConnection object to construct an IfsCallableStatement object.
Pass the arguments to the setString() method on the IfsCallableStatement object.
Call the execute() method on the IfsCallableStatement method to execute the SQL statement.
Catch any SQLExceptions thrown. Catching SQLExceptions allows the server-side override to handle the impact they have on a transaction that contains the JDBC operations.
Finally, call the dispose() method on the IfsCallableStatement.

Example 16-5 Using IfsCallableStatements to Execute SQL Stored Procedures

protected void extendedPreFree(OperationState opState, 
  S_LibraryObjectDefinition def) throws IfsException 
{ 
  super.extendedPreFree(opState, def);

Use the S_LibrarySession to construct the IfsConnection.

  IfsConnection conn = m_Session.getIfsConnection(); 

  try 
  {

Construct a string to hold the SQL call to the stored procedure.

    AttributeValue av = def.getAttribute("NAME"); 
    String recipe = av.getString(m_Session); 
    String sqlstmt = "{call yourcustompackage.test(?)}";

Pass the SQL statement to the IfsConnection object to construct an IfsCallableStatement object.
```
    IfsCallableStatement cstmt = conn.prepareCall(sqlstmt); 
```
Pass in the bind variables.
```
    cstmt.setString(1, recipe); 
```
Execute the SQL statement.
```
    cstmt.execute(); 
  } 
```

Catch any SQLExceptions.

 catch (SQLException e) 
  { 
    // should write your own exception message 
    throw new IfsException(98765, e); 
  }

Finally, close the IfsCallableStatement.

  finally 
  { 
    if (cstmt != null) 
    { 
       cstmt.dispose();
    } 
  } 
}

Restrictions

Oracle 9iFS places the following restrictions on performing JDBC operations within Oracle 9iFS transactions:

Data manipulation on Oracle 9iFS Tables

All permissible and valid operations on Oracle 9iFS tables are exposed through the Oracle 9iFS Java API. Oracle 9iFS does not support performing JDBC operations against tables in the Oracle 9iFS schema. Operations that directly manipulate schema objects (e.g., tables and views) or data stored in the schema (e.g., document data) will cause the caches maintained by Oracle 9iFS services to become stale and can corrupt Oracle 9iFS objects.

DDL Statements

You cannot use Oracle 9iFS to manage transactions across JDBC connections that invoke DDL statements, such as create or drop table. DDL statements are implicitly committed by the Oracle database and could interfere with Oracle 9iFS transaction management.

IfsConnection Methods

The following methods on IfsConnection are associated with JDBC transactions and will immediately throw an SQLException to restrict the use of such operations during the Oracle 9iFS connection:

setAutoCommit(boolean autoCommit)
public boolean isReadOnly()
public String getCatalog()
public void setTransactionIsolation(int level)

Explicit Commits and Rollbacks

The connections used in the read/write connection pool cache must not be committed or rolled back explicitly. Otherwise, the Oracle 9iFS transaction management cannot effectively rollback in response to an IfsException.

Sample Code

Oracle 9iFS is installed with sample code that helps you get started working with the Java API. The API sample code is located in the <ORACLE_HOME>/9ifs/samplecode/api directory.

Table 16-6 lists the API sample code that is relevant to this chapter.

Table 16-6 API Sample Code

Class	Usage
BaseSample.java	Starts a service, establishes and disconnects a session.
CreateLargeGroups.java	Demonstrates the use of transactions.

16 Managing Sessions and Transactions

Managing Sessions

How Oracle 9iFS Session Management Works

Figure 16-1 Session Management Object Model

LibraryServices

Connecting to the Database

Authenticating Users

Managing Sessions

Caching Information

Event Handling

LibrarySessions

Managing the State of the Session

Performing Operations

Managing Transactions

Caching Uncommitted Changes to Information

Session Management Classes

LibraryService

Table 16-1 LibraryService Methods

LibrarySession

Table 16-2 LibrarySession Methods

Common Classes

Table 16-3 ConnectOptions Methods

Table 16-4 ClearTextCredential Methods

Using the Session Management Framework

Table 16-5 Session Management Tasks

Managing Transactions

Beginning, Aborting, and Committing Transactions

Example 16-1 Using a LibrarySession to Manage Transactions

DDL Operations in Transactions

Availability of Changed LibraryObjects

Embedding Java Database Calls (JDBC) in Transactions

IfsConnection

Example 16-2 Using IfsConnection to Connect to a Database Schema

IfsStatement

Example 16-3 Using IfsStatement to Construct and Execute Static SQL Statements

IfsPreparedStatement

Example 16-4 Using IfsPreparedStatements to Call Pre-Compiled SQL Statements

IfsCallableStatement

Example 16-5 Using IfsCallableStatements to Execute SQL Stored Procedures

Restrictions

Data manipulation on Oracle 9iFS Tables

DDL Statements

IfsConnection Methods

Explicit Commits and Rollbacks

Sample Code

Table 16-6 API Sample Code

16
Managing Sessions and Transactions