Class COM.odi.Session

java.lang.Object
   |
   +----COM.odi.Session

public class Session

extends Object

Your application must create a session. After a session is created, it is an active session. A session remains active until your application or ObjectStore terminates it. After a session is terminated, it is never used again. You can, however, create a new session.

A session consists of a set of persistent objects, and a set of ObjectStore API objects, such as an instance of the Transaction class and instances of the Database class.

Different products allow different numbers of sessions in a single Java VM process:

• PSE allows one session.
• PSE Pro allows multiple sessions.
• ObjectStore allows one session in this release. It is expected that ObjectStore will allow multiple sessions in a future release.

activeSessions()

Obtains an enumeration of the active sessions at the time that the entrypoint is called.

create(String, Properties)

Creates a session, which permits the caller to use the rest of the ObjectStore API.

create(String, Properties, String)

Creates a session and allows you to specify a name for the session.

createGlobal(String, Properties)

Creates a global session, which permits the caller to use the rest of the ObjectStore API.

currentTransaction()

Obtains the current transaction for this session.

getCounters(boolean)

Gets the internal counters and meters for the session.

getCurrent()

Obtains the session for the calling thread if it is associated with a session.

getGlobal()

Obtains the current global session.

getName()

Returns the name of the session.

inTransaction()

Determines whether or not this session has a transaction in progress.

isActive()

Indicates whether or not this session is active.

join()

Associates the calling thread with this session.

leave()

Disassociates the calling thread from its associated session.

of(Object)

Obtains the session associated with the specified persistent object.

ofThread(Thread)

Obtains the session associated with the specified thread.

segmentOfpreFlushContentsObject()

Call this method from a class's preFlushContents() method if preFlushContents() must be able to identify the object's segment.

terminate()

Terminates the session.

  public static Session create(String host,
                               Properties properties)

Creates a session, which permits the caller to use the rest of the ObjectStore API. ObjectStore does not join the calling thread to the newly created session. Call the Session.join() method to join the current thread to the new session.

This method throws FatalApplicationException if there is an active session.

Parameters:

host - ObjectStore ignores this argument. Specify null.

properties - A property list that contains additional information needed to establish the session. ObjectStore first looks for properties defined in this list and then looks at the system properties list. If ObjectStore cannot find a property in either list it uses the default. All ObjectStore properties start with COM.odi. You can pass in property information by making it a system property.

You can specify the following properties:

• COM.odi.applicationName
• COM.odi.cacheSize
• COM.odi.disableWeakReferences
• COM.odi.migrateUnexportedStrings
• COM.odi.ObjectStoreLibrary
• COM.odi.password
• COM.odi.product
• COM.odi.queryDebugLevel
• COM.odi.stringPoolSize
• COM.odi.trapUnregisteredType
• COM.odi.user

COM.odi.applicationName indicates the name of the application for the current client. This allows users of the LockTimeoutBlocker class or the ossvrstat utility to retrieve information about clients involved in concurrency conflicts. When you set this property, it can provide information about your application to other clients.

COM.odi.cacheSize specifies the size of the C++ client cache in bytes. The default is 8388608 bytes, or 0x800000 bytes in hexadecimal. If the value is a String that starts with 0x or 0X, ObjectStore treats the value as a hexadecimal number. ObjectStore rounds the cache size down to the nearest whole number of pages.

COM.odi.disableWeakReferences is a Boolean value that defaults to "false". (Remember that all property values are strings, so you must enclose false or true in quotation marks.) When you specify this property, ObjectStore does not use the weak reference facility.

When you start the first session in a Java process, the setting of the COM.odi.disableWeakReferences property is in effect for the duration of the Java process. If you terminate the session and start another session with a different value for the COM.odi.disableWeakReferences property, the new value is ignored.

