Glassfish example source code file (AuthConfigFactory.java)

This example Glassfish source code file (AuthConfigFactory.java) is included in the DevDaily.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Java - Glassfish tags/keywords

authconfigfactory, authconfigfactory, authconfigprovider, classloader, default_factory_security_property, default_factory_security_property, illegalaccessexception, instantiationexception, registrationcontext, security, securityexception, securitypermission, securitypermission, string, string, util

The Glassfish AuthConfigFactory.java source code

/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright (c) 1997-2010 Oracle and/or its affiliates. All rights reserved.
 *
 * The contents of this file are subject to the terms of either the GNU
 * General Public License Version 2 only ("GPL") or the Common Development
 * and Distribution License("CDDL") (collectively, the "License").  You
 * may not use this file except in compliance with the License.  You can
 * obtain a copy of the License at
 * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
 * or packager/legal/LICENSE.txt.  See the License for the specific
 * language governing permissions and limitations under the License.
 *
 * When distributing the software, include this License Header Notice in each
 * file and include the License file at packager/legal/LICENSE.txt.
 *
 * GPL Classpath Exception:
 * Oracle designates this particular file as subject to the "Classpath"
 * exception as provided by Oracle in the GPL Version 2 section of the License
 * file that accompanied this code.
 *
 * Modifications:
 * If applicable, add the following below the License Header, with the fields
 * enclosed by brackets [] replaced by your own identifying information:
 * "Portions Copyright [year] [name of copyright owner]"
 *
 * Contributor(s):
 * If you wish your version of this file to be governed by only the CDDL or
 * only the GPL Version 2, indicate your decision by adding "[Contributor]
 * elects to include this software in this distribution under the [CDDL or GPL
 * Version 2] license."  If you don't indicate a single choice of license, a
 * recipient has the option to distribute your version of this file under
 * either the CDDL, the GPL Version 2 or to extend the choice of license to
 * its licensees as provided above.  However, if you add GPL Version 2 code
 * and therefore, elected the GPL Version 2 license, then the option applies
 * only if the new code is made subject to such option by the copyright
 * holder.
 */

package javax.security.auth.message.config;

import java.security.Permission;
import java.security.Security;
import java.security.SecurityPermission;

import java.util.Map;
// for @see
import java.util.Properties;

import javax.security.auth.message.*;

/**
 * This class is used to obtain <code>AuthConfigProvider objects 
 * that can be used to obtain authentication context configuration objects,
 * that is, <code>ClientAuthConfig and ServerAuthConfig
 * objects.
 * <p>Authentication context configuration objects are used to obtain
 * authentication context objects. Authentication context objects,
 * that is, <code>ClientAuthContext and ServerAuthContex
 * objects, encapsulate authentication modules. Authentication modules are 
 * pluggable components that perform security-related processing of
 * request and response messages.
 *
 * <p> Callers do not operate on modules directly.
 * Instead they rely on an authentication context to manage the 
 * invocation of modules.  A caller obtains an authentication context
 * by calling the <code>getAuthContext method on a 
 * <code>ClientAuthConfig or ServerAuthConfig 
 * obtained from an AuthConfigProvider.
 *
 * <p> The following represents a typical sequence of calls for obtaining
 * a client authentication context, and then using it to secure 
 * a request.
 * <ol>
 * <li>AuthConfigFactory factory = AuthConfigFactory.getFactory();
 * <li>AuthConfigProvider provider = factory.getConfigProvider(layer,appID,listener);
 * <li>ClientAuthConfig config = provider.getClientAuthConfig(layer,appID,cbh)
 * <li>String authContextID = config.getAuthContextID(messageInfo);
 * <li>ClientAuthContext context = config.getAuthContext(authContextID,subject,properties);
 * <li>context.secureRequest(messageInfo,subject);
 * </ol>
 *
 * <p> A system-wide AuthConfigFactory implementation can be set by invoking
 * <code>setFactory, and retrieved using getFactory.
 *
 * <p> Every implementation of this abstract class must offer a public,
 * zero argument constructor. This constructor must support the construction
 * and registration (including self-registration) of AuthConfigProviders 
 * from a persistent declarative representation.
 * For example, a factory implementation class could interpret the contents
 * of a file containing a sequence of configuration entries, with one entry per
 * AuthConfigProvider, and with each entry representing:
 * <ul>
 * <li> The fully qualified name of the provider implementation class (or null)
 * <li> The list of provider initialization properties (which could be empty)
 * </ul>
 * Any provider initialization properties must be specified in a 
 * form that can be passed to the provider constructor within a Map of key, 
 * value pairs, and where all keys and values within the Map are of type 
 * String.
 * <p>
 * The entry syntax must also provide for the optional inclusion of information
 * sufficient to define a RegistrationContext. This information would only 
 * be present when the factory will register the provider. 
 * For example, each entry could provide for the inclusion of one or more
 * RegistrationContext objects of the following form: 
 * <ul>
 * <li> The message layer name (or null)
 * <li> The application context identifier (or null)
 * <li> The registration description (or null)
 * </ul>
 * When a RegistrationContext is not included, the factory must make it 
 * convenient for the provider to self-register with the factory during 
 * the provider construction (see 
 * <code>registerConfigProvider(AuthConfigProvider provider, ...)).
 * <P> An AuthConfigFactory implementation is free to choose is own 
 * persistent declarative syntax as long as it conforms to the requirements 
 * defined by this class.
 *
 * @version %I%, %G%
 *
 * @see ClientAuthContext
 * @see ServerAuthContext
 * @see ClientAuthConfig
 * @see ServerAuthConfig
 * @see Properties
 */
