com.waveset.object
Interface CacheManager


public interface CacheManager

See Also:
ObjectRef, ObjectHandle, Encapsulates a Repository and various caches, maintaining consistency and integrity. Only an implementer of this class may call Repository directly.

Field Summary
static java.lang.String code_id
           
 
Method Summary
 void breakLock(Type type, java.lang.String id, java.lang.String brokenBy)
          Forcibly remove the lock on an object.
 void checkinObject(PersistentObject object, java.lang.String lockedBy)
          Stores the modifications to an object, and releases the lock.
 PersistentObject checkoutObject(Type type, java.lang.String id, java.lang.String lockedBy)
          Lock and retrieve an object for editing.
 void clearSuppressedTypes()
          Clear the suppression option for all types, allowing them to be in the cache.
 void createObject(PersistentObject po, java.lang.String createdBy)
          Creates a new object in the repository.
 void deleteObject(PersistentObject obj, java.lang.String lockedBy)
           
 void deleteObject(Type type, java.lang.String id, java.lang.String lockedBy)
          Permanently remove an object.
 void deleteObject(Type type, java.lang.String id, java.lang.String lockedBy, boolean force)
          Permanently remove an object from the repository.
 void destroyDeletedUpToMod(Type type, long modified)
          Physically delete any objects of the specified type that have been logically deleted with modification counter values less than or equal to the specified modification counter value.
 RepositoryResult getAllObjects(Type type)
          Deprecated. - use listObjects(Type).
 RepositoryResult getAllObjects(Type type, AttributeCondition[] attrConds)
          Deprecated. - use listObjects(Type, AttributeCondition[]).
 RepositoryResult getAllObjects(Type type, WSAttributes atts)
          Deprecated. - use listObjects(Type, WSAttributes).
 long getCounterValue(Type type, java.lang.String nameOrId)
           
 long getLastMod(Type type)
           
 long getLastMod(Type type, long freshnessDate)
           
 LockInfo getLockInfo(Type type, java.lang.String id)
          Retrieve information about a lock held on the object.
 PersistentObject getObject(Type type, java.lang.String id)
           
 PersistentObject getObjectIfExists(Type type, java.lang.String id)
           
 RepositoryResult getObjects(Type type)
           
 RepositoryResult getObjects(Type type, AttributeCondition[] attrConds)
           
 RepositoryResult getObjects(Type type, WSAttributes atts)
           
 void incrementCounter(Type type, java.lang.String nameOrId)
           
 void incrementCounter(Type type, java.lang.String nameOrId, long valueToAdd)
           
 boolean isSuppressedType(Type t)
           
 RepositoryResult listDeletedSinceMod(Type type, long modified)
          Return summary information for any objects of the specified type that have been logically deleted since the specified modification counter value.
 RepositoryResult listObjects(Type type)
           
 RepositoryResult listObjects(Type type, AttributeCondition[] attrConds)
           
 RepositoryResult listObjects(Type type, AttributeCondition[] attrConds, Attribute[] orderBy)
           
 RepositoryResult listObjects(Type type, WSAttributes atts)
           
 LockInfo lockObject(Type type, java.lang.String id, java.lang.String lockedBy)
          Lock an object to prevent another user from modifying it.
 void renameObject(Type type, java.lang.String id, java.lang.String newName, java.lang.String lockedBy)
          Changes the name of an existing object.
 PersistentObject resolve(ObjectRef ref)
           
 java.lang.String resolveName(Type type, java.lang.String id)
           
 void restore(PersistentObject po, java.lang.String restoredBy)
          Import an item, overlaying any existing item with the same id
 void restore(Type type, PersistentObject[] poArray, java.lang.String restoredBy)
          Import multiple items, overlaying any existing item with the same id
 void setCounterValue(Type type, java.lang.String nameOrId, long newValue)
           
 void setObject(PersistentObject po, java.lang.String lockedBy)
          Replace the value of an item.
 void setSuppressedTypes(Type[] types)
          Specifies a list of types that are to be kept out of the cache.
 long sumCounterValues(Type type, AttributeCondition[] attrConds)
           
 void unlockObject(Type type, java.lang.String id, java.lang.String lockedBy)
          Release a lock held on an object by the current user.
 

Field Detail

code_id

public static final java.lang.String code_id
See Also:
Constant Field Values
Method Detail

