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