A weak reference to an object is a reference that does not prevent the object from being garbage collected by the Java VM's garbage collector. In its internal Object Table, ObjectStore uses weak references to hold references to unmodified persistent objects. If your program does not have any references to a persistent object and the reference in the Object Table is the only reference, the object can be garbage collected. If the persistent object has been modified and the changes have not yet been saved, ObjectStore uses a strong reference to hold the reference to the object. A strong reference prevents the object from being garbage collected.

The COM.odi.migrateUnexportedStrings property controls what happens when ObjectStore encounters a cross-segment reference to an unexported String object. If this property is not set or if it is set to true, ObjectStore creates a new String object that has the same value as the referenced object. ObjectStore places this new string in the same segment as the referring object and substitutes this new string for the referenced string. If this property is set to false, ObjectStore throws ObjectNotExportedException if it encounters a reference to a string in another segment and that string is not exported.

COM.odi.ObjectStoreLibrary specifies the name of the native library that contains the ObjectStore schema and native methods for the application. The name should follow platform conventions for library names. If you do not specify this property, ObjectStore uses the standard library, which provides for primary Java objects but not Java peer objects.

COM.odi.user and COM.odi.password allow you to supply a user name and a password when the ObjectStore Server has Name Password set for the Authentication Required Server parameter.

COM.odi.product allows you to specify which Object Design Java product you want to use. The advantage of COM.odi.product is that it allows you to write an application that copies data among PSE, PSE Pro, and ObjectStore databases. You can set this property to one of the following three values: PSE, PSEPro, or ObjectStore. To use any of these products, you must have the software in your CLASSPATH environment variable. When this property is not set, Object Design software looks for PSE Pro, then PSE, then ObjectStore, and uses the first product it finds.

The setting of COM.odi.product applies only to the session for which it is specified. After you start a session, you cannot change the value of COM.odi.product. An example of how to use this property is in the user guide.

COM.odi.queryDebugLevel allows you to control debugging output when you are using the query facility defined in the COM.odi.util.query.Query class. In PSE, this property does nothing.

The default level is 0, which does not output any information. Set the property to a value greater than 0 to print debugging output to System.err. As the value of this property increases, the query facility outputs more information as follows:

• 0 - No debugging information.
• 1 - Indexes that are required and that would be useful; statistics about indexed and nonindexed lookups.
• 5 - Query parser tree and query evaluation tree.
• 10 - Information about generated classes.

COM.odi.stringPoolSize specifies the maximum size of the persistent string pool. The value of this property specifies the maximum number of newly created strings that ObjectStore can maintain in the string pool. If the number of newly created strings exceeds this number, only the ones that were most recently created and used are tracked by the pool. The default value is 100. Before ObjectStore migrates a string into a segment, it checks the pool to see if a string with the same value is already available in the segment. If it is, the string is reused and ObjectStore does not create a new one. ObjectStore clears the pool at the start of each transaction. You can turn off the pooling mechanism by setting the value of this property to 0.

The COM.odi.trapUnregisteredType property is useful for troubleshooting ClassCastExceptions. The default is that this property is not set, and it is usually best to use the default.

When ObjectStore encounters a type for which it does not have information (that is, the type is unregistered), it checks the setting of the COM.odi.trapUnregisteredType property.

If the property is not set, ObjectStore creates an instance of the UnregisteredType class to represent the unknown type. Your application continues to run as long as it does not try to use the UnregisteredType object. Often, this can be fine because your application has no need for that particular field. However, if you do try to use the unregistered type, ObjectStore throws ClassCastException.

If COM.odi.trapUnregisteredType is set, ObjectStore throws FatalApplicationException and provides a message that indicates the name of the unregistered class. See the user guide for additional information.

Returns:

The new session.

Throws: FatalApplicationException

If there is an active session.

Throws: ObjectStoreException

If there is an active global session.

  public static Session create(String host,
                               Properties properties,
                               String name)

Creates a session and allows you to specify a name for the session. A session permits the caller to use the rest of the ObjectStore API. ObjectStore does not join the calling thread to the newly created session. Call the Session.join() method to join the current thread to the new session.

