com.objy.db.iapp
Interface PooObj

All Superinterfaces:

PHasSession, PRoot

All Known Subinterfaces:

PooContObj, PooMap

public interface PooObj

extends PHasSession

Defines the behavior shared by all persistors.

Persistors

Every persistent object has an associated internal object called a persistor. Objectivity for Java creates a persistor when a transient object is made persistent and when an existing persistent object is retrieved from the database. During its lifetime, a persistent object may have different persistors; a null persistor indicates that the object is transient; a dead persistor indicates that the object is dead.

A persistor contains all the internal database state for a persistent object. A persistent object delegates all persistence operation requests to its persistor.

Note: Persistors should never be shared. A persistor's methods should be called only by its persistent object and Objectivity for Java. If an object of a persistence-capable class is transient or a dead object, its persistor should not be accessed; calling methods of the persistor may have unexpected results.

If you define your own persistence-capable classes that do not derive from ooObj, methods of your classes should ensure that persistor methods are called only when appropriate. In particular, these methods should verify that the object is persistent and not dead before calling any methods of its persistor that perform persistence operations.

API Summary

Functionality

Locking	lock(int) lockNoProp(int)
Fetching Persistent Data	fetch() fetch(int) markModified() clearModified() markFetchRequired() isFetchRequired()
Modifying	markModified() move(Object) delete() deleteNoProp() clearModified() write()
Copying	copy(Object)
Getting Information	getContainer() getSession() getOid()
Testing	isPersistent() isModified() isFetchRequired() isValid() isDead()
Clustering	cluster(Object)
Working With Scope-Named Objects	nameObj(Object, String) unnameObj(Object) lookupObj(String) lookupObj(String, int) lookupObjName(Object) scopedObjects()
Finding Scope Objects	scopedBy()
Working With Indexes	updateIndexes()

Method Summary

void	clearModified() Removes the modified mark from this persistor's object.
void	cluster(Object object) Makes the specified object persistent, clustering it near this persistor's object.
int	compareOoId(PooObj obj) Reserved for internal use; you should not call this method.
Object	copy(Object o) Copies this persistor's object (a basic object), clustering the new object with the specified object.
void	delete() Deletes this persistor's object from the database and propagates the deletion operation to related objects.
void	deleteNoProp() Deletes this persistor's object from the database.
void	deleteReference(Object objectReference) Reserved for internal use; you should not call this method.
void	dropCachedReference(Object objectReference) Reserved for internal use; you should not call this method.
void	fetch() Locks this persistor's object for read and fetches its persistent data.
void	fetch(int lockMode) Fetches this persistor's object's persistent data after obtaining a specified lock.
ooContObj	getContainer() Gets the container in which this persistor's object is stored.
ooId	getOid() Gets the object identifier of this persistor's object.
Session	getSession() Gets the session in which this persistor's object was made persistent or retrieved.
Object	getTarget() Reserved for internal use; you should not call this method.
int	hashOoId() Reserved for internal use; you should not call this method.
boolean	isDead() Tests whether this persistor is dead.
boolean	isFetchRequired() Tests whether this persistor's object's persistent data needs to be fetched.
boolean	isModified() Tests whether this persistor's object has been marked as modified.
boolean	isPersistent() Tests whether this persistor's object represents a valid persistent object.
boolean	isValid() Tests whether this persistor's object is a valid persistent object.
void	lock(int lockMode) Explicitly locks this persistor's object and propagates the lock to related objects.
void	lockNoProp(int lockMode) Explicitly locks this persistor's object for the specified access.
Object	lookupObj(String scopeName) Retrieves the object with the specified scope name in the scope defined by this persistor's object.
Object	lookupObj(String scopeName, int lockMode) Retrieves the object with the specified scope name in the scope defined by this persistor's object, locking the retrieved object as specified.
String	lookupObjName(Object obj) Looks up the name of the specified object in the scope defined by this persistor's object.
void	markFetchRequired() Marks this persistor's object as needing to have its persistent data fetched.
void	markModified() Locks this persistor's object for write, fetches its persistent data, and marks it as modified.
void	move(Object o) Moves this persistor's object (a basic object), clustering it with the specified object.
void	nameObj(Object o, String scopeName) Names the specified scope object in the scope of this persistor's object.
Iterator	scopedBy() Initializes an iterator to find all scope objects that define scope names for this persistor's object.
Iterator	scopedObjects() Initializes an iterator to find all objects named in the name scope of this persistor's object.
void	unnameObj(Object obj) Removes the specified object's name from the name scope or this persistor's object.
void	updateIndexes() Updates the indexes that include this persistor's object.
void	write() Transfers this persistor's object's data to the database cache.

