com.odi
Class Session

java.lang.Object
  com.odi.Session

public abstract class Session

extends Object

A session allows the use of the PSE/PSE Pro API. PSE/PSE Pro uses the abstract com.odi.Session class to represent sessions.

Your application must create a session. After a session is created, it is an active session. A session remains active until your application or PSE/PSE Pro 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 PSE/PSE Pro API objects, such as an instance of the Transaction class and an instance of the Database class.

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

• PSE allows one session.
• PSE Pro and ObjectStore allow multiple sessions.

Field Summary

protected static int

numExpectedSessions An integer to hold the number of expected sessions.

Method Summary

static Enumeration	activeSessions() Obtains an enumeration of the active sessions at the time that the entrypoint is called.
static Session	create(String host, Properties properties) Creates a session that permits the caller to use the rest of the PSE/PSE Pro API.
static Session	create(String host, Properties properties, String name) Creates a session and allows you to specify a name for the session.
static Session	createGlobal(String host, Properties properties) Creates a global session, which permits the caller to use the rest of the PSE/PSE Pro API.
static Session	createSchemaEvolve(String host, int numThreads, int prefetchKB, int secondaryPSRSize, Properties properties) Creates sessions for schema evolve and returns the main session.
abstract Transaction	currentTransaction() Obtains the current transaction for this session.
abstract Properties	getCounters(boolean reset) Gets the internal counters and meters for the session.
static Session	getCurrent() Obtains the session for the calling thread if it is associated with a session.
static Session	getGlobal() Obtains the current global session.
String	getName() Returns the name of the session.
abstract Properties	getSessionProperties() Returns the properties associated with this session.
abstract String	getSessionProperty(String name) Returns a property associated with this session.
abstract boolean	inTransaction() Determines whether or not this session has a transaction in progress.
boolean	isActive() Indicates whether or not this session is active.
void	join() Associates the calling thread with this session.
static void	leave() Disassociates the calling thread from its associated session.
static Session	of(Object object) Obtains the session associated with the specified persistent object.
static Session	ofThread(Thread thread) Obtains the session associated with the specified thread.
IPersistent	remapObject(IPersistent persistentObject) Map a reference to a persistent object in some session, to a reference to an object in this session.
abstract Segment	segmentOfpreFlushContentsObject() Call this method from a class's preFlushContents() method if preFlushContents() must be able to identify the object's segment.
void	terminate() Terminates the session.
void	terminateSchemaEvolve() Terminate Schema Evolve sessions.

Field Detail

numExpectedSessions

protected static int numExpectedSessions

An integer to hold the number of expected sessions. This variable should be set before any session has been created.

Method Detail

create

public static Session create(String host,
                             Properties properties)

Creates a session that permits the caller to use the rest of the PSE/PSE Pro API. PSE/PSE Pro 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 global session. In PSE, this method throws FatalApplicationException if there is an active nonglobal session. In PSE Pro, multiple active nonglobal sessions are allowed.

In PSE Pro, a thread that belongs to a nonglobal session can call the Session.create() method to create another nonglobal session.

Parameters:

host - PSE/PSE Pro ignores this argument. Specify null.

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

All property values are strings, so if a property value is a Boolean, you must put true and false in double quotation marks.

You can specify the following properties:

• com.odi.disableCrossTransactionCaching
• com.odi.disableWeakReferences
• com.odi.disableSoftReferences
• com.odi.queryDebugLevel
• com.odi.stringPoolSize
• com.odi.trapUnregisteredType
• com.odi.useDatabaseLocking
• com.odi.useFsync
• com.odi.useImmediateStrings

com.odi.disableCrossTransactionCaching - A Boolean value that defaults to true. This means that PSE/PSE Pro makes retained objects hollow at the start of a new transaction. This is the same way that ObjectStore functions.

When this property is set to false, at the beginning of a new transaction, PSE/PSE Pro does not hollow objects whose contents were retained after a committed transaction. This means that after you commit a transaction with ObjectStore.RETAIN_READONLY or ObjectStore.RETAIN_UPDATE, you have access to all objects that you read or updated during the previous transaction. If you then start a new transaction, the contents of objects that were retained are not hollowed out. If you always retain object contents when you commit a transaction, you have access to all objects you read or updated in the current session.

This property will be deprecated in a future release when an API that performs a similar function is available.

com.odi.disableWeakReferences- A Boolean value that defaults to false. When you specify this property, PSE/PSE Pro does not use the weak reference facility.

com.odi.disableSoftReferences - A Boolean value that defaults to false. If set to true, the soft reference facility is not used by PSE/PSE Pro.

