History

My first initial commit with all of mine experimental changes.

Dmitry Kabak (userdima committed 13 years ago

Commit d37b88d1 parent 3f5b46618352 files · +2598093 −-8690Browse files

Showing the changes to java/pkg/javax/security/auth/callback/CallbackHandler.java (1 of 18352 files). Show all

Unified · Split

java/pkg/javax/security/auth/callback/CallbackHandler.java+153−0
@@ -0,0 +1,153 @@
1+/*
2+ * Copyright (c) 1999, 2005, 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> An application implements a <code>CallbackHandler</code> and passes
30+ * it to underlying security services so that they may interact with
31+ * the application to retrieve specific authentication data,
32+ * such as usernames and passwords, or to display certain information,
33+ * such as error and warning messages.
34+ *
35+ * <p> CallbackHandlers are implemented in an application-dependent fashion.
36+ * For example, implementations for an application with a graphical user
37+ * interface (GUI) may pop up windows to prompt for requested information
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.
40+ *
41+ * <p> Underlying security services make requests for different types
42+ * of information by passing individual Callbacks to the
43+ * <code>CallbackHandler</code>. The <code>CallbackHandler</code>
44+ * implementation decides how to retrieve and display information
45+ * depending on the Callbacks passed to it. For example,
46+ * if the underlying service needs a username and password to
47+ * authenticate a user, it uses a <code>NameCallback</code> and
48+ * <code>PasswordCallback</code>. The <code>CallbackHandler</code>
49+ * can then choose to prompt for a username and password serially,
50+ * or to prompt for both in a single window.
51+ *
52+ * <p> A default <code>CallbackHandler</code> class implementation
53+ * may be specified in the <i>auth.login.defaultCallbackHandler</i>
54+ * security property. The security property can be set
55+ * in the Java security properties file located in the file named
56+ * &lt;JAVA_HOME&gt;/lib/security/java.security.
57+ * &lt;JAVA_HOME&gt; refers to the value of the java.home system property,
58+ * and specifies the directory where the JRE is installed.
59+ *
60+ * <p> If the security property is set to the fully qualified name of a
61+ * <code>CallbackHandler</code> implementation class,
62+ * then a <code>LoginContext</code> will load the specified
63+ * <code>CallbackHandler</code> and pass it to the underlying LoginModules.
64+ * The <code>LoginContext</code> only loads the default handler
65+ * if it was not provided one.
66+ *
67+ * <p> All default handler implementations must provide a public
68+ * zero-argument constructor.
69+ *
70+ */
71+public interface CallbackHandler {
72+
73+ /**
74+ * <p> Retrieve or display the information requested in the
75+ * provided Callbacks.
76+ *
77+ * <p> The <code>handle</code> method implementation checks the
78+ * instance(s) of the <code>Callback</code> object(s) passed in
79+ * to retrieve or display the requested information.
80+ * The following example is provided to help demonstrate what an
81+ * <code>handle</code> method implementation might look like.
82+ * This example code is for guidance only. Many details,
83+ * including proper error handling, are left out for simplicity.
84+ *
85+ * <pre>
86+ * public void handle(Callback[] callbacks)
87+ * throws IOException, UnsupportedCallbackException {
88+ *
89+ * for (int i = 0; i < callbacks.length; i++) {
90+ * if (callbacks[i] instanceof TextOutputCallback) {
91+ *
92+ * // display the message according to the specified type
93+ * TextOutputCallback toc = (TextOutputCallback)callbacks[i];
94+ * switch (toc.getMessageType()) {
95+ * case TextOutputCallback.INFORMATION:
96+ * System.out.println(toc.getMessage());
97+ * break;
98+ * case TextOutputCallback.ERROR:
99+ * System.out.println("ERROR: " + toc.getMessage());
100+ * break;
101+ * case TextOutputCallback.WARNING:
102+ * System.out.println("WARNING: " + toc.getMessage());
103+ * break;
104+ * default:
105+ * throw new IOException("Unsupported message type: " +
106+ * toc.getMessageType());
107+ * }
108+ *
109+ * } else if (callbacks[i] instanceof NameCallback) {
110+ *
111+ * // prompt the user for a username
112+ * NameCallback nc = (NameCallback)callbacks[i];
113+ *
114+ * // ignore the provided defaultName
115+ * System.err.print(nc.getPrompt());
116+ * System.err.flush();
117+ * nc.setName((new BufferedReader
118+ * (new InputStreamReader(System.in))).readLine());
119+ *
120+ * } else if (callbacks[i] instanceof PasswordCallback) {
121+ *
122+ * // prompt the user for sensitive information
123+ * PasswordCallback pc = (PasswordCallback)callbacks[i];
124+ * System.err.print(pc.getPrompt());
125+ * System.err.flush();
126+ * pc.setPassword(readPassword(System.in));
127+ *
128+ * } else {
129+ * throw new UnsupportedCallbackException
130+ * (callbacks[i], "Unrecognized Callback");
131+ * }
132+ * }
133+ * }
134+ *
135+ * // Reads user password from given input stream.
136+ * private char[] readPassword(InputStream in) throws IOException {
137+ * // insert code to read a user password from the input stream
138+ * }
139+ * </pre>
140+ *
141+ * @param callbacks an array of <code>Callback</code> objects provided
142+ * by an underlying security service which contains
143+ * the information requested to be retrieved or displayed.
144+ *
145+ * @exception java.io.IOException if an input or output error occurs. <p>
146+ *
147+ * @exception UnsupportedCallbackException if the implementation of this
148+ * method does not support one or more of the Callbacks
149+ * specified in the <code>callbacks</code> parameter.
150+ */
151+ void handle(Callback[] callbacks)
152+ throws java.io.IOException, UnsupportedCallbackException;
153+}