/* (c) Copyright 2003 Caleigo AB, All rights reserved. 
    * 
    * This library is free software; you can redistribute it and/or
    * modify it under the terms of the GNU Lesser General Public
    * License as published by the Free Software Foundation; either
    * version 2.1 of the License, or (at your option) any later version.
    * 
    * This library is distributed in the hope that it will be useful,
    * but WITHOUT ANY WARRANTY; without even the implied warranty of
   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   * Lesser General Public License for more details.
   * 
   * You should have received a copy of the GNU Lesser General Public
   * License along with this library; if not, write to the Free Software
   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
   *  
   */
  
  package org.caleigo.security;
  
  /*** Service that is used to handle the verification of users. There are three
   * login methods which can be used. 
   *
   * @author  Mattias Hagstrand
   * @version 1.00
   *
   *//*
    *
    * WHEN        WHO               WHY & WHAT
    * -----------------------------------------------------------------------------
    * 2002-10-18  Mattias Hagstrand    Creation
    */
  public interface ILoginService extends org.caleigo.service.IService
  {    
      /*** Registers an <I>ILoginInfoProvider</I> to use to provide login
       * information to the login() method.
       */
      public void setLoginInfoProvider(ILoginInfoProvider provider);
      
      /*** Add a login handler to the loginInfo class. This handler will then
       * be used to authenticate a user when the login(loginInfo) method is
       * called with a parameter of the specific class.
       */
      public void addLoginHandler(Class loginInfoClass, ILoginHandler loginHandler);
  
      /*** Removes a login handler
       */
      public void removeLoginHandler(Class loginInfoClass);
      
      /*** Tries to log in a user without supplying any login information. This
       * method preferably uses descendants of <I>ILoginInfoProvider</I> to
       * figure out the login information for the user. Returns <code>null</code>
       * if the login was canceled.
       */
      public UserInfo login();
      /*** This method takes login information supplied in the <I>loginInfo</I> 
       * object. There should be a corresponding <I>ILoginHandler</I> that 
       * is registered to handle the specific <I>loginInfo</I> class. Returns <code>null</code>
       * if the login was canceled.
       */
      public UserInfo login(Object loginInfo);
      /*** This is a helper method that logs in a user based on the supplied 
       * username-password pair. Returns <code>null</code>
       * if the login was canceled.
       */
      public UserInfo login(String username, String password);
      
      public boolean logout(UserInfo userInfo);
      
      /*** Updates an UserInfo object that represents an allready logged in user with
       * relevante user information.
       */
      public void updateUserInfo(UserInfo userInfo);
      
      public void handleError(String message);
      
      /*** Returns the maximum number of times a user is allowed to try to login
       * before the application exits.
       */
      public int getMaximumNumberOfLoginTries();
  
      // Nested classes ----------------------------------------------------------
      public static class UserLoginInfo
      {
          // Data members --------------------------------------------------------
          private String username;
          private String password;
          
          public UserLoginInfo(String username, String password)
          {
              this.username = username;
              this.password = password;
          }
          
          public String getUsername()
          {
              return username;
          }
          
         public String getPassword()
         {
             return password;
         }
     }
     
     public static class LoginMessage implements java.io.Serializable
     {
         // Data members --------------------------------------------------------
         protected String mUserID;
         protected String mPassword;
         
         // Constructors --------------------------------------------------------
         public LoginMessage(String userID, String password)
         {
             mUserID = userID;
             mPassword = password;
         }
         
         // Access methods ------------------------------------------------------
         public String getUserID()
         {
             return mUserID;
         }
         
         public String getPassword()
         {
             return mPassword;
         }
     }
     
     public static class LogoutMessage implements java.io.Serializable
     {
         // Data members --------------------------------------------------------
         protected UserInfo mUserInfo;
         protected int mSessionID;
         
         // Constructors --------------------------------------------------------
         public LogoutMessage(UserInfo userInfo, int sessionID)
         {
             mUserInfo = userInfo;
             mSessionID = sessionID;
         }
         
         // Access methods ------------------------------------------------------
         public UserInfo getUserInfo()
         {
             return mUserInfo;
         }
         
         public int getSessionID()
         {
             return mSessionID;
         }
     }
     
     public static class LoginServiceReturnMessage implements java.io.Serializable
     {
         // Data members --------------------------------------------------------
         protected UserInfo mUserInfo;
         protected boolean mResult;
         protected Throwable mException;
         
         // Constructors --------------------------------------------------------
         public LoginServiceReturnMessage(UserInfo userInfo, boolean result, Throwable exception)
         {
             mUserInfo = userInfo;
             mResult = result;
             mException = exception;
         }
         
         // Access methods ------------------------------------------------------
         public UserInfo getUserInfo()
         {
             return mUserInfo;
         }
         
         public boolean getResult()
         {
             return mResult;
         }
         
         public Throwable getException()
         {
             return mException;
         }
     }
 }