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.message.ClientAuth;
   25   
   26   //$Id: ClientAuthContext.java 45179 2006-05-23 20:18:57Z asaldhana $
   27   
   28   /**
   29    * <p>This ClientAuthContext class encapsulates ClientAuthModules that are used to 
   30    * secure service requests made by a client, and to validate any responses received 
   31    * to those requests. A caller typically uses this class in the following manner:<p>
   32    * <ol>
   33    * <li>Retrieve an instance of this class via ClientAuthConfig.getAuthContext.</li>
   34    * <li>Invoke secureRequest.</li>
   35    * <p> ClientAuthContext implementation invokes secureRequest of encapsulated 
   36    * ClientAuthModule(s). Module(s) attach credentials to initial request object 
   37    * (for example, a username and password), and/or secure the request (for example, 
   38    * sign and encrypt the request).</p>
   39    * <li>Send request and receive response.</li>
   40    * <li>Invoke validateResponse.</li>
   41    * <p>ClientAuthContext implementation invokes validateResponse of encapsulated 
   42    * ClientAuthModule(s). Module(s) verify or decrypt response as necessary.</p>
   43    * <li>Invoke cleanSubject method (as necessary) to clean up any authentication 
   44    * state in Subject.</li>
   45    * </ol>
   46    * <p>A ClientAuthContext instance may be used concurrently by multiple callers.</p>
   47    * <p>Implementations of this interface are responsible for constructing and 
   48    * initializing the encapsulated modules. The initialization step includes passing 
   49    * the relevant request and response MessagePolicy objects to the encapsulated modules. 
   50    * The MessagePolicy objects are obtained by the ClientAuthConfig instance used to obtain 
   51    * the ClientAuthContext object. See ClientAuthConfig.getAuthContext for more information.</p>
   52    * <p>Implementations of this interface are instantiated by their associated configuration 
   53    * object such that they know which modules to invoke, in what order, and how results 
   54    * returned by preceding modules are to influence subsequent module invocations.</p>
   55    * <p>Calls to the inherited methods of this interface pass a Map that maybe used by the 
   56    * underlying modules to save and communicate state across a sequence of calls from 
   57    * secureRequest to validateResponse to cleanSubject. The same Map instance must be passed 
   58    * to all methods in a call sequence, and a different Map should be passed to each 
   59    * call sequence.</p>
   60    * 
   61    *  @author <a href="mailto:Anil.Saldhana@jboss.org">Anil Saldhana</a>
   62    *  @author Charlie Lai, Ron Monzillo (Javadoc for JSR-196)</a> 
   63    *  @since  May 12, 2006 
   64    *  @version $Revision: 45179 $
   65    */
   66   public interface ClientAuthContext extends ClientAuth
   67   { 
   68   }