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.List;
14  import java.util.Map;
15  
16  /***
17   * The interface for generic wizards.  Often the actual operation of the
18   * wizard will be performed by another controller.  The wizard provides
19   * more of a domain model for traversing a series of steps.
20   *
21   * @author Michael Rimov
22   */
23  public interface Wizard extends Serializable {
24      /***
25       * Retrieve the first wizard page and initialize any special data for the
26       * Wizard.
27       *
28       * @return WizardPage instance.
29       * @throws WizardException upon error.
30       */
31      WizardPage begin() throws WizardException;
32  
33      /***
34       * Retrieves a pointer to the current page in the wizard.
35       *
36       * @return Wizard Page instance
37       * @throws IllegalStateException if this is called before begin() is
38       *                               ever invoked.
39       */
40      WizardPage getCurrentPage();
41  
42  
43      /***
44       * Retrieve a page by a given id.  The id is different dependong
45       * on the implementation.
46       *
47       * @param s Serializable the page key.
48       * @return WizardPage as defined.
49       * @throws IllegalArgumentException if s is null or the page given doesn't
50       *                                  exist.
51       */
52      WizardPage getPageById(Serializable s);
53  
54  
55      /***
56       * Allows programmatic rewinding to a previous page.
57       *
58       * @param pageId Serializable the page key.
59       * @return WizardPage the resulting page.
60       */
61      WizardPage backupToPage(Serializable pageId);
62  
63      /***
64       * Execute the next page in the wizard.
65       *
66       * @param newData the data to post to the Wizard.
67       * @param src     the source page of the next event.
68       * @return WizardPage instance.
69       * @throws WizardException upon error.
70       */
71      WizardPage next(WizardPage src, Serializable newData)
72              throws WizardException;
73  
74      /***
75       * Retrieve the first wizard page and initialize any special data for the
76       * Wizard.
77       *
78       * @return WizardPage instance.
79       * @throws WizardException upon error.
80       */
81      WizardPage previous() throws WizardException;
82  
83      /***
84       * Processes the final finish and returns some sort of data that can
85       * be whatever is desired.  If using a web environment, the WizardController
86       * will put the object on the request context with the name
87       * "WizardResult"
88       *
89       * @param src             WizardPage the source of the event.
90       * @param data            Serializable the data given during wht wizard post.
91       * @param additonalParams anything that the underlying wizard needs.
92       *                        The values are set by the Application Controller.
93       * @return Object: whatever object the wizard returns after
94       *         processing.
95       * @throws WizardException upon error.
96       */
97      Object processFinish(WizardPage src,
98                           Serializable data, Map additonalParams)
99              throws WizardException;
100 
101 
102     /***
103      * De-initialize all data for the wizard.
104      *
105      * @throws WizardException upon destruction error.
106      */
107     void destroy() throws WizardException;
108 
109     /***
110      * Retrieve all the data for the wizard keyed by page id.
111      *
112      * @return Map keyed by id.
113      * @throws WizardException upon error
114      */
115     Map getAllData() throws WizardException;
116 
117 
118     /***
119      * Retrieve all Pages in the order that the person has stepped through
120      * them.
121      *
122      * @return List of WizardPage objects.
123      * @throws WizardException if unable to query history.
124      */
125     List getStepHistory() throws WizardException;
126 
127     /***
128      * Retrieve the title of the wizard.
129      *
130      * @return java.lang.String.
131      */
132     String getTitle();
133 
134     /***
135      * Retrieve the text summary of the wizard.  May return null since summary
136      * attribute is optional.
137      *
138      * @return String or null if none is defined.
139      */
140     String getSummary();
141 
142     /***
143      * Retrieve the id of the Wizard.  Implementations may return
144      * null if they do not differentiate wizards by any id.
145      *
146      * @return Object any particular object.
147      */
148     Object getId();
149 }