/*
* Copyright (c) 1999, 2005, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package javax.security.auth.callback;
/**
* <p> An application implements a <code>CallbackHandler</code> and passes
* it to underlying security services so that they may interact with
* the application to retrieve specific authentication data,
* such as usernames and passwords, or to display certain information,
* such as error and warning messages.
*
* <p> CallbackHandlers are implemented in an application-dependent fashion.
* For example, implementations for an application with a graphical user
* interface (GUI) may pop up windows to prompt for requested information
* or to display error messages. An implementation may also choose to obtain
* requested information from an alternate source without asking the end user.
*
* <p> Underlying security services make requests for different types
* of information by passing individual Callbacks to the
* <code>CallbackHandler</code>. The <code>CallbackHandler</code>
* implementation decides how to retrieve and display information
* depending on the Callbacks passed to it. For example,
* if the underlying service needs a username and password to
* authenticate a user, it uses a <code>NameCallback</code> and
* <code>PasswordCallback</code>. The <code>CallbackHandler</code>
* can then choose to prompt for a username and password serially,
* or to prompt for both in a single window.
*
* <p> A default <code>CallbackHandler</code> class implementation
* may be specified in the <i>auth.login.defaultCallbackHandler</i>
* security property. The security property can be set
* in the Java security properties file located in the file named
* <JAVA_HOME>/lib/security/java.security.
* <JAVA_HOME> refers to the value of the java.home system property,
* and specifies the directory where the JRE is installed.
*
* <p> If the security property is set to the fully qualified name of a
* <code>CallbackHandler</code> implementation class,
* then a <code>LoginContext</code> will load the specified
* <code>CallbackHandler</code> and pass it to the underlying LoginModules.
* The <code>LoginContext</code> only loads the default handler
* if it was not provided one.
*
* <p> All default handler implementations must provide a public
* zero-argument constructor.
*
*/
public interface CallbackHandler {
/**
* <p> Retrieve or display the information requested in the
* provided Callbacks.
*
* <p> The <code>handle</code> method implementation checks the
* instance(s) of the <code>Callback</code> object(s) passed in
* to retrieve or display the requested information.
* The following example is provided to help demonstrate what an
* <code>handle</code> method implementation might look like.
* This example code is for guidance only. Many details,
* including proper error handling, are left out for simplicity.
*
* <pre>
* public void handle(Callback[] callbacks)
* throws IOException, UnsupportedCallbackException {
*
* for (int i = 0; i < callbacks.length; i++) {
* if (callbacks[i] instanceof TextOutputCallback) {
*
* // display the message according to the specified type
* TextOutputCallback toc = (TextOutputCallback)callbacks[i];
* switch (toc.getMessageType()) {
* case TextOutputCallback.INFORMATION:
* System.out.println(toc.getMessage());
* break;
* case TextOutputCallback.ERROR:
* System.out.println("ERROR: " + toc.getMessage());
* break;
* case TextOutputCallback.WARNING:
* System.out.println("WARNING: " + toc.getMessage());
* break;
* default:
* throw new IOException("Unsupported message type: " +
* toc.getMessageType());
* }
*
* } else if (callbacks[i] instanceof NameCallback) {
*
* // prompt the user for a username
* NameCallback nc = (NameCallback)callbacks[i];
*
* // ignore the provided defaultName
* System.err.print(nc.getPrompt());
* System.err.flush();
* nc.setName((new BufferedReader
* (new InputStreamReader(System.in))).readLine());
*
* } else if (callbacks[i] instanceof PasswordCallback) {
*
* // prompt the user for sensitive information
* PasswordCallback pc = (PasswordCallback)callbacks[i];
* System.err.print(pc.getPrompt());
* System.err.flush();
* pc.setPassword(readPassword(System.in));
*
* } else {
* throw new UnsupportedCallbackException
* (callbacks[i], "Unrecognized Callback");
* }
* }
* }
*
* // Reads user password from given input stream.
* private char[] readPassword(InputStream in) throws IOException {
* // insert code to read a user password from the input stream
* }
* </pre>
*
* @param callbacks an array of <code>Callback</code> objects provided
* by an underlying security service which contains
* the information requested to be retrieved or displayed.
*
* @exception java.io.IOException if an input or output error occurs. <p>
*
* @exception UnsupportedCallbackException if the implementation of this
* method does not support one or more of the Callbacks
* specified in the <code>callbacks</code> parameter.
*/
void handle(Callback[] callbacks)
throws java.io.IOException, UnsupportedCallbackException;
}