LockService


1   /*
2    * Copyright (C) 2005 Alfresco, Inc.
3    *
4    * Licensed under the Mozilla Public License version 1.1 
5    * with a permitted attribution clause. You may obtain a
6    * copy of the License at
7    *
8    *   http://www.alfresco.org/legal/license.txt
9    *
10   * Unless required by applicable law or agreed to in writing,
11   * software distributed under the License is distributed on an
12   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
13   * either express or implied. See the License for the specific
14   * language governing permissions and limitations under the
15   * License.
16   */
17  package org.alfresco.service.cmr.lock;
18  
19  import java.util.Collection  ;
20  import java.util.List  ;
21  
22  import org.alfresco.service.cmr.repository.NodeRef;
23  import org.alfresco.service.cmr.repository.StoreRef;
24  
25  
26  /**
27   * Interface for public and internal lock operations.
28   * 
29   * @author Roy Wetherall
30   */
31  public interface LockService
32  {
33     /**
34      * Places a lock on a node.  
35      * <p>
36      * The lock prevents any other user or process from comitting updates 
37      * to the node untill the lock is released.  
38      * <p>
39      * The user reference passed indicates who the owner of the lock is.
40      * <p>
41      * A lock made with this call will never expire.
42      * 
43      * @param  nodeRef  a reference to a node 
44      * @param  userName  a reference to the user that will own the lock
45      * @param  lockType the lock type
46      * @throws UnableToAquireLockException
47      *                  thrown if the lock could not be obtained
48      */
49     public void lock(NodeRef nodeRef, LockType lockType)
50         throws UnableToAquireLockException;
51     
52     /**
53      * Places a lock on a node.  
54      * <p>
55      * The lock prevents any other user or process from comitting updates 
56      * to the node untill the lock is released.  
57      * <p>
58      * The user reference passed indicates who the owner of the lock is.
59      * <p>
60      * If the time to expire is 0 then the lock will never expire.  Otherwise the
61      * timeToExpire indicates the number of seconds before the lock expires.  When
62      * a lock expires the lock is considered to have been released.
63      * <p>
64      * If the node is already locked and the user is the lock owner then the lock will
65      * be renewed with the passed timeToExpire.
66      * 
67      * @param  nodeRef       a reference to a node 
68      * @param  userName      a reference to the user that will own the lock
69      * @param  lockType      the lock type
70      * @param  timeToExpire  the number of seconds before the locks expires.
71      * @throws UnableToAquireLockException
72      *                       thrown if the lock could not be obtained
73      */
74     public void lock(NodeRef nodeRef, LockType lockType, int timeToExpire)
75         throws UnableToAquireLockException;
76     
77     /**
78      * Places a lock on a node and optionally on all its children.  
79      * <p>
80      * The lock prevents any other user or process from comitting updates 
81      * to the node untill the lock is released.  
82      * <p>
83      * The user reference passed indicates who the owner of the lock(s) is.  
84      * If any one of the child locks can not be taken then an exception will 
85      * be raised and all locks canceled.
86      * <p>
87      * If the time to expire is 0 then the lock will never expire.  Otherwise the
88      * timeToExpire indicates the number of seconds before the lock expires.  When
89      * a lock expires the lock is considered to have been released.
90      * <p>
91      * If the node is already locked and the user is the lock owner then the lock will
92      * be renewed with the passed timeToExpire.
93      * 
94      * @param nodeRef            a reference to a node
95      * @param userName           a reference to the user that will own the lock(s)
96      * @param lockType           the lock type 
97      * @param timeToExpire       the number of seconds before the locks expires.
98      * @param lockChildren       if true indicates that all the children (and 
99      *                           grandchildren, etc) of the node will also be locked, 
100     *                           false otherwise
101     * 
102     * @throws UnableToAquireLockException
103     *                           thrown if the lock could not be obtained
104     */
105    public void lock(NodeRef nodeRef, LockType lockType, int timeToExpire, boolean lockChildren)
106        throws UnableToAquireLockException;
107    
108    /**
109     * Places a lock on all the nodes referenced in the passed list.  
110     * <p>
111     * The lock prevents any other user or process from comitting updates 
112     * to the node untill the lock is released.  
113     * <p>
114     * The user reference passed indicates who the owner of the lock(s) is.  
115     * If any one of the child locks can not be taken then an exception will 
116     * be raised and all locks canceled.
117     * <p>
118     * If the time to expire is 0 then the lock will never expire.  Otherwise the
119     * timeToExpire indicates the number of seconds before the lock expires.  When
120     * a lock expires the lock is considered to have been released.
121     * <p>
122     * If the node is already locked and the user is the lock owner then the lock will
123     * be renewed with the passed timeToExpire.
124     * 
125     * @param  nodeRefs          a list of node references
126     * @param  userName          a reference to the user that will own the lock(s)
127     * @param  lockType          the type of lock being created
128     * @param  timeToExpire      the number of seconds before the locks expires.
129     * @throws UnableToAquireLockException
130     *                           thrown if the lock could not be obtained
131     */
132    public void lock(Collection  <NodeRef> nodeRefs, LockType lockType, int timeToExpire)
133        throws UnableToAquireLockException;
134    
135    /**
136     * Removes the lock on a node.  
137     * <p>
138     * The user must have sufficient permissions to remove the lock (ie: be the 
139     * owner of the lock or have admin rights) otherwise an exception will be raised. 
140     * 
141     * @param  nodeRef  a reference to a node
142     * @param  userName  the user reference
143     * @throws UnableToReleaseLockException
144     *                  thrown if the lock could not be released             
145     */
146    public void unlock(NodeRef nodeRef)
147        throws UnableToReleaseLockException;
148    
149    /**
150     * Removes the lock on a node and optional on its children.  
151     * <p>
152     * The user must have sufficient permissions to remove the lock(s) (ie: be 
153     * the owner of the lock(s) or have admin rights) otherwise an exception 
154     * will be raised.
155     * <p>
156     * If one of the child nodes is not locked then it will be ignored and 
157     * the process continue without error.  
158     * <p>
159     * If the lock on any one of the child nodes cannot be released then an 
160     * exception will be raised.
161     * 
162     * @param  nodeRef        a node reference
163     * @param  userName        the user reference
164     * @param  lockChildren   if true then all the children (and grandchildren, etc) 
165     *                        of the node will also be unlocked, false otherwise
166     * @throws UnableToReleaseLockException
167     *                  thrown if the lock could not be released
168     */
169    public void unlock(NodeRef nodeRef, boolean lockChildren)
170        throws UnableToReleaseLockException;
171    
172    /**
173     * Removes a lock on the nodes provided.
174     * <p>
175     * The user must have sufficient permissions to remove the locks (ie: be 
176     * the owner of the locks or have admin rights) otherwise an exception 
177     * will be raised.
178     * <p>
179     * If one of the nodes is not locked then it will be ignored and the
180     * process will continue without an error.
181     * <p>
182     * If the lock on any one of the nodes cannot be released than an exception 
183     * will be raised and the process rolled back.
184     * 
185     * @param  nodeRefs  the node references
186     * @param  userName   the user reference
187     * @throws UnableToReleaseLockException
188     *                  thrown if the lock could not be released
189     */
190    public void unlock(Collection  <NodeRef> nodeRefs)
191        throws UnableToReleaseLockException;
192    
193    /**
194     * Gets the lock status for the node reference relative to the current user.
195     * 
196     * @see LockService#getLockStatus(NodeRef, NodeRef)
197     * 
198     * @param nodeRef    the node reference
199     * @return           the lock status
200     */
201    public LockStatus getLockStatus(NodeRef nodeRef);
202    
203    /**
204     * Gets the lock type for the node indicated.  
205     * <p>
206     * Returns null if the node is not locked.
207     * <p>
208     * Throws an exception if the node does not have the lock aspect.
209     * 
210     * @param  nodeRef  the node reference
211     * @return          the lock type, null is returned if the object in question has no
212     *                  lock
213     */
214    public LockType getLockType(NodeRef nodeRef);
215    
216    /**
217     * Checks to see if the node is locked or not.  Gets the user reference from the current 
218     * session.
219     * <p>
220     * Throws a NodeLockedException based on the lock status of the lock, the user ref and the
221     * lock type.
222     * 
223     * @param nodeRef   the node reference
224     */
225    public void checkForLock(NodeRef nodeRef);   
226    
227    /**
228     * Get all the node references that the current user has locked.
229     * 
230     * @param    storeRef    the store reference
231     * @return               a list of nodes that the current user has locked.
232     */
233    public List  <NodeRef> getLocks(StoreRef storeRef);
234    
235    /**
236     * Get all the node references that the current user has locked filtered by the provided lock type.
237     * 
238     * @param storeRef   the store reference
239     * @param lockType   the lock type to filter the results by
240     * 
241     * @return           a list of nodes that the current user has locked filtered by the lock type provided
242     */
243    public List  <NodeRef> getLocks(StoreRef storeRef, LockType lockType);
244 }
245
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags