1 /**
2 * Copyright 2005-2015 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 java.util.List;
19 import java.util.Map;
20 import java.util.Set;
21
22 import org.kuali.rice.kim.api.identity.Person;
23 import org.kuali.rice.krad.document.Document;
24 import org.kuali.rice.krad.document.authorization.PessimisticLock;
25
26 /**
27 * Service interface for documents to use the Pessimistic Locking mechanism
28 *
29 * @author Kuali Rice Team (rice.collab@kuali.org)
30 */
31 public interface PessimisticLockService {
32
33 /**
34 * This method deletes the given lock object
35 *
36 * @param id - the id of the lock to delete
37 */
38 public void delete(String id);
39
40 /**
41 * This method will generate a new {@link PessimisticLock} object with a 'document'
42 * lock descriptor
43 *
44 * @param documentNumber - the document number of the document associated with the new lock
45 * @return the newly generated document descriptor {@link PessimisticLock}
46 */
47 public PessimisticLock generateNewLock(String documentNumber);
48
49 /**
50 * This method will generate a new {@link PessimisticLock} object with a lock descriptor of
51 * the given parameter
52 *
53 * @param documentNumber - the document number of the document associated with the new lock
54 * @param lockDescriptor - the lock descriptor the new PessimisticLock object should contain
55 * @return the newly generated {@link PessimisticLock} containing the given lockDescriptor
56 */
57 public PessimisticLock generateNewLock(String documentNumber, String lockDescriptor);
58
59 /**
60 * This method will generate a new {@link PessimisticLock} object with a 'document'
61 * lock descriptor
62 *
63 * @param documentNumber - the document number of the document associated with the new lock
64 * @param user - the user to set on the new lock being generated
65 * @return the newly generated document descriptor {@link PessimisticLock}
66 */
67 public PessimisticLock generateNewLock(String documentNumber, Person user);
68
69 /**
70 * This method will generate a new {@link PessimisticLock} object with a lock descriptor of
71 * the given parameter
72 *
73 * @param documentNumber - the document number of the document associated with the new lock
74 * @param lockDescriptor - the lock descriptor the new PessimisticLock object should contain
75 * @param user - the user to set on the new lock being generated
76 * @return the newly generated {@link PessimisticLock} containing the given lockDescriptor
77 */
78 public PessimisticLock generateNewLock(String documentNumber, String lockDescriptor, Person user);
79
80 /**
81 * This method gets all locks associated with the given document number
82 *
83 * @param documentNumber - the document number of the document requiring locks
84 * @return an empty list if no locks are found or the list of {@link PessimisticLock} objects
85 * found for the given documentNumber
86 */
87 public List<PessimisticLock> getPessimisticLocksForDocument(String documentNumber);
88
89 /**
90 * Return all locks associated with the given session id
91 *
92 * @param sessionId - the session id
93 * @return an empty list of no locks are found or the list of {@link PessimisticLock} objects
94 * found for the given sessionId
95 */
96 public List<PessimisticLock> getPessimisticLocksForSession(String sessionId);
97
98 /**
99 * This method is used to identify who is an admin user for {@link PessimisticLock} objects
100 *
101 * @param user - user to verify as admin
102 * @return true if the given use is an admin user or false if not
103 */
104 public boolean isPessimisticLockAdminUser(Person user);
105
106 /**
107 * This method will release all locks in the given list that are owned by the given user
108 *
109 * @param locks - locks to release if owned by given user
110 * @param user - user to check for lock ownership
111 */
112 public void releaseAllLocksForUser(List<PessimisticLock> locks, Person user);
113
114 /**
115 * This method will release all locks in the given list that are owned by the given user that have a matching lock
116 * descriptor value
117 *
118 * @param locks - locks to release if owned by given user
119 * @param user - user to check for lock ownership
120 * @param lockDescriptor - lock descriptor value to match locks against
121 */
122 public void releaseAllLocksForUser(List<PessimisticLock> locks, Person user, String lockDescriptor);
123
124 /**
125 * This method saves the given lock object
126 *
127 */
128 public PessimisticLock save(PessimisticLock lock);
129
130 /**
131 * Establishes pessimistic locks for {@code user} on the {@code document} based whether the {@code user} can edit
132 * the document.
133 *
134 * <p>
135 * Will only establish a new pessimistic lock if one doesn't exist for the {@code user} and one can be created based
136 * on other pessimistic locks in the system and whether {@code user} can edit the document. Will return true
137 * if either a new pessimistic lock was established or one already exists for the {@code user}.
138 * </p>
139 *
140 * @param document the document on which the locks will be established
141 * @param user the user for which the locks are being established
142 * @param canEdit whether the user currently can edit the document
143 *
144 * @return true if a pessimistic lock has been established, false otherwise
145 */
146 public boolean establishPessimisticLocks(Document document, Person user, boolean canEdit);
147
148 /**
149 * @param document - the document locks are to be established against or by
150 * @param editMode - the editMode
151 * @param user - the user locks are being established for
152 * @return New map generated by locking logic combined with passed in parameter editMode. Map contains keys
153 * AuthorizationConstants.EditMode value (String) which indicates what operations the user is currently
154 * allowed to take on that document. This may be a modified list of
155 * @deprecated For KRAD, use @{code establishPessimisticLocks} to generate locks and
156 * {@code calculatePessimisticLockEditModes} to get the edit modes based on the current locks
157 */
158 @Deprecated
159 public Map establishLocks(Document document, Map editMode, Person user);
160
161 /**
162 * @param document - the document to create the lock against and add the lock to
163 */
164 public void establishWorkflowPessimisticLocking(Document document);
165
166 /**
167 * @param document - document to release locks from
168 */
169 public void releaseWorkflowPessimisticLocking(Document document);
170
171 /**
172 * @param document
173 * @param user
174 * @return Set of actions are permitted the given user on the given document
175 * @deprecated KRAD has integrated this functionality into
176 * {@link org.kuali.rice.krad.document.TransactionalDocumentAuthorizerBase}
177 */
178 @Deprecated
179 public Set getDocumentActions(Document document, Person user, Set<String> documentActions);
180
181 }
182