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}