001/**
002 * Copyright 2005-2016 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 */
016package org.kuali.rice.krad.service;
017
018import org.kuali.rice.krad.maintenance.MaintenanceDocument;
019import org.kuali.rice.krad.maintenance.MaintenanceLock;
020import org.kuali.rice.krad.maintenance.Maintainable;
021
022import java.util.List;
023import java.util.Map;
024
025/**
026 * Provides methods for working with <code>MaintenanceDocument</code>(s)
027 *
028 * @author Kuali Rice Team (rice.collab@kuali.org)
029 */
030public interface MaintenanceDocumentService {
031
032        /**
033         * Prepares the <code>MaintenanceDocument</code> on initial request
034         * 
035         * <p>
036         * This includes retrieving the data object for edit or copy, clearing
037         * fields
038         * </p>
039         * 
040         * @param objectClassName
041         *            - class name for the object being maintained
042         * @param docTypeName
043         *            - workflow doc type for the maintenance document requested
044         * @param maintenanceAction
045         *            - indicates whether this is a new, copy, or edit maintenance
046         *            action
047         * @return MaintenanceDocument prepared document instance
048         */
049        public MaintenanceDocument setupNewMaintenanceDocument(
050                        String objectClassName, String docTypeName, String maintenanceAction);
051
052    /**
053     * Called to setup the object being maintained
054     *
055     * <p>
056     * For edit and copy actions, the old record is retrieved and prepared for
057     * editing (in the case of a copy some fields are cleared). In addition some
058     * authorization checks are performed and hooks for custom
059     * <code>Maintainble</code> implementations are invoked.
060     * </p>
061     *
062     * @param document - document instance for the maintenance object
063     * @param maintenanceAction - the requested maintenance action (new, new with existing,
064     * copy, edit)
065     * @param requestParameters - Map of parameters from the request
066     */
067    public void setupMaintenanceObject(MaintenanceDocument document, String maintenanceAction,
068            Map<String, String[]> requestParameters);
069
070    /**
071         * Attempts to find any other active documents that are pending on the same
072         * maintenance record.
073         * 
074         * If any are pending and locked, thereby blocking this document, then the
075         * docHeaderId/documentNumber of the blocking locked document is returned.
076         * 
077         * Otherwise, if nothing is blocking, then null is returned.
078         * 
079         * @param document
080         *            - document to test
081         * @return A String representing the docHeaderId of any blocking document,
082         *         or null if none are blocking
083         * 
084         */
085        public String getLockingDocumentId(MaintenanceDocument document);
086
087        /**
088         * Attempts to find any other active documents that are pending on the same
089         * maintenance record.
090         * 
091         * If any are pending and locked, thereby blocking this document, then the
092         * docHeaderId/documentNumber of the blocking locked document is returned.
093         * 
094         * Otherwise, if nothing is blocking, then null is returned.
095         * 
096         * @param maintainable
097         *            - maintainable representing the document to test
098         * @param documentNumber
099         *            - the documentNumber/docHeaderId of the document to test
100         * @return A String representing the docHeaderId of any blocking document,
101         *         or null if none are blocking
102         */
103        public String getLockingDocumentId(Maintainable maintainable,
104                        String documentNumber);
105
106        /**
107         * Call the same-named method in the Dao, since the service has access to
108         * the Dao, but the caller doesn't.
109         * 
110         * This method deletes the locks for the given document number. It is called
111         * when the document is final, thus it can be unlocked, or when the locks
112         * need to be regenerated (thus they get cleared first).
113         * 
114         * @param documentNumber
115         *            - document number whose locks should be deleted
116         */
117        public void deleteLocks(String documentNumber);
118
119        /**
120         * Call the same-named method in the Dao, since the service has access to
121         * the Dao, but the caller doesn't.
122         * 
123         * This method stores the given list of maintenance locks. Typically these
124         * will all be for the same document.
125         * 
126         * @param maintenanceLocks
127         *            - the list of maintenance locks to be stored
128         */
129        public void storeLocks(List<MaintenanceLock> maintenanceLocks);
130
131}