Source for javax.security.auth.callback.ConfirmationCallback

   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: }