8.4.11 Locking Methods

The methods for locking, unlocking and querying the locking status of a node are found in the Node interface itself:

javax.jcr.
Node

Lock

lock(boolean isDeep, boolean isSessionScoped)

Places a lock on this node. If successful, this node is said to hold the lock.

If isDeep is true then the lock applies to this node and all its descendant nodes; if false, the lock applies only to this, the holding node.

If isSessionScoped is true then this lock will expire upon the expiration of the current session (either through an automatic or explicit Session.logout); if false, this lock does not expire until explicitly unlocked or automatically unlocked due to a implementation-specific limitation, such as a timeout.

Returns a Lock object reflecting the state of the new lock and including a lock token.

The lock token is also automatically added to the set of lock tokens held by the current Session.

If successful, then the property jcr:lockOwner is created and set to the value of Session.getUserID for the current session and the property jcr:lockIsDeep is set to the value passed in as isDeep. These changes are persisted automatically; there is no need to call save.

Note that it is possible to lock a node even if it is checked-in (the lock-related properties will be changed despite the checked-in status). See 8.2 Versioning for an explanation of “checked-in” status.

If this node is not of mixin node type mix:lockable then a LockException is thrown.

If this node is already locked (either because it holds a lock or a lock above it applies to it), a LockException is thrown.

If isDeep is true and a descendant node of this node already holds a lock, then a LockException is thrown.

If the current session does not have sufficient permissions to place the lock, an AccessDeniedException is thrown.

An InvalidItemStateException is thrown if this node has pending unsaved changes.

An UnsupportedRepositoryOperationException is thrown if this implementation does not support locking.

A RepositoryException is thrown if another error occurs.

Lock

getLock()

Returns the Lock object that applies to this node. This may be either a lock on this node itself or a deep lock on a node above this node.

If this Session (the one through which this Node was acquired) holds the lock token for this lock, then the returned Lock object contains that lock token (accessible through Lock.getLockToken). If this Session does not hold the applicable lock token, then the returned Lock object will not contain the lock token (its Lock.getLockToken method will return null). See Lock, below.

If this node is not locked (no lock applies to this node) then a LockException is thrown.

If the current session does not have sufficient permissions to get the lock, an AccessDeniedException is thrown.

An UnsupportedRepositoryOperationException is thrown if this implementation does not support locking.

A RepositoryException is thrown if another error occurs.

void

unlock()

Removes the lock on this node. Also removes the properties jcr:lockOwner and jcr:lockIsDeep from this node. These changes are persisted automatically; there is no need to call save.

If this node does not currently hold a lock or holds a lock for which this Session does not have the correct lock token, then a LockException is thrown. Note however that the system may give permission to some users to unlock locks for which they do not have the lock token. Typically such “lock-superuser” capability is intended to facilitate administrational clean-up of orphaned open-scoped locks.

Note also that it is possible to unlock a node even if it is checked-in (the lock-related properties will be changed despite the checked-in status). See 8.2 Versioning for an explanation of “checked-in” status.

If the current session does not have sufficient permissions to remove the lock, an AccessDeniedException is thrown.

An InvalidItemStateException is thrown if this node has pending unsaved changes.

An UnsupportedRepositoryOperationException is thrown if this implementation does not support locking.

A RepositoryException is thrown if another error occurs.

boolean

holdsLock()

Returns true if this node holds a lock; otherwise returns false. To hold a lock means that this node has actually had a lock placed on it specifically, as opposed to just having a lock apply to it due to a deep lock held by an node above.

A RepositoryException is thrown if an error occurs.

boolean

isLocked()

Returns true if this node is locked either as a result of a lock held by this node or by a deep lock on a node above this node; otherwise returns false.

A RepositoryException is thrown if an error occurs.