1 /*
   2  * Copyright (c) 1999, 2015, Oracle and/or its affiliates. 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.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.security.auth.callback;
  27 
  28 /**
  29  * <p> Underlying security services instantiate and pass a
  30  * {@code ChoiceCallback} to the {@code handle}
  31  * method of a {@code CallbackHandler} to display a list of choices
  32  * and to retrieve the selected choice(s).
  33  *
  34  * @see javax.security.auth.callback.CallbackHandler
  35  */
  36 public class ChoiceCallback implements Callback, java.io.Serializable {
  37 
  38     private static final long serialVersionUID = -3975664071579892167L;
  39 
  40     /**
  41      * @serial
  42      * @since 1.4
  43      */
  44     private String prompt;
  45     /**
  46      * @serial the list of choices
  47      * @since 1.4
  48      */
  49     private String[] choices;
  50     /**
  51      * @serial the choice to be used as the default choice
  52      * @since 1.4
  53      */
  54     private int defaultChoice;
  55     /**
  56      * @serial whether multiple selections are allowed from the list of
  57      * choices
  58      * @since 1.4
  59      */
  60     private boolean multipleSelectionsAllowed;
  61     /**
  62      * @serial the selected choices, represented as indexes into the
  63      *          {@code choices} list.
  64      * @since 1.4
  65      */
  66     private int[] selections;
  67 
  68     /**
  69      * Construct a {@code ChoiceCallback} with a prompt,
  70      * a list of choices, a default choice, and a boolean specifying
  71      * whether or not multiple selections from the list of choices are allowed.
  72      *
  73      *
  74      * @param prompt the prompt used to describe the list of choices.
  75      *
  76      * @param choices the list of choices.
  77      *
  78      * @param defaultChoice the choice to be used as the default choice
  79      *                  when the list of choices are displayed.  This value
  80      *                  is represented as an index into the
  81      *                  {@code choices} array.
  82      *
  83      * @param multipleSelectionsAllowed boolean specifying whether or
  84      *                  not multiple selections can be made from the
  85      *                  list of choices.
  86      *
  87      * @exception IllegalArgumentException if {@code prompt} is null,
  88      *                  if {@code prompt} has a length of 0,
  89      *                  if {@code choices} is null,
  90      *                  if {@code choices} has a length of 0,
  91      *                  if any element from {@code choices} is null,
  92      *                  if any element from {@code choices}
  93      *                  has a length of 0 or if {@code defaultChoice}
  94      *                  does not fall within the array boundaries of
  95      *                  {@code choices}.
  96      */
  97     public ChoiceCallback(String prompt, String[] choices,
  98                 int defaultChoice, boolean multipleSelectionsAllowed) {
  99 
 100         if (prompt == null || prompt.length() == 0 ||
 101             choices == null || choices.length == 0 ||
 102             defaultChoice < 0 || defaultChoice >= choices.length)
 103             throw new IllegalArgumentException();
 104 
 105         for (int i = 0; i < choices.length; i++) {
 106             if (choices[i] == null || choices[i].length() == 0)
 107                 throw new IllegalArgumentException();
 108         }
 109 
 110         this.prompt = prompt;
 111         this.choices = choices;
 112         this.defaultChoice = defaultChoice;
 113         this.multipleSelectionsAllowed = multipleSelectionsAllowed;
 114     }
 115 
 116     /**
 117      * Get the prompt.
 118      *
 119      * @return the prompt.
 120      */
 121     public String getPrompt() {
 122         return prompt;
 123     }
 124 
 125     /**
 126      * Get the list of choices.
 127      *
 128      * @return the list of choices.
 129      */
 130     public String[] getChoices() {
 131         return choices;
 132     }
 133 
 134     /**
 135      * Get the defaultChoice.
 136      *
 137      * @return the defaultChoice, represented as an index into
 138      *          the {@code choices} list.
 139      */
 140     public int getDefaultChoice() {
 141         return defaultChoice;
 142     }
 143 
 144     /**
 145      * Get the boolean determining whether multiple selections from
 146      * the {@code choices} list are allowed.
 147      *
 148      * @return whether multiple selections are allowed.
 149      */
 150     public boolean allowMultipleSelections() {
 151         return multipleSelectionsAllowed;
 152     }
 153 
 154     /**
 155      * Set the selected choice.
 156      *
 157      * @param selection the selection represented as an index into the
 158      *          {@code choices} list.
 159      *
 160      * @see #getSelectedIndexes
 161      */
 162     public void setSelectedIndex(int selection) {
 163         this.selections = new int[1];
 164         this.selections[0] = selection;
 165     }
 166 
 167     /**
 168      * Set the selected choices.
 169      *
 170      * @param selections the selections represented as indexes into the
 171      *          {@code choices} list.
 172      *
 173      * @exception UnsupportedOperationException if multiple selections are
 174      *          not allowed, as determined by
 175      *          {@code allowMultipleSelections}.
 176      *
 177      * @see #getSelectedIndexes
 178      */
 179     public void setSelectedIndexes(int[] selections) {
 180         if (!multipleSelectionsAllowed)
 181             throw new UnsupportedOperationException();
 182         this.selections = selections;
 183     }
 184 
 185     /**
 186      * Get the selected choices.
 187      *
 188      * @return the selected choices, represented as indexes into the
 189      *          {@code choices} list.
 190      *
 191      * @see #setSelectedIndexes
 192      */
 193     public int[] getSelectedIndexes() {
 194         return selections;
 195     }
 196 }