001/* 
002    Licensed to the Apache Software Foundation (ASF) under one
003    or more contributor license agreements.  See the NOTICE file
004    distributed with this work for additional information
005    regarding copyright ownership.  The ASF licenses this file
006    to you under the Apache License, Version 2.0 (the
007    "License"); you may not use this file except in compliance
008    with the License.  You may obtain a copy of the License at
009
010       http://www.apache.org/licenses/LICENSE-2.0
011
012    Unless required by applicable law or agreed to in writing,
013    software distributed under the License is distributed on an
014    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015    KIND, either express or implied.  See the License for the
016    specific language governing permissions and limitations
017    under the License.  
018 */
019package org.apache.wiki.workflow;
020
021import org.apache.wiki.api.core.Session;
022import org.apache.wiki.api.engine.Initializable;
023import org.apache.wiki.api.exceptions.WikiException;
024import org.apache.wiki.event.WikiEventListener;
025
026import java.security.Principal;
027import java.util.List;
028import java.util.Set;
029
030
031/**
032 * <p>
033 * Monitor class that tracks running Workflows. The WorkflowManager also keeps track of the names of users or groups expected to approve
034 * particular Workflows.
035 * </p>
036 */
037public interface WorkflowManager extends WikiEventListener, Initializable {
038
039    /** The name of the key from jspwiki.properties which defines who shall approve the workflow of storing a wikipage.  Value is <tt>{@value}</tt> */
040    String WF_WP_SAVE_APPROVER = "workflow.saveWikiPage";
041    /** The message key for storing the Decision text for saving a page.  Value is {@value}. */
042    String WF_WP_SAVE_DECISION_MESSAGE_KEY = "decision.saveWikiPage";
043    /** The message key for rejecting the decision to save the page.  Value is {@value}. */
044    String WF_WP_SAVE_REJECT_MESSAGE_KEY = "notification.saveWikiPage.reject";
045    /** Fact name for storing the page name.  Value is {@value}. */
046    String WF_WP_SAVE_FACT_PAGE_NAME = "fact.pageName";
047    /** Fact name for storing a diff text. Value is {@value}. */
048    String WF_WP_SAVE_FACT_DIFF_TEXT = "fact.diffText";
049    /** Fact name for storing the current text.  Value is {@value}. */
050    String WF_WP_SAVE_FACT_CURRENT_TEXT = "fact.currentText";
051    /** Fact name for storing the proposed (edited) text.  Value is {@value}. */
052    String WF_WP_SAVE_FACT_PROPOSED_TEXT = "fact.proposedText";
053    /** Fact name for storing whether the user is authenticated or not.  Value is {@value}. */
054    String WF_WP_SAVE_FACT_IS_AUTHENTICATED = "fact.isAuthenticated";
055
056    /** The workflow attribute which stores the user profile. */
057    String WF_UP_CREATE_SAVE_ATTR_SAVED_PROFILE = "userProfile";
058    /** The name of the key from jspwiki.properties which defines who shall approve the workflow of creating a user profile.  Value is <tt>{@value}</tt> */
059    String WF_UP_CREATE_SAVE_APPROVER = "workflow.createUserProfile";
060    /** The message key for storing the Decision text for saving a user profile.  Value is {@value}. */
061    String WF_UP_CREATE_SAVE_DECISION_MESSAGE_KEY = "decision.createUserProfile";
062    /** Fact name for storing a the submitter name. Value is {@value}. */
063    String WF_UP_CREATE_SAVE_FACT_SUBMITTER = "fact.submitter";
064    /** Fact name for storing the preferences' login name. Value is {@value}. */
065    String WF_UP_CREATE_SAVE_FACT_PREFS_LOGIN_NAME = "prefs.loginname";
066    /** Fact name for storing the preferences' full name. Value is {@value}. */
067    String WF_UP_CREATE_SAVE_FACT_PREFS_FULL_NAME = "prefs.fullname";
068    /** Fact name for storing the preferences' email. Value is {@value}. */
069    String WF_UP_CREATE_SAVE_FACT_PREFS_EMAIL = "prefs.email";
070
071    /** The prefix to use for looking up <code>jspwiki.properties</code> approval roles. */
072    String PROPERTY_APPROVER_PREFIX = "jspwiki.approver.";
073
074    /**
075     * Returns a collection of the currently active workflows.
076     *
077     * @return the current workflows
078     */
079    Set< Workflow > getWorkflows();
080
081    /**
082     * Returns a collection of finished workflows; that is, those that have aborted or completed.
083     *
084     * @return the finished workflows
085     */
086    List< Workflow > getCompletedWorkflows();
087
088    /**
089     * Returns <code>true</code> if a workflow matching a particular key contains an approval step.
090     *
091     * @param messageKey the name of the workflow; corresponds to the value returned by {@link Workflow#getMessageKey()}.
092     * @return the result
093     */
094    boolean requiresApproval( String messageKey );
095
096    /**
097     * Looks up and resolves the actor who approves a Decision for a particular Workflow, based on the Workflow's message key.
098     * If not found, or if Principal is Unresolved, throws WikiException. This particular implementation always returns the
099     * GroupPrincipal <code>Admin</code>
100     *
101     * @param messageKey the Decision's message key
102     * @return the actor who approves Decisions
103     * @throws WikiException if the message key was not found, or the
104     * Principal value corresponding to the key could not be resolved
105     */
106    Principal getApprover( String messageKey ) throws WikiException;
107
108    /**
109     * Returns the DecisionQueue associated with this WorkflowManager
110     *
111     * @return the decision queue
112     */
113    DecisionQueue getDecisionQueue();
114
115    /**
116     * Returns the current workflows a wiki session owns. These are workflows whose {@link Workflow#getOwner()} method returns a Principal
117     * also possessed by the wiki session (see {@link org.apache.wiki.api.core.Session#getPrincipals()}). If the wiki session is not
118     * authenticated, this method returns an empty Collection.
119     *
120     * @param session the wiki session
121     * @return the collection workflows the wiki session owns, which may be empty
122     */
123    List< Workflow > getOwnerWorkflows( Session session );
124
125}