J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame^] | 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 | } |