AuthConfigProvider


1   /*
2     * JBoss, Home of Professional Open Source
3     * Copyright 2005, JBoss Inc., and individual contributors as indicated
4     * by the @authors tag. See the copyright.txt in the distribution for a
5     * full listing of individual contributors.
6     *
7     * This is free software; you can redistribute it and/or modify it
8     * under the terms of the GNU Lesser General Public License as
9     * published by the Free Software Foundation; either version 2.1 of
10    * the License, or (at your option) any later version.
11    *
12    * This software is distributed in the hope that it will be useful,
13    * but WITHOUT ANY WARRANTY; without even the implied warranty of
14    * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15    * Lesser General Public License for more details.
16    *
17    * You should have received a copy of the GNU Lesser General Public
18    * License along with this software; if not, write to the Free
19    * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
20    * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
21    */
22  package javax.security.auth.message.config;
23  
24  import javax.security.auth.callback.CallbackHandler  ;
25  import javax.security.auth.message.AuthException;
26  
27  //$Id: AuthConfigProvider.java 45179 2006-05-23 20:18:57Z asaldhana $
28  
29  /**
30   *  <p>This interface is implemented by objects that can be used to obtain authentication 
31   *  context configuration objects i.e., ClientAuthConfig or ServerAuthConfig objects.
32   *  Authentication context configuration objects serve as sources of the authentication 
33   *  context objects, i.e, ClientAuthContext or ServerAuthContext objects, for a 
34   *  specific message layer and messaging context.</p>
35   *  <p>Authentication context objects encapsulate the initialization, configuration, 
36   *  and invocation of authentication modules, i.e., ClientAuthModule or ServerAuthModule
37   *  objects, for a specific message exchange within a specific message layer and 
38   *  messaging context.</p>
39   *  <p>Callers do not directly operate on authentication modules. Instead, they rely on 
40   *  a ClientAuthContext or ServerAuthContext to manage the invocation of modules. A 
41   *  caller obtains an instance of ClientAuthContext or ServerAuthContext by calling the 
42   *  respective getAuthContext method on a ClientAuthConfig or ServerAuthConfig object 
43   *  obtained from an AuthConfigProvider.</p>
44   *  <p> The following represents a typical sequence of calls for obtaining a client 
45   *  authentication context object, and then using it to secure a request.</p>
46   *  <ol>
47   *  <li>AuthConfigProvider provider;</li>
48   *  <li>ClientAuthConfig config = provider.getClientAuthConfig(layer,appID,cbh);</li>
49   *  <li>String operation = config.getOperation(authParam);</li>
50   *  <li>ClientAuthContext context = config.getAuthContext(operation,properties);</li>
51   *  <li>context.secureRequest(authParam,subject,...);</li>
52   *  </ol>
53   *  <p>Every implementation of this interface must offer a public, single argument 
54   *  constructor with the following signature:</p>
55   *  <pre> public AuthConfigProviderImpl(Map properties);</pre>
56   *  <p>where the properties argument may be null, and where all values and keys occuring
57   *  in a non-null properties argument must be of type String.</p>
58   *  <p>An AuthConfigFactory may be used to obtain the ConfigProvider for a specific 
59   *  message layer and application context identifier.</p>
60   *  @author <a HREF="mailto:Anil.Saldhana@jboss.org">Anil Saldhana</a>
61   *  @author Charlie Lai, Ron Monzillo (Javadoc for JSR-196)</a> 
62   *  @since  May 12, 2006 
63   *  @version $Revision: 45179 $
64   */
65  public interface AuthConfigProvider
66  {
67     /**
68      * Get an instance of ClientAuthConfig from this provider.
69      * The implementation of this method returns a ClientAuthConfig instance that 
70      * describes the configuration of ClientAuthModules at a given message layer, and 
71      * for use in an identified application context.
72      * 
73      * @param layer a String identifying the message layer for the returned 
74      *              ClientAuthConfig object.
75      * @param appContext a String that identifies the messaging context for the 
76      *              returned ClientAuthConfig object.
77      * @param handler a CallbackHandler to be passed to the ClientAuthModules 
78      *               encapsulated by ClientAuthContext objects derived from the 
79      *               returned ClientAuthConfig. This parameter may be null, in which 
80      *               case the implementation may assign a default handler to the 
81      *               configuration. The �authconfigprovider.client.callbackhandler� 
82      *               security property is used to define the fully qualified name of 
83      *               the default CallbackHandler implementation class.
84      * @return a ClientAuthConfig Object that describes the configuration of 
85      *               ClientAuthModules at the message layer and messaging context 
86      *               identified by the layer and appContext arguments. This method does 
87      *               not return null.
88      * @throws AuthException if this factory does not support the assignment of a 
89      *               default CallbackHandler to the returned ClientAuthConfig.
90      * @throws SecurityException if the caller does not have permission to retrieve 
91      *               the configuration.
92      */
93     ClientAuthConfig getClientAuthConfig( String   layer, String   appContext, 
94           CallbackHandler   handler) throws AuthException, SecurityException  ;
95     
96     /**
97      * Get an instance of ServerAuthConfig from this provider.
98      * The implementation of this method returns a ServerAuthConfig instance that 
99      * describes the configuration of ServerAuthModules at a given message layer, and 
100     * for use in an identified application context.
101     * 
102     * @param layer a String identifying the message layer for the returned 
103     *              ServerAuthConfig object.
104     * @param appContext a String that identifies the messaging context for the 
105     *              returned ServerAuthConfig object.
106     * @param handler a CallbackHandler to be passed to the ServerAuthModules 
107     *               encapsulated by ServerAuthContext objects derived from the 
108     *               returned ServerAuthConfig. This parameter may be null, in which 
109     *               case the implementation may assign a default handler to the 
110     *               configuration. The �authconfigprovider.client.callbackhandler� 
111     *               security property is used to define the fully qualified name of 
112     *               the default CallbackHandler implementation class.
113     * @return a ServerAuthConfig Object that describes the configuration of 
114     *               ServerAuthModules at the message layer and messaging context 
115     *               identified by the layer and appContext arguments. This method does 
116     *               not return null.
117     * @throws AuthException if this factory does not support the assignment of a 
118     *               default CallbackHandler to the returned ServerAuthConfig.
119     * @throws SecurityException if the caller does not have permission to retrieve 
120     *               the configuration.
121     */
122    ServerAuthConfig getServerAuthConfig( String   layer, String   appContext,
123          CallbackHandler   handler) throws AuthException, SecurityException  ;
124    
125    /**
126     * Causes a dynamic configuration provider to update its internal state such that 
127     * any resulting change to its state is recognized by authentication context 
128     * configuration objects previously created by the provider within the current 
129     * process context.
130     * <p> The effect on the authentication context configuration objects should be 
131     * extended to the authentication context objects obtained from the configuration 
132     * objects, such that the context objects recognize changes in the state of the 
133     * configuration object from which they were obtained.</p>
134     * @throws AuthException if an error occured during the refresh.
135     * @throws SecurityException if the caller does not have permission to 
136     *                    refresh the provider.
137     */
138    void refresh() throws AuthException, SecurityException  ;
139 }
140
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags