001 /*
002 * Copyright 1999-2003 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.security.auth.callback;
027
028 /**
029 * <p> Underlying security services instantiate and pass a
030 * <code>ConfirmationCallback</code> to the <code>handle</code>
031 * method of a <code>CallbackHandler</code> to ask for YES/NO,
032 * OK/CANCEL, YES/NO/CANCEL or other similar confirmations.
033 *
034 * @version 1.23, 05/05/07
035 * @see javax.security.auth.callback.CallbackHandler
036 */
037 public class ConfirmationCallback implements Callback,
038 java.io.Serializable {
039
040 private static final long serialVersionUID = -9095656433782481624L;
041
042 /**
043 * Unspecified option type.
044 *
045 * <p> The <code>getOptionType</code> method returns this
046 * value if this <code>ConfirmationCallback</code> was instantiated
047 * with <code>options</code> instead of an <code>optionType</code>.
048 */
049 public static final int UNSPECIFIED_OPTION = -1;
050
051 /**
052 * YES/NO confirmation option.
053 *
054 * <p> An underlying security service specifies this as the
055 * <code>optionType</code> to a <code>ConfirmationCallback</code>
056 * constructor if it requires a confirmation which can be answered
057 * with either <code>YES</code> or <code>NO</code>.
058 */
059 public static final int YES_NO_OPTION = 0;
060
061 /**
062 * YES/NO/CANCEL confirmation confirmation option.
063 *
064 * <p> An underlying security service specifies this as the
065 * <code>optionType</code> to a <code>ConfirmationCallback</code>
066 * constructor if it requires a confirmation which can be answered
067 * with either <code>YES</code>, <code>NO</code> or <code>CANCEL</code>.
068 */
069 public static final int YES_NO_CANCEL_OPTION = 1;
070
071 /**
072 * OK/CANCEL confirmation confirmation option.
073 *
074 * <p> An underlying security service specifies this as the
075 * <code>optionType</code> to a <code>ConfirmationCallback</code>
076 * constructor if it requires a confirmation which can be answered
077 * with either <code>OK</code> or <code>CANCEL</code>.
078 */
079 public static final int OK_CANCEL_OPTION = 2;
080
081 /**
082 * YES option.
083 *
084 * <p> If an <code>optionType</code> was specified to this
085 * <code>ConfirmationCallback</code>, this option may be specified as a
086 * <code>defaultOption</code> or returned as the selected index.
087 */
088 public static final int YES = 0;
089
090 /**
091 * NO option.
092 *
093 * <p> If an <code>optionType</code> was specified to this
094 * <code>ConfirmationCallback</code>, this option may be specified as a
095 * <code>defaultOption</code> or returned as the selected index.
096 */
097 public static final int NO = 1;
098
099 /**
100 * CANCEL option.
101 *
102 * <p> If an <code>optionType</code> was specified to this
103 * <code>ConfirmationCallback</code>, this option may be specified as a
104 * <code>defaultOption</code> or returned as the selected index.
105 */
106 public static final int CANCEL = 2;
107
108 /**
109 * OK option.
110 *
111 * <p> If an <code>optionType</code> was specified to this
112 * <code>ConfirmationCallback</code>, this option may be specified as a
113 * <code>defaultOption</code> or returned as the selected index.
114 */
115 public static final int OK = 3;
116
117 /** INFORMATION message type. */
118 public static final int INFORMATION = 0;
119
120 /** WARNING message type. */
121 public static final int WARNING = 1;
122
123 /** ERROR message type. */
124 public static final int ERROR = 2;
125 /**
126 * @serial
127 * @since 1.4
128 */
129 private String prompt;
130 /**
131 * @serial
132 * @since 1.4
133 */
134 private int messageType;
135 /**
136 * @serial
137 * @since 1.4
138 */
139 private int optionType = UNSPECIFIED_OPTION;
140 /**
141 * @serial
142 * @since 1.4
143 */
144 private int defaultOption;
145 /**
146 * @serial
147 * @since 1.4
148 */
149 private String[] options;
150 /**
151 * @serial
152 * @since 1.4
153 */
154 private int selection;
155
156 /**
157 * Construct a <code>ConfirmationCallback</code> with a
158 * message type, an option type and a default option.
159 *
160 * <p> Underlying security services use this constructor if
161 * they require either a YES/NO, YES/NO/CANCEL or OK/CANCEL
162 * confirmation.
163 *
164 * <p>
165 *
166 * @param messageType the message type (<code>INFORMATION</code>,
167 * <code>WARNING</code> or <code>ERROR</code>). <p>
168 *
169 * @param optionType the option type (<code>YES_NO_OPTION</code>,
170 * <code>YES_NO_CANCEL_OPTION</code> or
171 * <code>OK_CANCEL_OPTION</code>). <p>
172 *
173 * @param defaultOption the default option
174 * from the provided optionType (<code>YES</code>,
175 * <code>NO</code>, <code>CANCEL</code> or
176 * <code>OK</code>).
177 *
178 * @exception IllegalArgumentException if messageType is not either
179 * <code>INFORMATION</code>, <code>WARNING</code>,
180 * or <code>ERROR</code>, if optionType is not either
181 * <code>YES_NO_OPTION</code>,
182 * <code>YES_NO_CANCEL_OPTION</code>, or
183 * <code>OK_CANCEL_OPTION</code>,
184 * or if <code>defaultOption</code>
185 * does not correspond to one of the options in
186 * <code>optionType</code>.
187 */
188 public ConfirmationCallback(int messageType, int optionType,
189 int defaultOption) {
190
191 if (messageType < INFORMATION || messageType > ERROR
192 || optionType < YES_NO_OPTION
193 || optionType > OK_CANCEL_OPTION)
194 throw new IllegalArgumentException();
195
196 switch (optionType) {
197 case YES_NO_OPTION:
198 if (defaultOption != YES && defaultOption != NO)
199 throw new IllegalArgumentException();
200 break;
201 case YES_NO_CANCEL_OPTION:
202 if (defaultOption != YES && defaultOption != NO
203 && defaultOption != CANCEL)
204 throw new IllegalArgumentException();
205 break;
206 case OK_CANCEL_OPTION:
207 if (defaultOption != OK && defaultOption != CANCEL)
208 throw new IllegalArgumentException();
209 break;
210 }
211
212 this .messageType = messageType;
213 this .optionType = optionType;
214 this .defaultOption = defaultOption;
215 }
216
217 /**
218 * Construct a <code>ConfirmationCallback</code> with a
219 * message type, a list of options and a default option.
220 *
221 * <p> Underlying security services use this constructor if
222 * they require a confirmation different from the available preset
223 * confirmations provided (for example, CONTINUE/ABORT or STOP/GO).
224 * The confirmation options are listed in the <code>options</code> array,
225 * and are displayed by the <code>CallbackHandler</code> implementation
226 * in a manner consistent with the way preset options are displayed.
227 *
228 * <p>
229 *
230 * @param messageType the message type (<code>INFORMATION</code>,
231 * <code>WARNING</code> or <code>ERROR</code>). <p>
232 *
233 * @param options the list of confirmation options. <p>
234 *
235 * @param defaultOption the default option, represented as an index
236 * into the <code>options</code> array.
237 *
238 * @exception IllegalArgumentException if messageType is not either
239 * <code>INFORMATION</code>, <code>WARNING</code>,
240 * or <code>ERROR</code>, if <code>options</code> is null,
241 * if <code>options</code> has a length of 0,
242 * if any element from <code>options</code> is null,
243 * if any element from <code>options</code>
244 * has a length of 0, or if <code>defaultOption</code>
245 * does not lie within the array boundaries of
246 * <code>options</code>.
247 */
248 public ConfirmationCallback(int messageType, String[] options,
249 int defaultOption) {
250
251 if (messageType < INFORMATION || messageType > ERROR
252 || options == null || options.length == 0
253 || defaultOption < 0 || defaultOption >= options.length)
254 throw new IllegalArgumentException();
255
256 for (int i = 0; i < options.length; i++) {
257 if (options[i] == null || options[i].length() == 0)
258 throw new IllegalArgumentException();
259 }
260
261 this .messageType = messageType;
262 this .options = options;
263 this .defaultOption = defaultOption;
264 }
265
266 /**
267 * Construct a <code>ConfirmationCallback</code> with a prompt,
268 * message type, an option type and a default option.
269 *
270 * <p> Underlying security services use this constructor if
271 * they require either a YES/NO, YES/NO/CANCEL or OK/CANCEL
272 * confirmation.
273 *
274 * <p>
275 *
276 * @param prompt the prompt used to describe the list of options. <p>
277 *
278 * @param messageType the message type (<code>INFORMATION</code>,
279 * <code>WARNING</code> or <code>ERROR</code>). <p>
280 *
281 * @param optionType the option type (<code>YES_NO_OPTION</code>,
282 * <code>YES_NO_CANCEL_OPTION</code> or
283 * <code>OK_CANCEL_OPTION</code>). <p>
284 *
285 * @param defaultOption the default option
286 * from the provided optionType (<code>YES</code>,
287 * <code>NO</code>, <code>CANCEL</code> or
288 * <code>OK</code>).
289 *
290 * @exception IllegalArgumentException if <code>prompt</code> is null,
291 * if <code>prompt</code> has a length of 0,
292 * if messageType is not either
293 * <code>INFORMATION</code>, <code>WARNING</code>,
294 * or <code>ERROR</code>, if optionType is not either
295 * <code>YES_NO_OPTION</code>,
296 * <code>YES_NO_CANCEL_OPTION</code>, or
297 * <code>OK_CANCEL_OPTION</code>,
298 * or if <code>defaultOption</code>
299 * does not correspond to one of the options in
300 * <code>optionType</code>.
301 */
302 public ConfirmationCallback(String prompt, int messageType,
303 int optionType, int defaultOption) {
304
305 if (prompt == null || prompt.length() == 0
306 || messageType < INFORMATION || messageType > ERROR
307 || optionType < YES_NO_OPTION
308 || optionType > OK_CANCEL_OPTION)
309 throw new IllegalArgumentException();
310
311 switch (optionType) {
312 case YES_NO_OPTION:
313 if (defaultOption != YES && defaultOption != NO)
314 throw new IllegalArgumentException();
315 break;
316 case YES_NO_CANCEL_OPTION:
317 if (defaultOption != YES && defaultOption != NO
318 && defaultOption != CANCEL)
319 throw new IllegalArgumentException();
320 break;
321 case OK_CANCEL_OPTION:
322 if (defaultOption != OK && defaultOption != CANCEL)
323 throw new IllegalArgumentException();
324 break;
325 }
326
327 this .prompt = prompt;
328 this .messageType = messageType;
329 this .optionType = optionType;
330 this .defaultOption = defaultOption;
331 }
332
333 /**
334 * Construct a <code>ConfirmationCallback</code> with a prompt,
335 * message type, a list of options and a default option.
336 *
337 * <p> Underlying security services use this constructor if
338 * they require a confirmation different from the available preset
339 * confirmations provided (for example, CONTINUE/ABORT or STOP/GO).
340 * The confirmation options are listed in the <code>options</code> array,
341 * and are displayed by the <code>CallbackHandler</code> implementation
342 * in a manner consistent with the way preset options are displayed.
343 *
344 * <p>
345 *
346 * @param prompt the prompt used to describe the list of options. <p>
347 *
348 * @param messageType the message type (<code>INFORMATION</code>,
349 * <code>WARNING</code> or <code>ERROR</code>). <p>
350 *
351 * @param options the list of confirmation options. <p>
352 *
353 * @param defaultOption the default option, represented as an index
354 * into the <code>options</code> array.
355 *
356 * @exception IllegalArgumentException if <code>prompt</code> is null,
357 * if <code>prompt</code> has a length of 0,
358 * if messageType is not either
359 * <code>INFORMATION</code>, <code>WARNING</code>,
360 * or <code>ERROR</code>, if <code>options</code> is null,
361 * if <code>options</code> has a length of 0,
362 * if any element from <code>options</code> is null,
363 * if any element from <code>options</code>
364 * has a length of 0, or if <code>defaultOption</code>
365 * does not lie within the array boundaries of
366 * <code>options</code>.
367 */
368 public ConfirmationCallback(String prompt, int messageType,
369 String[] options, int defaultOption) {
370
371 if (prompt == null || prompt.length() == 0
372 || messageType < INFORMATION || messageType > ERROR
373 || options == null || options.length == 0
374 || defaultOption < 0 || defaultOption >= options.length)
375 throw new IllegalArgumentException();
376
377 for (int i = 0; i < options.length; i++) {
378 if (options[i] == null || options[i].length() == 0)
379 throw new IllegalArgumentException();
380 }
381
382 this .prompt = prompt;
383 this .messageType = messageType;
384 this .options = options;
385 this .defaultOption = defaultOption;
386 }
387
388 /**
389 * Get the prompt.
390 *
391 * <p>
392 *
393 * @return the prompt, or null if this <code>ConfirmationCallback</code>
394 * was instantiated without a <code>prompt</code>.
395 */
396 public String getPrompt() {
397 return prompt;
398 }
399
400 /**
401 * Get the message type.
402 *
403 * <p>
404 *
405 * @return the message type (<code>INFORMATION</code>,
406 * <code>WARNING</code> or <code>ERROR</code>).
407 */
408 public int getMessageType() {
409 return messageType;
410 }
411
412 /**
413 * Get the option type.
414 *
415 * <p> If this method returns <code>UNSPECIFIED_OPTION</code>, then this
416 * <code>ConfirmationCallback</code> was instantiated with
417 * <code>options</code> instead of an <code>optionType</code>.
418 * In this case, invoke the <code>getOptions</code> method
419 * to determine which confirmation options to display.
420 *
421 * <p>
422 *
423 * @return the option type (<code>YES_NO_OPTION</code>,
424 * <code>YES_NO_CANCEL_OPTION</code> or
425 * <code>OK_CANCEL_OPTION</code>), or
426 * <code>UNSPECIFIED_OPTION</code> if this
427 * <code>ConfirmationCallback</code> was instantiated with
428 * <code>options</code> instead of an <code>optionType</code>.
429 */
430 public int getOptionType() {
431 return optionType;
432 }
433
434 /**
435 * Get the confirmation options.
436 *
437 * <p>
438 *
439 * @return the list of confirmation options, or null if this
440 * <code>ConfirmationCallback</code> was instantiated with
441 * an <code>optionType</code> instead of <code>options</code>.
442 */
443 public String[] getOptions() {
444 return options;
445 }
446
447 /**
448 * Get the default option.
449 *
450 * <p>
451 *
452 * @return the default option, represented as
453 * <code>YES</code>, <code>NO</code>, <code>OK</code> or
454 * <code>CANCEL</code> if an <code>optionType</code>
455 * was specified to the constructor of this
456 * <code>ConfirmationCallback</code>.
457 * Otherwise, this method returns the default option as
458 * an index into the
459 * <code>options</code> array specified to the constructor
460 * of this <code>ConfirmationCallback</code>.
461 */
462 public int getDefaultOption() {
463 return defaultOption;
464 }
465
466 /**
467 * Set the selected confirmation option.
468 *
469 * <p>
470 *
471 * @param selection the selection represented as <code>YES</code>,
472 * <code>NO</code>, <code>OK</code> or <code>CANCEL</code>
473 * if an <code>optionType</code> was specified to the constructor
474 * of this <code>ConfirmationCallback</code>.
475 * Otherwise, the selection represents the index into the
476 * <code>options</code> array specified to the constructor
477 * of this <code>ConfirmationCallback</code>.
478 *
479 * @see #getSelectedIndex
480 */
481 public void setSelectedIndex(int selection) {
482 this .selection = selection;
483 }
484
485 /**
486 * Get the selected confirmation option.
487 *
488 * <p>
489 *
490 * @return the selected confirmation option represented as
491 * <code>YES</code>, <code>NO</code>, <code>OK</code> or
492 * <code>CANCEL</code> if an <code>optionType</code>
493 * was specified to the constructor of this
494 * <code>ConfirmationCallback</code>.
495 * Otherwise, this method returns the selected confirmation
496 * option as an index into the
497 * <code>options</code> array specified to the constructor
498 * of this <code>ConfirmationCallback</code>.
499 *
500 * @see #setSelectedIndex
501 */
502 public int getSelectedIndex() {
503 return selection;
504 }
505 }
|