1 /**
2 * Copyright 2005-2014 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 * 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 * @param document - the document locks are to be established against or by
132 * @param editMode - the editMode returned by the method {@link #getEditMode(Document, Person)}
133 * @param user - the user locks are being established for
134 * @return New map generated by locking logic combined with passed in parameter editMode. Map contains keys
135 * AuthorizationConstants.EditMode value (String) which indicates what operations the user is currently
136 * allowed to take on that document. This may be a modified list of
137 */
138 public Map establishLocks(Document document, Map editMode, Person user);
139
140 /**
141 * @param document - the document to create the lock against and add the lock to
142 */
143 public void establishWorkflowPessimisticLocking(Document document);
144
145 /**
146 * @param document - document to release locks from
147 */
148 public void releaseWorkflowPessimisticLocking(Document document);
149
150 /**
151 * @param document
152 * @param user
153 * @return Set of actions are permitted the given user on the given document
154 */
155 public Set getDocumentActions(Document document, Person user, Set<String> documentActions);
156
157 }
158