This method throws FatalApplicationException if there is an active session.

Parameters:

host - ObjectStore ignores this argument. Specify null.

properties - A property list that contains additional information needed to establish the session. ObjectStore first looks for properties defined in this list and then looks at the system properties list. If ObjectStore cannot find a property in either list it uses the default. All ObjectStore properties start with COM.odi. You can pass in property information by making it a system property.

You can specify the following properties:

• COM.odi.applicationName
• COM.odi.cacheSize
• COM.odi.disableWeakReferences
• COM.odi.migrateUnexportedStrings
• COM.odi.ObjectStoreLibrary
• COM.odi.password
• COM.odi.product
• COM.odi.queryDebugLevel
• COM.odi.stringPoolSize
• COM.odi.trapUnregisteredType
• COM.odi.user

COM.odi.applicationName indicates the name of the application for the current client. This allows users of the LockTimeoutBlocker class or the ossvrstat utility to retrieve information about clients involved in concurrency conflicts. When you set this property, it can provide information about your application to other clients.

COM.odi.cacheSize specifies the size of the C++ client cache in bytes. The default is 8388608 bytes, or 0x800000 bytes in hexadecimal. If the value is a String that starts with 0x or 0X, ObjectStore treats the value as a hexadecimal number. ObjectStore rounds the cache size down to the nearest whole number of pages.

COM.odi.disableWeakReferences is a Boolean value that defaults to "false". (Remember that all property values are strings, so you must enclose true and false in quotation marks.) When you specify this property, ObjectStore does not use the weak reference facility.

When you start the first session in a Java process, the setting of the COM.odi.disableWeakReferences property is in effect for the duration of the Java process. If you terminate the session and start another session with a different value for the COM.odi.disableWeakReferences property, the new value is ignored.

A weak reference to an object is a reference that does not prevent the object from being garbage collected by the Java VM's garbage collector. In its internal Object Table, ObjectStore uses weak references to hold references to unmodified persistent objects. If your program does not have any references to a persistent object and the reference in the Object Table is the only reference, the object can be garbage collected. If the persistent object has been modified and the changes have not yet been saved, ObjectStore uses a strong reference to hold the reference to the object. A strong reference prevents the object from being garbage collected.

The COM.odi.migrateUnexportedStrings property controls what happens when ObjectStore encounters a cross-segment reference to an unexported String object. If this property is not set or if it is set to true, ObjectStore creates a new String object that has the same value as the referenced object. ObjectStore places this new string in the same segment as the referring object and substitutes this new string for the referenced string. If this property is set to false, ObjectStore throws ObjectNotExportedException if it encounters a reference to a string in another segment and that string is not exported.

COM.odi.ObjectStoreLibrary specifies the name of the native library that contains the ObjectStore schema and native methods for the application. The name should follow platform conventions for library names. If you do not specify this property, ObjectStore uses the standard library, which provides for primary Java objects but not Java peer objects.

COM.odi.user and COM.odi.password allow you to supply a user name and a password when the ObjectStore Server has Name Password set for the Authentication Required Server parameter.

COM.odi.product allows you to specify which Object Design Java product you want to use. The advantage of COM.odi.product is that it allows you to write an application that copies data among PSE, PSE Pro, and ObjectStore databases. You can set this property to one of the following three values: PSE, PSEPro, or ObjectStore. To use any of these products, you must have the software in your CLASSPATH environment variable. When this property is not set, Object Design software looks for PSE Pro, then PSE, then ObjectStore, and uses the first product it finds.

The setting of COM.odi.product applies only to the session for which it is specified. After you start a session, you cannot change the value of COM.odi.product. An example of how to use this property is in the user guide.

