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 java.util.Map;
   25   
   26   import javax.security.auth.Subject;
   27   import javax.security.auth.message.AuthException;
   28   
   29   //$Id: ClientAuthConfig.java 64016 2007-07-12 21:12:52Z anil.saldhana@jboss.com $
   30   
   31   /**
   32    *  <p>This interface encapsulates the configuration of ClientAuthContext objects 
   33    *  for a message layer and application context (e.g., the messaging context of a 
   34    *  specific application, or set of applications).<p>
   35    *  <p>Implementations of this interface are returned by an AuthConfigProvider.</p>
   36    *  <p>Callers interact with a ClientAuthConfig to obtain ClientAuthContext objects 
   37    *  suitable for processing a given message exchange at the layer and within the 
   38    *  application context of the ClientAuthConfig. Each ClientAuthContext object is 
   39    *  responsible for instantiating, initializing, and invoking the one or more 
   40    *  ClientAuthModules encapsulated in the ClientAuthContext.</p>
   41    *  <p>After having acquired a ClientAuthContext, a caller operates on the context 
   42    *  to cause it to invoke the encapsulated ClientAuthModules to secure client requests 
   43    *  and to validate server responses.</p>
   44    *  
   45    *  @author <a href="mailto:Anil.Saldhana@jboss.org">Anil Saldhana</a>
   46    *  @author Charlie Lai, Ron Monzillo (Javadoc for JSR-196)</a> 
   47    *  @since  May 12, 2006 
   48    *  @version $Revision: 64016 $
   49    */
   50   public interface ClientAuthConfig extends AuthConfig
   51   {
   52      /**
   53       * <p>Get a ClientAuthContext instance from this ClientAuthConfig.</p>
   54       * <p>The implementation of this method returns a ClientAuthContext instance that 
   55       * encapsulates the ClientAuthModules used to secure and validate requests/responses 
   56       * associated with the given operation.</p>
   57       * <p>Specifically, this method accesses this ClientAuthConfig object with the argument
   58       * operation to determine the ClientAuthModules that are to be encapsulated in the 
   59       * returned ClientAuthContext instance.</p>
   60       * <p>The ClientAuthConfig object establishes the request and response MessagePolicy 
   61       * objects that are passed to the encapsulated modules when they are initialized by the 
   62       * returned ClientAuthContext instance. It is the modules? responsibility to enforce 
   63       * these policies when invoked.</p>
   64       * 
   65       * @param operation an operation identifier used to index the provided config, or null. 
   66       *                This value must be identical to the value returned by the getOperation
   67       *                method for all AuthParam objects passed to the secureRequest method 
   68       *                of the returned ClientAuthContext.
   69       * @param properties a Map object that may be used by the caller to augment the 
   70       *                properties that will be passed to the encapsulated modules at module 
   71       *                initialization. The null value may be passed for this parameter.
   72       * @return a ClientAuthContext instance that encapsulates the ClientAuthModules used to 
   73       *               secure and validate requests/responses associated with the given 
   74       *               operation, or null (indicating that no modules are configured).
   75       * @throws AuthException if this operation fails.
   76       */
   77      public ClientAuthContext getAuthContext(String authContextID,
   78            Subject clientSubject, Map properties)
   79            throws AuthException;
   80   }