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.kew.impl.document;
017
018import org.kuali.rice.kew.api.WorkflowDocument;
019import org.kuali.rice.kew.api.document.DocumentContentUpdate;
020import org.kuali.rice.kew.api.document.DocumentUpdate;
021
022/**
023 * Service provider interface for creation and loading of {@link WorkflowDocument}s.
024 * NOTE: WorkflowDocumentFactory constructs a single global instance, so implementations of this interface
025 * must be thread-safe.
026 * 
027 * @author Kuali Rice Team (rice.collab@kuali.org)
028 */
029public interface WorkflowDocumentProvider {
030     /**
031     * Creates a new workflow document of the given type with the given initiator.
032     *
033     * @param principalId the document initiator
034     * @param documentTypeName the document type
035     * @param documentUpdate pre-constructed state with which to initialize the document
036     * @param documentContentUpdate pre-constructed document content with which to initialize the document
037     *
038     * @return a WorkflowDocument object through which to interact with the new workflow document
039     *
040     * @throws IllegalArgumentException if principalId is null or blank
041     * @throws IllegalArgumentException if documentTypeName is null or blank
042     * @throws org.kuali.rice.kew.api.doctype.IllegalDocumentTypeException if documentTypeName does not represent a valid document type
043     */
044    WorkflowDocument createDocument(String principalId, String documentTypeName, DocumentUpdate documentUpdate, DocumentContentUpdate documentContentUpdate);
045
046    /**
047     * Loads an existing workflow document.
048     * @param principalId the principal id under which to perform document actions
049     * @param documentId the id of the document to load
050     *
051     * @return a WorkflowDocument object through which to interact with the loaded workflow document
052     *
053     * @throws IllegalArgumentException if principalId is null or blank
054     * @throws IllegalArgumentException if documentTypeName is null or blank
055     * @throws org.kuali.rice.kew.api.doctype.IllegalDocumentTypeException if the specified document type is not active
056     * @throws org.kuali.rice.kew.api.doctype.IllegalDocumentTypeException if the specified document type does not support document
057     *         creation (in other words, it's a document type that is only used as a parent)
058     * @throws org.kuali.rice.kew.api.action.InvalidActionTakenException if the supplied principal is not allowed to execute this
059     *         action
060     * @see org.kuali.rice.kew.impl.document.WorkflowDocumentProvider#loadDocument(String, String)
061     */
062    WorkflowDocument loadDocument(String principalId, String documentId);
063}