Class COM.odi.ExternalReference

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

public class ExternalReference

extends Object

implements Cloneable

You can use external references across transaction boundaries. They remain valid even if the database holding the referenced object is closed and opened.

However, external references to nonexported objects are not valid if the segment holding the referenced object has been reorganized, for example, a compaction tool has been run on the segment. To ensure that its encoded external references are still valid, an application must either only use external references to exported objects, or ensure that no reorgnization tools are run on the relevant segments.

Like other objects such as objects of class Database and Segment, an ExternalReference object can only be used in one session.

ExternalReference()

Constructs an ExternalReference that refers to the null reference.

ExternalReference(Database, int, int)

Constructs an ExternalReference with the specified contents.

ExternalReference(Object)

Constructs an ExternalReference that refers to the specified object.

equals(Object)

Two ExternalReference objects are considered to be equal if they both refer to the same underlying persistent object.

fromString(String)

Take a string that encodes an external reference, and create and return a corresponding ExternalReference object.

getDatabase()

Obtains the database that contains the referenced persistent object, or null if the underlying object is null.

getLocation()

Obtains the location of the referenced persistent object within its segment.

getObject()

Obtains the persistent object refered to by this ExternalReference.

getSegmentId()

Obtains the segment ID of the segment that contains the referenced persistent object.

hashCode()

Returns a hashCode for this ExternalReference.

setDatabase(Database)

Sets the database component of this external reference.

setLocation(int)

Sets the location component of this external reference.

setObject(Object)

Makes this ExternalReference refer to the specified persistent object.

setSegmentId(int)

Sets the segment ID component of this external reference.

toString()

Encodes this ExternalReference as a string.

  public ExternalReference()

Constructs an ExternalReference that refers to the null reference.

Throws: NoTransactionInProgressException

If there is no transaction in progress.

Throws: ObjectStoreException

If the current thread does not belong to a session and there is no global session.

  public ExternalReference(Object o)

Constructs an ExternalReference that refers to the specified object.

Parameters:

o - The object that this external reference refers to. You can specify a Java peer object if it identifies a persistent C++ object.

Throws: DatabaseException

If the object belongs to the transient segment; in other words, if the object is a Java peer object that identifies a transient C++ object.

Throws: DatabaseNotOpenException

If the database is not open.

Throws: NoTransactionInProgressException

If there is no transaction in progress.

Throws: ObjectException

If the object is stale.

Throws: ObjectNotFoundException

If the object has been deleted.

Throws: ObjectNotPersistentException

The object is transient.

Throws: ObjectStoreException

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

  public ExternalReference(Database d,
                           int segid,
                           int loc)

Constructs an ExternalReference with the specified contents.

Parameters:

d - The new database.

segid - The new segment ID.

loc - The new location.

  public boolean equals(Object obj)

Two ExternalReference objects are considered to be equal if they both refer to the same underlying persistent object.

Overrides:

equals in class Object

  public int hashCode()

Returns a hashCode for this ExternalReference.

Overrides:

hashCode in class Object

  public Database getDatabase()

Obtains the database that contains the referenced persistent object, or null if the underlying object is null.

Returns:

The database that contains the underlying persistent object.

  public int getSegmentId()

Obtains the segment ID of the segment that contains the referenced persistent object.

Returns:

The segment ID of the segment that contains the underlying persistent object or -1 if the underlying object is null.

  public int getLocation()

Obtains the location of the referenced persistent object within its segment.

Returns:

The location of the underlying persistent object within its segment, or -1 if the underlying object is null.

  public void setDatabase(Database d)

Sets the database component of this external reference.

Parameters:

d - The new database.

  public void setSegmentId(int segid)

Sets the segment ID component of this external reference.

Parameters:

segid - The new segment ID.

  public void setLocation(int loc)

Sets the location component of this external reference.

Parameters:

loc - The new location.

  public Object getObject()

Obtains the persistent object refered to by this ExternalReference.

Returns:

The persistent object refered to by this ExternalReference.

Throws: DatabaseException

If this is the transient database.

Throws: DatabaseNotOpenException

If the database is not open.

Throws: NoTransactionInProgressException

If no transaction is in progress.

Throws: ObjectNotFoundException

If the object was destroyed, or its segment was destroyed, or the contents of this object are not valid (for example, the segment ID is negative).

Throws: ObjectStoreException

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

Throws: SegmentException

If the Database is the transient database.

  public void setObject(Object o)

Makes this ExternalReference refer to the specified persistent object.

Parameters:

o - The object that this external reference should refer to.

Throws: DatabaseException

If the object belongs to the transient segment. In other words, if the object is a Java peer object that identifies a transient C++ object.

Throws: DatabaseNotOpenException

If the database is not open.

Throws: NoTransactionInProgressException

If there is no transaction in progress.

Throws: ObjectException

If the object is stale.

Throws: ObjectNotFoundException

If the object has been deleted.

Throws: ObjectNotPersistentException

If the object is transient.

Throws: ObjectStoreException

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

  public String toString()

Encodes this ExternalReference as a string.

Returns:

The string encoding of this object.

Throws: ObjectStoreException

If the database's path name contains a vertical-bar character.

Overrides:

toString in class Object

  public static ExternalReference fromString(String string)

Take a string that encodes an external reference, and create and return a corresponding ExternalReference object. Open the object's database in ObjectStore.DEFAULT mode.

Parameters:

string - A string that encodes an external reference, with the encoding used by ExternalReference.toString.

Returns:

A new ExternalReference object.

Throws: AccessViolationException

If ObjectStore is unable to read the database because of a file system access violation.

Throws: DatabaseException

If the database is not in a valid format.

Throws: DatabaseNotFoundException

If a database with that name does not exist.

Throws: IllegalArgumentException

If the string is not a proper encoding of an external reference.

Throws: NoTransactionInProgressException

If no transaction is in progress.

Throws: ObjectStoreException

If the current thread is not associated with a session and there is no global session.