public abstract class AuthConfigFactory {

    private static AuthConfigFactory factory = null;

    /**
     * The name of the Security property used to define the
     * default AuthConfigFactory implementation class.
     */
    public static final String DEFAULT_FACTORY_SECURITY_PROPERTY = 
    "authconfigprovider.factory";

    // XXX verify that key need not include java.security.
 
    private static SecurityPermission getPerm = 
	new SecurityPermission
    ("getProperty."+DEFAULT_FACTORY_SECURITY_PROPERTY);

    private static SecurityPermission setPerm = 
	new SecurityPermission
    ("setProperty."+DEFAULT_FACTORY_SECURITY_PROPERTY);

    /**
     * utility method to check for permission to operate on the factory.
     *
     * @exception SecurityException if the caller does not have
     *		permission to operate on the factory.
     */
    private static void checkPermission(Permission p) 
	throws SecurityException {
	SecurityManager sm = System.getSecurityManager();
	if (sm != null) {
	    sm.checkPermission(p);
	}
    }

    /**
     * Get the system-wide AuthConfigFactory implementation.
     *
     * <p> If a non-null system-wide factory instance is defined at the time 
     * of the call,
     * for example, with <code>setFactory, it will be returned. Otherwise, an
     * attempt will be made to construct an instance of the default
     * AuthConfigFactory implementation class. The fully qualified class name
     * of the default factory implementation class is obtained from the
     * value of the authconfigprovider.factory security property. When an
     * instance of the default factory implementation class is successfully
     * constructed by this method, this method will set it as the system-wide 
     * factory instance.
     * 
     * <p> The absolute pathname of the Java security properties file is
     * JAVA_HOME/lib/security/java.security, where JAVA_HOME
     * refers to the directory where the JDK was installed.
     *
     * @return The non-null system-wide AuthConfigFactory instance set at the 
     *          time of the call, or if that value was null, the value of the
     *          system-wide factory instance established by this method. 
     *          This method returns null when the system-wide factory was not 
     *          defined when this method was called and no default factory name
     *          was defined via the security property. 
     *
     * @exception AuthException If an error occurred during the class loading, 
     *          or construction of the default AuthConfigFactory
     *          implementation class.
     *
     * @exception SecurityException If the caller does not have permission
     *		to retrieve the factory, or set it as the system-wide 
     *          instance.
     *
     */
    public static synchronized AuthConfigFactory getFactory() {
	checkPermission(getPerm);
	if (AuthConfigFactory.factory == null) {
	    final String className = Security.getProperty
		(DEFAULT_FACTORY_SECURITY_PROPERTY);
	    if (className != null) {
		checkPermission(setPerm);
		try {
		    AuthConfigFactory.factory = (AuthConfigFactory)
			java.security.AccessController.doPrivileged
			(new java.security.PrivilegedExceptionAction() {
				public Object run() 
				    throws ClassNotFoundException,
					   InstantiationException,
				           IllegalAccessException {
				    ClassLoader loader =
					Thread.currentThread().
					getContextClassLoader();
				    
				    Class clazz = Class.forName
					(className,true,loader);

				    return clazz.newInstance();
				}
			    });
		} catch (java.security.PrivilegedActionException pae) {
		    throw (SecurityException)
			new SecurityException().initCause(pae.getException());
		} 
	    }
	} 
	return AuthConfigFactory.factory;
    }

