[Struts-cvs] dialogs/src/net/jspcontrols/wizard/intf IWizard.java,NONE,1.1 IWizardListener.java,NONE,1.1 IWizardStep.java,NONE,1.1 IWizardTransition.java,NONE,1.1 package.html,NONE,1.1

[<jm...@us...>]

Update of /cvsroot/struts/dialogs/src/net/jspcontrols/wizard/intf
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv12963/src/net/jspcontrols/wizard/intf

Added Files:
	IWizard.java IWizardListener.java IWizardStep.java 
	IWizardTransition.java package.html 
Log Message:


--- NEW FILE: IWizard.java ---
/*
 * Copyright 2004-2005 Michael Jouravlev.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package net.jspcontrols.wizard.intf;

import java.util.Map;

/**
 * This interface defines an Easy Wizard controller. The wizard controller
 * contains references to wizard steps and transitions, and allows to
 * move from one step to another.
 *
 * @version 0.5
 * @author Michael Jouravlev
 */
public interface IWizard {

    /**************************************************************************
     * Where are we and where did we come from
     **************************************************************************/

    /**
     * Locates the initial step of this wizard.
     * @return the initial step of this wizard
     */
    public IWizardStep getSourceStep();

    /**
     * Locates the current step of this wizard.
     * @return the current step of this wizard
     */
    public IWizardStep getCurrentStep();

    /**
     * Locates a step by its name. Step name is used by clients
     * of wizard controller, for example by Dialog Manager to refer
     * to a corresponding view.
     * @param name  step name
     * @return the first step found traversing forward from the initial step,
     *         having passed name; or null if the step not found.
     */
    public IWizardStep getStepByName(String name);

    /**
     * Returns a mapping name for a wizard panel. Usually wizard step name
     * is used as mapping name.
     * @return mapping name for a wizard view, usually path to JSP page
     */
    String getCurrentStepName();

    /**
     * Returns errors for current wizard state.
     * @return error messages for current wizard state
     */
    Map getWizardErrors();

    /**
     * Attempts to move to the next step. If it is not possible, stays on the
     * current step.
     * <p>
     * Easy Wizard does not blindly choose a transition based on input command
     * or event. Instead, it iterates over all transitions defined for current
     * step, validates them, and chooses th one which is valid. If several
     * transitions happen to be valid, the first one is chosen.
     * @return true if was able to move to a next step, false otherwise
     * @see IWizardStep#addOutgoingTransition(IWizardTransition)
     */
    public boolean forward();

    /**
     * Attempts to move to the previous step. If the previous step does not
     * exist or the current step is the initial step of the wizard, stays
     * on the current step. Transition is not validated while traversing back.
     * @return true if was able to move to a previous step, false otherwise
     */
    public boolean back();

    /**
     * Returns wizard completion status. This method is redundant,
     * but is defined to hide Wizard instance from WizardAction.
     * @return true is wizard was successfully completed and disposed;
     *         false if wizard is still active or has not been initialized yet.
     */
    boolean isCompleted();

    /**
     * Clean wizard errors. Just in case. Usually Wizard Manager
     * cleans errors if needed.
     */
    void clearWizardErrors();

    /**
     * Resets certain wizard fields, like booleans. Called with every user
     * input. The primary reason for this method is older frameworks like
     * Struts, which use default HTTP handling of boolean properties, and
     * do not notifiy a property when it is cleared.
     */
    void wizardReset();

    /**
     * Adds a listener for state change event.
     */
    void addListener(IWizardListener listener);

    /**
     * Removes a listener for state change event.
     */
    void removeListener(IWizardListener listener);

    /**
     * Removes all wizard listeners for state change event.
     */
    void removeAllListeners();

}

--- NEW FILE: IWizardListener.java ---
/*
 * Copyright 2004-2005 Michael Jouravlev
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package net.jspcontrols.wizard.intf;

/**
 * Listens to state change events. Usually is called from Wizard Manager.
 *
 * @version 0.5
 * @author Michael Jouravlev
 */
public interface IWizardListener {

    public int STEP_REGULAR = 1;
    public int STEP_LAST = 2;

    /**
     * Performs action when wizard is about to change the step during
     * the forward transition.
     *
     * @param event WizardEvent.STEP_REGULAR if about to leave "middle" step,
     *        WizardEvent.STEP_LAST if about to leave the final wizard
     *        step, effectively finishing the wizard.
     * @return true if it is ok to move to the next step, false if step
     *         cannot be changed.
     */
    boolean onTransition(int event);
}

--- NEW FILE: IWizardStep.java ---
/*
 * Copyright 2004-2005 Michael Jouravlev.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package net.jspcontrols.wizard.intf;

/**
 * Represents a state of a wizard Finite State Machine (FSM).
 * <br/><br/>
 * A base state contains common navigation methods, a concrete state also
 * contains setters/getters for domain data, relevant to this state.
 *
 * @version 0.5
 * @author Michael Jouravlev
 */
