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