Class COM.odi.Segment

java.lang.Object
   |
   +----COM.odi.Placement
           |
           +----COM.odi.Segment

public class Segment

extends Placement

implements ObjectStoreConstants

Segment is an abstract class. When you invoke the Segment.of(), Database.getSegment(), or Database.createSegment() method, ObjectStore automatically finds the subclass of Segment, creates an instance of that subclass, and uses it to represent the segment.

acquireLock(int, int)

Attempts to acquire a lock on a segment.

destroy()

Destroys a segment (not available in PSE or PSE Pro).

GC()

Collects garbage in the segment.

GC(Properties)

Garbage collects the segment.

getDatabase()

Obtains the Database object associated with the database that contains the segment.

getObjects()

Returns an enumeration of the objects in the segment.

getObjects(Class)

Returns an enumeration of the objects that can be converted to the specified type in the segment.

getSegmentId()

Obtains the segment ID of a segment.

getSizeInBytes()

Obtains the number of bytes of storage occupied by the segment.

isDestroyed()

Determines whether or not the segment has been destroyed.

isInternal()

Determines if this is an internal segment.

of(Object)

Obtains the segment that contains the object.

  public abstract void destroy()

Destroys a segment (not available in PSE or PSE Pro). If an application tries to call a method on a segment that has been destroyed, ObjectStore throws SegmentNotFoundException. Destroying a segment causes any objects stored in that segment to become inaccessible. If you try to access an object in a destroyed segment, ObjectStore throws ObjectNotFoundException. You cannot recover a destroyed segment.

If you destroy a segment and then abort the transaction in which you destroyed the segment, this undoes the destruction of the segment.

Throws: DatabaseNotOpenException

If the database is not open.

Throws: NoTransactionInProgressException

If there is no transaction in progress.

Throws: ObjectStoreException

If the session implied by the segment has been terminated or if the current thread is associated with a session other than the session implied by the segment.

Throws: SegmentException

If you are using PSE or PSE Pro, or if this is the transient segment or an internal segment.

Throws: SegmentNotFoundException

If the segment is not found, perhaps because it was already destroyed.

Throws: UpdateReadOnlyException

If there is a read-only transaction in progress or if the database is open for read-only.

  public abstract boolean isDestroyed()

Determines whether or not the segment has been destroyed.

Returns:

The true constant if the segment has been destroyed. The false constant if it has not been destroyed.

Throws: DatabaseNotOpenException

If the database is not open.

Throws: NoTransactionInProgressException

If there is no transaction in progress.

Throws: ObjectStoreException

If the session implied by the segment has been terminated or if the current thread is associated with a session other than the session implied by the segment.

  public abstract int getSegmentId()

Obtains the segment ID of a segment.

Returns:

The segment ID.

  public abstract Database getDatabase()

Obtains the Database object associated with the database that contains the segment.

Returns:

The instance of Database associated with the database.

Throws: DatabaseNotOpenException

If the database is not open.

Throws: ObjectStoreException

If the session implied by the segment has been terminated or if the current thread is associated with a session other than the session implied by the segment.

  public abstract int getSizeInBytes()

Obtains the number of bytes of storage occupied by the segment.

Returns:

The number of bytes of storage.

Throws: DatabaseNotOpenException

If the database is not open.

Throws: NoTransactionInProgressException

If there is no transaction in progress.

Throws: ObjectStoreException

If the session implied by the segment has been terminated or if the current thread is associated with a session other than the session implied by the segment.

Throws: SegmentException

If this is the transient segment.

Throws: SegmentNotFoundException

If the segment is not found.

  public abstract boolean isInternal()

Determines if this is an internal segment. Internal segments are used to store schema information in ObjectStore and cannot be modified.

Returns:

True if the segment is internal, otherwise false.

Throws: DatabaseNotOpenException

If the database is not open.

Throws: ObjectStoreException

If the session implied by the segment has been terminated or if the current thread is associated with a session other than the session implied by the segment.

Throws: SegmentNotFoundException

If the segment is not found.

  public static Segment of(Object object)

Obtains the segment that contains the object.

Parameters:

object - A persistent object in the segment you want to obtain.

Returns:

The instance of Segment that represents the segment that contains the specified object.

Throws: DatabaseNotOpenException

If the database is not open.

Throws: IllegalArgumentException

If the object argument is null.

Throws: NoTransactionInProgressException

If there is no transaction in progress.

Throws: ObjectException

If the object is stale.

Throws: ObjectNotPersistentException

If the object is not persistent.

Throws: ObjectStoreException

If the session implied by the segment has been terminated or if the current thread is associated with a session other than the session implied by the segment.

Throws: SegmentNotFoundException

If the segment is not found.

  public abstract SegmentObjectEnumeration getObjects()

Returns an enumeration of the objects in the segment. Use the SegmentObjectEnumeration methods to access each of the objects. If you add an object to the segment after the call to getObjects(), the new object might or might not be in the enumeration.

Returns:

The enumeration of the objects in the segment. This enumeration must be used within transactions. The enumeration throws StaleEnumeratorException if it is used after being used in a transaction that is aborted.

Throws: DatabaseNotOpenException

If the database is not open.

Throws: NoTransactionInProgressException

If a transaction is not in progress.

Throws: ObjectStoreException

If the session implied by the segment has been terminated or if the current thread is associated with a session other than the session implied by the segment.

Throws: SegmentException

If this is the transient segment.

Throws: SegmentNotFoundException

If the segment is not found.

See Also:

SegmentObjectEnumeration

  public abstract SegmentObjectEnumeration getObjects(Class ofType)