Methods inherited from interface com.objy.db.iapp.PHasSession

connectionId

Methods inherited from interface com.objy.db.iapp.PRoot

clusterReason

Method Detail

getSession

public Session getSession()

Gets the session in which this persistor's object was made persistent or retrieved.

Specified by:

getSession in interface PHasSession

Returns:

The session to which this persistor's object belongs.

getContainer

public ooContObj getContainer()

Gets the container in which this persistor's object is stored.

If an object was retrieved from a database, the return value is the container in which the object is stored. If the object was created programmatically, the return value is the container in which the object will be stored when the transaction is committed.

Returns:

The container in which the object is stored.

getOid

public ooId getOid()

Gets the object identifier of this persistor's object.

Returns:

The object identifier of this persistor's object.

isPersistent

public boolean isPersistent()

Tests whether this persistor's object represents a valid persistent object.

Returns:

True if the object is persistent, and false if it is dead. (An object is persistent if it is neither dead nor transient; however, transient objects do not have persistors, so this method cannot be called for a transient object.)

isDead

public boolean isDead()

Tests whether this persistor is dead.

A persistor is made dead when you delete it. Once a persistor is dead, you should not call its methods that perform persistence operations.

Returns:

True if this persistor is dead; otherwise, false.

isModified

public boolean isModified()

Tests whether this persistor's object has been marked as modified.

A persistent object that is marked as modified will be written to the database when the transaction is committed.

Returns:

True if the object is persistent and marked as modified; otherwise, false.

See Also:

markModified()

isFetchRequired

public boolean isFetchRequired()

Tests whether this persistor's object's persistent data needs to be fetched.

If the object does not contain its most recent persistent data, you can call the fetch method to fetch the data.

You shouldn't need to call this method. Instead, you can simply call fetch, which will fetch the persistent data if necessary.

Returns:

True if the object's persistent data must be fetched; false if the object already contains its most recent persistent data.

isValid

public boolean isValid()

Tests whether this persistor's object is a valid persistent object.

When you retrieve a persistent object, the retrieved object is guaranteed to reference a valid persistent object. However, if some other session then deletes the object from the federated database, the retrieved object becomes invalid.

Returns:

True if the object represents a valid persistent object, otherwise, false.

markFetchRequired

public void markFetchRequired()

Marks this persistor's object as needing to have its persistent data fetched.

This method is called automatically when you commit the transaction in which you set or fetched the object's persistent data. On commit, the transaction releases its locks; a different client may then modify the object's persistent data. If such a modification occurs, the object's persistent data will be out of date. To ensure that you have the most current data for an object, open the transaction again and call the object's fetch method.

Applications typically do not need to call this method explicitly.

See Also:

ooObj.markFetchRequired()

markModified

public void markModified()

Locks this persistor's object for write, fetches its persistent data, and marks it as modified.

If the object is not currently locked for write, this method locks it for write. The write lock is not propagated to related objects. If the object does not contain its most recent persistent data, this method fetches that data. There is no overhead for calling this method if the object is already locked for write and its data has already been fetched during the current transaction.

You must call this method whenever you make changes to the object's persistent fields; typically, you call this method from every access method that sets the value of a persistent field of your subclass of ooObj. Only objects that are marked as modified are written to the database when the transaction is committed.

The modified mark is removed at the end of the current transaction or by an explicit call to the write method.

See Also:

ooObj.markModified(), isModified()

clearModified

public void clearModified()

Removes the modified mark from this persistor's object.

The modified mark indicates that the object needs to be written to the database. You can call this method if you want to prevent your changes to the object from being written to the database.

If you want to prevent a newly persistent object from being written to the database, you should either abort the transaction, or call the object's delete method.

fetch

public void fetch()

Locks this persistor's object for read and fetches its persistent data.

If the object is not currently locked, this method locks it for read before fetching its data. The read lock is not propagated to related objects.

When an object is first brought into memory, its persistent fields are left empty. You must call this method before you can safely access the object's persistent data.

If the object is already locked and the object's persistent data is current, this method has no effect; there is no overhead for repeated calls to fetch.

If the fetch fails, this method should throw a FetchCompletedWithErrors.

fetch

public void fetch(int lockMode)

Fetches this persistor's object's persistent data after obtaining a specified lock.

If an object is not currently locked as specified, this method obtains the specified lock before fetching the object's data. The lock is not propagated to related objects.

When an object is first brought into memory, its persistent fields are left empty. You must call this method before you can safely access the object's persistent data.

