phpcr/src/PHPCR/Lock/LockManagerInterface.php

Show:

inherited

Table of Contents

This file is part of the PHPCR API and was originally ported from the Java JCR API to PHP by Karsten Dambekalns for the FLOW3 project.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

License: Apache Software License 2.0
Link: http://phpcr.github.com/

\PHPCR\Lock\LockManagerInterface
jump to top

Package: Default

This interface encapsulates methods for the management of locks.

The \Traversable interface enables the implementation to be addressed with foreach. LockManager has to implement either \IteratorAggregate or \Iterator. The iterator is equivalent to getLockTokens() returning a list of all locks. The iterator keys have no significant meaning.

Parent(s): \Traversable
Api

Methods

addLockToken(string $lockToken) : void

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

Name	Type	Description
$lockToken	string	A lock token (a string).

Throws

Exception	Description
\PHPCR\Lock\LockException	if the specified lock token is already held by another Session and the implementation does not support simultaneous ownership of open-scoped locks.
\PHPCR\RepositoryException	if another error occurs.

Details

Api

createLockInfo() : \PHPCR\Lock\LockInfoInterface

Creates a ockInfo object that can then be configured and passed to the method lockWithInfo

Returns

Type	Description
\PHPCR\Lock\LockInfoInterface	the object instance to be configured

Details

Api

getLock(string $absPath) : \PHPCR\Lock\LockInterface

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

Name	Type	Description
$absPath	string	absolute path of node for which to obtain the lock.

Returns

Type	Description
\PHPCR\Lock\LockInterface	The applicable Lock object.

Throws

Exception	Description
\PHPCR\Lock\LockException	if no lock applies to this node.
\PHPCR\AccessDeniedException	if the current session does not have sufficient access to get the lock.
\PHPCR\PathNotFoundException	if no node is found at $absPath
\PHPCR\RepositoryException	if another error occurs.

Details

Api

getLockTokens() : array

Gets the list of previously registered tokens.

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

Type	Description
array	an array of lock tokens (strings)

Throws

Exception	Description
\PHPCR\RepositoryException	if an error occurs.

Details

Api

holdsLock(string $absPath) : boolean

Determines if the node identified by the passed path holds a lock.

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

Name	Type	Description
$absPath	string	The absolute path of node to be checked.

Returns

Type	Description
boolean	True, if the node identified by the given path holds a lock, else false.

Throws

Exception	Description
\PHPCR\PathNotFoundException	if no node is found at $absPath
\PHPCR\RepositoryException	if an error occurs.

Details

Api

isLocked(string $absPath) : boolean

Determines if the node at absPath is locked.

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

Name	Type	Description
$absPath	string	The absolute path of a node to be checked.

Returns

Type	Description
boolean	True, if the identified node has a lock.

Throws

Exception	Description
\PHPCR\PathNotFoundException	if no node is found at $absPath.
\PHPCR\RepositoryException	if an error occurs.

Details

Api

lock(string $absPath, boolean $isDeep, boolean $isSessionScoped, integer $timeoutHint = PHP_INT_MAX, string $ownerInfo = null) : \PHPCR\Lock\LockInterface

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 SessionInterface::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 LockInterface::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 LockInterface::getLockOwner(). If it ignores this parameter the jcr:lockOwner property (and the value returned by LockInterface::getLockOwner()) is set to either the value returned by SessionInterface::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:lockOwnerare persisted immediately; there is no need to call save.

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

Parameters

Name	Type	Description
$absPath	string	The absolute path of node to be locked
$isDeep	boolean	If true this lock will apply to this node and all its descendants; if false, it applies only to this node.
$isSessionScoped	boolean	If true, this lock expires with the current session; if false it expires when explicitly or automatically unlocked for some other reason.
$timeoutHint	integer	Desired lock timeout in seconds (servers are free to ignore this value); specify PHP_INT_MAX for no timeout. If not specified, defaults to no timeout.
$ownerInfo	string	A string containing owner information supplied by the client; servers are free to ignore this value. If none is specified, the implementation chooses one (i.e. user name of current backend authentication credentials)

Returns

Type	Description
\PHPCR\Lock\LockInterface	A Lock object containing a lock token.

Throws

Exception	Description
\PHPCR\Lock\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.
\PHPCR\AccessDeniedException	if this session does not have sufficient access to lock this node.
\PHPCR\InvalidItemStateException	if this node has pending unsaved changes.
\PHPCR\PathNotFoundException	if no node is found at $absPath
\PHPCR\RepositoryException	if another error occurs.

Details

Api

lockWithInfo(string $absPath, \PHPCR\Lock\LockInfoInterface $lockInfo) : \PHPCR\Lock\LockInterface

Alternative method to lock with all the options in one configuration class.

Parameters

Name	Type	Description
$absPath	string	The absolute path of node to be locked
$lockInfo	\PHPCR\Lock\LockInfoInterface	configured with the desired characteristics for this lock.

Returns

Type	Description
\PHPCR\Lock\LockInterface	A Lock object containing a lock token.

Throws

Exception	Description
\PHPCR\Lock\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.
\PHPCR\AccessDeniedException	if this session does not have sufficient access to lock this node.
\PHPCR\InvalidItemStateException	if this node has pending unsaved changes.
\PHPCR\PathNotFoundException	if no node is found at $absPath
\PHPCR\RepositoryException	if another error occurs.

removeLockToken(string $lockToken) : void

Removes the specified lock token from this Session.

Parameters

Name	Type	Description
$lockToken	string	a lock token (a string)

Throws

Exception	Description
\PHPCR\Lock\LockException	if the current Session does not hold the specified lock token.
\PHPCR\RepositoryException	if another error occurs.

Details

Api

unlock(string $absPath) : void

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 \PHPCR\Lock\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).

Parameters

Name	Type	Description
$absPath	string	The absolute path of node to be unlocked.

Throws

Exception	Description
\PHPCR\Lock\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.
\PHPCR\AccessDeniedException	if the current session does not have permission to unlock this node.
\PHPCR\InvalidItemStateException	if this node has pending unsaved changes.
\PHPCR\PathNotFoundException	if no node is found at $absPath
\PHPCR\RepositoryException	if another error occurs.

Details

Api

phpcr/src/PHPCR/Lock/LockManagerInterface.php

\PHPCR\Lock\LockManagerInterfacejump to top

Methods

\PHPCR\Lock\LockManagerInterface
jump to top