Package wt.fc

Interface PersistenceManager

All Known Implementing Classes:

StandardPersistenceManager

@RemoteInterface
public interface PersistenceManager

The PersistenceManager interface identifies the set of methods that applications use to manage the persistent state of their business objects. While all of the methods declared by this interface execute on the server, they are accessable to client application through a helper class. See PersistenceHelper.

Supported API: true

Extendable: false

Method Summary

Modifier and Type	Method	Description
WTSet	delete(WTSet a_objects)	Removes the specified persistable objects from the datastore.
Persistable	delete(Persistable obj)	Removes the given persistable object from the datastore.
QueryResult	find(Class targetLinkClass, ObjectIdentifier obj1Oid, String obj1Role, ObjectIdentifier obj2Oid)	Retrieves any and all link objects that exist between two Persistable objects given their object identifiers.
QueryResult	find(Class targetLinkClass, Persistable obj1, String obj1Role, Persistable obj2)	Retrieves any and all link objects that exist between two given Persistable objects.
QueryResult	find(StatementSpec a_statementSpec)	Retrieves persistable objects from the datastore given the specified statement.
ResultProcessor	find(StatementSpec a_statementSpec, ResultProcessor a_resultProcessor)	Retrieves persistable objects from the datastore for the specified statement.
String	getCurrentSequence(Class a_class)	Given the sequence class, return the sequence inrement.
String	getCurrentSequence(Class a_class, String AttributeName)	Given the class for the column sequence as required input, and attribute name for the column sequence, return the current sequence.
InputStream	getLob(LobLocator lob)	Returns an input stream to the Lob associated with the given lob locator.
String	getNextSequence(Class a_class)	Given the sequence class as input, return the next value.
String	getNextSequence(Class a_class, String attributeName)	Given the class for the column sequence as required input, and attribute name for the column sequence, return the next sequence.
Long	getSequenceIncrement(Class a_class)	Given the sequence class, return the current sequence.
Long	getSequenceIncrement(Class a_class, String AttributeName)	Given the class for the column sequence as required input, and attribute name for the column sequence, return the sequence inrement.
WTCollection	modify(WTCollection a_objects)	Updates the specified Persistable objects in the datastore.
Persistable	modify(Persistable obj)	Updates the given Persistable object in the datastore.
Persistable	modify(Persistable obj, String attrName, ObjectMappable objAttr)	Updates the given Persistable object in the datastore with the values specified in the ObjectMappable attribute.
QueryResult	navigate(Persistable obj, String role, Class linkClass)	Retrieves objects related to the given persistable object given a role and link class.
QueryResult	navigate(Persistable obj, String role, Class linkClass, boolean onlyOtherSide)	Retrieves objects related to the given persistable object given a role and link class.
QueryResult	navigate(Persistable obj, String role, QuerySpec criteria)	Retrieves objects related to the given persistable object given a role, an association name and selection criteria.
QueryResult	navigate(Persistable obj, String role, QuerySpec criteria, boolean onlyOtherSide)	Retrieves objects related to the given persistable object given a role, an association name and selection criteria.
Persistable	refresh(ObjectIdentifier objId)	Retrieves a Persistable object from the database given its object identifier.
Persistable	refresh(ObjectIdentifier objId, boolean lock)	Retrieves a Persistable object from the database given its object identifier.
Persistable	refresh(Persistable obj)	Retrieves the given Persistable object from the database to restore its state.
Persistable	refresh(Persistable obj, boolean fullRefresh)	Retrieves the given Persistable object from the database to restore its state.
Persistable	refresh(Persistable obj, boolean fullRefresh, boolean inPlace)	Retrieves the given Persistable object from the database to restore its state.
Persistable	refresh(Persistable obj, boolean fullRefresh, boolean inPlace, boolean lock)	Retrieves the given Persistable object from the database to restore its state.
WTCollection	save(WTCollection objects)	Invokes the modify method on the objects that are already persisted, otherwise invokes the store method.
Persistable	save(Persistable obj)	Invokes the modify method if the given object is persistent, otherwise the save method invokes the store method.
WTCollection	store(WTCollection a_objects)	Stores the specified collection of Persistable objects in the datastore.
WTCollection	store(WTCollection a_objects, wt.fc.WTCollectionExceptionHandler a_handler)	Stores the specified collection of Persistable objects in the datastore.
Persistable	store(Persistable obj)	Stores the specified Persistable object in the datastore.

