1 /*
2 * Copyright 1999-2003 Sun Microsystems, Inc. All Rights Reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package javax.security.auth.callback;
27
28 /**
29 * <p> Underlying security services instantiate and pass a
30 * <code>ConfirmationCallback</code> to the <code>handle</code>
31 * method of a <code>CallbackHandler</code> to ask for YES/NO,
32 * OK/CANCEL, YES/NO/CANCEL or other similar confirmations.
33 *
34 * @see javax.security.auth.callback.CallbackHandler
35 */
36 public class ConfirmationCallback implements Callback, java.io.Serializable {
37
38 private static final long serialVersionUID = -9095656433782481624L;
39
40 /**
41 * Unspecified option type.
42 *
43 * <p> The <code>getOptionType</code> method returns this
44 * value if this <code>ConfirmationCallback</code> was instantiated
45 * with <code>options</code> instead of an <code>optionType</code>.
46 */
47 public static final int UNSPECIFIED_OPTION = -1;
48
49 /**
50 * YES/NO confirmation option.
51 *
52 * <p> An underlying security service specifies this as the
53 * <code>optionType</code> to a <code>ConfirmationCallback</code>
54 * constructor if it requires a confirmation which can be answered
55 * with either <code>YES</code> or <code>NO</code>.
56 */
57 public static final int YES_NO_OPTION = 0;
58
59 /**
60 * YES/NO/CANCEL confirmation confirmation option.
61 *
62 * <p> An underlying security service specifies this as the
63 * <code>optionType</code> to a <code>ConfirmationCallback</code>
64 * constructor if it requires a confirmation which can be answered
65 * with either <code>YES</code>, <code>NO</code> or <code>CANCEL</code>.
66 */
67 public static final int YES_NO_CANCEL_OPTION = 1;
68
69 /**
70 * OK/CANCEL confirmation confirmation option.
71 *
72 * <p> An underlying security service specifies this as the
73 * <code>optionType</code> to a <code>ConfirmationCallback</code>
74 * constructor if it requires a confirmation which can be answered
75 * with either <code>OK</code> or <code>CANCEL</code>.
76 */
77 public static final int OK_CANCEL_OPTION = 2;
78
79 /**
80 * YES option.
81 *
82 * <p> If an <code>optionType</code> was specified to this
83 * <code>ConfirmationCallback</code>, this option may be specified as a
84 * <code>defaultOption</code> or returned as the selected index.
85 */
86 public static final int YES = 0;
87
88 /**
89 * NO option.
90 *
91 * <p> If an <code>optionType</code> was specified to this
92 * <code>ConfirmationCallback</code>, this option may be specified as a
93 * <code>defaultOption</code> or returned as the selected index.
94 */
95 public static final int NO = 1;
96
97 /**
98 * CANCEL option.
99 *
100 * <p> If an <code>optionType</code> was specified to this
101 * <code>ConfirmationCallback</code>, this option may be specified as a
102 * <code>defaultOption</code> or returned as the selected index.
103 */
104 public static final int CANCEL = 2;
105
106 /**
107 * OK option.
108 *
109 * <p> If an <code>optionType</code> was specified to this
110 * <code>ConfirmationCallback</code>, this option may be specified as a
111 * <code>defaultOption</code> or returned as the selected index.
112 */
113 public static final int OK = 3;
114
115 /** INFORMATION message type. */
116 public static final int INFORMATION = 0;
117
118 /** WARNING message type. */
119 public static final int WARNING = 1;
120
121 /** ERROR message type. */
122 public static final int ERROR = 2;
123 /**
124 * @serial
125 * @since 1.4
126 */
127 private String prompt;
128 /**
129 * @serial
130 * @since 1.4
131 */
132 private int messageType;
133 /**
134 * @serial
135 * @since 1.4
136 */
137 private int optionType = UNSPECIFIED_OPTION;
138 /**
139 * @serial
140 * @since 1.4
141 */
142 private int defaultOption;
143 /**
144 * @serial
145 * @since 1.4
146 */
147 private String[] options;
148 /**
149 * @serial
150 * @since 1.4
151 */
152 private int selection;
153
154 /**
155 * Construct a <code>ConfirmationCallback</code> with a
156 * message type, an option type and a default option.
157 *
158 * <p> Underlying security services use this constructor if
159 * they require either a YES/NO, YES/NO/CANCEL or OK/CANCEL
160 * confirmation.
161 *
162 * <p>
163 *
164 * @param messageType the message type (<code>INFORMATION</code>,
165 * <code>WARNING</code> or <code>ERROR</code>). <p>
166 *
167 * @param optionType the option type (<code>YES_NO_OPTION</code>,
168 * <code>YES_NO_CANCEL_OPTION</code> or
169 * <code>OK_CANCEL_OPTION</code>). <p>
170 *
171 * @param defaultOption the default option
172 * from the provided optionType (<code>YES</code>,
173 * <code>NO</code>, <code>CANCEL</code> or
174 * <code>OK</code>).
175 *
176 * @exception IllegalArgumentException if messageType is not either
177 * <code>INFORMATION</code>, <code>WARNING</code>,
178 * or <code>ERROR</code>, if optionType is not either
179 * <code>YES_NO_OPTION</code>,
180 * <code>YES_NO_CANCEL_OPTION</code>, or
181 * <code>OK_CANCEL_OPTION</code>,
182 * or if <code>defaultOption</code>
183 * does not correspond to one of the options in
184 * <code>optionType</code>.
185 */
186 public ConfirmationCallback(int messageType,
187 int optionType, int defaultOption) {
188
189 if (messageType < INFORMATION || messageType > ERROR ||
190 optionType < YES_NO_OPTION || optionType > OK_CANCEL_OPTION)
191 throw new IllegalArgumentException();
192
193 switch (optionType) {
194 case YES_NO_OPTION:
195 if (defaultOption != YES && defaultOption != NO)
196 throw new IllegalArgumentException();
197 break;
198 case YES_NO_CANCEL_OPTION:
199 if (defaultOption != YES && defaultOption != NO &&
200 defaultOption != CANCEL)
201 throw new IllegalArgumentException();
202 break;
203 case OK_CANCEL_OPTION:
204 if (defaultOption != OK && defaultOption != CANCEL)
205 throw new IllegalArgumentException();
206 break;
207 }
208
209 this.messageType = messageType;
210 this.optionType = optionType;
211 this.defaultOption = defaultOption;
212 }
213
214 /**
215 * Construct a <code>ConfirmationCallback</code> with a
216 * message type, a list of options and a default option.
217 *
218 * <p> Underlying security services use this constructor if
219 * they require a confirmation different from the available preset
220 * confirmations provided (for example, CONTINUE/ABORT or STOP/GO).
221 * The confirmation options are listed in the <code>options</code> array,
222 * and are displayed by the <code>CallbackHandler</code> implementation
223 * in a manner consistent with the way preset options are displayed.
224 *
225 * <p>
226 *
227 * @param messageType the message type (<code>INFORMATION</code>,
228 * <code>WARNING</code> or <code>ERROR</code>). <p>
229 *
230 * @param options the list of confirmation options. <p>
231 *
232 * @param defaultOption the default option, represented as an index
233 * into the <code>options</code> array.
234 *
235 * @exception IllegalArgumentException if messageType is not either
236 * <code>INFORMATION</code>, <code>WARNING</code>,
237 * or <code>ERROR</code>, if <code>options</code> is null,
238 * if <code>options</code> has a length of 0,
239 * if any element from <code>options</code> is null,
240 * if any element from <code>options</code>
241 * has a length of 0, or if <code>defaultOption</code>
242 * does not lie within the array boundaries of
243 * <code>options</code>.
244 */
245 public ConfirmationCallback(int messageType,
246 String[] options, int defaultOption) {
247
248 if (messageType < INFORMATION || messageType > ERROR ||
249 options == null || options.length == 0 ||
250 defaultOption < 0 || defaultOption >= options.length)
251 throw new IllegalArgumentException();
252
253 for (int i = 0; i < options.length; i++) {
254 if (options[i] == null || options[i].length() == 0)
255 throw new IllegalArgumentException();
256 }
257
258 this.messageType = messageType;
259 this.options = options;
260 this.defaultOption = defaultOption;
261 }
262
263 /**
264 * Construct a <code>ConfirmationCallback</code> with a prompt,
265 * message type, an option type and a default option.
266 *
267 * <p> Underlying security services use this constructor if
268 * they require either a YES/NO, YES/NO/CANCEL or OK/CANCEL
269 * confirmation.
270 *
271 * <p>
272 *
273 * @param prompt the prompt used to describe the list of options. <p>
274 *
275 * @param messageType the message type (<code>INFORMATION</code>,
276 * <code>WARNING</code> or <code>ERROR</code>). <p>
277 *
278 * @param optionType the option type (<code>YES_NO_OPTION</code>,
279 * <code>YES_NO_CANCEL_OPTION</code> or
280 * <code>OK_CANCEL_OPTION</code>). <p>
281 *
282 * @param defaultOption the default option
283 * from the provided optionType (<code>YES</code>,
284 * <code>NO</code>, <code>CANCEL</code> or
285 * <code>OK</code>).
286 *
287 * @exception IllegalArgumentException if <code>prompt</code> is null,
288 * if <code>prompt</code> has a length of 0,
289 * if messageType is not either
290 * <code>INFORMATION</code>, <code>WARNING</code>,
291 * or <code>ERROR</code>, if optionType is not either
292 * <code>YES_NO_OPTION</code>,
293 * <code>YES_NO_CANCEL_OPTION</code>, or
294 * <code>OK_CANCEL_OPTION</code>,
295 * or if <code>defaultOption</code>
296 * does not correspond to one of the options in
297 * <code>optionType</code>.
298 */
299 public ConfirmationCallback(String prompt, int messageType,
300 int optionType, int defaultOption) {
301
302 if (prompt == null || prompt.length() == 0 ||
303 messageType < INFORMATION || messageType > ERROR ||
304 optionType < YES_NO_OPTION || optionType > OK_CANCEL_OPTION)
305 throw new IllegalArgumentException();
306
307 switch (optionType) {
308 case YES_NO_OPTION:
309 if (defaultOption != YES && defaultOption != NO)
310 throw new IllegalArgumentException();
311 break;
312 case YES_NO_CANCEL_OPTION:
313 if (defaultOption != YES && defaultOption != NO &&
314 defaultOption != CANCEL)
315 throw new IllegalArgumentException();
316 break;
317 case OK_CANCEL_OPTION:
318 if (defaultOption != OK && defaultOption != CANCEL)
319 throw new IllegalArgumentException();
320 break;
321 }
322
323 this.prompt = prompt;
324 this.messageType = messageType;
325 this.optionType = optionType;
326 this.defaultOption = defaultOption;
327 }
328
329 /**
330 * Construct a <code>ConfirmationCallback</code> with a prompt,
331 * message type, a list of options and a default option.
332 *
333 * <p> Underlying security services use this constructor if
334 * they require a confirmation different from the available preset
335 * confirmations provided (for example, CONTINUE/ABORT or STOP/GO).
336 * The confirmation options are listed in the <code>options</code> array,
337 * and are displayed by the <code>CallbackHandler</code> implementation
338 * in a manner consistent with the way preset options are displayed.
339 *
340 * <p>
341 *
342 * @param prompt the prompt used to describe the list of options. <p>
343 *
344 * @param messageType the message type (<code>INFORMATION</code>,
345 * <code>WARNING</code> or <code>ERROR</code>). <p>
346 *
347 * @param options the list of confirmation options. <p>
348 *
349 * @param defaultOption the default option, represented as an index
350 * into the <code>options</code> array.
351 *
352 * @exception IllegalArgumentException if <code>prompt</code> is null,
353 * if <code>prompt</code> has a length of 0,
354 * if messageType is not either
355 * <code>INFORMATION</code>, <code>WARNING</code>,
356 * or <code>ERROR</code>, if <code>options</code> is null,
357 * if <code>options</code> has a length of 0,
358 * if any element from <code>options</code> is null,
359 * if any element from <code>options</code>
360 * has a length of 0, or if <code>defaultOption</code>
361 * does not lie within the array boundaries of
362 * <code>options</code>.
363 */
364 public ConfirmationCallback(String prompt, int messageType,
365 String[] options, int defaultOption) {
366
367 if (prompt == null || prompt.length() == 0 ||
368 messageType < INFORMATION || messageType > ERROR ||
369 options == null || options.length == 0 ||
370 defaultOption < 0 || defaultOption >= options.length)
371 throw new IllegalArgumentException();
372
373 for (int i = 0; i < options.length; i++) {
374 if (options[i] == null || options[i].length() == 0)
375 throw new IllegalArgumentException();
376 }
377
378 this.prompt = prompt;
379 this.messageType = messageType;
380 this.options = options;
381 this.defaultOption = defaultOption;
382 }
383
384 /**
385 * Get the prompt.
386 *
387 * <p>
388 *
389 * @return the prompt, or null if this <code>ConfirmationCallback</code>
390 * was instantiated without a <code>prompt</code>.
391 */
392 public String getPrompt() {
393 return prompt;
394 }
395
396 /**
397 * Get the message type.
398 *
399 * <p>
400 *
401 * @return the message type (<code>INFORMATION</code>,
402 * <code>WARNING</code> or <code>ERROR</code>).
403 */
404 public int getMessageType() {
405 return messageType;
406 }
407
408 /**
409 * Get the option type.
410 *
411 * <p> If this method returns <code>UNSPECIFIED_OPTION</code>, then this
412 * <code>ConfirmationCallback</code> was instantiated with
413 * <code>options</code> instead of an <code>optionType</code>.
414 * In this case, invoke the <code>getOptions</code> method
415 * to determine which confirmation options to display.
416 *
417 * <p>
418 *
419 * @return the option type (<code>YES_NO_OPTION</code>,
420 * <code>YES_NO_CANCEL_OPTION</code> or
421 * <code>OK_CANCEL_OPTION</code>), or
422 * <code>UNSPECIFIED_OPTION</code> if this
423 * <code>ConfirmationCallback</code> was instantiated with
424 * <code>options</code> instead of an <code>optionType</code>.
425 */
426 public int getOptionType() {
427 return optionType;
428 }
429
430 /**
431 * Get the confirmation options.
432 *
433 * <p>
434 *
435 * @return the list of confirmation options, or null if this
436 * <code>ConfirmationCallback</code> was instantiated with
437 * an <code>optionType</code> instead of <code>options</code>.
438 */
439 public String[] getOptions() {
440 return options;
441 }
442
443 /**
444 * Get the default option.
445 *
446 * <p>
447 *
448 * @return the default option, represented as
449 * <code>YES</code>, <code>NO</code>, <code>OK</code> or
450 * <code>CANCEL</code> if an <code>optionType</code>
451 * was specified to the constructor of this
452 * <code>ConfirmationCallback</code>.
453 * Otherwise, this method returns the default option as
454 * an index into the
455 * <code>options</code> array specified to the constructor
456 * of this <code>ConfirmationCallback</code>.
457 */
458 public int getDefaultOption() {
459 return defaultOption;
460 }
461
462 /**
463 * Set the selected confirmation option.
464 *
465 * <p>
466 *
467 * @param selection the selection represented as <code>YES</code>,
468 * <code>NO</code>, <code>OK</code> or <code>CANCEL</code>
469 * if an <code>optionType</code> was specified to the constructor
470 * of this <code>ConfirmationCallback</code>.
471 * Otherwise, the selection represents the index into the
472 * <code>options</code> array specified to the constructor
473 * of this <code>ConfirmationCallback</code>.
474 *
475 * @see #getSelectedIndex
476 */
477 public void setSelectedIndex(int selection) {
478 this.selection = selection;
479 }
480
481 /**
482 * Get the selected confirmation option.
483 *
484 * <p>
485 *
486 * @return the selected confirmation option represented as
487 * <code>YES</code>, <code>NO</code>, <code>OK</code> or
488 * <code>CANCEL</code> if an <code>optionType</code>
489 * was specified to the constructor of this
490 * <code>ConfirmationCallback</code>.
491 * Otherwise, this method returns the selected confirmation
492 * option as an index into the
493 * <code>options</code> array specified to the constructor
494 * of this <code>ConfirmationCallback</code>.
495 *
496 * @see #setSelectedIndex
497 */
498 public int getSelectedIndex() {
499 return selection;
500 }
501 }
Save This Page