COM.odi.stringPoolSize specifies the maximum size of the persistent string pool. The value of this property specifies the maximum number of newly created strings that ObjectStore can maintain in the string pool. If the number of newly created strings exceeds this number, only the ones that were most recently created and used are tracked by the pool. The default value is 100. Before ObjectStore migrates a string into a segment, it checks the pool to see if a string with the same value is already available in the segment. If it is, the string is reused and ObjectStore does not create a new one. ObjectStore clears the pool at the start of each transaction. You can turn off the pooling mechanism by setting the value of this property to 0.

COM.odi.queryDebugLevel allows you to control debugging output when you are using the PSE Pro query facility defined in the COM.odi.util.query.Query class. In PSE, this property does nothing.

The default level is 0, which does not output any information. Set the property to a value greater than 0 to print debugging output to System.err. As the value of this property increases, the query facility outputs more information as follows:

• 0 - No debugging information.
• 1 - Indexes that are required and that would be useful; statistics about indexed and nonindexed lookups.
• 5 - Query parser tree and query evaluation tree.
• 10 - Information about generated classes.

COM.odi.stringPoolSize specifies the maximum size of the persistent string pool. The value of this property specifies the maximum number of newly created strings that ObjectStore can maintain in the string pool. If the number of newly created strings exceeds this number, only the ones that were most recently created and used are tracked by the pool. The default value is 100. value is 100. Before ObjectStore migrates a string into a segment, it checks the pool to see if a string with the same value is already available in the segment. If it is, the string is reused and ObjectStore does not create a new one. ObjectStore clears the pool at the start of each transaction. You can turn off the pooling mechanism by setting the value of this property to 0.

The COM.odi.trapUnregisteredType property is useful for troubleshooting ClassCastExceptions. The default is that this property is not set, and it is usually best to use the default.

When ObjectStore encounters a type for which it does not have information, it checks the setting of the COM.odi.trapUnregisteredType property.

If the property is not set, ObjectStore creates an instance of the UnregisteredType class to represent the unknown type. Your application continues to run as long as it does not try to use the UnregisteredType object. Often, this can be fine because your application has no need for that particular field. However, if you do try to use the unregistered type, ObjectStore throws ClassCastException.

If COM.odi.trapUnregisteredType is set, ObjectStore throws FatalApplicationException and provides a message that indicates the name of the unregistered class. See the user guide for additional information.

name - The name of the session. If the name is null, then a unique name is generated.

Returns:

The new session.

Throws: FatalApplicationException

If there is an active session.

Throws: ObjectStoreException

If there is an active global session.

  public static Session createGlobal(String host,
                                     Properties properties)

Creates a global session, which permits the caller to use the rest of the ObjectStore API. Global sessions differ from nonglobal sessions in two ways:

• Any threads that call ObjectStore entrypoints automatically join the global session if there is an active global session.
• There can be only one active session if there is an active global session.

There is a bug in the software that prevents a global session from automatically joining threads to the session. To work around this, you must explicitly join threads to a global session. Call the Session.join() method on each thread that you want to be associated with the global session. This bug will be fixed in a future release.

This method throws an exception if there is an active session.

Parameters:

host - ObjectStore ignores this argument. Specify null.

properties - A property list that contains additional information needed to establish the session. ObjectStore first looks for properties defined in this list and then looks at the system properties list. If ObjectStore cannot find a property in either list it uses the default. All ObjectStore properties start with COM.odi. You can pass in property information by making it a system property.

You can specify the following properties:

• COM.odi.applicationName
• COM.odi.cacheSize
• COM.odi.disableWeakReferences
• COM.odi.migrateUnexportedStrings
• COM.odi.ObjectStoreLibrary
• COM.odi.password
• COM.odi.product
• COM.odi.queryDebugLevel
• COM.odi.stringPoolSize
• COM.odi.trapUnregisteredType
• COM.odi.user

COM.odi.applicationName indicates the name of the application for the current client. This allows users of the LockTimeoutBlocker class or the ossvrstat utility to retrieve information about clients involved in concurrency conflicts. When you set this property, it can provide information about your application to other clients.