If the object is already locked in the specified mode and the object's persistent data is current, this method has no effect; there is no overhead for repeated calls to fetch.

Parameters:

lockMode - The type of lock to obtain for the object; one of the following constants defined in the oo interface:

READ

Obtain a read lock.

WRITE

Obtain a write lock.

write

public void write()

Transfers this persistor's object's data to the database cache.

This method makes the changes to the object visible to other transactions within the same process; however, the changes are not transferred to the database until you commit or checkpoint the current transaction. If the transaction is aborted, the changes are never transferred to the database.

This method removes any modified mark from the object. If you make additional changes after calling this method, you must call markModified or write again; otherwise, your changes would be lost.

You typically do not call this method. Instead, you call the session's checkpoint method, which writes all changes to the database. The checkpoint method makes changes accessible to all other clients, not just to other transactions of your process.

lock

public void lock(int lockMode)

Explicitly locks this persistor's object and propagates the lock to related objects.

This method locks an object for the specified access and propagates the lock to any objects associated to the object through relationships for which lock propagation is enabled.

Locking a basic object implicitly locks the object's container. Locking a container implicitly locks all basic objects in the container.

Parameters:

lockMode - The type of lock to obtain for the object; one of the following constants defined in the oo interface:

READ

Obtain a read lock.

WRITE

Obtain a write lock.

The lock mode is limited by the open mode of the object's session. If you try to set the lock mode to WRITE when the session's open mode is openReadOnly, this method throws a runtime exception.

If the object is already locked, you can call this method to upgrade a read lock to a write lock, but not to downgrade a write lock to a read lock.

See Also:

lockNoProp(int)

lockNoProp

public void lockNoProp(int lockMode)

Explicitly locks this persistor's object for the specified access.

Unlike the lock method, this method does not propagate the lock to related objects.

Locking a basic object implicitly locks the object's container. Locking a container implicitly locks all basic objects in the container.

Parameters:

lockMode - The type of lock to obtain for the object; one of the following constants defined in the oo interface:

READ

Obtain a read lock.

WRITE

Obtain a write lock.

The lock mode is limited by the open mode of the object's session. If you try to set the lock mode to WRITE when the session's open mode is openReadOnly, you should throw a runtime exception in the implementation.

deleteNoProp

public void deleteNoProp()

Deletes this persistor's object from the database.

Until the current transaction is committed, the deleted object continues to exist in your application's memory, but its persistor is marked dead. Once a persistor is dead, you should not call its methods that perform persistence operations.

The deleted object is removed from any bidirectional relationships in which it is involved. However, if another persistent object references the deleted object in a unidirectional relationship or directly in one of its persistent fields, you are responsible for removing that reference. An exception is thrown if you attempt to write a persistent object that references a dead object.

Unlike the delete method, this method does not propagate the deletion operation to related objects.

See Also:

isDead(), delete()

delete

public void delete()

Deletes this persistor's object from the database and propagates the deletion operation to related objects.

This method propagates the deletion operation to any objects associated to the object through relationships for which deletion propagation is enabled.

Until the current transaction is committed, the deleted objects continue to exist in your application's memory, but their persistors are marked Once a persistor is dead, you should not call its methods that perform persistence operations.

Each deleted object is removed from any bidirectional relationships in which it is involved. However, if another persistent object references the deleted object in a unidirectional relationship or directly in one of its persistent fields, you are responsible for removing that reference. An exception is thrown if you attempt to write a persistent object that references a dead object.

See Also:

deleteNoProp(), isDead()

deleteReference

public void deleteReference(Object objectReference)

Reserved for internal use; you should not call this method.

dropCachedReference

public void dropCachedReference(Object objectReference)

Reserved for internal use; you should not call this method.

cluster

public void cluster(Object object)

Makes the specified object persistent, clustering it near this persistor's object.

Parameters:

object - The transient object to be made persistent. The object to be clustered must be an instance of a persistence-capable class.

If object is a basic object:

This method assigns it a storage location in the object's container, close to the object. If possible, object will be stored on the same page as the object.

If object is a container:

This method assigns it a location in the object's database, adding it to that database as a hashed container with no system name, 5 initial pages, a hash value of 10, and a growth factor of 10%.

See Also:

ooDBObj.addContainer(com.objy.db.app.ooContObj, java.lang.String, long, long, long)

copy

public Object copy(Object o)

Copies this persistor's object (a basic object), clustering the new object with the specified object.

You should call this method for persistent objects only. If this object is not locked, this method locks its container for read-only access.

Parameters:

