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 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()
      • 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)
      • 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,
                                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)
      • 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)