001 /**
002 * Copyright 2005-2013 The Kuali Foundation
003 *
004 * Licensed under the Educational Community License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.opensource.org/licenses/ecl2.php
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.kuali.rice.krad.service;
017
018 import org.kuali.rice.kim.api.identity.Person;
019 import org.kuali.rice.krad.document.Document;
020 import org.kuali.rice.krad.document.authorization.PessimisticLock;
021
022 import java.util.List;
023 import java.util.Map;
024 import java.util.Set;
025
026 /**
027 * This is the service interface for documents to use the Pessimistic Locking mechanism
028 *
029 * @author Kuali Rice Team (rice.collab@kuali.org)
030 *
031 */
032 public interface PessimisticLockService {
033
034 /**
035 * This method deletes the given lock object
036 *
037 * @param id - the id of the lock to delete
038 */
039 public void delete(String id);
040
041 /**
042 * This method will generate a new {@link PessimisticLock} object with a 'document'
043 * lock descriptor
044 *
045 * @param documentNumber - the document number of the document associated with the new lock
046 * @return the newly generated document descriptor {@link PessimisticLock}
047 */
048 public PessimisticLock generateNewLock(String documentNumber);
049
050 /**
051 * This method will generate a new {@link PessimisticLock} object with a lock descriptor of
052 * the given parameter
053 *
054 * @param documentNumber - the document number of the document associated with the new lock
055 * @param lockDescriptor - the lock descriptor the new PessimisticLock object should contain
056 * @return the newly generated {@link PessimisticLock} containing the given lockDescriptor
057 */
058 public PessimisticLock generateNewLock(String documentNumber, String lockDescriptor);
059
060 /**
061 * This method will generate a new {@link PessimisticLock} object with a 'document'
062 * lock descriptor
063 *
064 * @param documentNumber - the document number of the document associated with the new lock
065 * @param user - the user to set on the new lock being generated
066 * @return the newly generated document descriptor {@link PessimisticLock}
067 */
068 public PessimisticLock generateNewLock(String documentNumber, Person user);
069
070 /**
071 * This method will generate a new {@link PessimisticLock} object with a lock descriptor of
072 * the given parameter
073 *
074 * @param documentNumber - the document number of the document associated with the new lock
075 * @param lockDescriptor - the lock descriptor the new PessimisticLock object should contain
076 * @param user - the user to set on the new lock being generated
077 * @return the newly generated {@link PessimisticLock} containing the given lockDescriptor
078 */
079 public PessimisticLock generateNewLock(String documentNumber, String lockDescriptor, Person user);
080
081 /**
082 * This method gets all locks associated with the given document number
083 *
084 * @param documentNumber - the document number of the document requiring locks
085 * @return an empty list if no locks are found or the list of {@link PessimisticLock} objects
086 * found for the given documentNumber
087 */
088 public List<PessimisticLock> getPessimisticLocksForDocument(String documentNumber);
089
090 /**
091 * Return all locks associated with the given session id
092 *
093 * @param sessionId - the session id
094 * @return an empty list of no locks are found or the list of {@link PessimisticLock} objects
095 * found for the given sessionId
096 */
097 public List<PessimisticLock> getPessimisticLocksForSession(String sessionId);
098
099 /**
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