    /**
     * Set the system-wide AuthConfigFactory implementation.
     *
     * <p> If an implementation was set previously, it will be replaced.
     * <p> Listeners are not notified of a change to the registered factory.
     *
     * @param factory The AuthConfigFactory instance, which may be null. 
     *
     * @exception SecurityException If the caller does not have
     *		permission to set the factory.
     */
    public static synchronized void setFactory(AuthConfigFactory factory) {
	checkPermission(setPerm);
	AuthConfigFactory.factory = factory;
    }

    /**
     * Get a registered AuthConfigProvider from the factory.
     *
     * Get the provider of ServerAuthConfig and
     * ClientAuthConfig objects registered for the identified message 
     * layer and application context.
     *
     * <p>All factories shall employ the following precedence rules to select
     * the registered AuthConfigProvider that matches the layer and appContext 
     * arguments:
     *<ul>
     * <li> The provider specifically registered for the values 
     * passed as the layer and appContext arguments 
     * shall be selected.
     * <li> If no provider is selected according to the preceding rule,
     * the provider specifically registered for the value passed as the 
     * appContext argument and for all (that is, null) layers
     * shall be selected.
     * <li> If no provider is selected according to the preceding rules,
     * the provider specifically registered for the value passed as the
     * layer argument and for all (that is, null) appContexts
     * shall be selected.
     * <li> If no provider is selected according to the preceding rules,
     * the provider registered for all (that is, null) layers 
     * and for all (that is, null) appContexts shall be selected.
     * <li> If no provider is selected according to the preceding rules,
     * the factory shall terminate its search for a registered provider.
     *</ul>
     * <p>
     * The above precedence rules apply equivalently to registrations created
     * with a null or non-null <code>className argument.
     *
     * @param layer A String identifying the message layer
     *		for which the registered AuthConfigProvider is
     *          to be returned. The value of this argument may be null.
     *
     * @param appContext A String that identifies the application messaging 
     *          context for which the registered AuthConfigProvider
     *          is to be returned. The value of this argument may be null.
     *
     * @param listener The RegistrationListener whose 
     *          <code>notify method is to be invoked 
     *          if the corresponding registration is unregistered or 
     *          replaced. The value of this argument may be null.
     *
     * @return The implementation of the AuthConfigProvider interface 
     *          registered at the factory for the layer and appContext,
     *          or null if no AuthConfigProvider is selected. An argument
     *          listener is attached even if the return value is null.
     */
    public abstract AuthConfigProvider 
    getConfigProvider(String layer, String appContext,
		      RegistrationListener listener);

