1 /* |
1 /* |
2 * Copyright (c) 1999, 2012, Oracle and/or its affiliates. All rights reserved. |
2 * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved. |
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
4 * |
4 * |
5 * This code is free software; you can redistribute it and/or modify it |
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 |
6 * under the terms of the GNU General Public License version 2 only, as |
7 * published by the Free Software Foundation. Oracle designates this |
7 * published by the Free Software Foundation. Oracle designates this |
24 */ |
24 */ |
25 |
25 |
26 package javax.security.auth.callback; |
26 package javax.security.auth.callback; |
27 |
27 |
28 /** |
28 /** |
29 * <p> An application implements a <code>CallbackHandler</code> and passes |
29 * <p> An application implements a {@code CallbackHandler} and passes |
30 * it to underlying security services so that they may interact with |
30 * it to underlying security services so that they may interact with |
31 * the application to retrieve specific authentication data, |
31 * the application to retrieve specific authentication data, |
32 * such as usernames and passwords, or to display certain information, |
32 * such as usernames and passwords, or to display certain information, |
33 * such as error and warning messages. |
33 * such as error and warning messages. |
34 * |
34 * |
38 * or to display error messages. An implementation may also choose to obtain |
38 * or to display error messages. An implementation may also choose to obtain |
39 * requested information from an alternate source without asking the end user. |
39 * requested information from an alternate source without asking the end user. |
40 * |
40 * |
41 * <p> Underlying security services make requests for different types |
41 * <p> Underlying security services make requests for different types |
42 * of information by passing individual Callbacks to the |
42 * of information by passing individual Callbacks to the |
43 * <code>CallbackHandler</code>. The <code>CallbackHandler</code> |
43 * {@code CallbackHandler}. The {@code CallbackHandler} |
44 * implementation decides how to retrieve and display information |
44 * implementation decides how to retrieve and display information |
45 * depending on the Callbacks passed to it. For example, |
45 * depending on the Callbacks passed to it. For example, |
46 * if the underlying service needs a username and password to |
46 * if the underlying service needs a username and password to |
47 * authenticate a user, it uses a <code>NameCallback</code> and |
47 * authenticate a user, it uses a {@code NameCallback} and |
48 * <code>PasswordCallback</code>. The <code>CallbackHandler</code> |
48 * {@code PasswordCallback}. The {@code CallbackHandler} |
49 * can then choose to prompt for a username and password serially, |
49 * can then choose to prompt for a username and password serially, |
50 * or to prompt for both in a single window. |
50 * or to prompt for both in a single window. |
51 * |
51 * |
52 * <p> A default {@code CallbackHandler} class implementation |
52 * <p> A default {@code CallbackHandler} class implementation |
53 * may be specified by setting the value of the |
53 * may be specified by setting the value of the |
54 * {@code auth.login.defaultCallbackHandler} security property. |
54 * {@code auth.login.defaultCallbackHandler} security property. |
55 * |
55 * |
56 * <p> If the security property is set to the fully qualified name of a |
56 * <p> If the security property is set to the fully qualified name of a |
57 * <code>CallbackHandler</code> implementation class, |
57 * {@code CallbackHandler} implementation class, |
58 * then a <code>LoginContext</code> will load the specified |
58 * then a {@code LoginContext} will load the specified |
59 * <code>CallbackHandler</code> and pass it to the underlying LoginModules. |
59 * {@code CallbackHandler} and pass it to the underlying LoginModules. |
60 * The <code>LoginContext</code> only loads the default handler |
60 * The {@code LoginContext} only loads the default handler |
61 * if it was not provided one. |
61 * if it was not provided one. |
62 * |
62 * |
63 * <p> All default handler implementations must provide a public |
63 * <p> All default handler implementations must provide a public |
64 * zero-argument constructor. |
64 * zero-argument constructor. |
65 * |
65 * |
69 |
69 |
70 /** |
70 /** |
71 * <p> Retrieve or display the information requested in the |
71 * <p> Retrieve or display the information requested in the |
72 * provided Callbacks. |
72 * provided Callbacks. |
73 * |
73 * |
74 * <p> The <code>handle</code> method implementation checks the |
74 * <p> The {@code handle} method implementation checks the |
75 * instance(s) of the <code>Callback</code> object(s) passed in |
75 * instance(s) of the {@code Callback} object(s) passed in |
76 * to retrieve or display the requested information. |
76 * to retrieve or display the requested information. |
77 * The following example is provided to help demonstrate what an |
77 * The following example is provided to help demonstrate what an |
78 * <code>handle</code> method implementation might look like. |
78 * {@code handle} method implementation might look like. |
79 * This example code is for guidance only. Many details, |
79 * This example code is for guidance only. Many details, |
80 * including proper error handling, are left out for simplicity. |
80 * including proper error handling, are left out for simplicity. |
81 * |
81 * |
82 * <pre>{@code |
82 * <pre>{@code |
83 * public void handle(Callback[] callbacks) |
83 * public void handle(Callback[] callbacks) |
133 * private char[] readPassword(InputStream in) throws IOException { |
133 * private char[] readPassword(InputStream in) throws IOException { |
134 * // insert code to read a user password from the input stream |
134 * // insert code to read a user password from the input stream |
135 * } |
135 * } |
136 * }</pre> |
136 * }</pre> |
137 * |
137 * |
138 * @param callbacks an array of <code>Callback</code> objects provided |
138 * @param callbacks an array of {@code Callback} objects provided |
139 * by an underlying security service which contains |
139 * by an underlying security service which contains |
140 * the information requested to be retrieved or displayed. |
140 * the information requested to be retrieved or displayed. |
141 * |
141 * |
142 * @exception java.io.IOException if an input or output error occurs. <p> |
142 * @exception java.io.IOException if an input or output error occurs. <p> |
143 * |
143 * |
144 * @exception UnsupportedCallbackException if the implementation of this |
144 * @exception UnsupportedCallbackException if the implementation of this |
145 * method does not support one or more of the Callbacks |
145 * method does not support one or more of the Callbacks |
146 * specified in the <code>callbacks</code> parameter. |
146 * specified in the {@code callbacks} parameter. |
147 */ |
147 */ |
148 void handle(Callback[] callbacks) |
148 void handle(Callback[] callbacks) |
149 throws java.io.IOException, UnsupportedCallbackException; |
149 throws java.io.IOException, UnsupportedCallbackException; |
150 } |
150 } |