com.odi
Class Segment

java.lang.Object
  com.odi.Placement
      com.odi.Segment

All Implemented Interfaces:

ObjectStoreConstants

public abstract class Segment

extends Placement

implements ObjectStoreConstants

PSE/PSE Pro uses the Segment class to represent a segment in a database. Every segment has a number that is unique in the database. PSE/PSE Pro assigns this number and uses it as a segment ID, which identifies the segment.

When you are using PSE or PSE Pro, a database can have only one segment.

Field Summary

Fields inherited from interface com.odi.ObjectStoreConstants

ALL_EXECUTE, ALL_READ, ALL_WRITE, DEFAULT, DISABLE_AUTO_OPEN, GROUP_EXECUTE, GROUP_READ, GROUP_WRITE, INSTALL_SCHEMA_BATCH, INSTALL_SCHEMA_INCREMENTAL, MULTI_DB_MVCC, MVCC, OBJECTSTORE, OTHER_EXECUTE, OTHER_READ, OTHER_WRITE, OWNER_EXECUTE, OWNER_READ, OWNER_WRITE, PSE, PSE_PRO, READONLY, READONLY_NON_BLOCKING, RETAIN_HOLLOW, RETAIN_READONLY, RETAIN_STALE, RETAIN_TRANSIENT, RETAIN_UPDATE, UPDATE, UPDATE_NON_BLOCKING, WAIT_FOREVER, XA_TRANSACTION

Method Summary

abstract void	acquireLock(int lockType, int timeoutMillis) Attempts to acquire a lock on a segment
abstract boolean	clusterExists(int clusterId) Checks whether a cluster exists.
abstract Cluster	createCluster() Creates a new cluster in the segment if you are using ObjectStore, and not PSE or PSE Pro.
abstract void	destroy() Destroys a segment (not available in PSE or PSE Pro)
abstract Properties	GC() Collects garbage in the segment.
abstract Properties	GC(Properties GCProperties) Garbage collects the segment.
abstract Cluster	getCluster(int clusterId) Returns a handle to an existing cluster.
abstract Iterator	getClusters() Returns an iterator over the clusters in the segment.
abstract Database	getDatabase() Obtains the Database object associated with the database that contains the segment.
abstract Cluster	getDefaultCluster() Returns the default cluster for this segment.
abstract Iterator	getObjects() Returns an iterator over the objects in the segment.
abstract Iterator	getObjects(Class ofType) Returns an iterator over the objects that can be converted to the specified type in the segment.
abstract int	getSegmentId() Obtains the segment ID of a segment.
abstract long	getSizeInBytes() Obtains the number of bytes of storage occupied by the segment.
abstract boolean	isDestroyed() Determines whether or not the segment has been destroyed.
abstract boolean	isInternal() Determines if this is an internal segment.
static Segment	of(Object object) Obtains the segment that contains the object.
abstract void	setDefaultCluster(Cluster cluster) Sets the default cluster for this segment.

Methods inherited from class com.odi.Placement

getCluster, getSegment, getSession

Method Detail

destroy

public abstract void destroy()

Destroys a segment (not available in PSE or PSE Pro). This API is useful when you are using the Java interface to ObjectStore. When you are using PSE or PSE Pro there is never more than one segment in a database and you cannot destroy it.

Throws:

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

isDestroyed

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.

NoTransactionInProgressException - If there is no transaction in progress.

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.

getSegmentId

public abstract int getSegmentId()

Obtains the segment ID of a segment.

Returns:

The segment ID.

getDatabase

public abstract Database getDatabase()

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

Specified by:

getDatabase in class Placement

Returns:

The instance of Database associated with the database.

Throws:

DatabaseNotOpenException - If the database is not open.

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.

getSizeInBytes

public abstract long 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.

NoTransactionInProgressException - If there is no transaction in progress.

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.

SegmentNotFoundException - If the segment is not found.

isInternal

public abstract boolean isInternal()

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

Returns:

True if the segment is internal, otherwise false.

Throws:

DatabaseNotOpenException - If the database is not open.

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.

SegmentNotFoundException - If the segment is not found.

createCluster

public abstract Cluster createCluster()

Creates a new cluster in the segment if you are using ObjectStore, and not PSE or PSE Pro.

Returns:

The new cluster.

DatabaseNotOpenException - If the database is not open.

NoTransactionInProgressException - If a transaction is not in progress.

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.

SegmentException - If you are using PSE or PSE Pro. PSE and PSE Pro allow only one cluster for application data per segment (and one segment per database) and they create the allowed segment and cluster when they create a database.

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

getDefaultCluster

public abstract Cluster getDefaultCluster()

Returns the default cluster for this segment.

Throws:

DatabaseNotOpenException - If the database is not open.

NoTransactionInProgressException - If a transaction is not in progress.

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

SegmentNotFoundException - If the specified segment is not found.

