001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.wicket.extensions.wizard;
018
019import java.util.Iterator;
020
021import org.apache.wicket.util.io.IClusterable;
022
023/**
024 * This interface defines the model for wizards. This model knows about the wizard's steps and the
025 * transitions between them, and it holds a reference to the currently active step. It might
026 * function as a generic state holder for the wizard too, though you might find it more convenient
027 * to use the wizard component itself for that, or even an external model.
028 * 
029 * <p>
030 * {@link IWizardModelListener wizard model listeners} can be registered to be notified of important
031 * events (changing the active step) using the {@link #addListener(IWizardModelListener) add
032 * listener} method.
033 * </p>
034 * 
035 * <p>
036 * Typically, you would use {@link WizardModel the default implementation of this interface}, but if
037 * you need to do more sophisticated stuff, like branching etc, you can consider creating your own
038 * implementation. In that case, it is recommended you start by extending from
039 * {@link AbstractWizardModel}.
040 * </p>
041 * 
042 * <p>
043 * <a href="https://wizard-framework.dev.java.net/">Swing Wizard Framework</a> served as a valuable
044 * source of inspiration.
045 * </p>
046 * 
047 * @see AbstractWizardModel
048 * @see WizardModel
049 * 
050 * @author Eelco Hillenius
051 */
052public interface IWizardModel extends IClusterable
053{
054        /**
055         * Adds a wizard model listener.
056         * 
057         * @param listener
058         *            The wizard model listener to add
059         */
060        void addListener(IWizardModelListener listener);
061        
062        /**
063         * Removes a wizard model listener.
064         * 
065         * @param listener
066         *            The listener to remove
067         */
068        void removeListener(IWizardModelListener listener);
069        
070        /**
071         * Resets the model, setting it to the first step. Implementors should notify
072         * {@link IWizardModelListener listeners} through calling
073         * {@link IWizardModelListener#onActiveStepChanged(IWizardStep)}.
074         */
075        void reset();
076        
077        /**
078         * Returns an iterator over all the steps in the model. The iteration order is not guaranteed to
079         * the be the order of visit. This is an optional operation; dynamic models can just return
080         * null, and should call init the first time a step is encountered right before rendering it.
081         * 
082         * @return an iterator over all the steps of the model or null if the wizard model is not static
083         */
084        Iterator<IWizardStep> stepIterator();
085        
086        /**
087         * Gets whether the specified step is the last step in the wizard.
088         * 
089         * @param step
090         *            the step to check
091         * @return True if its the final step in the wizard, false otherwise.
092         */
093        boolean isLastStep(IWizardStep step);
094
095        /**
096         * Gets the current active step the wizard should display.
097         * 
098         * @return the active step.
099         */
100        IWizardStep getActiveStep();
101
102        /**
103         * Gets whether the cancel button should be displayed.
104         * 
105         * @return True if the cancel button should be displayed
106         * 
107         * @see #cancel()
108         */
109        boolean isCancelVisible();
110
111        /**
112         * Cancels further processing. Implementations may clean up and reset the model. Implementations
113         * should notify the registered {@link IWizardModelListener#onCancel() model listeners}.
114         */
115        void cancel();
116
117        /**
118         * Gets whether the previous button should be enabled.
119         * 
120         * @return True if the previous button should be enabled, false otherwise.
121         * 
122         * @see #previous()
123         */
124        boolean isPreviousAvailable();
125
126        /**
127         * Takes the model to the previous step.This method must only be called if
128         * {@link #isPreviousAvailable} returns <tt>true</tt>. Implementors should notify
129         * {@link IWizardModelListener listeners} through calling
130         * {@link IWizardModelListener#onActiveStepChanged(IWizardStep)}.
131         * 
132         * @see #isPreviousAvailable()
133         */
134        void previous();
135
136        /**
137         * Gets whether the next button should be enabled.
138         * 
139         * @return True if the next button should be enabled, false otherwise.
140         * 
141         * @see #next()
142         */
143        boolean isNextAvailable();
144
145        /**
146         * Increments the model to the next step. This method must only be called if
147         * {@link #isNextAvailable} returns <tt>true</tt>. Implementors should notify
148         * {@link IWizardModelListener listeners} through calling
149         * {@link IWizardModelListener#onActiveStepChanged(IWizardStep)}.
150         * 
151         * @see #isNextAvailable()
152         */
153        void next();
154
155        /**
156         * Gets whether the last button should be displayed. This method should only return true if the
157         * {@link #isLastAvailable} will return true at any point. Returning false will prevent the last
158         * button from appearing on the wizard at all.
159         * 
160         * @return True if the last button should be displayed, False otherwise.
161        
162         * @see #isLastAvailable()
163         * @see #last()
164         */
165        boolean isLastVisible();
166
167        /**
168         * Checks if the last button should be enabled.
169         * 
170         * @return <tt>true</tt> if the last button should be enabled, <tt>false</tt> otherwise.
171         * 
172         * @see #isLastVisible()
173         * @see #last()
174         */
175        boolean isLastAvailable();
176
177        /**
178         * Takes the model to the last step in the wizard. This method must only be called if
179         * {@link #isLastAvailable} returns <tt>true</tt>. Implementors should notify
180         * {@link IWizardModelListener listeners} through calling
181         * {@link IWizardModelListener#onActiveStepChanged(IWizardStep)}.
182         * 
183         * @see #isLastVisible()
184         * @see #isLastAvailable()
185         */
186        void last();
187
188        /**
189         * Gets whether the finish button should be enabled.
190         * <p>
191         * By default the finish button is available for the last step only.
192         * 
193         * @return True if the finish button should be enabled, false otherwise.
194         * 
195         * @see #isLastStep(IWizardStep)
196         * @see #finish()
197         */
198        default boolean isFinishAvailable() {
199                return isLastStep(getActiveStep());
200        }
201
202        /**
203         * Instructs the wizard to finish succesfully. Typically, implementations check whether this
204         * option is available at all. Implementations may clean up and reset the model. Implementations
205         * should notify the registered {@link IWizardModelListener#onFinish() model listeners}.
206         */
207        void finish();
208}