1
2
3
4
5
6
7
8
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 }