public interface IWizardStep {

    /**
     * Returns array of outgoing transitions for this state. The transitions
     * are weighed according to the order in which they were added to this
     * state.
     *
     * @return array of outgoing transitions
     */
    IWizardTransition[] getOutgoingTransitions();

    /**
     * Selects a transition which will be used to move forward from
     * from this state.
     * <p>
     * All outgoing transitions are validated in the order of their weight.
     * The first valid transition is chosen.
     *
     * @return a valid outgoing edge or null if no valid edges found
     */
    IWizardTransition getOutgoingTransition();

    /**
     * Returns the incoming transition, was used to get to this state.
     *
     * @return incoming transition
     */
    IWizardTransition getIncomingTransition();

    /**
     * Sets the incoming transition. Used during forward traversal
     * to mark the way through the wizard. The incoming transition
     * is used for backward traversal.
     *
     * @param value  incoming transition
     */
    void setIncomingTransition(IWizardTransition value);

    /**
     * Adds an outgoing transition. Order in which transitions are added
     * to a state, defines their weight (or rank). Transition added to
     * a state first, has the highest weight. Transitions are validated
     * during forward traversal in order of their weight, and the first
     * valid transition is chosen for state change.
     *
     * @param value outgoing transition
     */
    void addOutgoingTransition(IWizardTransition value);

    /**
     * Returns true if this state has been marked as checkpoint. This means
     * that a wizard cannot return back from this state.
     *
     * @return true if this state is a checkpoint
     */
    boolean isCheckpoint();

    /**
     * Returns the name of this state. Each state must have a unique name..
     *
     * @return state name
     */
    String getStateName();

    /**
     * Returns the wizard, which contains this state as part
     * of the wizard sequence.
     *
     * @return wizard which owns this node
     */
    IWizard getWizard();

    /**
     * Verifies that this state is included in the path to the current state.
     *
     * @return true if this state is present in the actual path to the current
     *          state, but is not a current state itself; false otherwise.
     */
    boolean isStateInPath();

    /**
     * Instructs the state to clear all its boolean properties.
     * Usually called before the properties are about to be set.
     * <br><br>
     * The reason for this method is that browsers/HTTP do not notify
     * server about cleared checkboxes or radiobuttons. So, these values
     * should be cleared before they are set with client values.
     * <br><br>
     * This method is not used in JSF.
     */
    void resetBooleans();
}

--- NEW FILE: IWizardTransition.java ---
/**
 * Copyright 2004-2005 Michael Jouravlev.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package net.jspcontrols.wizard.intf;

/**
 * Represents a state transition. In Easy Wizard a transition is an object, it
 * can refer to its source and target states, and can validate itself. When
 * wizard controller moves from one state to another, it iterates through
 * transitions of current state, and validates each of them in order of their
 * weight. The first valid transition is used to change the state.
 *
 * @version 0.5
 * @author Michael Jouravlev
 */
public interface IWizardTransition {

    /**
     * Returns human-readable name of the transition, or null if not set.
     * <br><br>
     * The name is not needed for wizard navigation and thus is optional.
     * Nevertheless, names are highly recommended because they allow to
     * find a transition by name, and also may provide mapping name
     * for UI layer.
     *
     * @return transition name or null if name is not set
     */
    public String getName();

    /**
     * Returns source of this state, cannot be null. Each transition refers
     * to its source and target states.
     *
     * @return source of this transition
     */
    public IWizardStep getSource();

    /**
     * Sets source state for this transition
     * @param value  source state for this transition
     */
    public void setSource(IWizardStep value);

    /**
     * Returns target state of this transition, cannot be null. Each transition
     * refers to its source and target states.
     *
     * @return target state of this transition
     */
    public IWizardStep getTarget();

    /**
     * Validates this transition. Usually checks the domain accounts, which
     * is referenced from the source state of this transition.
     * <br><br>
     * Outgoing transitions are validated in order of their weight,
     * when state is about to change. The first valid transition is chosen
     * for traversal.
     *
     * @return true if this transition is valid
     */
    public boolean validate();

    /**
     * Returns wizard controller object, which owns this state
     * @return wizard which owns this state
     */
    IWizard getWizard();
}

--- NEW FILE: package.html ---
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<title>net.jspcontrols.wizard.intf package</title>
<!--

 Copyright 2004-2005 Michael Jouravlev.

 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.

-->
</head>
<body>

Provides interfaces for wizard components, like state, transition
and wizard controller.

<p>Easy Wizard is designed as a specific type of FSM.

<p><b>Instead of calculating the transition based on current state and command,
Easy Wizard iterates over all transitions defined for current state and
validates them.</b> This is possible, because transitions in Easy Wizard are
objects, not just string identifiers. If a transition considers itself
valid, then FSM moves from its current state to the state identified by
chosed transition.</p>

<!-- Last updated: Sat, Mar 26 2005 -->

</body>

</html>