o - The object with which to cluster the new copy. The o object must be a database, a persistent container, or a persistent basic object.

If o is a database:

The new copy is stored in the default container of that database.

If o is a persistent container:

The new copy is stored in that container.

If o is a persistent basic object:

The new copy is stored in the same container as o. If possible, it will be stored on the same page as o or on a page close to that o.

Returns:

A new object with the same persistent data as this persistor's object. The returned object is persistent. If the transaction is aborted, the new object becomes a dead object and is not stored persistently.

move

public void move(Object o)

Moves this persistor's object (a basic object), clustering it with the specified object.

You should call this method for persistent objects only. If this object is not locked, this method locks its container and the container to which it will be moved, for read-write access.

Warning: This method changes the object identifier of the object. When you move an object you should, within the same transaction, update references to the object within all relevant relationships, name maps (including root name maps), scope names, and indexes. For the cases of a reference within a name map or root name, database corruption could result if the reference is not updated. See Moving a Persistent Basic Object for further information.

If the transaction is aborted, the new object becomes a dead object and is not stored persistently.

Parameters:

o - The object with which to cluster the object. The o object must be a database, a persistent container, or a persistent basic object.

If o is a database:

The object is stored in the default container of that database.

If o is a persistent container:

The object is stored in that container.

If o is a persistent basic object:

The object is stored in the same container as o. If possible, it will be stored on the same page as o or on a page close to o.

nameObj

public void nameObj(Object o,
                    String scopeName)

Names the specified scope object in the scope of this persistor's object.

If the specified object is transient, this method makes it persistent. If the specified object is already persistent, this method locks its container for write.

This method obtains a write lock on the name map in which the object stores its scope names.

Parameters:

o - The object to be named.

scopeName - The name for the specified object in the scope of this persistor's object. This name can be any valid Java string and must be unique within the name scope of this persistor's object.

See Also:

lookupObj(java.lang.String), unnameObj(java.lang.Object)

unnameObj

public void unnameObj(Object obj)

Removes the specified object's name from the name scope or this persistor's object.

This method locks both this persistor's object and object for write.

Parameters:

obj - The object whose name is to be removed. This method throws an ObjyRuntimeException if object has no name in the name scope of this persistor's object.

See Also:

lookupObj(java.lang.String), nameObj(java.lang.Object, java.lang.String)

lookupObjName

public String lookupObjName(Object obj)

Looks up the name of the specified object in the scope defined by this persistor's object.

Parameters:

obj - The object whose name is to be looked up. This method throws an ObjyRuntimeException if object has no name in the name scope of this persistor's object.

Returns:

The scope name of the specified object in the name scope of this persistor's object.

See Also:

lookupObj(java.lang.String)

lookupObj

public Object lookupObj(String scopeName)

Retrieves the object with the specified scope name in the scope defined by this persistor's object.

Parameters:

scopeName - The scope name to look up. This method throws an ObjyRuntimeException if there is no object named scopeName in the scope of this database.

Returns:

The object with the specified scope name in the scope of this persistor's object.

See Also:

lookupObjName(java.lang.Object)

lookupObj

public Object lookupObj(String scopeName,
                        int lockMode)

Retrieves the object with the specified scope name in the scope defined by this persistor's object, locking the retrieved object as specified.

Parameters:

scopeName - The scope name to look up. This method throws an ObjyRuntimeException if there is no object named scopeName in the scope of this database.

lockMode - The type of lock to obtain for the object; one of the following constants defined in the oo interface:

READ

Obtain a read lock.

WRITE

Obtain a write lock.

Returns:

The object with the specified scope name in the scope of this persistor's object; the returned object is locked as specified by lockMode.

See Also:

lookupObjName(java.lang.Object)

scopedObjects

public Iterator scopedObjects()

Initializes an iterator to find all objects named in the name scope of this persistor's object.

Returns:

An iterator that finds the named objects.

scopedBy

public Iterator scopedBy()

Initializes an iterator to find all scope objects that define scope names for this persistor's object.

Returns:

An iterator that finds the scope objects.

updateIndexes

public void updateIndexes()

Updates the indexes that include this persistor's object.

If a session's index mode is EXPLICIT_UPDATE, indexes are not updated automatically to reflect changes to indexed fields. You must call this method after creating an object and initializing its indexed fields, and after modifying the indexed fields of an existing object.

compareOoId

public int compareOoId(PooObj obj)

Reserved for internal use; you should not call this method.

hashOoId

public int hashOoId()

Reserved for internal use; you should not call this method.

getTarget

public Object getTarget()

Reserved for internal use; you should not call this method.