Overview

The JADE Object Manager client maintains a local cache of objects. When a request is made for an object, the client checks its local cache before loading the object from the server. If the object is not present in the local cache, it is loaded from the server into the client local cache.

The object is the unit of transfer between the client and the server.

When an object is updated, a lock is automatically registered with the server if the object has not been manually locked in an exclusive manner.

When an object is locked, the client passes the edition of the object in local cache to the server. If the local copy is out of date, a new copy of the object is passed to the client.

If an object is to be locked, the first reference to it should be the lock operation itself.

For details about locking when reading and writing transactions and examples of transaction locks and applying shared locks on global objects, see also "Using Read and Write Transactions", in Chapter 1.

For a discussion about locking, see the Erewhon.pdf file that is included in the erewhon subdirectory of the examples directory on the JADE release medium.

You can optimize locking based on the frequency at which an object is updated, by specifying that an object has one of the following volatility states.

Volatile, indicating that the object is often updated

A volatile object is recorded as locked by any processes that have it locked until they unlock it, and whenever locked, the latest edition of the object is fetched from the database.
Stable, indicating that the object is updated infrequently

A shared lock in a stable object is locked by the process and by the node. A node lock is retained, avoiding a call the server on subsequent locks on that node, until the object is swapped out of cache or an exclusive lock is requested on any node.
Frozen, indicating that the object is not updated

A frozen object in cache is assumed to always be the latest edition, avoiding the fetch from the server node. A frozen object must have its volatility changed before it can be changed.

The Object class provides the cache concurrency methods summarized in the following table.

Method	Description
changeObjectVolatility	Changes the volatility of a persistent object
getObjectVolatility	Returns the volatility state of the specified object
isObjectFrozen	Determines whether the receiver object is frozen (not updated)
isObjectStable	Determines whether the receiver object is stable (updated infrequently)
isObjectVolatile	Determines whether the receiver object is volatile (often updated)
makeObjectFrozen	Makes the specified persistent object frozen
makeObjectStable	Makes the specified persistent object stable
makeObjectVolatile	Makes the specified persistent object volatile

Volatility applies only to persistent objects. All transient objects are considered volatile. For details, see "Cache Concurrency", later in this chapter.

The Object class provides methods that enable you to specify the action that is taken if a lock cannot be obtained on an object. For more details, see the following methods under "Object Class", in Volume 2 of the JADE Encyclopaedia of Classes.

Method	Description
exclusiveLock	Attempts to acquire an exclusive lock on the specified object
getLockStatus	Gets the status of the specified lock
isLockedByMe	Returns true if you are the owner of the lock on the specified object
lock	Obtains a lock of the specified type or raises a lock exception if the lock cannot be obtained
reserveLock	Attempts to acquire a reserve lock on the specified object
sharedLock	Places a shared lock on the specified object
tryLock	Returns true if the lock was obtained or returns false if the lock could not be obtained (your code determines the action that is then taken)
unlock	Removes the current lock from the specified object
updateLock	Attempts to acquire an update lock on the specified object

The Node class describes the behavior of the JADE node. For details, see the following method under "Node Class", in Volume 2 of the JADE Encyclopaedia of Classes.

Method	Description
getLocks	Populates an array with transient instances of the current locks for the shared transient objects in the node

The Process class describes the behavior of the JADE process. For details, see the following methods under "Process Class", in Volume 2 of the JADE Encyclopaedia of Classes

Method	Description
isCommitting	Returns true if the process is currently committing a transaction
setDefaultLockTimeout	Programmatically changes the default lock timeout period for the receiving process
useUpdateLocks	Update locks rather than Exclusive locks are implicitly acquired when an object is updated

The System class describes the behavior of the JADE system. For details, see the following methods under "System Class", in Volume 2 of the JADE Encyclopaedia of Classes.

Method	Populates …
getLocks	An array with transient instances of the current locks held by all processes in the system
getObjectLockProcesses	A dictionary parameter with processes that have locks on the specified object
getQueuedLocks	An array with lock requests that are waiting for objects to be unlocked by the processes that currently have them locked

The Lock class describes the lock requests maintained by the system, and provides the target method that is used to get the object that is the target of a lock request.

The method summarized in the following table is defined in the Lock class.

Method	Description
target	Gets the object that is the target of the lock request

In addition, the Lock class provides the properties summarized in the following table.

Property	Description
duration	Specifies when the object is automatically unlocked
elapsedTime	Contains the time that the lock has been in place
kind	Contains the type of lock (that is, normal, local, node, or node lock to be removed)
lockedBy	Contains the process that currently holds a lock
requestedBy	Contains the process that submitted the lock request
requestTime	Contains the date and time of the lock request
type	Contains the type of lock request
waitTime	Contains the length of time the lock request waits

For more details, see "Lock Class", in Chapter 1 of the JADE Encyclopaedia of Classes.

The RootSchema provides two generic lock exception handler methods. You can arm these lock exception handlers in your own applications to handle lock exceptions. These can be armed as local exception handlers or as global exception handlers; for example:

// global exception handler
on LockException do app.globalLockException(exception) global;

// local exception handler on the global object
on LockException do global.lockExceptionHandler(exception);