1 /**
2 * Copyright 2005-2012 The Kuali Foundation
3 *
4 * Licensed under the Educational Community License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.opensource.org/licenses/ecl2.php
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.kuali.rice.krad.service;
17
18 import org.kuali.rice.kim.api.identity.Person;
19 import org.kuali.rice.krad.document.Document;
20 import org.kuali.rice.krad.document.authorization.PessimisticLock;
21
22 import java.util.List;
23 import java.util.Map;
24 import java.util.Set;
25
26 /**
27 * This is the service interface for documents to use the Pessimistic Locking mechanism
28 *
29 * @author Kuali Rice Team (rice.collab@kuali.org)
30 *
31 */
32 public interface PessimisticLockService {
33
34 /**
35 * This method deletes the given lock object
36 *
37 * @param id - the id of the lock to delete
38 */
39 public void delete(String id);
40
41 /**
42 * This method will generate a new {@link PessimisticLock} object with a 'document'
43 * lock descriptor
44 *
45 * @param documentNumber - the document number of the document associated with the new lock
46 * @return the newly generated document descriptor {@link PessimisticLock}
47 */
48 public PessimisticLock generateNewLock(String documentNumber);
49
50 /**
51 * This method will generate a new {@link PessimisticLock} object with a lock descriptor of
52 * the given parameter
53 *
54 * @param documentNumber - the document number of the document associated with the new lock
55 * @param lockDescriptor - the lock descriptor the new PessimisticLock object should contain
56 * @return the newly generated {@link PessimisticLock} containing the given lockDescriptor
57 */
58 public PessimisticLock generateNewLock(String documentNumber, String lockDescriptor);
59
60 /**
61 * This method will generate a new {@link PessimisticLock} object with a 'document'
62 * lock descriptor
63 *
64 * @param documentNumber - the document number of the document associated with the new lock
65 * @param user - the user to set on the new lock being generated
66 * @return the newly generated document descriptor {@link PessimisticLock}
67 */
68 public PessimisticLock generateNewLock(String documentNumber, Person user);
69
70 /**
71 * This method will generate a new {@link PessimisticLock} object with a lock descriptor of
72 * the given parameter
73 *
74 * @param documentNumber - the document number of the document associated with the new lock
75 * @param lockDescriptor - the lock descriptor the new PessimisticLock object should contain
76 * @param user - the user to set on the new lock being generated
77 * @return the newly generated {@link PessimisticLock} containing the given lockDescriptor
78 */
79 public PessimisticLock generateNewLock(String documentNumber, String lockDescriptor, Person user);
80
81 /**
82 * This method gets all locks associated with the given document number
83 *
84 * @param documentNumber - the document number of the document requiring locks
85 * @return an empty list if no locks are found or the list of {@link PessimisticLock} objects
86 * found for the given documentNumber
87 */
88 public List<PessimisticLock> getPessimisticLocksForDocument(String documentNumber);
89
90 /**
91 * This method is used to identify who is an admin user for {@link PessimisticLock} objects
92 *
93 * @param user - user to verify as admin
94 * @return true if the given use is an admin user or false if not
95 */
96 public boolean isPessimisticLockAdminUser(Person user);
97
98 /**
99 * This method will release all locks in the given list that are owned by the given user
100 *
101 * @param locks - locks to release if owned by given user
102 * @param user - user to check for lock ownership
103 */
104 public void releaseAllLocksForUser(List<PessimisticLock> locks, Person user);
105
106 /**
107 * This method will release all locks in the given list that are owned by the given user that have a matching lock
108 * descriptor value
109 *
110 * @param locks - locks to release if owned by given user
111 * @param user - user to check for lock ownership
112 * @param lockDescriptor - lock descriptor value to match locks against
113 */
114 public void releaseAllLocksForUser(List<PessimisticLock> locks, Person user, String lockDescriptor);
115
116 /**
117 * This method saves the given lock object
118 *
119 */
120 public PessimisticLock save(PessimisticLock lock);
121
122 /**
123 * @param document - the document locks are to be established against or by
124 * @param editMode - the editMode returned by the method {@link #getEditMode(Document, Person)}
125 * @param user - the user locks are being established for
126 * @return New map generated by locking logic combined with passed in parameter editMode. Map contains keys
127 * AuthorizationConstants.EditMode value (String) which indicates what operations the user is currently
128 * allowed to take on that document. This may be a modified list of
129 */
130 public Map establishLocks(Document document, Map editMode, Person user);
131
132 /**
133 * @param document - the document to create the lock against and add the lock to
134 */
135 public void establishWorkflowPessimisticLocking(Document document);
136
137 /**
138 * @param document - document to release locks from
139 */
140 public void releaseWorkflowPessimisticLocking(Document document);
141
142 /**
143 * @param document
144 * @param user
145 * @return Set of actions are permitted the given user on the given document
146 */
147 public Set getDocumentActions(Document document, Person user, Set<String> documentActions);
148
149 }
150