/* ConfirmationCallback.java -- callback for confirmations. Copyright (C) 2003, Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version. */ package javax.security.auth.callback; import java.io.Serializable; /** * Underlying security services instantiate and pass a * ConfirmationCallback to the handle() method of a * {@link CallbackHandler} to ask for YES/NO, OK/CANCEL, YES/NO/CANCEL or other * similar confirmations. * * @see CallbackHandler * @version $Revision: 1.1 $ */ public class ConfirmationCallback implements Callback, Serializable { // Constants and variables // ------------------------------------------------------------------------- /** *

Unspecified option type.

* *

The getOptionType method returns this value if this * ConfirmationCallback was instantiated with options * instead of an optionType.

*/ public static final int UNSPECIFIED_OPTION = -1; /** *

YES/NO confirmation option.

* *

An underlying security service specifies this as the optionType * to a ConfirmationCallback constructor if it requires a * confirmation which can be answered with either YES or * NO.

*/ public static final int YES_NO_OPTION = 0; /** *

YES/NO/CANCEL confirmation confirmation option.

* *

An underlying security service specifies this as the optionType * to a ConfirmationCallback constructor if it requires a * confirmation which can be answered with either YES, * NO or CANCEL. */ public static final int YES_NO_CANCEL_OPTION = 1; /** *

OK/CANCEL confirmation confirmation option.

* *

An underlying security service specifies this as the optionType * to a ConfirmationCallback constructor if it requires a * confirmation which can be answered with either OK or * CANCEL.

*/ public static final int OK_CANCEL_OPTION = 2; /** *

YES option.

* *

If an optionType was specified to this * ConfirmationCallback, this option may be specified as a * defaultOption or returned as the selected index.

*/ public static final int YES = 0; /** *

NO option.

* *

If an optionType was specified to this * ConfirmationCallback, this option may be specified as a * defaultOption or returned as the selected index.

*/ public static final int NO = 1; /** *

CANCEL option.

* *

If an optionType was specified to this * ConfirmationCallback, this option may be specified as a * defaultOption or returned as the selected index.

*/ public static final int CANCEL = 2; /** *

OK option.

* *

If an optionType was specified to this * ConfirmationCallback, this option may be specified as a * defaultOption or returned as the selected index.

*/ public static final int OK = 3; /** INFORMATION message type. */ public static final int INFORMATION = 0; /** WARNING message type. */ public static final int WARNING = 1; /** ERROR message type. */ public static final int ERROR = 2; /** * @serial * @since 1.4 */ private String prompt; /** * @serial * @since 1.4 */ private int messageType; /** * @serial * @since 1.4 */ private int optionType; /** * @serial * @since 1.4 */ private int defaultOption; /** * @serial * @since 1.4 */ private String[] options = null; /** * @serial * @since 1.4 */ private int selection; // Constructor(s) // ------------------------------------------------------------------------- /** *

Construct a ConfirmationCallback with a message type, an * option type and a default option.

* *

Underlying security services use this constructor if they require * either a YES/NO, YES/NO/CANCEL or OK/CANCEL confirmation.

* * @param messageType the message type (INFORMATION, WARNING or ERROR). * @param optionType the option type (YES_NO_OPTION, YES_NO_CANCEL_OPTION or * OK_CANCEL_OPTION). * @param defaultOption the default option from the provided optionType (YES, * NO, CANCEL or OK). * @throws IllegalArgumentException if messageType is not either * INFORMATION, WARNING, or ERROR, if * optionType is not either YES_NO_OPTION, * YES_NO_CANCEL_OPTION, or OK_CANCEL_OPTION, or if * defaultOption does not correspond to one of the options in * optionType. */ public ConfirmationCallback(int messageType, int optionType, int defaultOption) throws IllegalArgumentException { super(); setMessageType(messageType); setOptionType(optionType, defaultOption); this.defaultOption = defaultOption; } /** *

Construct a ConfirmationCallback with a message type, a * list of options and a default option.

* *

Underlying security services use this constructor if they require a * confirmation different from the available preset confirmations provided * (for example, CONTINUE/ABORT or STOP/GO). The confirmation options are * listed in the options array, and are displayed by the * {@link CallbackHandler} implementation in a manner consistent with the * way preset options are displayed.

* * @param messageType the message type (INFORMATION, WARNING or ERROR). * @param options the list of confirmation options. * @param defaultOption the default option, represented as an index into the * options array. * @throws IllegalArgumentException if messageType is not either * INFORMATION, WARNING, or ERROR, if * options is null, if options has a * length of 0, if any element from options is * null, if any element from options has a length * of 0, or if defaultOption does not lie within * the array boundaries of options. */ public ConfirmationCallback(int messageType, String[] options, int defaultOption) { super(); setMessageType(messageType); setOptions(options, defaultOption); this.defaultOption = defaultOption; } /** *

Construct a ConfirmationCallback with a prompt, message * type, an option type and a default option.

* *

Underlying security services use this constructor if they require * either a YES/NO, YES/NO/CANCEL or OK/CANCEL confirmation.

* * @param prompt the prompt used to describe the list of options. * @param messageType the message type (INFORMATION, WARNING or ERROR). * @param optionType the option type (YES_NO_OPTION, YES_NO_CANCEL_OPTION or * OK_CANCEL_OPTION). * @param defaultOption the default option from the provided optionType (YES, * NO, CANCEL or OK). * @throws IllegalArgumentException if prompt is null, * if prompt has a length of 0, if * messageType is not either INFORMATION, * WARNING, or ERROR, if optionType is * not either YES_NO_OPTION, YES_NO_CANCEL_OPTION, * or OK_CANCEL_OPTION, or if defaultOption does * not correspond to one of the options in optionType. */ public ConfirmationCallback(String prompt, int messageType, int optionType, int defaultOption) { super(); setPrompt(prompt); setMessageType(messageType); setOptionType(optionType, defaultOption); this.defaultOption = defaultOption; } /** *

Construct a ConfirmationCallback with a prompt, message * type, a list of options and a default option.

* *

Underlying security services use this constructor if they require a * confirmation different from the available preset confirmations provided * (for example, CONTINUE/ABORT or STOP/GO). The confirmation options are * listed in the options array, and are displayed by the * {@link CallbackHandler} implementation in a manner consistent with the * way preset options are displayed.

* * @param prompt the prompt used to describe the list of options. * @param messageType the message type (INFORMATION, WARNING or ERROR). * @param options the list of confirmation options. * @param defaultOption the default option, represented as an index into the * options array. * @throws IllegalArgumentException if prompt is null, * if prompt has a length of 0, if * messageType is not either INFORMATION, * WARNING, or ERROR, if options is * null, if options has a length of 0, * if any element from options is null, if any * element from options has a length of 0, or if * defaultOption does not lie within the array boundaries of * options. */ public ConfirmationCallback(String prompt, int messageType, String[] options, int defaultOption) { super(); setPrompt(prompt); setMessageType(messageType); setOptions(options, defaultOption); this.defaultOption = defaultOption; } // Class methods // ------------------------------------------------------------------------- // Instance methods // ------------------------------------------------------------------------- /** * Get the prompt. * * @return the prompt, or null if this * ConfirmationCallback was instantiated without a prompt. */ public String getPrompt() { return prompt; } /** * Get the message type. * * @return the message type (INFORMATION, WARNING or ERROR). */ public int getMessageType() { return messageType; } /** *

Get the option type.

* *

If this method returns {@link #UNSPECIFIED_OPTION}, then this * ConfirmationCallback was instantiated with options * instead of an optionType. In this case, invoke the * {@link #getOptions()} method to determine which confirmation options to * display.

* * @return the option type (YES_NO_OPTION, YES_NO_CANCEL_OPTION or * OK_CANCEL_OPTION), or UNSPECIFIED_OPTION if this * ConfirmationCallback was instantiated with options * instead of an optionType. */ public int getOptionType() { if (options != null) { return UNSPECIFIED_OPTION; } return optionType; } /** * Get the confirmation options. * * @return the list of confirmation options, or null if this * ConfirmationCallback was instantiated with an * optionType instead of options. */ public String[] getOptions() { return options; } /** * Get the default option. * * @return the default option, represented as YES, NO, * OK or CANCEL if an optionType was * specified to the constructor of this ConfirmationCallback. * Otherwise, this method returns the default option as an index into the * options array specified to the constructor of this * ConfirmationCallback. */ public int getDefaultOption() { return defaultOption; } /** * Set the selected confirmation option. * * @param selection the selection represented as YES, * NO, OK or CANCEL if an * optionType was specified to the constructor of this * ConfirmationCallback. Otherwise, the selection * represents the index into the options array specified to the * constructor of this ConfirmationCallback. * @see #getSelectedIndex() */ public void setSelectedIndex(int selection) { if (options != null) { setOptions(options, selection); } else { setOptionType(optionType, selection); } } /** * Get the selected confirmation option. * * @return the selected confirmation option represented as YES, * NO, OK or CANCEL if an * optionType was specified to the constructor of this * ConfirmationCallback. Otherwise, this method returns the * selected confirmation option as an index into the options * array specified to the constructor of this ConfirmationCallback. * @see #setSelectedIndex(int) */ public int getSelectedIndex() { return this.selection; } private void setMessageType(int messageType) throws IllegalArgumentException { switch (messageType) { case INFORMATION: case WARNING: case ERROR: this.messageType = messageType; break; default: throw new IllegalArgumentException("illegal message type"); } } private void setOptionType(int optionType, int selectedOption) throws IllegalArgumentException { switch (optionType) { case YES_NO_OPTION: this.optionType = optionType; switch (selectedOption) { case YES: case NO: this.selection = selectedOption; break; default: throw new IllegalArgumentException("invalid option"); } break; case YES_NO_CANCEL_OPTION: this.optionType = optionType; switch (selectedOption) { case YES: case NO: case CANCEL: this.selection = selectedOption; break; default: throw new IllegalArgumentException("invalid option"); } break; case OK_CANCEL_OPTION: this.optionType = optionType; switch (selectedOption) { case OK: case CANCEL: this.selection = selectedOption; break; default: throw new IllegalArgumentException("invalid option"); } break; default: throw new IllegalArgumentException("illegal option type"); } } private void setOptions(String[] options, int selectedOption) throws IllegalArgumentException { if ((selectedOption < 0) || (selectedOption > options.length - 1)) { throw new IllegalArgumentException("invalid selection"); } if ((options == null) || (options.length == 0)) { throw new IllegalArgumentException("options is null or empty"); } for (int i = 0; i < options.length; i++) { if ((options[i] == null) || (options[i].length() == 0)) { throw new IllegalArgumentException("options[" + i + "] is null or empty"); } } this.options = options; this.selection = selectedOption; } private void setPrompt(String prompt) throws IllegalArgumentException { if ((prompt == null) || (prompt.length() == 0)) { throw new IllegalArgumentException("prompt is null or empty"); } this.prompt = prompt; } }