setSuppressedTypes

public void setSuppressedTypes(Type[] types)
Specifies a list of types that are to be kept out of the cache. We'll still provide an interface for accessing them, but they will never be retained in the cache.

This makes usage of some PersistentObject types like WSUser and WorkflowTask more convenient, since we never want them in the cache, but its nice not to have special case checks in lots of places. Instead we let the cache decide.

This does not affect objects already in the cache, you should call this shortly after cache construction, or clear it yourself.


clearSuppressedTypes

public void clearSuppressedTypes()
Clear the suppression option for all types, allowing them to be in the cache.

This was added mostly for an old cache test that wanted to load up the cache with WorkflowCases's and other normally suppressed things.


isSuppressedType

public boolean isSuppressedType(Type t)

getObject

public PersistentObject getObject(Type type,
                                  java.lang.String id)
                           throws WavesetException
Returns:
the specified object.

Throws:
ItemNotFound - if the object was not found.

NOTE: unlike getAllObjects, getObject will NOT traverse subtypes if they exist. This is harder to rationalize here since there could be more than one object with the given name.

WavesetException

getObjectIfExists

public PersistentObject getObjectIfExists(Type type,
                                          java.lang.String id)
                                   throws WavesetException
Returns:
the specified object if it can be found; otherwise null.

Does not throw an exception if the object wasn't found.

Throws:
WavesetException

createObject

public void createObject(PersistentObject po,
                         java.lang.String createdBy)
                  throws AlreadyExists,
                         ValidationFailed,
                         WavesetException
Creates a new object in the repository.

Objects are created by first instantiating a subclass of PersistentObject, then calling appropriate accessor methods to specify the object's attributes, and finally calling the addObject method to store the object in the repository.

The new object must be given a name that is unique within the specified type. If another instance of the type already has this name, an exception is thrown.

Other type specific validation may also be performed before the object is stored in the repository. If any of these validation tests fail, a ValidationFailed exception will be thrown describing the nature of the failure.

After the method returns, the supplied object will be in the session's cache, but the server will not retain any references to this object.

Parameters:
po - - the object to store in the repository.
createdBy - - the name to record as the creator.
Throws:
AlreadyExists - if another object of the same type has the same name.
ValidationFailed - if the object was not constructed properly.
WavesetException - if an internal server error was encountered.

restore

public void restore(PersistentObject po,
                    java.lang.String restoredBy)
             throws Shutdown,
                    NotInitialized,
                    InvalidArgument,
                    java.io.IOException,
                    WavesetException
Import an item, overlaying any existing item with the same id

Parameters:
po - - the item
restoredBy - - the subject to record in Attribute.LAST_MODIFIER.
Throws:
NotInitialized - - the DataStore's internal state is bad.
java.io.IOException - - failure accessing the underlying resource
Shutdown
InvalidArgument
WavesetException

restore

public void restore(Type type,
                    PersistentObject[] poArray,
                    java.lang.String restoredBy)
             throws Shutdown,
                    NotInitialized,
                    InvalidArgument,
                    java.io.IOException,
                    WavesetException
Import multiple items, overlaying any existing item with the same id

Parameters:
poArray - - contains each item to be added
restoredBy - - the subject to record in Attribute.LAST_MODIFIER.
Throws:
NotInitialized - - the DataStore's internal state is bad.
java.io.IOException - - failure accessing the underlying resource
Shutdown
InvalidArgument
WavesetException

setObject

public void setObject(PersistentObject po,
                      java.lang.String lockedBy)
               throws Shutdown,
                      NotInitialized,
                      InvalidArgument,
                      ItemNotFound,
                      LockedByAnother,
                      java.io.IOException,
                      WavesetException
Replace the value of an item.

Parameters:
po - - a modified object to replace the current object.
lockedBy - - a string identifying the caller. If the item has been locked by a caller, then only that caller may update the item.
Throws:
NotInitialized - - the DataStore's internal state is bad.
ItemNotFound - - name is not defined within type
LockedByAnother - - another caller has already locked this item
java.io.IOException - - failure accessing the underlying resource
Shutdown
InvalidArgument
WavesetException

deleteObject

public void deleteObject(Type type,
                         java.lang.String id,
                         java.lang.String lockedBy)
                  throws ItemNotFound,
                         LockedByAnother,
                         ObjectInUse,
                         ObjectProtected,
                         WavesetException