ClusterNotFoundException - If the default cluster is not found.

setDefaultCluster

public abstract void setDefaultCluster(Cluster cluster)

Sets the default cluster for this segment. While this is not not useful in PSE and PSE Pro, because they allow only one cluster for application data, this method is provided for compatibility with ObjectStore. In PSE and PSE Pro, this method does nothing.

Parameters:

cluster - The cluster to make the default cluster.

DatabaseNotOpenException - If this database, or the database associated with the cluster argument, is not open.

SegmentNotFoundException - If the specified segment is not found.

ClusterNotFoundException - If the specified cluster is not found.

IllegalArgumentException - If the cluster parameter is null or is associated with a different segment or database.

NoTransactionInProgressException - If a transaction is not in progress.

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

getCluster

public abstract Cluster getCluster(int clusterId)

Returns a handle to an existing cluster. A call to getCluster() on a given segment with a given cluster ID always returns the same Cluster object.

Parameters:

clusterId - The cluster identifier.

Returns:

The cluster.

Throws:

DatabaseNotOpenException - If the database is not open.

NoTransactionInProgressException - If a transaction is not in progress.

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

ClusterNotFoundException - If the cluster is not found.

SegmentNotFoundException - If the segment is not found.

getClusters

public abstract Iterator getClusters()

Returns an iterator over the clusters in the segment. Use the Iterator methods to access each of the clusters. If you create a cluster after the call to getClusters(), the new cluster might or might not be in the iteration. If it is important that the iteration include the new segment, create the iterator again.

Returns:

The iterator over the clusters in the segment. This iterator is valid only until the end of the transaction. Subsequent access throws a StaleIteratorException. This iterator throws UnsupportedOperationException if its Iterator.remove() method is called.

DatabaseNotOpenException - If the database is not open.

SegmentNotFoundException - If the segment is destroyed.

NoTransactionInProgressException - If a transaction is not in progress.

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.

clusterExists

public abstract boolean clusterExists(int clusterId)

Checks whether a cluster exists.

Parameters:

clusterId - The cluster identifier.

Returns:

True if a cluster with that clusterId exists in this segment; false otherwise.

Throws:

DatabaseNotOpenException - If the database is not open.

NoTransactionInProgressException - If a transaction is not in progress.

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

SegmentNotFoundException - If the segment is not found.

of

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:

IllegalArgumentException - If the object argument is null.

NoTransactionInProgressException - If there is no transaction in progress.

ObjectException - If the object is stale.

ObjectNotPersistentException - If the object is not persistent.

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.

SegmentNotFoundException - If the segment is not found.

getObjects

public abstract Iterator getObjects()

Returns an iterator over the objects in the segment. Use the Iterator 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 iteration.

Returns:

The iterator over the objects in the segment. This iterator must be used within transactions. The iterator throws StaleIteratorException if it is used after being used in a transaction that is aborted.

Throws:

DatabaseNotOpenException - If the database is not open.

NoTransactionInProgressException - If a transaction is not in progress.

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.

SegmentNotFoundException - If the segment is not found.

getObjects

public abstract Iterator getObjects(Class ofType)

Returns an iterator over the objects that can be converted to the specified type in the segment. Use the Iterator 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 iteration.

The class type argument can be any class type, interface type, or array type. Because primitive types are stored using wrapper types, the type argument should not be a primitive type. For array types, the objects in the iteration 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 iterator over the objects in the segment. This iterator must be used within transactions. The iterator throws StaleIteratorException if it is used after being used in a transaction that is aborted.

Throws:

DatabaseNotOpenException - If the database is not open.

NoTransactionInProgressException - If a transaction is not in progress.

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.

SegmentNotFoundException - If the segment is not found.

IllegalArgumentException - If ofType is null.

GC

public abstract Properties GC()

Collects garbage in the segment. PSE/PSE Pro 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 PSE/PSE Pro is unable to open the database that contains the segment because of a file system access violation.

DatabaseNotFoundException - If the database that contains the segment does not exist.

DatabaseOpenException - If the database associated with the segment is open.

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.

TransactionException - If a transaction is in progress.

GC

public abstract Properties GC(Properties GCProperties)

Garbage collects the segment. PSE/PSE Pro 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 PSE/PSE Pro should use during garbage collection. A null value instructs the GC to use the default properties. The properties you can specify are

Returns:

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

Throws:

AccessViolationException - If PSE/PSE Pro is unable to open the database that contains the segment because of a file system access violation.

DatabaseNotFoundException - If the database that contains the segment does not exist.

DatabaseOpenException - If the database associated with the segment is open.

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.

TransactionException - If a transaction is in progress.

acquireLock

public abstract void acquireLock(int lockType,
                                 int timeoutMillis)

Attempts to acquire a lock on a segment. This method does nothing in PSE and PSE Pro.