Method Details

delete

Persistable delete(Persistable obj)
            throws WTException

Removes the given persistable object from the datastore. If the given Persistable object participates as either a role A or role B member, then referential integrity processing will occur as specified for that role. The delete method ensures that the operation is valid before removing the Persistable object from the datastore.

The target for this operations dispatched event is the specified Persistable object for a single object event listener and a WTCollection containing the specified Persistable object for a multiple object event listener. Note that the PRE_REMOVE event is not supported for a single object event listener.

The delete performs the following operations.

1. Dispatches a PersistenceManagerEvent.PRE_DELETE event.
2. Ensures that this Persistable object is persistent.
3. Ensures that attributes are valid (by invoking Persistable.checkAttributes()).
4. Uses Access Control to determine if the user is allowed to delete this business object.
5. Deletes associated BinaryLink objects that are owned by the role object that is being deleted.
6. Dispatches a PersistenceManagerEvent.CLEANUP_LINK event.
7. Dispatches a PersistenceManagerEvent.PRE_REMOVE event.
8. Deletes this Persistable object in the database, ensuring that the object has not gone stale (that is, someone else has already modified this object in the database).
9. Sets new values in the persistent information attributes to indicate that this object has been deleted.
10. Dispatches a PersistenceManagerEvent.REMOVE event.
11. If this object is of type BinaryLink, then any cascaded role objects are deleted.
12. Dispatches a PersistenceManagerEvent.POST_DELETE event.
13. Returns the Persistable object to the caller.

Before the commit of the transaction that this delete operation occurs in, the persistence service verifies that no BinaryLink objects exist that reference any of the removed objects.

Supported API: true

Parameters:

obj - The object to be deleted from the datastore.

Returns:

Persistable

Throws:

WTException

See Also:

• Delete

find

QueryResult find(Class targetLinkClass,
 Persistable obj1,
 String obj1Role,
 Persistable obj2)
          throws WTException

Retrieves any and all link objects that exist between two given Persistable objects. The method validates the resulting set of link objects retrieved from the database before returning them to the invoking method.

Supported API: true

Parameters:

targetLinkClass -

obj1 -

obj1Role -

obj2 -

Returns:

QueryResult

Throws:

WTException

find

QueryResult find(Class targetLinkClass,
 ObjectIdentifier obj1Oid,
 String obj1Role,
 ObjectIdentifier obj2Oid)
          throws WTException,
InvalidRoleException

Retrieves any and all link objects that exist between two Persistable objects given their object identifiers. The method validates the resulting set of link objects retrieved from the database before returning them to the invoking method.

Supported API: true

Parameters:

targetLinkClass -

obj1Oid -

obj1Role -

obj2Oid -

Returns:

QueryResult

Throws:

WTException

InvalidRoleException

getLob

InputStream getLob(LobLocator lob)
            throws WTException

Returns an input stream to the Lob associated with the given lob locator.

Supported API: true

Parameters:

lob - the Lob locator.

Returns:

InputStream

Throws:

WTException

modify

Persistable modify(Persistable obj)
            throws WTException

Updates the given Persistable object in the datastore. The modify method ensures that the operation is valid before updating the Persistable object in the datastore.

The target for this operations dispatched event is the specified Persistable object for a single object event listener and a WTCollection containing the specified Persistable object for a multiple object event listener.

The modify method performs the following operations.

