1: <?php
2: /**
3: * The Horde_Lock class provides an API to create, store, check and expire locks
4: * based on a given resource URI.
5: *
6: * Copyright 2008-2012 Horde LLC (http://www.horde.org/)
7: *
8: * See the enclosed file COPYING for license information (LGPL). If you did
9: * not receive this file, see http://www.horde.org/licenses/lgpl21.
10: *
11: * @author Ben Klang <bklang@horde.org>
12: * @category Horde
13: * @package Lock
14: */
15: abstract class Horde_Lock
16: {
17: /* Class constants. */
18: const TYPE_EXCLUSIVE = 1;
19: const TYPE_SHARED = 2;
20:
21: /**
22: * Driver parameters.
23: *
24: * @var array
25: */
26: protected $_params;
27:
28: /**
29: * Logger.
30: *
31: * @var Horde_Log_Logger
32: */
33: protected $_logger;
34:
35: /**
36: * Constructor.
37: *
38: * @param array $params Configuration parameters:
39: * <pre>
40: * 'logger' - (Horde_Log_Logger) A logger instance.
41: * </pre>
42: */
43: public function __construct($params = array())
44: {
45: if (!empty($params['logger'])) {
46: $this->_logger = $params['logger'];
47: unset($params['logger']);
48: }
49:
50: $this->_params = $params;
51: }
52:
53: /**
54: * Return an array of information about the requested lock.
55: *
56: * @param string $lockid Lock ID to look up.
57: *
58: * @return array Lock information.
59: * @throws Horde_Lock_Exception
60: */
61: abstract public function getLockInfo($lockid);
62:
63: /**
64: * Return a list of valid locks with the option to limit the results
65: * by principal, scope and/or type.
66: *
67: * @param string $scope The scope of the lock. Typically the name of
68: * the application requesting the lock or some
69: * other identifier used to group locks together.
70: * @param string $principal Principal for which to check for locks
71: * @param integer $type Only return locks of the given type.
72: * Defaults to null, or all locks
73: *
74: * @return array Array of locks with the ID as the key and the lock details
75: * as the value. If there are no current locks this will
76: * return an empty array.
77: * @throws Horde_Lock_Exception
78: */
79: abstract public function getLocks($scope = null, $principal = null,
80: $type = null);
81:
82: /**
83: * Extend the valid lifetime of a valid lock to now + $extend.
84: *
85: * @param string $lockid Lock ID to reset. Must be a valid, non-expired
86: * lock.
87: * @param integer $extend Extend lock this many seconds from now.
88: *
89: * @return boolean Returns true on success.
90: * @throws Horde_Lock_Exception
91: */
92: abstract public function resetLock($lockid, $extend);
93:
94: /**
95: * Sets a lock on the requested principal and returns the generated lock
96: * ID. NOTE: No security checks are done in the Horde_Lock API. It is
97: * expected that the calling application has done all necessary security
98: * checks before requesting a lock be granted.
99: *
100: * @param string $requestor User ID of the lock requestor.
101: * @param string $scope The scope of the lock. Typically the name of
102: * the application requesting the lock or some
103: * other identifier used to group locks
104: * together.
105: * @param string $principal A principal on which a lock should be
106: * granted. The format can be any string but is
107: * suggested to be in URI form.
108: * @param integer $lifetime Time (in seconds) for which the lock will be
109: * considered valid.
110: * @param string exclusive One of Horde_Lock::TYPE_SHARED or
111: * Horde_Lock::TYPE_EXCLUSIVE.
112: * - An exclusive lock will be enforced strictly
113: * and must be interpreted to mean that the
114: * resource can not be modified. Only one
115: * exclusive lock per principal is allowed.
116: * - A shared lock is one that notifies other
117: * potential lock requestors that the resource
118: * is in use. This lock can be overridden
119: * (cleared or replaced with a subsequent
120: * call to setLock()) by other users. Multiple
121: * users may request (and will be granted) a
122: * shared lock on a given principal. All locks
123: * will be considered valid until they are
124: * cleared or expire.
125: *
126: * @return mixed A string lock ID.
127: * @throws Horde_Lock_Exception
128: */
129: abstract public function setLock($requestor, $scope, $principal,
130: $lifetime = 1,
131: $exclusive = Horde_Lock::TYPE_SHARED);
132:
133: /**
134: * Removes a lock given the lock ID.
135: * NOTE: No security checks are done in the Horde_Lock API. It is
136: * expected that the calling application has done all necessary security
137: * checks before requesting a lock be cleared.
138: *
139: * @param string $lockid The lock ID as generated by a previous call
140: * to setLock()
141: *
142: * @return boolean Returns true on success.
143: * @throws Horde_Lock_Exception
144: */
145: abstract public function clearLock($lockid);
146: }
147: