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