COM.odi.cacheSize specifies the size of the C++ client cache in bytes. The default is 8388608 bytes, or 0x800000 bytes in hexadecimal. If the value is a String that starts with 0x or 0X, ObjectStore treats the value as a hexadecimal number. ObjectStore rounds the cache size down to the nearest whole number of pages.

COM.odi.disableWeakReferences is a Boolean value that defaults to "false". (Remember that all property values are strings, so you must enclose true and false in quotation marks.) When you specify this property, ObjectStore does not use the weak reference facility.

When you start the first session in a Java process, the setting of the COM.odi.disableWeakReferences property is in effect for the duration of the Java process. If you terminate the session and start another session with a different value for the COM.odi.disableWeakReferences property, the new value is ignored.

A weak reference to an object is a reference that does not prevent the object from being garbage collected by the Java VM's garbage collector. In its internal Object Table, ObjectStore uses weak references to hold references to unmodified persistent objects. If your program does not have any references to a persistent object and the reference in the Object Table is the only reference, the object can be garbage collected. If the persistent object has been modified and the changes have not yet been saved, ObjectStore uses a strong reference to the reference to the object. A strong reference prevents the object from being garbage collected.

The COM.odi.migrateUnexportedStrings property controls what happens when ObjectStore encounters a cross-segment reference to an unexported String object. If this property is not set or if it is set to true, ObjectStore creates a new String object that has the same value as the referenced object. ObjectStore places this new string in the same segment as the referring object and substitutes this new string for the referenced string. If this property is set to false, ObjectStore throws ObjectNotExportedException if it encounters a reference to a string in another segment and that string is not exported.

COM.odi.ObjectStoreLibrary specifies the name of the native library that contains the ObjectStore schema and native methods for the application. The name should follow platform conventions for library names. If you do not specify this property, ObjectStore uses the standard library, which provides for primary Java objects but not Java peer objects.

COM.odi.user and COM.odi.password allow you to supply a user name and a password when the ObjectStore Server has Name Password set for the Authentication Required Server parameter.

COM.odi.product allows you to specify which Object Design Java product you want to use. The advantage of COM.odi.product is that it allows you to write an application that copies data among PSE, PSE Pro, and ObjectStore databases. You can set this property to one of the following three values: PSE, PSEPro, or ObjectStore. To use any of these products, you must have the software in your CLASSPATH environment variable. When this property is not set, Object Design software looks for PSE Pro, then PSE, then ObjectStore, and uses the first product it finds.

The setting of COM.odi.product applies only to the session for which it is specified. After you start a session, you cannot change the value of COM.odi.product. An example of how to use this property is in the user guide.

COM.odi.queryDebugLevel allows you to control debugging output when you are using the PSE Pro query facility defined in the COM.odi.util.query.Query class. In PSE, this property does nothing.

The default level is 0, which does not output any information. Set the property to a value greater than 0 to print debugging output to System.err. As the value of this property increases, the query facility outputs more information as follows:

0 - No debugging information.

1 - Indexes that are required and that would be useful; statistics about indexed and nonindexed lookups.

5 - Query parser tree and query evaluation tree.

10 - Information about generated classes.

In PSE, this property does nothing.

COM.odi.stringPoolSize specifies the maximum size of the persistent string pool. The value of this property specifies the maximum number of newly created strings that ObjectStore can maintain in the string pool. If the number of newly created strings exceeds this number, only the ones that were most recently created and used are tracked by the pool. The default value is 100. value is 100. Before ObjectStore migrates a string into a segment, it checks the pool to see if a string with the same value is already available in the segment. If it is, the string is reused and ObjectStore does not create a new one. ObjectStore clears the pool at the start of each transaction. You can turn off the pooling mechanism by setting the value of this property to 0.

The COM.odi.trapUnregisteredType property is useful for troubleshooting ClassCastExceptions. The default is that this property is not set, and it is usually best to use the default.

