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