org.apache.jackrabbit.api.jsr283.lock
Interface LockManager

All Known Implementing Classes:

LockManagerImpl, SessionLockManager

public interface LockManager

This interface holds extensions made in JCR 2.0 while work is in progress implementing JCR 2.0. It encapsulates methods for the management of locks.

Since:

JCR 2.0

Method Summary

void	addLockToken(String lockToken) Adds the specified lock token to the current Session.
Lock	getLock(String absPath) Returns the Lock object that applies to the node at the specified absPath.
String[]	getLockTokens() Returns an array containing all lock tokens currently held by the current Session.
boolean	holdsLock(String absPath) Returns true if the node at absPath holds a lock; otherwise returns false.
boolean	isLocked(String absPath) Returns true if the node at absPath is locked either as a result of a lock held by that node or by a deep lock on a node above that node; otherwise returns false.
Lock	lock(String absPath, boolean isDeep, boolean isSessionScoped, long timeoutHint, String ownerInfo) Places a lock on the node at absPath.
void	removeLockToken(String lockToken) Removes the specified lock token from this Session.
void	unlock(String absPath) Removes the lock on the node at absPath.

Method Detail

addLockToken

void addLockToken(String lockToken)
                  throws LockException,
                         RepositoryException

Adds the specified lock token to the current Session. Holding a lock token makes the current Session the owner of the lock specified by that particular lock token.

A LockException is thrown if the specified lock token is already held by another Session and the implementation does not support simultaneous ownership of open-scoped locks.

Parameters:

lockToken - a lock token (a string).

Throws:

LockException - if the specified lock token is already held by another Session and the implementation does not support simultaneous ownership of open-scoped locks.

RepositoryException - if another error occurs.

getLock

Lock getLock(String absPath)
             throws UnsupportedRepositoryOperationException,
                    LockException,
                    AccessDeniedException,
                    RepositoryException

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

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

If the current session does not have sufficient privileges 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.

Parameters:

absPath - absolute path of node for which to obtain the lock

Returns:

The applicable Lock object.

Throws:

UnsupportedRepositoryOperationException - if this implementation does not support locking.

LockException - if no lock applies to this node.

AccessDeniedException - if the current session does not have permission to get the lock.

RepositoryException - if another error occurs.

getLockTokens

String[] getLockTokens()
                       throws RepositoryException

Returns an array containing all lock tokens currently held by the current Session. Note that any such tokens will represent open-scoped locks, since session-scoped locks do not have tokens.

Returns:

an array of lock tokens (strings)

Throws:

RepositoryException - if an error occurs.

holdsLock

boolean holdsLock(String absPath)
                  throws RepositoryException

Returns true if the node at absPath 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 a node above.

Parameters:

absPath - absolute path of node

Returns:

a boolean.

Throws:

RepositoryException - if an error occurs.

lock

Lock lock(String absPath,
          boolean isDeep,
          boolean isSessionScoped,
          long timeoutHint,
          String ownerInfo)
          throws RepositoryException

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

If isDeep is true then the lock applies to the specified node and all its descendant nodes; if false, the lock applies only to the specified node. On a successful lock, the jcr:isDeep property of the locked node is set to this value.

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 it is explicitly unlocked, it times out, or it is automatically unlocked due to a implementation-specific limitation.

The timeout parameter specifies the number of seconds until the lock times out (if it is not refreshed with Lock.refresh in the meantime). An implementation may use this information as a hint or ignore it altogether. Clients can discover the actual timeout by inspecting the returned Lock object.

The ownerInfo parameter can be used to pass a string holding owner information relevant to the client. An implementation may either use or ignore this parameter. If it uses the parameter it must set the jcr:lockOwner property of the locked node to this value and return this value on Lock.getLockOwner. If it ignores this parameter the jcr:lockOwner property (and the value returned by Lock.getLockOwner) is set to either the value returned by Session.getUserID of the owning session or an implementation-specific string identifying the owner.

The method returns a Lock object representing the new lock. If the lock is open-scoped the returned lock will include a lock token. The lock token is also automatically added to the set of lock tokens held by the current session.

The addition or change of the properties jcr:isDeep and jcr:lockOwner are persisted immediately; there is no need to call save.

It is possible to lock a node even if it is checked-in.

If this node is not of mixin node type mix:lockable then an 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 this node does not have a persistent state (has never been saved or otherwise persisted), a LockException is thrown.

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

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

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

A RepositoryException is thrown if another error occurs.

Parameters:

absPath - absolute path of node to be locked

isDeep - if true this lock will apply to this node and all its descendants; if false, it applies only to this node.

isSessionScoped - if true, this lock expires with the current session; if false it expires when explicitly or automatically unlocked for some other reason.

timeoutHint - desired lock timeout in seconds (servers are free to ignore this value); specify Long.MAX_VALUE for no timeout.

ownerInfo - a string containing owner information supplied by the client; servers are free to ignore this value.

Returns:

A Lock object containing a lock token.

Throws:

UnsupportedRepositoryOperationException - if this implementation does not support locking.

LockException - if this node is not mix:lockable or this node is already locked or isDeep is true and a descendant node of this node already holds a lock.

AccessDeniedException - if this session does not have permission to lock this node.

InvalidItemStateException - if this node has pending unsaved changes.

RepositoryException - if another error occurs.

isLocked

boolean isLocked(String absPath)
                 throws RepositoryException

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

Parameters:

absPath - absolute path of node

Returns:

a boolean.

Throws:

RepositoryException - if an error occurs.

removeLockToken

void removeLockToken(String lockToken)
                     throws LockException,
                            RepositoryException

Removes the specified lock token from this Session.

A LockException is thrown if the current Session does not hold the specified lock token.

A RepositoryException is thrown if another error occurs.

Parameters:

lockToken - a lock token (a string)

Throws:

LockException - if the current Session does not hold the specified lock token.

RepositoryException - if another error occurs.

unlock

void unlock(String absPath)
            throws UnsupportedRepositoryOperationException,
                   LockException,
                   AccessDeniedException,
                   InvalidItemStateException,
                   RepositoryException

Removes the lock on the node at absPath. Also removes the properties jcr:lockOwner and jcr:lockIsDeep from that node. As well, the corresponding lock token is removed from the set of lock tokens held by the current Session.

If the node does not currently hold a lock or holds a lock for which this Session is not the owner, then a LockException is thrown. Note however that the system may give permission to a non-owning session to unlock a lock. Typically such "lock-superuser" capability is intended to facilitate administrational clean-up of orphaned open-scoped locks.

Note 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).

If the current session does not have sufficient privileges 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.

Parameters:

absPath - absolute path of node to be unlocked

Throws:

UnsupportedRepositoryOperationException - if this implementation does not support locking.

LockException - if this node does not currently hold a lock or holds a lock for which this Session does not have the correct lock token

AccessDeniedException - if the current session does not have permission to unlock this node.

InvalidItemStateException - if this node has pending unsaved changes.

RepositoryException - if another error occurs.