1. Dispatches a PersistenceManagerEvent.PRE_MODIFY event.
2. Ensures that this Persistable object is persistent.
3. Ensures that attributes are valid (by invoking Persistable.checkAttributes()).
4. Uses Access Control to determine if the user is allowed to modify this business object.
5. Updates this Persistable object in the database, ensuring that the object has not gone stale (that is, someone else has already modified this object in the database). Note that any attributes derived from values that exist in other tables are not updated in the database.
6. Sets new values in the persistent information attributes, such as update count and modify timestamp.
7. Dispatches a PersistenceManagerEvent.UPDATE event.
8. Dispatches a PersistenceManagerEvent.POST_MODIFY event.
9. Returns the Persistable object to the caller.

Supported API: true

Parameters:

obj - The object to be modified in the datastore

Returns:

Persistable

Throws:

WTException

navigate

QueryResult navigate(Persistable obj,
 String role,
 Class linkClass)
              throws WTException

Retrieves objects related to the given persistable object given a role and link class. The navigate methods validates the resulting set of objects that were retrieved from the datastore before returning them to the invoking method. Returns only the otherside objects, not the links.

Supported API: true

Parameters:

obj - The persistable object to navigate.

role - The role to navigate to

linkClass - The link class to navigate

Returns:

QueryResult

Throws:

WTException

navigate

QueryResult navigate(Persistable obj,
 String role,
 Class linkClass,
 boolean onlyOtherSide)
              throws WTException

Retrieves objects related to the given persistable object given a role and link class. The navigate methods validates the resulting set of objects that were retrieved from the datastore before returning them to the invoking method. If onlyOtherSide is false, the links are returned as well as the other side objects. Note that only the links are returned in the QueryResult, the other side objects are accessible using the link's getOtherObject() method.

Supported API: true

Parameters:

obj -

role -

linkClass - The link class for the association to navigate