    /**
     * Registers within the factory and records within the factory's  
     * persistent declarative representation of provider registrations
     * a provider of ServerAuthConfig and/or ClientAuthConfig objects for a
     * message layer and application context identifier.
     * 
     * This method typically constructs an instance of the provider
     * before registering it with the factory. Factories may extend or modify 
     * the persisted registrations of existing provider instances, if 
     * those instances were registered with ClassName and 
     * properties arguments equivalent to those passed in the current call. 
     * <P>
     * This method employs the two argument constructor required to
     * be supported by every implementation of the AuthConfigProvider 
     * interface, and this method must pass a null value for the factory 
     * argument of the constructor.
     * <code>AuthConfigProviderImpl AuthConfigProviderImpl(Map properties, 
     * AuthConfigFactory factory)</code>. 
     *
     * <P>At most one registration may exist within the factory for a 
     * given combination of message layer 
     * and appContext. Any pre-existing
     * registration with identical values for layer and appContext is replaced 
     * by a subsequent registration. When replacement occurs, the registration
     * identifier, layer, and appContext identifier remain unchanged,
     * and the AuthConfigProvider (with initialization properties) and 
     * description are replaced. 
     *
     *<p>Within the lifetime of its Java process, a factory must assign unique
     * registration identifiers to registrations, and must never 
     * assign a previously used registration identifier to a registration 
     * whose message layer and or appContext identifier differ from 
     * the previous use.
     * 
     * <p>Programmatic registrations performed by using this method must update
     * (according to the replacement rules described above) the persistent 
     * declarative representation of provider registrations employed by the 
     * factory constructor.
     *
     * @param className The fully qualified name of an AuthConfigProvider
     *          implementation class (or null). Calling this method with a 
     *          null value for this parameter shall cause 
     *          <code>getConfigProvider to return null when it is
     *          called with layer and appContext values for which the 
     *          resulting registration is the best match.
     *
     * @param properties A Map object containing the initialization 
     *          properties to be passed to the properties argument of the
     *          provider constructor.
     *          This argument may be null. When this argument is not null, 
     *          all the values and keys occuring in the Map must be of 
     *          type String.
     *
     * @param layer A String identifying the message layer
     *		for which the provider will be registered at the factory.
     *          A null value may be passed as an argument for this parameter,
     *          in which case the provider is registered at all layers.
     *
     * @param appContext A String value that may be used by a runtime
     *          to request a configuration object from this provider.
     *          A null value may be passed as an argument for this parameter,
     *          in which case the provider is registered for all 
     *          configuration ids (at the indicated layers).
     *
     * @param description A text String describing the provider.
     *          This value may be null.
     *
     * @return A String identifier assigned by 
     *          the factory to the provider registration, and that may be 
     *          used to remove the registration from the factory.
     *
     * @exception SecurityException If the caller does not have
     *		permission to register a provider at the factory.
     *
     * @exception AuthException If the provider 
     *          construction (given a non-null <code>className) 
     *          or registration fails.
     */
    public abstract String 
    registerConfigProvider(String className,
			   Map properties,
			   String layer,
			   String appContext,
			   String description);

    /**
     * Registers within the (in-memory) factory, a provider 
     * of ServerAuthConfig and/or ClientAuthConfig objects for a 
     * message layer and application context identifier.
     * This method does NOT effect the factory's persistent 
     * declarative representation of provider registrations, and is intended
     * to be used by providers to perform self-Registration.
     *
     * <P>At most one registration may exist within the factory for a 
     * given combination of message layer 
     * and appContext. Any pre-existing
     * registration with identical values for layer and appContext is replaced 
     * by a subsequent registration. When replacement occurs, the registration
     * identifier, layer, and appContext identifier remain unchanged,
     * and the AuthConfigProvider (with initialization properties) and 
     * description are replaced. 
     *
     *<p>Within the lifetime of its Java process, a factory must assign unique
     * registration identifiers to registrations, and must never 
     * assign a previously used registration identifier to a registration 
     * whose message layer and or appContext identifier differ from 
     * the previous use.
     * 
     * @param provider The AuthConfigProvider to be registered at the factory
     *          (or null). Calling this method with a null value for this 
     *          parameter shall cause <code>getConfigProvider to 
     *          return null when it is called with layer and appContext values 
     *          for which the resulting registration is the best match.
     *
     * @param layer A String identifying the message layer
     *		for which the provider will be registered at the factory.
     *          A null value may be passed as an argument for this parameter,
     *          in which case the provider is registered at all layers.
     *
     * @param appContext A String value that may be used by a runtime
     *          to request a configuration object from this provider.
     *          A null value may be passed as an argument for this parameter,
     *          in which case the provider is registered for all 
     *          configuration ids (at the indicated layers).
     *
     * @param description A text String describing the provider.
     *          This value may be null.
     *
     * @return A String identifier assigned by 
     *          the factory to the provider registration, and that may be 
     *          used to remove the registration from the factory.
     *
     * @exception SecurityException If the caller does not have
     *		permission to register a provider at the factory.
     *
     * @exception AuthException If the provider registration fails.
     */
    public abstract String
    registerConfigProvider(AuthConfigProvider provider,
			   String layer,
			   String appContext,
			   String description);

