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 system. 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:

• addPasswordCacheEntry()
• authenticate()
• connectService()
• validateSignon()

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

Methods

Modifier and Type	Method and Description
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, java.net.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, java.lang.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

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:

• addPasswordCacheEntry()
• authenticate()
• connectService()
• validateSignon()

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

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

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

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

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

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

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

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

boolean systemNameUnknown(SignonEvent event,
                        java.net.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

boolean userIdDefaultAlreadyAssigned(SignonEvent event,
                                   java.lang.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

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

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

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

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

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)