When you start the first session in a Java process, the setting of the com.odi.disableWeakReferences and com.odi.disableSoftReferences properties are 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 or com.odi.disableSoftReferences properties, the new values are ignored.

By default, the soft reference reference facility is used. If you want to use the weak reference reference facility, set the com.odi.disableSoftReferences property to true. To be able to use the strong reference facility, the com.odi.disableWeakReferences property should be set to true.

A weak or soft 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, PSE/PSE Pro uses weak or soft 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, PSE/PSE Pro uses a strong reference to hold the reference to the object. A strong reference prevents the object from being garbage collected.

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 PSE/PSE Pro 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. In PSE Pro, the default is 100. In PSE, the default is 0, that is, string pooling is disabled by default. In PSE, there is no persistent garbage collector and so string pooling might not be safe. Before PSE/PSE Pro 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 PSE/PSE Pro does not create a new one. PSE/PSE Pro 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.trapUnregisteredType - Used to troubleshoot for ClassCastExceptions. The default is that this property is not set, and it is usually best to use the default.

When PSE/PSE Pro 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, PSE/PSE Pro 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, PSE/PSE Pro throws ClassCastException.

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

com.odi.useDatabaseLocking - Allows you to turn cross-process locking off. By default, cross-process locking is turned on. This means that if a session has a database open, a session in another Java VM process cannot open that database. If a session tries to open a database that is already open in another process, PSE/PSE Pro throws com.odi.DatabaseLockedException.

com.odi.useFsync - A Boolean value that defaults to true. If it is false, disk buffers are not forced to disk from the underlying operating system buffers prior to commit. It is recommended that this be left at the default setting of true.

com.odi.useImmediateStrings - Specifies whether PSE/PSE Pro should attempt to store small Strings as immediate values. Immediate strings are enabled by default or if the value is set to true. Set the value to false to disable immediate strings.

If immediate strings are enabled, Strings of eight characters or less might not be stored as independent objects in the database, unless they are explicitly migrated. The result is smaller databases and elimination of the run-time overhead of tracking the Strings in the object table.

When immediate strings are in use, applications should not assume that Strings stored as the values of fields in persistent objects will themselves be persistent, unless the application explicitly calls ObjectStore.migrate() on the String.

Returns:

The new session.

Throws:

IllegalArgumentException - If the values for any of the specified properties are not valid values.

FatalApplicationException - If you are running PSE and there is an active session.

ObjectStoreException - If there is an active global session.

create

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 PSE/PSE Pro API. PSE/PSE Pro 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 global session. In PSE, this method throws FatalApplicationException if there is an active nonglobal session. In PSE Pro, multiple active nonglobal sessions are allowed.

In PSE Pro, a thread that belongs to a nonglobal session can call the Session.create() method to create another nonglobal session.

Parameters:

host - PSE/PSE Pro ignores this argument. Specify null.

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

All property values are strings, so if a property value is a Boolean, you must put true and false in double quotation marks.

You can specify the following properties:

• com.odi.disableCrossTransactionCaching
• com.odi.disableWeakReferences
• com.odi.disableSoftReferences
• com.odi.queryDebugLevel
• com.odi.stringPoolSize
• com.odi.trapUnregisteredType
• com.odi.useDatabaseLocking
• com.odi.useFsync
• com.odi.useImmediateStrings

com.odi.disableCrossTransactionCaching - A Boolean value that defaults to true. This means that PSE/PSE Pro makes retained objects hollow at the start of a new transaction. This is the same way that ObjectStore functions.

When this property is set to false at the beginning of a new transaction, PSE/PSE Pro does not hollow objects whose contents were retained after a committed transaction. This means that after you commit a transaction with ObjectStore.RETAIN_READONLY or ObjectStore.RETAIN_UPDATE, you have access to all objects that you read or updated during the previous transaction. If you then start a new transaction, the contents of objects that were retained are not hollowed out. If you always retain object contents when you commit a transaction, you have access to all objects you read or updated in the current session.

This property will be deprecated in a future release when an API that performs a similar function is available.

com.odi.disableWeakReferences - A Boolean value that defaults to false. When you specify this property, PSE/PSE Pro does not use the weak reference facility.

com.odi.disableSoftReferences - A Boolean value that defaults to false. If set to true, the soft reference facility is not used by PSE/PSE Pro.

By default, the soft reference reference facility is used. If you want to use the weak reference reference facility, set the com.odi.disableSoftReferences property to true. To be able to use the strong reference facility, the com.odi.disableWeakReferences property should be set to true.

