Chapter 8. Security Client

package org.jboss.security.client;
 
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.login.LoginException; 

/**
 *  Generic Security Client class <br/>
 *  <b>Basic Users:</b><br/>
 *  <p>Basic users will just use the methods that set the username and credential 
 *  @see {@link #setUserName(String)} and @see {@link #setCredential(Object)} </p>
 *  <b>Intermediate Users:</b></br/>
 *  <p>You can specify usage of JAAS as the framework in the client implementation.
 *  In this case, you will @see {@link #setLoginConfigName(String)} and
 *  @see #setCallbackHandler(CallbackHandler)</p>
 *  <b>Advanced Users:</b>
 *  <p>You will use the @see {@link #setSASLMechanism(String)} method</p> 
 */
public abstract class SecurityClient
{   
   protected Object userPrincipal = null; 
   protected Object credential = null;
   protected CallbackHandler callbackHandler = null;
   protected String loginConfigName = null;
   protected String saslMechanism = null;
   protected String saslAuthorizationId = null;
   
   protected boolean jaasDesired = false;
   protected boolean saslDesired = false;
   
   /**
    * Login with the desired method
    * @throws LoginException
    */
   public void login() throws LoginException
   {
      if(jaasDesired)
         performJAASLogin();
      else
         if(saslDesired)
            peformSASLLogin();
         else
            performSimpleLogin(); 
   }
   
   /**
    * Log Out
    */
   public void logout()
   {
      setSimple(null,null);
      setJAAS(null,null);
      setSASL(null,null,null);
      cleanUp();
   }
   
   /**
    * Set the user name and credential for simple login (non-jaas, non-sasl)
    * @param username (Can be null)
    * @param credential (Can be null)
    */
   public void setSimple(Object username, Object credential)
   {
      this.userPrincipal = username;
      this.credential = credential;
   }
   
   /**
    * Set the JAAS Login Configuration Name and Callback handler
    * @param configName can be null
    * @param cbh can be null
    */
   public void setJAAS(String configName, CallbackHandler cbh)
   {
      this.loginConfigName = configName;
      this.callbackHandler = cbh;
      clearUpDesires();
      this.jaasDesired = true;
   }
   
   /**
    * Set the mechanism and other parameters for SASL Client
    * @param mechanism
    * @param authorizationId
    * @param cbh
    */
   public void setSASL(String mechanism, String authorizationId,
         CallbackHandler cbh)
   {
      this.saslMechanism = mechanism;
      this.saslAuthorizationId = authorizationId;
      this.callbackHandler = cbh;
      clearUpDesires();
      this.saslDesired = true;
   }
   
   protected abstract void performJAASLogin() throws LoginException;
   protected abstract void peformSASLLogin();
   protected abstract void performSimpleLogin();
   
   /**
    * Provide an opportunity for client implementations to clean up
    */
   protected abstract void cleanUp();
   
   private void clearUpDesires()
   {
      jaasDesired = false;
      saslDesired = false;  
   } 
}