gomp-20050608-branch/libjava/classpath/javax/security/auth/spi/LoginModule.java

   1 /* LoginModule.java -- interface for login implementations.
   2    Copyright (C) 2004  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package javax.security.auth.spi;
  40
  41 import java.util.Map;
  42
  43 import javax.security.auth.Subject;
  44 import javax.security.auth.callback.CallbackHandler;
  45 import javax.security.auth.login.LoginException;
  46
  47 /**
  48  * The base interface for login methods in the Java Authentication and
  49  * Authorization Service (JAAS).
  50  *
  51  * <p>This interface is used by service providers that implement login
  52  * services, and is used internally by the JAAS system. It is not useful
  53  * to application programmers, who should use the {@link
  54  * javax.security.auth.login.LoginContext} instead.
  55  *
  56  * @author Casey Marshall (csm@gnu.org)
  57  */
  58 public interface LoginModule
  59 {
  60   /**
  61    * Abort the current login attempt. This is called after {@link #login()}
  62    * if the overall login attempt fails (that is, if one of the other login
  63    * modules that is REQUIRED or REQUISITE fails). This method should clean
  64    * up this module's saved state, if any.
  65    *
  66    * @return True if the abort succeeded, or false if this module should
  67    * be ignored.
  68    * @throws LoginException If the abort fails.
  69    */
  70   boolean abort() throws LoginException;
  71
  72   /**
  73    * Commit the current login attempt. This is called after {@link
  74    * #login()} if the overall login attempt succeeds (that is, all
  75    * methods have satisfied all REQUIRED, REQUISITE, SUFFICIENT and
  76    * OPTIONAL module requirements).
  77    *
  78    * @return True if the commit succeeded, or false if this module
  79    * should be ignored.
  80    * @throws LoginException If the commit fails.
  81    */
  82   boolean commit() throws LoginException;
  83
  84   /**
  85    * Initializes this login module. This method is called when the
  86    * instance implementing this interface is instantiated, and should
  87    * perform any initialization based on the given parameters.
  88    * Implementations should ignore state variables and options they do
  89    * not recognize.
  90    *
  91    * @param subject The subject being authenticated.
  92    * @param handler The callback handler for user input.
  93    * @param sharedState A mapping that is shared between all login
  94    * modules.
  95    * @param options A mapping of options given to this module.
  96    */
  97   void initialize(Subject subject, CallbackHandler handler,
  98                   Map sharedState, Map options);
  99
 100   /**
 101    * Authenticates a subject to the system. This is the primary
 102    * mechanism by which subjects are authenticated, and typically
 103    * implementations will ask for credentials (for example, a user
 104    * name and password) which will then be verified.
 105    *
 106    * @return True if the subject was authenticated, or false if this
 107    * module should be ignored.
 108    * @throws LoginException If this method fails.
 109    */
 110   boolean login() throws LoginException;
 111
 112   /**
 113    * Logs a subject out. This is primarily used for modules that must
 114    * destroy or remove the authentication state associated with a
 115    * logged-in subject.
 116    *
 117    * @return True if the logout succeeds, or false if this module
 118    * should be ignored.
 119    * @throws LoginException If this method fails.
 120    */
 121   boolean logout() throws LoginException;
 122 }