javax.jcr.lock
Interface LockManager

public interface LockManager

This interface encapsulates methods for the management of locks.

Since:

JCR 2.0

Method Summary

void	addLockToken(java.lang.String lockToken) Adds the specified lock token to the current Session.
Lock	getLock(java.lang.String absPath) Returns the Lock object that applies to the node at the specified absPath.
java.lang.String[]	getLockTokens() Returns an array containing all lock tokens currently held by the current Session.
boolean	holdsLock(java.lang.String absPath) Returns true if the node at absPath holds a lock; otherwise returns false.
boolean	isLocked(java.lang.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(java.lang.String absPath, boolean isDeep, boolean isSessionScoped, long timeoutHint, java.lang.String ownerInfo) Places a lock on the node at absPath.
void	removeLockToken(java.lang.String lockToken) Removes the specified lock token from this Session.
void	unlock(java.lang.String absPath) Removes the lock on the node at absPath.

Method Detail

addLockToken

void addLockToken(java.lang.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.

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(java.lang.String absPath)
             throws PathNotFoundException,
                    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.

Parameters:

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

Returns:

The applicable Lock object.

Throws:

LockException - if no lock applies to this node.

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

PathNotFoundException - if no node is found at absPath

RepositoryException - if another error occurs.

getLockTokens

java.lang.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(java.lang.String absPath)
                  throws PathNotFoundException,
                         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:

PathNotFoundException - if no node is found at absPath

RepositoryException - if an error occurs.

lock

Lock lock(java.lang.String absPath,
          boolean isDeep,
          boolean isSessionScoped,
          long timeoutHint,
          java.lang.String ownerInfo)
          throws LockException,
                 PathNotFoundException,
                 AccessDeniedException,
                 InvalidItemStateException,
                 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:lockIsDeep 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:lockIsDeep 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.

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:

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 sufficent access to lock this node.

InvalidItemStateException - if this node has pending unsaved changes.

PathNotFoundException - if no node is found at absPath

RepositoryException - if another error occurs.

isLocked

boolean isLocked(java.lang.String absPath)
                 throws PathNotFoundException,
                        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:

PathNotFoundException - if no node is found at absPath

RepositoryException - if an error occurs.

removeLockToken

void removeLockToken(java.lang.String lockToken)
                     throws LockException,
                            RepositoryException

Removes the specified lock token from this Session.

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(java.lang.String absPath)
            throws PathNotFoundException,
                   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 and is not a "lock-superuser", then a LockException is thrown. Note 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.

Parameters:

absPath - absolute path of node to be unlocked

Throws:

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.

PathNotFoundException - if no node is found at absPath

RepositoryException - if another error occurs.