When you start the first session in a Java process, the setting of the com.odi.disableWeakReferences and com.odi.disableSoftReferences properties are 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 or com.odi.disableSoftReferences properties, the new values are ignored.

A weak or soft 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, PSE/PSE Pro uses weak or soft 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, PSE/PSE Pro uses a strong reference to hold the reference to the object. A strong reference prevents the object from being garbage collected.

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 PSE/PSE Pro 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 PSE/PSE Pro 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 PSE/PSE Pro does not create a new one. PSE/PSE Pro 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 PSE/PSE Pro 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. In PSE Pro, the default is 100. In PSE, the default is 0, that is, string pooling is disabled by default. In PSE, there is no persistent garbage collector and so string pooling might not be safe. Before PSE/PSE Pro 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 PSE/PSE Pro does not create a new one. PSE/PSE Pro 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.trapUnregisteredType - Used to troubleshoot ClassCastExceptions. The default is that this property is not set, and it is usually best to use the default.

When PSE/PSE Pro 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, PSE/PSE Pro 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, PSE/PSE Pro throws ClassCastException.

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

com.odi.useDatabaseLocking - Allows you to turn cross-process locking off. By default, cross-process locking is turned on. This means that if a session has a database open, a session in another Java VM process cannot open that database. If a session tries to open a database that is already open in another process, PSE/PSE Pro throws com.odi.DatabaseLockedException.

com.odi.useFsync - A Boolean value that defaults to true. If it is false, disk buffers are not forced to disk from the underlying operating system buffers prior to commit. It is recommended that this be left at the default setting of true.

com.odi.useImmediateStrings - Specifies whether PSE/PSE Pro should attempt to store small Strings as immediate values. Immediate strings are enabled by default, or if the value is set to true. Set the value to false to disable immediate strings.

If immediate strings are enabled, Strings of eight characters or less might not be stored as independent objects in the database, unless they are explicitly migrated. The result is smaller databases and elimination of the runtime overhead of tracking the Strings in the object table.

When immediate strings are in use, applications should not assume that Strings stored as the values of fields in persistent objects will themselves be persistent, unless the application explicitly calls ObjectStore.migrate() on the String.

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

Returns:

The new session.

Throws:

FatalApplicationException - If you are running PSE and there is an active session.

IllegalArgumentException - If the values for any of the specified properties are not valid values.

ObjectStoreException - If there is an active global session.

createGlobal

public static Session createGlobal(String host,
                                   Properties properties)

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

• Any threads that call PSE/PSE Pro 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.

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

Parameters:

host - PSE/PSE Pro ignores this argument. Specify null.

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

All property values are strings, so if a property value is a Boolean, you must put true and false in double quotation marks.

You can specify the following properties:

• com.odi.disableCrossTransactionCaching
• com.odi.disableWeakReferences
• com.odi.disableSoftReferences
• com.odi.queryDebugLevel
• com.odi.stringPoolSize
• com.odi.trapUnregisteredType
• com.odi.useDatabaseLocking
• com.odi.useFsync
• com.odi.useImmediateStrings

com.odi.disableCrossTransactionCaching - Defaults to true. This means that PSE/PSE Pro makes retained objects hollow at the start of a new transaction. This is the same way that ObjectStore functions. When this property is set to false, at the beginning of a new transaction, PSE/PSE Pro does not hollow objects whose contents were retained after a committed transaction. This means that after you commit a transaction with ObjectStore.RETAIN_READONLY or ObjectStore.RETAIN_UPDATE, you have access to all objects that you read or updated during the previous transaction. If you then start a new transaction, the contents of objects that were retained are not hollowed out. If you always retain object contents when you commit a transaction, you have access to all objects you read or updated in the current session.

This property will be deprecated in a future release when an API that performs a similar function is available.

com.odi.disableWeakReferences is a Boolean value that defaults to false. When you specify this property, PSE/PSE Pro does not use the weak reference facility.

com.odi.disableSoftReferences - A Boolean value that defaults to false. If set to true, the soft reference facility is not used by PSE/PSE Pro.

By default, the soft reference reference facility is used. If you want to use the weak reference reference facility, set the com.odi.disableSoftReferences property to true. To be able to use the strong reference facility, the com.odi.disableWeakReferences property should be set to true.

When you start the first session in a Java process, the setting of the com.odi.disableWeakReferences and com.odi.disableSoftReferences properties are 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 or com.odi.disableSoftReferences properties, the new values are ignored.

