    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}