|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object | +--com.odi.Session
A session allows the use of the ObjectStore API. ObjectStore 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 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:
| Field Summary | |
protected static int |
numExpectedSessions
An integer to hold the number of expected sessions. |
| Method Summary | |
static java.util.Enumeration |
activeSessions()
Obtains an enumeration of the active sessions at the time that the entrypoint is called. |
static Session |
create(java.lang.String host,
java.util.Properties properties)
Creates a session that permits the caller to use the rest of the ObjectStore API. |
static Session |
create(java.lang.String host,
java.util.Properties properties,
java.lang.String name)
Creates a session and allows you to specify a name for the session. |
static Session |
createGlobal(java.lang.String host,
java.util.Properties properties)
Creates a global session, which permits the caller to use the rest of the ObjectStore API. |
static Session |
createSchemaEvolve(java.lang.String host,
int numThreads,
int prefetchKB,
int secondaryPSRSize,
java.util.Properties properties)
Creates sessions for schema evolve and returns the main session. |
abstract Transaction |
currentTransaction()
Obtains the current transaction for this session. |
abstract java.util.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. |
java.lang.String |
getName()
Returns the name of the session. |
abstract java.util.Properties |
getSessionProperties()
Returns the properties associated with this session. |
abstract java.lang.String |
getSessionProperty(java.lang.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(java.lang.Object object)
Obtains the session associated with the specified persistent object. |
static Session |
ofThread(java.lang.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. |
| Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Field Detail |
protected static int numExpectedSessions
| Method Detail |
public static Session create(java.lang.String host,
java.util.Properties properties)
This method throws ObjectStoreException if there is an active global session. In ObjecStore, multiple active nonglobal sessions are allowed.
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.
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.addressSpaceSize - Specifies in bytes, the amount of C++ client address space available for the current session. The actual value used is the amount specified rounded up to the nearest 64 KB.
If the amount of address space requested is not available, an exception is signaled. If the addressSpaceSize property is not specified, the default amount of address space is determined by calls to ObjectStore.setNumExpectedSessions(), as well as the values of the OS_AS_SIZE and OS_DEFAULT_AS_PARTITION_ SIZE environment variables.
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. This property can only be set once - the first time a session is created. Any changes to this property after a session has been created are ignored.
com.odi.cachedObjectCount - Determines the maximum number of objects that are cached if caching is enabled. This value should be greater than 0. See com.odi.disableObjectCaching for more details on object caching. This property has no effect if caching is disabled.
com.odi.cachedObjectTransactionAge - Specifies the maximum number of transactions an object is retained in the cache. This value should lie between 1 and 255 (inclusive). A negative value for this property will result in an IllegalArgumentException being thrown and values greater than 255 will be converted to 255. See com.odi.disableObjectCaching for more details on object caching. This property has no effect if caching is disabled.
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.disableObjectCaching - Allows ObjectStore to decide whether to cache the contents of objects across transactions. When this property is set to false (the default), ObjectStore might choose to cache the contents of active objects when they are made hollow. When this property is set to true, ObjectStore does not cache the contents of objects across transactions.
When an active object is made hollow, ObjectStore might choose to cache the object by not calling the clearContents method on it. Objects that are in hollow states, but still have their contents from a prior transaction are considered to be cached. When a cached, hollow object is subsequently accessed, ObjectStore checks whether the object's contents are still valid. If the contents are valid, ObjectStore makes the object active without re-reading its contents from the database.
Using the false setting for this property has the advantage of improving the performance of your application by reducing the time needed to fetch objects. However, the disadvantage is that garbage collection is less effective. You might find that the performance of your application degrades over time as unaccessed objects are being cached across many transactions.
To determine whether your application is running slowly because too many objects are being cached, try setting the com.odi.disableObjectCaching property to true. If you see an improvement in performance, then you might want to reduce the number of cached objects either by specifying appropriate values for the com.odi.cachedObjectTransactionAge or com.odi.cachedObjectCount properties, or by decaching some cached objects using the following ObjectStore API methods that manipulate cached objects:
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 - 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 ObjectStore 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, ObjectStore 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:
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 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.
com.odi.useImmediateStrings - Specifies whether ObjectStore should attempt to store small Strings as immediates values. Immediate strings are disabled by default, or if the value is set to false. Set the value to true to enable immediate strings.
If you enable immediate strings, Strings of eight characters or 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.
Note that if you enable immediate strings, immediate string values are not understood by queries on com.odi.coll collections. Queries on com.odi.util collections are not affected by this limitation.
If a query on a com.odi.coll collection accesses a String stored as an immediate value, the query will interpret the String as a null object. If a class contains indexable fields, ObjectStore does not store immediate string values in any of the fields for that class. If there are classes with no indexable fields that you reference in queries on com.odi.coll collections and you enable immediate strings, you should call ClassInfo.setAllowsPeerQueries() on the ClassInfo for the class in question.
java.lang.IllegalArgumentException - If the values for any of the specified
properties are not valid values.
ObjectStoreException - If there is an active global session.
public static Session create(java.lang.String host,
java.util.Properties properties,
java.lang.String name)
In ObjectStore, multiple active nonglobal sessions are allowed.
In ObjectStore, a thread that belongs to a nonglobal session can call the Session.create() method to create another nonglobal session.
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.
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.addressSpaceSize - Specifies in bytes, the amount of C++ client address space available for the current session. The actual value used is the amount specified rounded up to the nearest 64 KB.
If the amount of address space requested is not available, an exception is signaled. If the addressSpaceSize property is not specified, the default amount of address space is determined by calls to ObjectStore.setNumExpectedSessions(), as well as the values of the OS_AS_SIZE and OS_DEFAULT_AS_PARTITION_ SIZE environment variables.
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. This property can only be set once - the first time a session is created. Any changes to this property after a session has been created are ignored.
com.odi.cachedObjectCount - Determines the maximum number of objects that are cached if caching is enabled. This value should be greater than 0. See com.odi.disableObjectCaching for more details on object caching. This property has no effect if caching is disabled.
com.odi.cachedObjectTransactionAge - Specifies the maximum number of transactions an object is retained in the cache. This value should lie between 1 and 255 (inclusive). A negative value for this property will result in an IllegalArgumentException being thrown and values greater than 255 will be converted to 255. See com.odi.disableObjectCaching for more details on object caching. This property has no effect if caching is disabled.
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.disableObjectCaching - Allows ObjectStore to decide whether to cache the contents of objects across transactions. When this property is set to false (the default), ObjectStore might choose to cache the contents of active objects when they are made hollow. When this property is set to true, ObjectStore does not cache the contents of objects across transactions.
When an active object is made hollow, ObjectStore might choose to cache the object by not calling the clearContents() method on it. Objects that are in hollow states, but still have their contents from a prior transaction are considered to be cached. When a cached, hollow object is subsequently accessed, ObjectStore checks whether the object's contents are still valid. If the contents are valid, ObjectStore makes the object active without re-reading its contents from the database.
Using the false setting for this property has the advantage of improving the performance of your application by reducing the time needed to fetch objects. However, the disadvantage is that garbage collection is less effective. You might find that the performance of your application degrades over time as unaccessed objects are being cached across many transactions.
To determine whether your application is running slowly because too many objects are being cached, try setting the com.odi.disableObjectCaching property to true. If you see an improvement in performance, then you might want to reduce the number of cached objects either by specifying appropriate values for the com.odi.cachedObjectTransactionAge or com.odi.cachedObjectCount properties, or by decaching some cached objects using the following ObjectStore API methods that manipulate cached objects:
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.
com.odi.migrateUnexportedStrings - 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 ObjectStore 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, ObjectStore software looks for PSE Pro, then PSE, then ObjectStore, and uses the first product it finds.
The setting of com.odi.product property 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:
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 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.
com.odi.useImmediateStrings - Specifies whether ObjectStore should attempt to store small Strings as immediates values. Immediate strings are disabled by default, or if the value is set to false. Set the value to true to enable immediate strings.
If you enable immediate strings, Strings of eight characters 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.
Note that if you enable immediate strings, immediate string values are not understood by queries on com.odi.coll collections. Queries on com.odi.util collections are not affected by this limitation.
If a query on a com.odi.coll collection accesses a String stored as an immediate value, the query will interpret the String as a null object. If a class contains indexable fields, ObjectStore does not store immediate string values in any of the fields for that class. If there are classes with no indexable fields that you reference in queries on com.odi.coll collections and you enable immediate strings, you should call ClassInfo.setAllowsPeerQueries() on the ClassInfo for the class in question.
name - The name of the session. If the name is null, then a unique
name is generated.
java.lang.IllegalArgumentException - If the values for any of the specified
properties are not valid values.ObjectStoreException - If there is an active global session.
public static Session createGlobal(java.lang.String host,
java.util.Properties properties)
This method throws an exception if there is an active session.
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.
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.addressSpaceSize - Specifies in bytes, the amount of C++ client address space available for the current session. The actual value used is the amount specified rounded up to the nearest 64 KB.
If the amount of address space requested is not available, an exception is signaled. If the addressSpaceSize property is not specified, the default amount of address space is determined by calls to ObjectStore.setNumExpectedSessions(), as well as the values of the OS_AS_SIZE and OS_DEFAULT_AS_PARTITION_ SIZE environment variables.
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. This property can only be set once - the first time a session is created. Any changes to this property after a session has been created are ignored.
com.odi.cachedObjectCount - Determines the maximum number of objects that are cached if caching is enabled. This value should be greater than 0. See com.odi.disableObjectCaching for more details on object caching. This property has no effect if caching is disabled.
com.odi.cachedObjectTransactionAge - Specifies the maximum number of transactions an object is retained in the cache. This value should lie between 1 and 255 (inclusive). A negative value for this property will result in an IllegalArgumentException being thrown and values greater than 255 will be converted to 255. See com.odi.disableObjectCaching for more details on object caching. This property has no effect if caching is disabled.
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.disableObjectCaching - Allows ObjectStore to decide whether to cache the contents of objects across transactions. When this property is set to false (the default), ObjectStore might choose to cache the contents of active objects when they are made hollow. When this property is set to true, ObjectStore does not cache the contents of objects across transactions.
When an active object is made hollow, ObjectStore might choose to cache the object by not calling the clearContents() method on it. Objects that are in hollow states, but still have their contents from a prior transaction are considered to be cached. When a cached, hollow object is subsequently accessed, ObjectStore checks whether the object's contents are still valid. If the contents are valid, ObjectStore makes the object active without re-reading its contents from the database.
Using the false setting for this property has the advantage of improving the performance of your application by reducing the time needed to fetch objects. However, the disadvantage is that garbage collection is less effective. You might find that the performance of your application degrades over time as unaccessed objects are being cached across many transactions.
To determine whether your application is running slowly because too many objects are being cached, try setting the com.odi.disableObjectCaching property to true. If you see an improvement in performance, then you might want to reduce the number of cached objects either by specifying appropriate values for the com.odi.cachedObjectTransactionAge or com.odi.cachedObjectCount properties, or by decaching some cached objects using the following ObjectStore API methods that manipulate cached objects:
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.
com.odi.migrateUnexportedStrings - 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 ObjectStore 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, ObjectStore 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:
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.trapUnregisteredType Used to troubleshoot 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.
com.odi.useImmediateStrings - Specifies whether ObjectStore should attempt to store small Strings as immediates values. Immediate strings are disabled by default, or if the value is set to false. Set the value to true to enable immediate strings.
If you enable immediate strings, 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.
Note that if you enable immediate strings, immediate string values are not understood by queries on com.odi.coll collections. Queries on com.odi.util collections are not affected by this limitation.
If a query on a com.odi.coll collection accesses a String stored as an immediate value, the query will interpret the String as a null object. If a class contains indexable fields, ObjectStore does not store immediate string values in any of the fields for that class. If there are classes with no indexable fields that you reference in queries on com.odi.coll collections and you enable immediate strings, you should call ClassInfo.setAllowsPeerQueries() on the ClassInfo for the class in question.
java.lang.IllegalArgumentException - If the values for any of the specified
properties are not valid values.ObjectStoreException - If there is an active global session.
public static Session createSchemaEvolve(java.lang.String host,
int numThreads,
int prefetchKB,
int secondaryPSRSize,
java.util.Properties properties)
host - ObjectStore ignores this argument. Specify null. numThreads - Number of threads to create for schema
evolution. Default is 3/2 the number of CPUs in the system. prefetchKB - Size of data to prefetch(in KB).
Default is 1024 KB. secondaryPSRSize - Size of secondary session PSR
in MB. Default is 16 MB. 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.
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.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. This property can only be set once - the first time a session is created. Any changes to this property after a session has been created are ignored.
com.odi.cachedObjectCount - Determines the maximum number of objects that are cached if caching is enabled. This value should be greater than 0. See com.odi.disableObjectCaching for more details on object caching. This property has no effect if caching is disabled.
com.odi.cachedObjectTransactionAge - Specifies the maximum number of transactions an object is retained in the cache. This value should lie between 1 and 255 (inclusive). A negative value for this property will result in an IllegalArgumentException being thrown and values greater than 255 will be converted to 255. See com.odi.disableObjectCaching for more details on object caching. This property has no effect if caching is disabled.
com.odi.disableObjectCaching - Allows ObjectStore to decide whether to cache the contents of objects across transactions. When this property is set to false (the default), ObjectStore might choose to cache the contents of active objects when they are made hollow. When this property is set to true, ObjectStore does not cache the contents of objects across transactions.
When an active object is made hollow, ObjectStore might choose to cache the object by not calling the clearContents() method on it. Objects that are in hollow states, but still have their contents from a prior transaction are considered to be cached. When a cached, hollow object is subsequently accessed, ObjectStore checks whether the object's contents are still valid. If the contents are valid, ObjectStore makes the object active without re-reading its contents from the database.
Using the false setting for this property has the advantage of improving the performance of your application by reducing the time needed to fetch objects. However, the disadvantage is that garbage collection is less effective. You might find that the performance of your application degrades over time as unaccessed objects are being cached across many transactions.
To determine whether your application is running slowly because too many objects are being cached, try setting the com.odi.disableObjectCaching property to true. If you see an improvement in performance, then you might want to reduce the number of cached objects either by specifying appropriate values for the com.odi.cachedObjectTransactionAge or com.odi.cachedObjectCount properties, or by decaching some cached objects using the following ObjectStore API methods that manipulate cached objects:
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. 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.
com.odi.migrateUnexportedStrings - 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.
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:
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 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.
com.odi.useImmediateStrings - Specifies whether ObjectStore should attempt to store small Strings as immediates values. Immediate strings are disabled by default, or if the value is set to false. Set the value to true to enable immediate strings.
If you enable immediate strings, 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.
Note that if you enable immediate strings, immediate string values are not understood by queries on com.odi.coll collections. Queries on com.odi.util collections are not affected by this limitation.
If a query on a com.odi.coll collection accesses a String stored as an immediate value, the query will interpret the String as a null object. If a class contains indexable fields, ObjectStore does not store immediate string values in any of the fields for that class. If there are classes with no indexable fields that you reference in queries on com.odi.coll collections and you enable immediate strings, you should call ClassInfo.setAllowsPeerQueries() on the ClassInfo for the class in question.
java.lang.IllegalArgumentException - If the values for any of the specified
properties are not valid values.
ObjectException - If the application is using PSE or PSE Pro.public void terminate()
public void terminateSchemaEvolve()
public void join()
WrongSessionException - If the calling thread is already associated
with a different session.NoSessionException - If the session was terminated.public static void leave()
public abstract Transaction currentTransaction()
ObjectStoreException - If this session was terminated.NoTransactionInProgressException - If this session does not have a
transaction in progress.public abstract boolean inTransaction()
ObjectStoreException - If this session was terminated.public static Session getGlobal()
public final boolean isActive()
public static java.util.Enumeration activeSessions()
public abstract Segment segmentOfpreFlushContentsObject()
NoTransactionInProgressException - If there is no transaction
in progress.ObjectStoreException - If this method is not invoked in the dynamic
scope of a preFlushContents() call.public static Session getCurrent()
public static Session ofThread(java.lang.Thread thread)
java.lang.IllegalArgumentException - If the thread argument is null.public final java.lang.String getName()
public static Session of(java.lang.Object object)
object - A persistent object. public abstract java.util.Properties getCounters(boolean reset)
reset - If true, resets the counters to 0.ObjectStoreException - If the session has been terminated.public IPersistent remapObject(IPersistent persistentObject)
persistentObject - an instance of a persistence-capable object.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.public abstract java.util.Properties getSessionProperties()
public abstract java.lang.String getSessionProperty(java.lang.String name)
name - the property name whose value is required.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||