Permanently remove an object.

The object must be locked by the current user. After deletion, the object will also be removed from all object caches, including the session's object cache. Some objects cannot be deleted if they are being referenced by other objects. In these cases, the method will throw the ObjectInUse exception.

Some special system objects cannot be deleted. If an attempt is made to delete these objects, the ObjectProtected exception is thrown.

Parameters:
type - the type of the object.
id - the object id or name.
lockedBy - - uniquely identifies the caller. A caller must lock the object before deleting it.
Throws:
ItemNotFound - if the object does not exist in the repository.
LockedByAnother - if the object is locked by someone else.
ObjectInUse - if there is an unbreakable reference to this object.
ObjectProtected - if the object is protected from deletion.
WavesetException - if an internal server error was encountered.

deleteObject

public void deleteObject(PersistentObject obj,
                         java.lang.String lockedBy)
                  throws ItemNotFound,
                         LockedByAnother,
                         ObjectInUse,
                         ObjectProtected,
                         WavesetException
Throws:
ItemNotFound
LockedByAnother
ObjectInUse
ObjectProtected
WavesetException

deleteObject

public void deleteObject(Type type,
                         java.lang.String id,
                         java.lang.String lockedBy,
                         boolean force)
                  throws ItemNotFound,
                         LockedByAnother,
                         ObjectInUse,
                         ObjectProtected,
                         WavesetException
Permanently remove an object from the repository.

This is the same as deleteObject, except that we will allow the object to be deleted even if there are references to it from another object. This is the signature we should move to, the other can be deprecated.

Throws:
ItemNotFound
LockedByAnother
ObjectInUse
ObjectProtected
WavesetException

getObjects

public RepositoryResult getObjects(Type type)
                            throws WavesetException
Returns:
all objects of a specified type.
Throws:
WavesetException

getObjects

public RepositoryResult getObjects(Type type,
                                   WSAttributes atts)
                            throws WavesetException
Returns:
all objects of a specified type that match the specified attribute values.
Throws:
WavesetException

getObjects

public RepositoryResult getObjects(Type type,
                                   AttributeCondition[] attrConds)
                            throws WavesetException
Returns:
all objects of a specified type that satisfy the specified attribute conditions.
Throws:
WavesetException

getAllObjects

public RepositoryResult getAllObjects(Type type)
                               throws WavesetException
Deprecated. - use listObjects(Type).

Returns:
all objects of a specified type including subtypes.
Throws:
WavesetException

getAllObjects

public RepositoryResult getAllObjects(Type type,
                                      WSAttributes atts)
                               throws WavesetException
Deprecated. - use listObjects(Type, WSAttributes).

Returns:
all objects of a specified type including subtypes that match the specified attribute values.
Throws:
WavesetException

getAllObjects

public RepositoryResult getAllObjects(Type type,
                                      AttributeCondition[] attrConds)
                               throws WavesetException
Deprecated. - use listObjects(Type, AttributeCondition[]).

Returns:
all objects of a specified type including subtypes that satisfy the specified attribute conditions.
Throws:
WavesetException

listObjects

public RepositoryResult listObjects(Type type)
                             throws WavesetException
Returns:
summary information for all of objects of the specified type.
Throws:
WavesetException

listObjects

public RepositoryResult listObjects(Type type,
                                    WSAttributes atts)
                             throws WavesetException
Returns:
summary information for all of objects of the specified type that match the specified attribute values.
Throws:
WavesetException

listObjects

public RepositoryResult listObjects(Type type,
                                    AttributeCondition[] attrConds)
                             throws WavesetException
Returns:
summary information for all of objects of the specified type that satisfy the specified attribute conditions.
Throws:
WavesetException

listObjects

public RepositoryResult listObjects(Type type,
                                    AttributeCondition[] attrConds,
                                    Attribute[] orderBy)
                             throws WavesetException
Parameters:
orderBy - - specifies the order in which to return results.
Returns:
summary information for all of objects of the specified type that satisfy the specified attribute conditions.
Throws:
WavesetException

lockObject

public LockInfo lockObject(Type type,
                           java.lang.String id,
                           java.lang.String lockedBy)
                    throws ItemNotFound,
                           LockedByAnother,
                           WavesetException