onlyOtherSide - Indicates that only the other side objects of the association should be returned. If false, then the link objects are returned (the other side object can be obtained via the link object's getter method).

Returns:

QueryResult

Throws:

WTException

navigate

QueryResult navigate(Persistable obj,
 String role,
 QuerySpec criteria)
              throws WTException

Retrieves objects related to the given persistable object given a role, an association name and selection criteria. The find methods validates the resulting set of objects that were retrieved from the datastore before returning them to the invoking method. This version only returns other side objects.

Supported API: true

Parameters:

obj - The persistable object to navigate

role - The role to navigate to

criteria - Selection criteria for the navigate. This QuerySpec must contain the target and link class at class index 0 and 1, respectively.

Returns:

QueryResult

Throws:

WTException

navigate

QueryResult navigate(Persistable obj,
 String role,
 QuerySpec criteria,
 boolean onlyOtherSide)
              throws WTException

Retrieves objects related to the given persistable object given a role, an association name and selection criteria. The find methods validates the resulting set of objects that were retrieved from the datastore before returning them to the invoking method. This version returns other side objects and also the links if onlyOtherSide is false. Note that only the links are returned in the QueryResult, the other side objects are accessible using the link's getOtherObject() method.

Supported API: true

Parameters:

obj - The persistable object to navigate

role - The role to navigate to

criteria - Selection criteria for the navigate. This QuerySpec must contain the target and link class at class index 0 and 1, respectively.

onlyOtherSide - Indicates that only the other side objects of the association should be returned. If false, then the link objects are returned (the other side object can be obtained via the link object's getter method).

Returns:

QueryResult

Throws:

WTException

refresh

Persistable refresh(Persistable obj,
 boolean fullRefresh)
             throws WTException,
ObjectNoLongerExistsException

Retrieves the given Persistable object from the database to restore its state. The object is not refreshed in place.

Supported API: true

Parameters:

obj - The persistable object to be refreshed

fullRefresh - Set to true if the object references for the target object should be refreshed as well.

Returns:

Persistable

Throws:

WTException

ObjectNoLongerExistsException

refresh

Persistable refresh(Persistable obj)
             throws WTException,
ObjectNoLongerExistsException

Retrieves the given Persistable object from the database to restore its state. Object references for the target object are not refreshed and the object is not refreshed in place.

Supported API: true

Parameters:

obj - The persistable object to be refreshed

Returns:

Persistable

Throws:

WTException

ObjectNoLongerExistsException

refresh

Persistable refresh(ObjectIdentifier objId)
             throws WTException,
ObjectNoLongerExistsException

Retrieves a Persistable object from the database given its object identifier. Object references of the target object are not refreshed.

Supported API: true

Parameters:

objId -

Returns:

Persistable

Throws:

WTException

ObjectNoLongerExistsException

save

Persistable save(Persistable obj)
          throws WTException

Invokes the modify method if the given object is persistent, otherwise the save method invokes the store method.

Supported API: true

Parameters:

obj - The persistable object to be saved

Returns:

Persistable

Throws:

WTException

store

Persistable store(Persistable obj)
           throws WTException

Stores the specified Persistable object in the datastore. The store method ensures that the operation is valid before storing the Persistable object in the datastore.

The target for this operations dispatched event is the specified Persistable object for a single object event listener and a WTCollection containing the specified Persistable object for a multiple object event listener.

The store method performs the following operations.

1. Dispatches a PersistenceManagerEvent.PRE_STORE event.
2. Ensures that this Persistable object is not yet persistent.
3. Ensures that attributes are valid (by invoking Persistable.checkAttributes()).
4. Uses Access Control to determine if the user is allowed to create this business object.
5. Inserts the Persistable object into the database and, in so doing, assigns an ObjectIdentifier and initializes the persistence information.
6. Dispatches a PersistenceManagerEvent.INSERT event.
7. Dispatches a PersistenceManagerEvent.POST_STORE event.
8. Returns the Persistable object to the caller.

Supported API: true

Parameters:

obj - The object to be stored in the datastore

Returns:

Persistable

Throws:

WTException

modify

Persistable modify(Persistable obj,
 String attrName,
 ObjectMappable objAttr)
            throws WTException

Updates the given Persistable object in the datastore with the values specified in the ObjectMappable attribute.

Supported API: true

Parameters:

obj -

attrName -

objAttr -

Returns:

Persistable

Throws:

WTException

find

QueryResult find(StatementSpec a_statementSpec)
          throws WTException

Retrieves persistable objects from the datastore given the specified statement. The find methods validates the resulting set of objects that were retrieved from the datastore before returning them to the invoking method.

Supported API: true

Parameters:

a_statementSpec - The search criteria to use for the find

Returns:

QueryResult

Throws:

WTException

refresh

Persistable refresh(Persistable obj,
 boolean fullRefresh,
 boolean inPlace)
             throws WTException,
ObjectNoLongerExistsException

Retrieves the given Persistable object from the database to restore its state.

Supported API: true

Parameters:

obj - The persistable object to be refreshed

fullRefresh - Set to true if the object references for the target object should be refreshed as well.

inPlace - Set to true if the target object should be refreshed in place.

Returns:

Persistable

Throws:

WTException

ObjectNoLongerExistsException

See Also:

• In-place refresh

find

ResultProcessor find(StatementSpec a_statementSpec,
 ResultProcessor a_resultProcessor)
              throws WTException

Retrieves persistable objects from the datastore for the specified statement. The find methods validates the resulting set of objects that were retrieved from the datastore before returning via the specified ResultProcessor.

Supported API: true

Parameters:

a_statementSpec -

a_resultProcessor -

Returns:

ResultProcessor

Throws:

WTException

refresh

Persistable refresh(Persistable obj,
 boolean fullRefresh,
 boolean inPlace,
 boolean lock)
             throws WTException,
ObjectNoLongerExistsException

Retrieves the given Persistable object from the database to restore its state.

Supported API: true

Parameters:

obj - The persistable object to be refreshed

fullRefresh - Set to true if the object references for the target object should be refreshed as well.

inPlace - Set to true if the target object should be refreshed in place.

lock - Specifies whether the object should be locked as part of the refresh. This value should only be true when the call is within the context of a server-side transaction.

Returns:

Persistable

Throws:

WTException

ObjectNoLongerExistsException

See Also:

• In-place refresh

store

WTCollection store(WTCollection a_objects,
 wt.fc.WTCollectionExceptionHandler a_handler)
            throws WTException

Stores the specified collection of Persistable objects in the datastore. The store method ensures that the operation is valid before storing the Persistable objects in the datastore.

The target for this operations dispatched event is a Persistable object for a single object event listener (the listener is called once for each object in the collection) and the specified collection of Persistable objects for a multiple object event listener.

The store method performs the following operations.

1. Dispatches a PersistenceManagerEvent.PRE_STORE event.
2. Ensures that each Persistable object is not yet persistent.
3. Ensures that attributes are valid (by invoking Persistable.checkAttributes() for each object).
4. Uses Access Control to determine if the user is allowed to create each business object.
5. Inserts the Persistable objects into the database and, in so doing, assigns each an ObjectIdentifier and initializes the persistence information.
6. Dispatches a PersistenceManagerEvent.INSERT event.
7. Dispatches a PersistenceManagerEvent.POST_STORE event.
8. Returns the collection of Persistable objects to the caller.

Supported API: true

Parameters:

a_objects - The objects to be stored in the datastore

a_handler - Specifies a custom handler for processing any exceptions that occur. If null, then default processing will be used.

Returns:

WTCollection

Throws:

WTException

delete

WTSet delete(WTSet a_objects)
      throws WTException

Removes the specified persistable objects from the datastore. If a given Persistable object in the set participates as either a role A or role B member, then referential integrity processing will occur as specified for that role. The delete method ensures that the operation is valid before removing the Persistable objects from the datastore.

The target for this operations dispatched event is the specified Persistable object for a single object event listener (the listener is called once for each object in the collection) and a WTCollection containing the specified Persistable object for a multiple object event listener. Note that the PRE_REMOVE event is not supported for a single object event listener.

The delete performs the following operations.

1. Dispatches a PersistenceManagerEvent.PRE_DELETE event.
2. Ensures that this Persistable objects are persistent.
3. Ensures that attributes are valid (by invoking Persistable.checkAttributes() for each object).
4. Uses Access Control to determine if the user is allowed to delete the business objects.
5. Deletes associated BinaryLink objects that are owned by the role objects that are being deleted.
6. Dispatches a PersistenceManagerEvent.CLEANUP_LINK event.
7. Dispatches a PersistenceManagerEvent.PRE_REMOVE event.
8. Deletes the Persistable objects in the datastore, ensuring that the objects have not gone stale (that is, someone else has already modified this object in the datastore).
9. Sets new values in the persistent information attributes to indicate that this objects have been deleted.
10. Dispatches a PersistenceManagerEvent.REMOVE event.
11. For any objects that are of type BinaryLink, cascaded role objects are deleted.
12. Dispatches a PersistenceManagerEvent.POST_DELETE event.
13. Returns the collection of Persistable objects to the caller.

Before the commit of the transaction that this delete operation occurs in, the persistence service verifies that no BinaryLink objects exist that reference any of the removed objects.

Supported API: true

Parameters:

a_objects - The objects to be deleted from the datastore.

Returns:

WTSet

Throws:

WTException

See Also:

• Delete

save

WTCollection save(WTCollection objects)
           throws WTException

Invokes the modify method on the objects that are already persisted, otherwise invokes the store method.

Supported API: true

Parameters:

objects - The persistable objects to be saved

Returns:

WTCollection

Throws:

WTException

getNextSequence

String getNextSequence(Class a_class)
                throws WTException

Given the sequence class as input, return the next value. The specified sequence class must implement the DatastoreSequence interface.

Supported API: true

Parameters:

a_class -

Returns:

String

Throws:

WTException

getNextSequence

String getNextSequence(Class a_class,
 String attributeName)
                throws WTException

Given the class for the column sequence as required input, and attribute name for the column sequence, return the next sequence. The specified attribute must be specified as sequence type.

Supported API: true

Parameters:

a_class -

Returns:

String

Throws:

WTException

getSequenceIncrement

Long getSequenceIncrement(Class a_class,
 String AttributeName)
                   throws WTException

Given the class for the column sequence as required input, and attribute name for the column sequence, return the sequence inrement. The specified attribute must be specified as sequence type.

Supported API: true

Parameters:

a_class -

Returns:

String

Throws:

WTException

getSequenceIncrement

Long getSequenceIncrement(Class a_class)
                   throws WTException

Given the sequence class, return the current sequence. The specified sequence class must implement the DatastoreSequence interface.

Supported API: true

Parameters:

a_class -

Returns:

String

Throws:

WTException

getCurrentSequence

String getCurrentSequence(Class a_class,
 String AttributeName)
                   throws WTException

Given the class for the column sequence as required input, and attribute name for the column sequence, return the current sequence. The specified attribute must be specified as sequence type.

Supported API: true

Parameters:

a_class -

Returns:

String

Throws:

WTException

getCurrentSequence

String getCurrentSequence(Class a_class)
                   throws WTException

Given the sequence class, return the sequence inrement. The specified sequence class must implement the DatastoreSequence interface.

Supported API: true

Parameters:

a_class -

Returns:

String

Throws:

WTException

refresh

Persistable refresh(ObjectIdentifier objId,
 boolean lock)
             throws WTException,
ObjectNoLongerExistsException

Retrieves a Persistable object from the database given its object identifier. Object references of the target object are not refreshed.

Supported API: true

Parameters:

objId -

lock -

Returns:

Persistable

Throws:

WTException

ObjectNoLongerExistsException

store

WTCollection store(WTCollection a_objects)
            throws WTException

Stores the specified collection of Persistable objects in the datastore. The store method ensures that the operation is valid before storing the Persistable objects in the datastore.

The target for this operations dispatched event is a Persistable object for a single object event listener (the listener is called once for each object in the collection) and the specified collection of Persistable objects for a multiple object event listener.

The store method performs the following operations.

1. Dispatches a PersistenceManagerEvent.PRE_STORE event.
2. Ensures that each Persistable object is not yet persistent.
3. Ensures that attributes are valid (by invoking Persistable.checkAttributes() for each object).
4. Uses Access Control to determine if the user is allowed to create each business object.
5. Inserts the Persistable objects into the database and, in so doing, assigns each an ObjectIdentifier and initializes the persistence information.
6. Dispatches a PersistenceManagerEvent.INSERT event.
7. Dispatches a PersistenceManagerEvent.POST_STORE event.
8. Returns the collection of Persistable objects to the caller.

Supported API: true

Parameters:

a_objects - The objects to be stored in the datastore

Returns:

WTCollection

Throws:

WTException

modify

WTCollection modify(WTCollection a_objects)
             throws WTException

Updates the specified Persistable objects in the datastore. The modify method ensures that the operation is valid before updating the Persistable objects in the datastore.

The target for this operations dispatched event is the specified Persistable object for a single object event listener (the listener is called once for each object in the collection) and a WTCollection containing the specified Persistable object for a multiple object event listener.

The modify method performs the following operations.

1. Dispatches a PersistenceManagerEvent.PRE_MODIFY event.
2. Ensures that each Persistable object is persistent.
3. Ensures that attributes are valid (by invoking Persistable.checkAttributes() for each object).
4. Uses Access Control to determine if the user is allowed to modify each business object.
5. Updates the Persistable objects in the database, ensuring that the objects have not gone stale (that is, someone else has already modified this object in the database). Note that any attributes derived from values that exist in other tables are not updated in the database.
6. Sets new values in the persistent information attributes, such as update count and modify timestamp.
7. Dispatches a PersistenceManagerEvent.UPDATE event.
8. Dispatches a PersistenceManagerEvent.POST_MODIFY event.
9. Returns the collection of Persistable objects to the caller.

Supported API: true

Parameters:

a_objects - The objects to be modified in the datastore

Returns:

WTCollection

Throws:

WTException