    /**
     * Remove the identified provider registration from the factory (and from
     * the persistent declarative representation of provider registrations, 
     * if appropriate) and invoke any listeners associated with the removed 
     * registration.
     *
     * @param registrationID A String that identifies a provider registration
     *          at the factory
     *
     * @return True if there was a registration with the specified identifier 
     *          and it was removed. Return false if the registrationID was
     *          invalid.
     *
     * @exception SecurityException If the caller does not have
     *		permission to unregister the provider at the factory.
     *
     */
    public abstract boolean
    removeRegistration(String registrationID);

    /**
     * Disassociate the listener from all the provider
     * registrations whose layer and appContext values are matched
     * by the corresponding arguments to this method.
     * <p>
     * Factories should periodically notify Listeners to effectively
     * detach listeners that are no longer in use.
     *
     * @param listener The RegistrationListener to be detached.
     *
     * @param layer A String identifying the message layer or null.
     *
     * @param appContext A String value identifying the application contex
     *          or null.
     *
     * @return An array of String values where each value identifies a 
     *          provider registration from which the listener was removed.
     *          This method never returns null; it returns an empty array if 
     *          the listener was not removed from any registrations.
     *
     * @exception SecurityException If the caller does not have
     *		permission to detach the listener from the factory.
     *
     */
    public abstract String[]
    detachListener(RegistrationListener listener,
		   String layer, String appContext);

    /**
     * Get the registration identifiers for all registrations of the 
     * provider instance at the factory.
     *
     * @param provider The AuthConfigurationProvider whose registration
     *          identifiers are to be returned. This argument may be
     *          null, in which case it indicates that the IDs of
     *          all active registrations within the factory are to be returned.
     *
     * @return An array of String values where each value identifies a 
     * provider registration at the factory. This method never returns null;
     * it returns an empty array when there are no registrations at the 
     * factory for the identified provider.
     */
    public abstract String[] getRegistrationIDs(AuthConfigProvider provider);

    /**
     * Get the the registration context for the identified registration.
     *
     * @param registrationID A String that identifies a provider registration
     *          at the factory
     *
     * @return A RegistrationContext or null. When a Non-null value is
     * returned, it is a copy of the registration context corresponding to the
     * registration. Null is returned when the registration identifier does
     * not correpond to an active registration
      */
    public abstract RegistrationContext 
    getRegistrationContext(String registrationID);

   /**
     * Cause the factory to reprocess its persisent declarative 
     * representation of provider registrations. 
     *
     * <p> A factory should only replace an existing registration when 
     * a change of provider implementation class or initialization 
     * properties has occurred. 
     *
     * @exception AuthException If an error occured during the 
     *          reinitialization.
     *
     * @exception SecurityException If the caller does not have permission
     *		to refresh the factory.
     */
    public abstract void refresh();

    /**
     * Represents the layer identifier, application context identifier,
     * and description components of an AuthConfigProvider registration at the
     * factory.
     */

    public interface RegistrationContext {

       /**
	* Get the layer name from the registration context
	*
	* @return A String identifying the message layer
	*	  for which the AuthConfigProvider was registered.
	*         The returned value may be null.
	*/

        public String getMessageLayer();
	
       /**
	* Get the application context identifier from the registration context
	*
	* @return A String identifying the application context
	*	  for which the AuthConfigProvider was registered.
	*         The returned value may be null.
	*/
        public String getAppContext();

       /**
	* Get the description from the registration context
	*
	* @return The description String from the registration, or null
	*         if no description string was included in the registration.
	*/
	public String getDescription();


       /**
	* Get the persisted status from the registration context.
	*
	* @return A boolean indicating whether the registration is the result 
	*         of a className based registration, or an instance-based
	*         (for example, self-) registration. Only registrations performed
	*         using the five argument <code>registerConfigProvider
	*         method are persistent.
	*/
	public boolean isPersistent();

    }

}