Lock an object to prevent another user from modifying it.

Locking is used to prevent other users from modifying the object for some period of time. This would be used in an application that presented an editing interface for fields in the object. While the object is being edited, it is desireable to prevent other users from editing the same object, to prevent overwriting of changes. Normally the checkoutObject is used to both lock and retrieve the object for editing. A call to checkoutObject is semantically the same as a call to lockObject followed by a call to getObject.

Locks are maintained in the repository and will persist until one of the following events:

  1. The checkinObject method is called on the object.
  2. The unlockObject method is called on the object.
  3. The lock times out.
Normally the application will call checkinObject to store changes to the object in the repository and release the lock. If the application has checked out an object for editing, and wishes to cancel the edit without storing any changes, the unlockObject method is called.

The repository will automatically remove or time out locks that have been held longer than a certain period of tome. This is necessary to prevent errant applications or forgetful users from holding onto locks for long periods of time. This is especially important in a web environment.

Parameters:
type - the type of the object.
id - the object id or name.
lockedBy - - uniquely identifies the caller. The lockedBy() method returns this same value.
Returns:
a LockInfo object containing information about the lock.
Throws:
LockedByAnother - if the object is already locked by someone else.
WavesetException - if an internal server error was encountered.
ItemNotFound
See Also:
checkoutObject(com.waveset.object.Type, java.lang.String, java.lang.String), getObject(com.waveset.object.Type, java.lang.String), unlockObject(com.waveset.object.Type, java.lang.String, java.lang.String), LockInfo

getLockInfo

public LockInfo getLockInfo(Type type,
                            java.lang.String id)
                     throws ItemNotFound,
                            WavesetException
Retrieve information about a lock held on the object.

A lock may be placed on an object through either the lockObject or checkoutObject methods. This mehtod may be used to determine whether or not such a lock exists.

Parameters:
type - the type of the object.
id - the object id or name.
Returns:
a LockInfo object containing information about the lock or null if there is no lock.
Throws:
ItemNotFound - if the object does not exist in the repository.
WavesetException - if an internal server error was encountered.
See Also:
lockObject(com.waveset.object.Type, java.lang.String, java.lang.String), unlockObject(com.waveset.object.Type, java.lang.String, java.lang.String), checkoutObject(com.waveset.object.Type, java.lang.String, java.lang.String), LockInfo

unlockObject

public void unlockObject(Type type,
                         java.lang.String id,
                         java.lang.String lockedBy)
                  throws ItemNotFound,
                         ItemNotLocked,
                         LockedByAnother,
                         WavesetException
Release a lock held on an object by the current user.

This method should be called by an application when the user wishes to cancel an editing operation on an object after a lock has been obtained.

Parameters:
type - the type of the object.
id - the object id or name.
lockedBy - - uniquely identifies the caller. If the object is currently locked by a caller, then only that caller may unlock the object.
Throws:
ItemNotFound - if the object does not exist in the repository.
ItemNotLocked - if the object is not locked.
LockedByAnother - if the object is locked by someone else.
WavesetException - if an internal server error was encountered.
See Also:
lockObject(com.waveset.object.Type, java.lang.String, java.lang.String), checkoutObject(com.waveset.object.Type, java.lang.String, java.lang.String)

breakLock

public void breakLock(Type type,
                      java.lang.String id,
                      java.lang.String brokenBy)
               throws ItemNotFound,
                      WavesetException
Forcibly remove the lock on an object.

This was originally added for the unit tests, which would sometimes crash and leave locks behind. It can also be useful to allow administrators to steal each others locks in case someone goes to lunch.

The user must have authorization to modify the object in order to break a lock. If no lock is held on the object, the method has no effect.

Parameters:
type - the type of the object.
id - the object id or name.
brokenBy - - a string identifying the caller.
Throws:
ItemNotFound - if the object does not exist in the repository.
WavesetException - if an internal server error was encountered.

checkoutObject

public PersistentObject checkoutObject(Type type,
                                       java.lang.String id,
                                       java.lang.String lockedBy)
                                throws ItemNotFound,
                                       LockedByAnother,
                                       WavesetException
Lock and retrieve an object for editing.

This method is normally used by an application that presents an editing interface for the fields in the object. Locking is used to prevent other users from modifying the object for some period of time. While the object is being edited, it is desireable to prevent other users from editing the same object, to prevent overwriting of changes.

