com.odi
Class ExternalReference

java.lang.Object
  com.odi.ExternalReference

All Implemented Interfaces:

Cloneable

public class ExternalReference

extends Object

implements Cloneable

An object of the ExternalReference class is a reference to a particular persistent object. An application can encode the contents of an external reference into a text string, a network message, or any other data structure, and later decode it back into an external reference, from which it can get the persistent Java object.

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

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

Constructor Summary

ExternalReference()
Constructs an ExternalReference that refers to the null reference.

ExternalReference(Database d, int segid, int cluid, int loc)
Constructs an ExternalReference with the specified contents.

ExternalReference(Object o)
Constructs an ExternalReference that refers to the specified object.

Method Summary

boolean	equals(Object obj) Two ExternalReference objects are considered to be equal if they both refer to the same underlying persistent object
static ExternalReference	fromString(String string) Take a string that encodes an external reference, and create and return a corresponding ExternalReference object.
int	getClusterId() Obtains the cluster ID of the cluster that contains the referenced persistent object.
Database	getDatabase() Obtains the database that contains the referenced persistent object, or null if the underlying object is null.
int	getLocation() Obtains the location of the referenced persistent object within its cluster.
Object	getObject() Obtains the persistent object refered to by this ExternalReference.
int	getSegmentId() Obtains the segment ID of the segment that contains the referenced persistent object.
int	hashCode() Returns a hashCode for this ExternalReference.
void	setClusterId(int cluid) Sets the cluster ID component of this external reference.
void	setDatabase(Database d) Sets the database component of this external reference.
void	setLocation(int loc) Sets the location component of this external reference.
void	setObject(Object o) Makes this ExternalReference refer to the specified persistent object.
void	setSegmentId(int segid) Sets the segment ID component of this external reference.
String	toString() Encodes this ExternalReference as a string.

Constructor Detail

ExternalReference

public ExternalReference()

Constructs an ExternalReference that refers to the null reference.

Throws:

NoTransactionInProgressException - If there is no transaction in progress.

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

ExternalReference

public ExternalReference(Object o)

Constructs an ExternalReference that refers to the specified object.

Parameters:

o - The object that this external reference refers to.

DatabaseNotOpenException - If the database is not open.

NoTransactionInProgressException - If there is no transaction in progress.

ObjectException - If the object is stale.

ObjectNotFoundException - If the object has been deleted.

ObjectNotPersistentException - The object is transient.

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.

ExternalReference

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

Constructs an ExternalReference with the specified contents.

Parameters:

d - The new database.

segid - The new segment ID.

cluid - The new cluster ID.

loc - The new location.

Method Detail

equals

public boolean equals(Object obj)

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

hashCode

public int hashCode()

Returns a hashCode for this ExternalReference.

getDatabase

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.

getSegmentId

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.

getClusterId

public int getClusterId()

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

Returns:

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

getLocation

public int getLocation()

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

Returns:

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

setDatabase

public void setDatabase(Database d)

Sets the database component of this external reference.

Parameters:

d - The new database.

setSegmentId

public void setSegmentId(int segid)

Sets the segment ID component of this external reference.

Parameters:

segid - The new segment ID.

setClusterId

public void setClusterId(int cluid)

Sets the cluster ID component of this external reference.

Parameters:

cluid - The new cluster ID.

setLocation

public void setLocation(int loc)

Sets the location component of this external reference.

Parameters:

loc - The new location.

getObject

public Object getObject()

Obtains the persistent object refered to by this ExternalReference.

Returns:

The persistent object refered to by this ExternalReference.

DatabaseNotOpenException - If the database is not open.

NoTransactionInProgressException - If no transaction is in progress.

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

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.

setObject

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.

DatabaseNotOpenException - If the database is not open.

NoTransactionInProgressException - If there is no transaction in progress and the Object argument is non-null.

ObjectException - If the object is stale.

ObjectNotFoundException - If the object has been deleted.

ObjectNotPersistentException - If the object is transient.

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.

toString

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.

fromString

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 PSE/PSE Pro is unable to read the database because of a file system access violation.

DatabaseException - If the database is not in a valid format.

DatabaseNotFoundException - If a database with that name does not exist.

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

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