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