The returned object may be modified by the application. When complete, the modifications are then stored in the repository by calling the checkinObject method.

Locks are maintained in the repository and will persist until one of the following events:

  1. The checkinObject method is called on the object.
  2. The unlockObject method is called on the object.
  3. The lock times out.
Normally the application will call checkinObject to store changes to the object in the repository and release the lock. If the application has checked out an object for editing, and wishes to cancel the edit without storing any changes, the unlockObject method is called.

The repository will automatically remove or time out locks that have been held longer than a certain period of tome. This is necessary to prevent errant applications or forgetful users from holding onto locks for long periods of time. This is especially important in a web environment.

Parameters:
type - the type of the object.
id - the object id or name.
lockedBy - - a string identifying the caller. If the item has been locked by a caller, then only that caller may update the item.
Returns:
a PersistentObject instance representing the contents of the requested object.
Throws:
ItemNotFound - if the object does not exist in the repository.
LockedByAnother - if the object is already locked by someone else.
WavesetException - if an internal server error was encountered.
See Also:
checkinObject(com.waveset.object.PersistentObject, java.lang.String), unlockObject(com.waveset.object.Type, java.lang.String, java.lang.String)

checkinObject

public void checkinObject(PersistentObject object,
                          java.lang.String lockedBy)
                   throws ItemNotFound,
                          ItemNotLocked,
                          LockedByAnother,
                          AlreadyExists,
                          ValidationFailed,
                          WavesetException
Stores the modifications to an object, and releases the lock.

This method is normally used by an application that presents an editing interface for the fields in the object. First the application calls checkoutObject to obtain a memory representation of the object. Next, the application uses accessor methods on the object to make the desired modifications. Finally the modifications are stored by calling checkinObject.

The object must have been locked by the current user for the checkin to succees. If the application has been executing for a long time, the lock originally obtained by a call to code>checkoutObject may have timed out. In this case the checkin will fail, and the ItemNotLocked exception is thrown. When this happens, the application should not simply obtain a new lock and store the changes, since changes made by another user may have been stored and would be lost. It is suggested that the application cancel the edit in progress, and require the user to perform the edit again. More sophisticated applications may attempt to merge the changes, though for some objects this can be difficult, and is not recommended.

The system will perform type specific validation on the object to ensure that it is well formed before storing it in the repository. If any of the validation tests fail, the ValidationFailed exception is thrown, which will contain an informative message.

Parameters:
object - a modified object to replace the old one.
lockedBy - - a string identifying the caller. If the item has been locked by a caller, then only that caller may delete the item.
Throws:
ItemNotFound - if the object does not exist in the repository.
ItemNotLocked - if the object is not locked.
LockedByANother - if the object is locked by someone else.
ValidationFailed - if the object has not been constructed properly.
WavesetException - if an internal server error was encountered.
LockedByAnother
AlreadyExists
See Also:
checkoutObject(com.waveset.object.Type, java.lang.String, java.lang.String), unlockObject(com.waveset.object.Type, java.lang.String, java.lang.String)

renameObject

public void renameObject(Type type,
                         java.lang.String id,
                         java.lang.String newName,
                         java.lang.String lockedBy)
                  throws ItemNotFound,
                         LockedByAnother,
                         AlreadyExists,
                         WavesetException
Changes the name of an existing object.

The object must either be unlocked, or locked by the current user. References to this object will still exist after the name change, references are made using the object's generated system identifier which does not change when the name changes.

Parameters:
type - the type of the object.
id - the object id or name.
newName - the new object name.
lockedBy - - a string identifying the caller. If the item has been locked by a caller, then only that caller may rename the item.
Throws:
ItemNotFound - if the object does not exist in the repository.
LockedByAnother - if the object is locked by someone else.
AlreadyExists - if the new name has already been assigned to another object.
WavesetException - if an internal server error was encountered.

resolveName

public java.lang.String resolveName(Type type,
                                    java.lang.String id)
                             throws ItemNotFound,
                                    WavesetException
Parameters:
type - the type of the object.
id - the object.
Returns:
the name of the object specified by type and ID.
Throws:
ItemNotFound - if the object does not exist in the repository.
WavesetException - if an internal server error was encountered.

resolve

