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 * 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 * Return all locks associated with the given session id
92 *
93 * @param sessionId - the session id
94 * @return an empty list of no locks are found or the list of {@link PessimisticLock} objects
95 * found for the given sessionId
96 */
97 public List<PessimisticLock> getPessimisticLocksForSession(String sessionId);
98
99 /**
100 * This method is used to identify who is an admin user for {@link PessimisticLock} objects
101 *
102 * @param user - user to verify as admin
103 * @return true if the given use is an admin user or false if not
104 */
105 public boolean isPessimisticLockAdminUser(Person user);
106
107 /**
108 * This method will release all locks in the given list that are owned by the given user
109 *
110 * @param locks - locks to release if owned by given user
111 * @param user - user to check for lock ownership
112 */
113 public void releaseAllLocksForUser(List<PessimisticLock> locks, Person user);
114
115 /**
116 * This method will release all locks in the given list that are owned by the given user that have a matching lock
117 * descriptor value
118 *
119 * @param locks - locks to release if owned by given user
120 * @param user - user to check for lock ownership
121 * @param lockDescriptor - lock descriptor value to match locks against
122 */
123 public void releaseAllLocksForUser(List<PessimisticLock> locks, Person user, String lockDescriptor);
124
125 /**
126 * This method saves the given lock object
127 *
128 */
129 public PessimisticLock save(PessimisticLock lock);
130
131 /**
132 * @param document - the document locks are to be established against or by
133 * @param editMode - the editMode returned by the method {@link #getEditMode(Document, Person)}
134 * @param user - the user locks are being established for
135 * @return New map generated by locking logic combined with passed in parameter editMode. Map contains keys
136 * AuthorizationConstants.EditMode value (String) which indicates what operations the user is currently
137 * allowed to take on that document. This may be a modified list of
138 */
139 public Map establishLocks(Document document, Map editMode, Person user);
140
141 /**
142 * @param document - the document to create the lock against and add the lock to
143 */
144 public void establishWorkflowPessimisticLocking(Document document);
145
146 /**
147 * @param document - document to release locks from
148 */
149 public void releaseWorkflowPessimisticLocking(Document document);
150
151 /**
152 * @param document
153 * @param user
154 * @return Set of actions are permitted the given user on the given document
155 */
156 public Set getDocumentActions(Document document, Person user, Set<String> documentActions);
157
158 }
159