com.ibm.as400.access
Interface SignonHandler

All Known Implementing Classes:
SignonHandlerAdapter

public interface SignonHandler

Specifies the methods required for a SignonHandler. The application can direct the system object to use a specific SignonHandler by calling setSignonHandler(). The AS400 class invokes the SignonHandler at runtime, if additional information (such as userID or password) must be obtained while attempting to connect to the server. By default, the Toolbox uses an internal AWT-based implementation of SignonHandler.

For all methods that return a boolean, a returned value of true indicates that the sign-on should proceed; false indicates that the sign-on should not proceed, in which case the system object will throw an AS400SecurityException with an error code indicating what information is missing or incorrect. In the case of connectionInitiated() and passwordAboutToExpire(), the return code will be SIGNON_CANCELED.

Suggestions for implementers:
Extend SignonHandlerAdapter rather than implementing this interface directly. That will insulate your implementation from future additions to the interface.
In order to avoid hang conditions, the SignonHandler should not attempt to display a GUI if isGuiAvailable() indicates false.
In order to avoid infinite loops, a SignonHandler must not call the following AS400 methods:

Here is a minimal implementation that just prints a message when connectionInitiated() is called.:

import com.ibm.as400.access.SignonHandlerAdapter;
import com.ibm.as400.access.SignonEvent;
public class SimpleSignonHandler extends SignonHandlerAdapter
{
  public boolean connectionInitiated(SignonEvent event)
    throws SignonHandlerException
  {
    System.out.println("SimpleSignonHandler.connectionInitiated()");
    return true;  // indicate that the sign-on should proceed
  }
}

Here is a somewhat more realistic sample implementation:

import com.ibm.as400.access.*;
import java.io.File;
public class MySignonHandler extends SignonHandlerAdapter
{
  public boolean connectionInitiated(SignonEvent event)
  {
    AS400 system = (AS400)event.getSource();
    if (system.isGuiAvailable())
    {
      // Display an interactive dialog to prompt user for userid and password.
      ...
      system.setUserId(userId);
      system.setPassword(password);
    }
    else  // no GUI available
    {
      File myPasswordFile = new File(...);  // file containing sign-on information
      if (myPasswordFile.exists())
      {
        // Read systemName, userId, and password from file, and update the system object.
        ...
        system.setUserId(userId);
        system.setPassword(password);
      }
      else
      {
        // Just return 'true'.  Let the system object proceed with the connection.
        // If anything necessary is missing, the Toolbox will call handleEvent().
      }
    }
    return true;  // indicate that the sign-on should proceed
  }
}

See Also:
AS400.setSignonHandler(com.ibm.as400.access.SignonHandler), AS400.getSignonHandler(), AS400.setDefaultSignonHandler(com.ibm.as400.access.SignonHandler), AS400.getDefaultSignonHandler()

Method Summary
 boolean connectionInitiated(SignonEvent event, boolean forceUpdate)
          Informs the SignonHandler that a connection operation has been initiated.
 void exceptionOccurred(SignonEvent event)
          Handles an exception that was thrown during a sign-on attempt.
 boolean passwordAboutToExpire(SignonEvent event, int daysUntilExpiration)
          Handles the situation where the password is within a few days of expiring.
 boolean passwordExpired(SignonEvent event)
          Handles the situation where the password has expired.
 boolean passwordIncorrect(SignonEvent event)
          Handles the situation where an incorrect password has been specified.
 boolean passwordLengthIncorrect(SignonEvent event)
          Handles the situation where a specified password is either too long or too short.
 boolean passwordMissing(SignonEvent event)
          Handles the situation where a password has not been specified.
 boolean systemNameMissing(SignonEvent event)
          Handles the situation where the system name has not been specified.
 boolean systemNameUnknown(SignonEvent event, UnknownHostException exc)
          Handles the situation where the specified system name is unknown to the network.
 boolean userIdAboutToBeDisabled(SignonEvent event)
          Handles the situation where the specified user profile will be disabled after next incorrect sign-on attempt.
 boolean userIdDefaultAlreadyAssigned(SignonEvent event, String defaultUser)
          Handles the situation where a default userID has already been assigned for the system object.
 boolean userIdDisabled(SignonEvent event)
          Handles the situation where the specified user profile has been disabled.
 boolean userIdLengthIncorrect(SignonEvent event)
          Handles the situation where a specified userID is either too long or too short.
 boolean userIdMissing(SignonEvent event)
          Handles the situation where a userID has not been specified.
 boolean userIdUnknown(SignonEvent event)
          Handles the situation where a specified userID is unknown to the system.
 

Method Detail

connectionInitiated

public boolean connectionInitiated(SignonEvent event,
                                   boolean forceUpdate)
Informs the SignonHandler that a connection operation has been initiated. The SignonHandler inspects the state of the system object (the source of the event), and calls the appropriate setter methods on the system object to fill in or correct fields.

In order to avoid infinite loops, a SignonHandler must not call the following AS400 methods:

Parameters:
event - The sign-on event.
forceUpdate - true indicates that the sign-on information is known to be incomplete or incorrect. false indicates that the information may be correct.
Returns:
true if sign-on should proceed, false if sign-on should not proceed.
See Also:
EventObject.getSource()

exceptionOccurred

