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.Map;
029import java.util.Set;
030
031
032/**
033 * <p>
034 * Monitor class that tracks running Workflows. The WorkflowManager also keeps track of the names of users or groups expected to approve
035 * particular Workflows.
036 * </p>
037 */
038public interface WorkflowManager extends WikiEventListener, Initializable {
039
040    /** The name of the key from jspwiki.properties which defines who shall approve the workflow of storing a wikipage.  Value is <tt>{@value}</tt> */
041    String WF_WP_SAVE_APPROVER = "workflow.saveWikiPage";
042    /** The message key for storing the Decision text for saving a page.  Value is {@value}. */
043    String WF_WP_SAVE_DECISION_MESSAGE_KEY = "decision.saveWikiPage";
044    /** The message key for rejecting the decision to save the page.  Value is {@value}. */
045    String WF_WP_SAVE_REJECT_MESSAGE_KEY = "notification.saveWikiPage.reject";
046    /** Fact name for storing the page name.  Value is {@value}. */
047    String WF_WP_SAVE_FACT_PAGE_NAME = "fact.pageName";
048    /** Fact name for storing a diff text. Value is {@value}. */
049    String WF_WP_SAVE_FACT_DIFF_TEXT = "fact.diffText";
050    /** Fact name for storing the current text.  Value is {@value}. */
051    String WF_WP_SAVE_FACT_CURRENT_TEXT = "fact.currentText";
052    /** Fact name for storing the proposed (edited) text.  Value is {@value}. */
053    String WF_WP_SAVE_FACT_PROPOSED_TEXT = "fact.proposedText";
054    /** Fact name for storing whether the user is authenticated or not.  Value is {@value}. */
055    String WF_WP_SAVE_FACT_IS_AUTHENTICATED = "fact.isAuthenticated";
056
057    /** The workflow attribute which stores the user profile. */
058    String WF_UP_CREATE_SAVE_ATTR_SAVED_PROFILE = "userProfile";
059    /** 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> */
060    String WF_UP_CREATE_SAVE_APPROVER = "workflow.createUserProfile";
061    /** The message key for storing the Decision text for saving a user profile.  Value is {@value}. */
062    String WF_UP_CREATE_SAVE_DECISION_MESSAGE_KEY = "decision.createUserProfile";
063    /** Fact name for storing a the submitter name. Value is {@value}. */
064    String WF_UP_CREATE_SAVE_FACT_SUBMITTER = "fact.submitter";
065    /** Fact name for storing the preferences' login name. Value is {@value}. */
066    String WF_UP_CREATE_SAVE_FACT_PREFS_LOGIN_NAME = "prefs.loginname";
067    /** Fact name for storing the preferences' full name. Value is {@value}. */
068    String WF_UP_CREATE_SAVE_FACT_PREFS_FULL_NAME = "prefs.fullname";
069    /** Fact name for storing the preferences' email. Value is {@value}. */
070    String WF_UP_CREATE_SAVE_FACT_PREFS_EMAIL = "prefs.email";
071
072    /** The prefix to use for looking up <code>jspwiki.properties</code> approval roles. */
073    String PROPERTY_APPROVER_PREFIX = "jspwiki.approver.";
074
075    /**
076     * Returns a collection of the currently active workflows.
077     *
078     * @return the current workflows
079     */
080    Set< Workflow > getWorkflows();
081
082    /**
083     * Returns a map of the currently active workflows.
084     *
085     * @return the current workflows as workflowId -> workflow tuples
086     */
087    Map< Integer, Workflow > getWorkflowsAsMap();
088
089    /**
090     * Returns a collection of finished workflows; that is, those that have aborted or completed.
091     *
092     * @return the finished workflows
093     */
094    List< Workflow > getCompletedWorkflows();
095
096    /**
097     * Returns <code>true</code> if a workflow matching a particular key contains an approval step.
098     *
099     * @param messageKey the name of the workflow; corresponds to the value returned by {@link Workflow#getMessageKey()}.
100     * @return the result
101     */
102    boolean requiresApproval( String messageKey );
103
104    /**
105     * Looks up and resolves the actor who approves a Decision for a particular Workflow, based on the Workflow's message key.
106     * If not found, or if Principal is Unresolved, throws WikiException. This particular implementation always returns the
107     * GroupPrincipal <code>Admin</code>
108     *
109     * @param messageKey the Decision's message key
110     * @return the actor who approves Decisions
111     * @throws WikiException if the message key was not found, or the
112     * Principal value corresponding to the key could not be resolved
113     */
114    Principal getApprover( String messageKey ) throws WikiException;
115
116    /**
117     * Returns the DecisionQueue associated with this WorkflowManager
118     *
119     * @return the decision queue
120     */
121    DecisionQueue getDecisionQueue();
122
123    /**
124     * Returns the current workflows a wiki session owns. These are workflows whose {@link Workflow#getOwner()} method returns a Principal
125     * also possessed by the wiki session (see {@link org.apache.wiki.api.core.Session#getPrincipals()}). If the wiki session is not
126     * authenticated, this method returns an empty Collection.
127     *
128     * @param session the wiki session
129     * @return the collection workflows the wiki session owns, which may be empty
130     */
131    List< Workflow > getOwnerWorkflows( Session session );
132
133}