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