When ObjectStore encounters a type for which it does not have information, it checks the setting of the COM.odi.trapUnregisteredType property.

If the property is not set, ObjectStore creates an instance of the UnregisteredType class to represent the unknown type. Your application continues to run as long as it does not try to use the UnregisteredType object. Often, this can be fine because your application has no need for that particular field. However, if you do try to use the unregistered type, ObjectStore throws ClassCastException.

If COM.odi.trapUnregisteredType is set, ObjectStore throws FatalApplicationException and provides a message that indicates the name of the unregistered class. See the user guide for additional information.

Returns:

The new global session.

Throws: ObjectStoreException

If there is an active session.

  public void terminate()

Terminates the session. This method does nothing if the session has already been terminated. Terminating a session causes all threads associated with the session to leave the session and all Database, Segment, and Transaction objects created in this session to have no associated session. If the session has an open database, ObjectStore closes it. Any thread that is joined to a session can terminate that session. The thread that creates the session does not have to be the thread that terminates the session.

  public void join()

Associates the calling thread with this session. This makes the calling thread and any threads that already belong to the session cooperating threads and it permits the calling thread to use the rest of the ObjectStore API.

Throws: ObjectStoreException

If the session was terminated or if the calling thread is already associated with a session, including if it is associated with this session.

  public static void leave()

Disassociates the calling thread from its associated session.

Throws: ObjectStoreException

If the thread is not currently associated with a session.

  public abstract Transaction currentTransaction()

Obtains the current transaction for this session.

Throws: ObjectStoreException

If this session was terminated.

Throws: NoTransactionInProgressException

If this session does not have a transaction in progress.

  public abstract boolean inTransaction()

Determines whether or not this session has a transaction in progress.

Returns:

The true constant if the session has a transaction in progress. The false constant if it does not.

Throws: ObjectStoreException

If this session was terminated.

  public static Session getGlobal()

Obtains the current global session.

Returns:

The global session or null if there is no global session.

  public final boolean isActive()

Indicates whether or not this session is active.

Returns:

The true constant if this session is active. The false constant if it was terminated.

  public static Enumeration activeSessions()

Obtains an enumeration of the active sessions at the time that the entrypoint is called. The return value is a snapshot of the active sessions. Sessions created after this entrypoint is called are not included in the enumeration. Sessions that are terminated after the entrypoint is called are still included in the enumeration.

Returns:

The enumeration of sessions that are active when the method was called.

  public abstract Segment segmentOfpreFlushContentsObject()

Call this method from a class's preFlushContents() method if preFlushContents() must be able to identify the object's segment. The correct segment is returned even when the object is in the process of being made persistent through transitive persistence. If there is more than one object currently being flushed due to a recursion, it returns the segment associated with the most recent active invocation of preFlushContents().

Returns:

The segment associated with the object being flushed.

Throws: NoTransactionInProgressException

If there is no transaction in progress.

Throws: ObjectStoreException

If this method is not invoked in the dynamic scope of a preFlushContents() call.

  public static Session getCurrent()

Obtains the session for the calling thread if it is associated with a session.

Returns:

The session for the calling thread or null if the calling thread is not associated with a session.

  public static Session ofThread(Thread thread)

Obtains the session associated with the specified thread.

Returns:

The session for the specified thread or null if the thread is not associated with a session.

Throws: IllegalArgumentException

If the thread argument is null.

  public final String getName()

Returns the name of the session.

  public static Session of(Object object)

Obtains the session associated with the specified persistent object. Returns null if the object is transient, stale, destroyed, or if the object's session has been terminated. The performance of this method is currently proportional to the number of sessions currently active.

Parameters:

object - A persistent object.

Returns:

The specified object's session or null.

  public abstract Properties getCounters(boolean reset)

Gets the internal counters and meters for the session.

Parameters:

reset - If true, resets the counters to 0.

Throws: ObjectStoreException

If the session has been terminated.