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)

connectionInitiated

exceptionOccurred

passwordAboutToExpire

passwordExpired

passwordIncorrect

passwordLengthIncorrect

passwordMissing

systemNameMissing

systemNameUnknown

userIdDefaultAlreadyAssigned

userIdAboutToBeDisabled

userIdDisabled

userIdLengthIncorrect

userIdMissing

userIdUnknown