public PersistentObject resolve(ObjectRef ref)
                         throws WavesetException
Returns:
the persistent object specified by the object reference.
Throws:
WavesetException

getLastMod

public long getLastMod(Type type)
                throws Shutdown,
                       NotInitialized,
                       ConfigurationError,
                       InternalError,
                       java.io.IOException
Parameters:
type - - the specified type (whether by this DataStore or another).
Returns:
the last time an item of the specified type was changed
Throws:
Shutdown
NotInitialized
ConfigurationError
InternalError
java.io.IOException

getLastMod

public long getLastMod(Type type,
                       long freshnessDate)
                throws Shutdown,
                       NotInitialized,
                       ConfigurationError,
                       InternalError,
                       java.io.IOException
Parameters:
type - - the specified type
freshnessDate - - reobtain value if cached before this time
Returns:
the last time an item of the specified type was changed. If the timestamp value was cached before the specified "freshness date", then re-obtain the value, incurring any necessary I/O.
Throws:
Shutdown
NotInitialized
ConfigurationError
InternalError
java.io.IOException

incrementCounter

public void incrementCounter(Type type,
                             java.lang.String nameOrId)
                      throws Shutdown,
                             NotInitialized,
                             ConfigurationError,
                             InvalidArgument,
                             ItemNotFound,
                             LockedByAnother,
                             InternalError,
                             java.io.IOException
Throws:
Shutdown
NotInitialized
ConfigurationError
InvalidArgument
ItemNotFound
LockedByAnother
InternalError
java.io.IOException

incrementCounter

public void incrementCounter(Type type,
                             java.lang.String nameOrId,
                             long valueToAdd)
                      throws Shutdown,
                             NotInitialized,
                             ConfigurationError,
                             InvalidArgument,
                             ItemNotFound,
                             LockedByAnother,
                             InternalError,
                             java.io.IOException
Throws:
Shutdown
NotInitialized
ConfigurationError
InvalidArgument
ItemNotFound
LockedByAnother
InternalError
java.io.IOException

setCounterValue

public void setCounterValue(Type type,
                            java.lang.String nameOrId,
                            long newValue)
                     throws Shutdown,
                            NotInitialized,
                            ConfigurationError,
                            InvalidArgument,
                            ItemNotFound,
                            LockedByAnother,
                            InternalError,
                            java.io.IOException
Throws:
Shutdown
NotInitialized
ConfigurationError
InvalidArgument
ItemNotFound
LockedByAnother
InternalError
java.io.IOException

getCounterValue

public long getCounterValue(Type type,
                            java.lang.String nameOrId)
                     throws Shutdown,
                            NotInitialized,
                            ConfigurationError,
                            InvalidArgument,
                            ItemNotFound,
                            InternalError,
                            java.io.IOException
Throws:
Shutdown
NotInitialized
ConfigurationError
InvalidArgument
ItemNotFound
InternalError
java.io.IOException

sumCounterValues

public long sumCounterValues(Type type,
                             AttributeCondition[] attrConds)
                      throws Shutdown,
                             NotInitialized,
                             ConfigurationError,
                             InvalidArgument,
                             ItemNotFound,
                             InternalError,
                             java.io.IOException
Throws:
Shutdown
NotInitialized
ConfigurationError
InvalidArgument
ItemNotFound
InternalError
java.io.IOException

listDeletedSinceMod

public RepositoryResult listDeletedSinceMod(Type type,
                                            long modified)
                                     throws Shutdown,
                                            NotInitialized,
                                            ConfigurationError,
                                            InvalidArgument,
                                            InternalError,
                                            java.io.IOException
Return summary information for any objects of the specified type that have been logically deleted since the specified modification counter value.

Throws:
Shutdown
NotInitialized
ConfigurationError
InvalidArgument
InternalError
java.io.IOException

destroyDeletedUpToMod

public void destroyDeletedUpToMod(Type type,
                                  long modified)
                           throws Shutdown,
                                  NotInitialized,
                                  ConfigurationError,
                                  InvalidArgument,
                                  InternalError,
                                  java.io.IOException
Physically delete any objects of the specified type that have been logically deleted with modification counter values less than or equal to the specified modification counter value.

Throws:
Shutdown
NotInitialized
ConfigurationError
InvalidArgument
InternalError
java.io.IOException