View Javadoc

1   /* ===================================================================
2    * Copyright 2002-04 SRI International.
3    * Released under the MOZILLA PUBLIC LICENSE Version 1.1
4    * which can be obtained at http://www.mozilla.org/MPL/MPL-1.1.html
5    * This software is distributed on an "AS IS"
6    * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied.
7    * See the License for the specific language governing rights and
8    * limitations under the License.
9    * =================================================================== */
10  package com.sri.emo.wizard;
11  
12  import java.io.Serializable;
13  import java.util.Map;
14  import java.util.Stack;
15  
16  
17  /***
18   * Base class for wizard implementations.  Use one of the constructors for
19   * customization of behavior.
20   *
21   * @author Michael Rimov
22   */
23  abstract public class AbstractWizard implements Wizard, Serializable {
24      /***
25       * Instance for the event monitor.
26       */
27      private WizardMonitor monitor;
28  
29      /***
30       * Instance for the backtrack stack.
31       */
32      private Stack backtrace;
33  
34      /***
35       * Wizard Title.
36       */
37      private String title;
38  
39      /***
40       * Wizard Text Summary.
41       */
42      private String summary;
43  
44      /***
45       * Current wizard page.
46       */
47      private WizardPage currentPage;
48  
49      /***
50       * The Wizard Id.
51       */
52      private Object wizardId;
53  
54      /***
55       * Constructor for brand new wizard.
56       *
57       * @param wizMonitor the wizard monitor.
58       */
59      public AbstractWizard(final WizardMonitor wizMonitor) {
60          monitor = wizMonitor;
61          backtrace = new Stack();
62      }
63  
64      /***
65       * Retreieve the monitor associated with this wizard.
66       *
67       * @return WizardMonitor
68       */
69      protected WizardMonitor getMonitor() {
70          return monitor;
71      }
72  
73      /***
74       * Retrieve the backtrace stack
75       *
76       * @return java.util.Stack
77       */
78      protected Stack getBackTrace() {
79          return backtrace;
80      }
81  
82      public WizardPage begin() throws WizardException {
83          backtrace.clear();
84  
85          WizardPage returnValue = getInitialPage();
86          setCurrentPage(returnValue);
87          monitor.onEnterPage(returnValue);
88  
89          return returnValue;
90      }
91  
92      /***
93       * Retrieve the initial page defined for the wizard in the sequence.
94       *
95       * @return WizardPage instance.
96       */
97      abstract protected WizardPage getInitialPage();
98  
99      abstract public WizardPage next(final WizardPage src, final Serializable newData)
100             throws WizardException;
101 
102     public WizardPage getCurrentPage() {
103         if (currentPage == null) {
104             throw new IllegalStateException("No current page!");
105         }
106 
107         return currentPage;
108     }
109 
110     /***
111      * Set the current page for the wizard.
112      *
113      * @param current the current page.
114      */
115     protected void setCurrentPage(final WizardPage current) {
116         currentPage = current;
117     }
118 
119     /***
120      * Backtracks the stack.
121      * <p> {@inheritDoc} </p>
122      *
123      * @return WizardPage instance
124      * @throws WizardException upon error, including if we are already
125      *                         at the first state.
126      */
127     public WizardPage previous() throws WizardException {
128         if (backtrace.isEmpty()) {
129             throw new WizardException("Already at the first state!");
130         }
131 
132         WizardPage returnValue = (WizardPage) backtrace.pop();
133         setCurrentPage(returnValue);
134         monitor.onBack(returnValue);
135 
136         return returnValue;
137     }
138 
139     public void destroy() throws WizardException {
140         backtrace.clear();
141         currentPage = null;
142     }
143 
144     /***
145      * {@inheritDoc}
146      * <p>Override in subclasses to return somethingfun useful.  Call the superclass
147      * implementation to set the final version and trigger the monitor
148      * execution.  This particular version returns getAllData(), but of
149      * course, in your derived class you can return anything you want.
150      * </p>
151      *
152      * @param src             WizardPage
153      * @param data            Serializable
154      * @param additonalParams Map: whatever the desired wizard needs
155      *                        from the controller.  Values and objects will vary and is defined
156      *                        by the Application Layer that calls this method.
157      * @return Serializable in this case a data Map.
158      * @throws WizardException
159      */
160     public Object processFinish(final WizardPage src, final Serializable data, final Map additonalParams) throws
161             WizardException {
162         src.setData(data);
163         monitor.onFinish(src);
164         return getAllData();
165     }
166 
167     public String getTitle() {
168         return title;
169     }
170 
171     /***
172      * Set the title of the wizard.
173      *
174      * @param wizardTitle the new wizard title.
175      */
176     public void setTitle(final String wizardTitle) {
177         title = wizardTitle;
178     }
179 
180     public String getSummary() {
181         return summary;
182     }
183 
184     /***
185      * Set the summary text of the wizard.
186      *
187      * @param wizardSummary String, the new summary value.
188      */
189     public void setSummary(final String wizardSummary) {
190         summary = wizardSummary;
191     }
192 
193     /***
194      * Override of toString().
195      *
196      * @return Wizard Title
197      */
198     public String toString() {
199         return getTitle();
200     }
201 
202     /***
203      * Retrieve the id of the Wizard.  Implementations may return
204      * null if they do not differentiate wizards by any id.
205      *
206      * @return Object any particular object.
207      */
208     public Object getId() {
209         return wizardId;
210     }
211 
212     /***
213      * Sets the wizard Id.
214      *
215      * @param id Object the object that represents the wizard id.
216      */
217     public void setId(Object id) {
218         wizardId = id;
219     }
220 
221 
222     /***
223      * Returns hashcode of the title.
224      *
225      * @return integer
226      */
227     public int hashCode() {
228         return getTitle().hashCode();
229     }
230 
231     /***
232      * Checks for equality field by field.
233      *
234      * @param parm1 the other object
235      * @return true if the objects are equal
236      */
237     public boolean equals(final Object parm1) {
238         if (parm1 == null) {
239             return false;
240         }
241 
242         if (!(parm1 instanceof AbstractWizard)) {
243             return false;
244         }
245 
246         AbstractWizard other = (AbstractWizard) parm1;
247         boolean returnValue = true;
248         returnValue &= summary.equals(other.summary);
249         returnValue &= title.equals(other.title);
250         return returnValue;
251     }
252 
253 }