public void exceptionOccurred(SignonEvent event)
                       throws AS400SecurityException
Handles an exception that was thrown during a sign-on attempt. If the handler cannot deal with the exception, the handler should rethrow exc.

Parameters:
event - The sign-on event. getException() is guaranteed to return non-null.
Throws:
AS400SecurityException - If the handler cannot handle the exception.
See Also:
AS400SecurityException.getReturnCode()

passwordAboutToExpire

public boolean passwordAboutToExpire(SignonEvent event,
                                     int daysUntilExpiration)
Handles the situation where the password is within a few days of expiring. A typical implementation is to put up a warning message, ask the user if they want to change the password, and if so, solicit a new password and call changePassword. Another reasonable implementation is to just return true, indicating that the password is not to be changed at this time, and the sign-on should proceed.

Parameters:
event - The sign-on event.
daysUntilExpiration - The number of days until the password expires.
Returns:
true if sign-on should proceed, false if sign-on should not proceed.
See Also:
AS400.changePassword(java.lang.String, java.lang.String)

passwordExpired

public boolean passwordExpired(SignonEvent event)
Handles the situation where the password has expired. The typical implementation is to solicit the user for old and new passwords, and call changePassword.

Parameters:
event - The sign-on event.
Returns:
true if sign-on should proceed, false if sign-on should not proceed.
See Also:
AS400.changePassword(java.lang.String, java.lang.String)

passwordIncorrect

public boolean passwordIncorrect(SignonEvent event)
Handles the situation where an incorrect password has been specified.

Parameters:
event - The sign-on event.
Returns:
true if sign-on should proceed, false if sign-on should not proceed.
See Also:
AS400.setPassword(java.lang.String)

passwordLengthIncorrect

public boolean passwordLengthIncorrect(SignonEvent event)
Handles the situation where a specified password is either too long or too short.

Parameters:
event - The sign-on event.
Returns:
true if sign-on should proceed, false if sign-on should not proceed.
See Also:
AS400.setPassword(java.lang.String)

passwordMissing

public boolean passwordMissing(SignonEvent event)
Handles the situation where a password has not been specified.

Parameters:
event - The sign-on event.
Returns:
true if sign-on should proceed, false if sign-on should not proceed.
See Also:
AS400.setPassword(java.lang.String)

systemNameMissing

public boolean systemNameMissing(SignonEvent event)
Handles the situation where the system name has not been specified.

Parameters:
event - The sign-on event.
Returns:
true if sign-on should proceed, false if sign-on should not proceed.
See Also:
AS400.setSystemName(java.lang.String)

systemNameUnknown

public boolean systemNameUnknown(SignonEvent event,
                                 UnknownHostException exc)
Handles the situation where the specified system name is unknown to the network.

Parameters:
event - The sign-on event.
exc - The exception.
Returns:
true if sign-on should proceed, false if sign-on should not proceed.
See Also:
AS400.setSystemName(java.lang.String)

userIdDefaultAlreadyAssigned

public boolean userIdDefaultAlreadyAssigned(SignonEvent event,
                                            String defaultUser)
Handles the situation where a default userID has already been assigned for the system object. A typical implementation is simply to put up a warning message. Another reasonable implementation is simply to return true, indicating that the sign-on should proceed.

Parameters:
event - The sign-on event.
defaultUser - The current default user.
Returns:
true if sign-on should proceed, false if sign-on should not proceed.
See Also:
AS400.isUseDefaultUser(), AS400.setUseDefaultUser(boolean), AS400.setDefaultUser(java.lang.String, java.lang.String), AS400.removeDefaultUser(java.lang.String)

userIdAboutToBeDisabled

public boolean userIdAboutToBeDisabled(SignonEvent event)
Handles the situation where the specified user profile will be disabled after next incorrect sign-on attempt. This usually indicates that several successive incorrect sign-on attempts have occurred.

Parameters:
event - The sign-on event.
Returns:
true if sign-on should proceed, false if sign-on should not proceed.
See Also:
AS400.setUserId(java.lang.String), AS400.setPassword(java.lang.String)

userIdDisabled

public boolean userIdDisabled(SignonEvent event)
Handles the situation where the specified user profile has been disabled. The application may choose to specify a different userID, or re-enable the user profile.

Parameters:
event - The sign-on event.
Returns:
true if sign-on should proceed, false if sign-on should not proceed.
See Also:
AS400.setUserId(java.lang.String)

userIdLengthIncorrect

public boolean userIdLengthIncorrect(SignonEvent event)
Handles the situation where a specified userID is either too long or too short.

Parameters:
event - The sign-on event.
Returns:
true if sign-on should proceed, false if sign-on should not proceed.
See Also:
AS400.setUserId(java.lang.String)

userIdMissing

public boolean userIdMissing(SignonEvent event)
Handles the situation where a userID has not been specified.

Parameters:
event - The sign-on event.
Returns:
true if sign-on should proceed, false if sign-on should not proceed.
See Also:
AS400.setUserId(java.lang.String)

userIdUnknown

public boolean userIdUnknown(SignonEvent event)
Handles the situation where a specified userID is unknown to the system.

Parameters:
event - The sign-on event.
Returns:
true if sign-on should proceed, false if sign-on should not proceed.
See Also:
AS400.setUserId(java.lang.String)