Returns an enumeration of the objects that can be converted to the specified type in the segment. Use the SegmentObjectEnumeration methods to access each of the objects. If you add an object to the segment after the call to getObjects(), the new object might or might not be in the enumeration.

The class type argument can be any class type, interface type, or array type. Since primitive types are stored using wrapper types, the type argument should not be a primitive type. For array types, the objects in the enumeration are all arrays of the element type (or types that can be converted to this type) regardless of the dimension of the array.

Returns:

The enumeration of the objects in the segment. This enumeration must be used within transactions. The enumeration throws StaleEnumeratorException if it is used after being used in a transaction that is aborted.

Throws: DatabaseNotOpenException

If the database is not open.

Throws: NoTransactionInProgressException

If a transaction is not in progress.

Throws: ObjectStoreException

If the session implied by the segment has been terminated or if the current thread is associated with a session other than the session implied by the segment.

Throws: SegmentException

If this is the transient segment.

Throws: SegmentNotFoundException

If the segment is not found.

Throws: IllegalArgumentException

If ofType is null.

See Also:

SegmentObjectEnumeration

  public abstract Properties GC()

Collects garbage in the segment. ObjectStore destroys objects that are unreachable through references in the database and makes their storage available for the allocation of new persistent objects. The database that contains the segment must be closed.

Returns:

A Properties object that contains information about the results of the GC.

Throws: AccessViolationException

If ObjectStore is unable to open the database that contains the segment because of a file system access violation.

Throws: DatabaseNotFoundException

If the database that contains the segment does not exist.

Throws: DatabaseOpenException

If the database associated with the segment is open.

Throws: SegmentException

If this is the transient segment or an internal segment.

Throws: SegmentNotFoundException

If the segment is not found, perhaps because it was destroyed.

Throws: ObjectStoreException

If the session implied by the segment has been terminated or if the current thread is associated with a session other than the session implied by the segment.

Throws: TransactionException

If a transaction is in progress.

  public abstract Properties GC(Properties GCProperties)

Garbage collects the segment. ObjectStore destroys objects that are unreachable through references in the database and makes their storage available for the allocation of new persistent objects. The database that contains the segment must be closed.

Parameters:

GCProperties - Specifies the properties ObjectStore should use during garbage collection. A null value instructs the GC to use the default properties. The properties you can specify are int COM.odi.gc.retries specifies the number of times the GC trys to resume the sweep operation if it runs into a lock conflict as it tries to update the segment. The default is 10.

int COM.odi.gc.retryInterval specifies the number of milliseconds the sweep operation waits before it tries to resume a sweep. The default is 1000 milliseconds.

int COM.odi.gc.lockTimeOut specifies the number of milliseconds before the sweep operation times out on a lock conflict. The default is 1000 milliseconds.

int COM.odi.gc.transactionPriority specifies the transaction priority the GC uses when it selects a victim in a deadlock. The default is 0.

int COM.odi.gc.displayGarbage if not zero, objects that are unreachable are not destroyed, but are displayed instead. The argument controls the detail: 0 - no display (the default) 1 - list the total number of garbage objects 2 - list GC object totals by type (not supported) 3 - list the location of every garbage object 4 - list the roots of garbage object graphs.

Returns:

A Properties object that contains information about the results of the GC.

The properties in this object are int COM.odi.gc.reclaimedObjects indicates the number of objects reclaimed by the GC.
int COM.odi.gc.reachableObjects indicates the number of objects found to be reachable by the GC.

Throws: AccessViolationException

If ObjectStore is unable to open the database that contains the segment because of a file system access violation.

Throws: DatabaseNotFoundException

If the database that contains the segment does not exist.

Throws: DatabaseOpenException

If the database associated with the segment is open.

Throws: SegmentException

If this is the transient segment or an internal segment.

Throws: SegmentNotFoundException

If the segment is not found, perhaps because it was destroyed.

Throws: ObjectStoreException

If the session implied by the segment has been terminated or if the current thread is associated with a session other than the session implied by the segment.

Throws: TransactionException

If a transaction is in progress.

  public abstract void acquireLock(int lockType,
                                   int timeoutMillis)

Attempts to acquire a lock on a segment. Locking a segment is equivalent to locking all the objects in the segment.

To release the lock, end the transaction in which you acquired the lock. It is not possible to release a lock during a transaction.

Parameters:

lockType - The lock type. One of ObjectStore.READONLY or ObjectStore.UPDATE.

timeoutMillis - The number of milliseconds to wait when attempting to acquire the lock. Specifying 0 means only acquire the lock if no waiting is needed. Other positive values are rounded up to the nearest number of seconds and specify the number of milliseconds to wait for the lock to become available. Specifying the constant ObjectStore.WAIT_FOREVER means to wait until the lock becomes available.

Throws: DatabaseNotOpenException

If the database containing the object is not open.

Throws: IllegalArgumentException

If the object argument is null, if the lockType is not one of ObjectStore.READONLY or ObjectStore.UPDATE, or if the timeoutMillis argument is a negative number other than ObjectStore.WAIT_FOREVER.

Throws: LockTimeoutException

If it is not possible to acquire the lock within the specified timeout.

Throws: NoTransactionInProgressException

If there is no transaction in progress.

Throws: ObjectStoreException

If the session implied by the segment has been terminated or if the current thread is associated with a session other than the session implied by the segment.

Throws: SegmentNotFoundException

If the segment is destroyed.

Throws: UpdateReadOnlyException

If the lockType argument is ObjectStore.UPDATE and either there is a read-only transaction in progress or the database is open read-only.