ConfirmationCallback


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