A weak or soft 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, PSE/PSE Pro uses weak or soft 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, PSE/PSE Pro uses a strong reference to the reference to the object. A strong reference prevents the object from being garbage collected.

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 PSE/PSE Pro 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. In PSE Pro, the default is 100. In PSE, the default is 0, that is, string pooling is disabled by default. In PSE, there is no persistent garbage collector and so string pooling might not be safe. Before PSE/PSE Pro 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 PSE/PSE Pro does not create a new one. PSE/PSE Pro 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.trapUnregisteredType Used to troubleshoot ClassCastExceptions. The default is that this property is not set, and it is usually best to use the default.

When PSE/PSE Pro 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, PSE/PSE Pro 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, PSE/PSE Pro throws ClassCastException. If com.odi.trapUnregisteredType is set, PSE/PSE Pro throws FatalApplicationException and provides a message that indicates the name of the unregistered class. See the user guide for additional information.

com.odi.useDatabaseLocking - Allows you to turn cross process locking off. By default, cross-process locking is turned on. This means that if a session has a database open, a session in another Java VM process cannot open that database. If a session tries to open a database that is already open in another process, PSE/PSE Pro throws com.odi.DatabaseLockedException.

com.odi.useFsync - A Boolean value that defaults to true. If it is false, disk buffers are not forced to disk from the underlying operating system buffers prior to commit. It is recommended that this be left at the default setting of true.

com.odi.useImmediateStrings - Specifies whether PSE/PSE Pro should attempt to store small Strings as immediate values. Immediate strings are enabled by default, or if the value is set to true. Set the value to false to disable immediate strings.

If immediate strings are enabled, Strings of eight characters or less might not be stored as independent objects in the database, unless they are explicitly migrated. The result is smaller databases and elimination of the run-time overhead of tracking the Strings in the object table.

When immediate strings are in use, applications should not assume that Strings stored as the values of fields in persistent objects will themselves be persistent, unless the application explicitly calls ObjectStore.migrate() on the String.

Returns:

The new global session.

Throws:

IllegalArgumentException - If the values for any of the specified properties are not valid values.

ObjectStoreException - If there is an active global session.

createSchemaEvolve

public static Session createSchemaEvolve(String host,
                                         int numThreads,
                                         int prefetchKB,
                                         int secondaryPSRSize,
                                         Properties properties)

Creates sessions for schema evolve and returns the main session. (this method is not available in PSE/PSE Pro).

ObjectException - If the application is using PSE or PSE Pro.

terminate

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, PSE/PSE Pro 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.

terminateSchemaEvolve

public void terminateSchemaEvolve()

Terminate Schema Evolve sessions.

join

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 PSE/PSE Pro API. This api is a no-op if the calling thread is already joined to this session.

Throws:

WrongSessionException - If the calling thread is already associated with a different session.

NoSessionException - If the session was terminated.

leave

public static void leave()

Disassociates the calling thread from its associated session.

currentTransaction

public abstract Transaction currentTransaction()

Obtains the current transaction for this session.

Throws:

ObjectStoreException - If this session was terminated.

NoTransactionInProgressException - If this session does not have a transaction in progress.

inTransaction

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.

getGlobal

public static Session getGlobal()

Obtains the current global session.

Returns:

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

isActive

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.

activeSessions

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.

segmentOfpreFlushContentsObject

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.

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

getCurrent

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.

ofThread

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.

getName

public final String getName()

Returns the name of the session.

of

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 only proportional to the number of active sessions for non-IPersistent objects.

Parameters:

object - A persistent object.

Returns:

The specified object's session or null.

getCounters

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.

remapObject

public IPersistent remapObject(IPersistent persistentObject)

Map a reference to a persistent object in some session, to a reference to an object in this session. This method is useful for communicating the identity of objects across sessions. References to transient or null objects are returned unchanged.

Parameters:

persistentObject - an instance of a persistence-capable object.

Returns:

The instance of the persistent object in this session or null if persistentObject was null.

Throws:

ObjectNotFoundException - If the object was destroyed, or its segment or cluster was destroyed.

ObjectException - If the persistentObject reference is stale.

DatabaseNotOpenException - If the database containing the persistent object is not open in this session.

NoTransactionInProgressException - If no transaction is in progress in this session.

NoSessionException - If this session is not active.

getSessionProperties

public abstract Properties getSessionProperties()

Returns the properties associated with this session. The returned properties is not guaranteed to be a full listing of all the properties associated with this session. The session's properties cannot be changed by modifying the values in the returned list.

Returns:

properties of this session.

getSessionProperty

public abstract String getSessionProperty(String name)

Returns a property associated with this session.

Parameters:

name - the property name whose value is required.

Returns:

the value of the property