com.internationalnetwork.gui
Class Login

Object
  extended by com.internationalnetwork.gui.Login
All Implemented Interfaces:
java.awt.event.ActionListener, java.awt.event.KeyListener, java.awt.event.MouseListener, java.awt.event.WindowListener, EventListener

public class Login
extends Object
implements java.awt.event.ActionListener, java.awt.event.KeyListener, java.awt.event.MouseListener, java.awt.event.WindowListener

The Login class provides a fancy, easy-to-use, blocking dialogue that prompts the user for a Login name and Password.

Customization options include setting a default login name and password (to reduce typing for the user), defining call-back methods for the Help and Login buttons, defining a banner graphic, etc.

You'll notice that many of the methods return a Login object.  This is the same object that you're accessing, and we provide this as a convenience to developers who need to use a fully customized, and dynamically created on-the-fly, Login object within a switch or if statement, but prefer not to have the hassle of writing multiple lines of code before-hand.  This definitely leads to simpler code.


Field Summary
static String VERSION
          Version number of this Package (read-only).
 
Constructor Summary
Login()
          Constructs a new Login object with default parameters.
Login(String title)
          Constructs a new Login object with default parameters, except that here the title of the Login window may also be set (this is a convenience constructor that simplifies coding for developers).
 
Method Summary
 void actionPerformed(java.awt.event.ActionEvent e)
          DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...
protected  void finalize()
          Erases the characters (by replacing them with spaces) in the internal StringBuffer objects when this Login object is destroyed.  This is an important step because it ensures that the user's login name and password are not stored in RAM after the Login object is no longer needed.
 char getAction()
          Provides information about the user's action after an unsuccessful login.
 String getExitButtonIcon()
          Returns the current Exit button icon filename.
 String getExitButtonLabel()
          Returns the Exit button label.
 String getHelpButtonIcon()
          Returns the current Help button icon filename.
 String getHelpButtonLabel()
          Returns the Help button label.
 String getLoginBanner()
          Returns the current login banner image filename.
 String getLoginButtonIcon()
          Returns the current Login button icon filename.
 String getLoginButtonLabel()
          Returns the Login button label.
 String getLoginName()
          Returns the current Login name text.  Normally used after calling the prompt() method.
 String getLoginNameIcon()
          Returns the current Login name label icon filename.
 String getLoginNameLabel()
          Returns the current Login name label text.  The default is "Login name:" (with some additional HTML tags).
 int getLoginNamePolicyMaximumLength()
          Gets the policy setting for the maximum Login name length.
 int getLoginNamePolicyMinimumLength()
          Gets the policy setting for the minimum Login name length.
 String getPassword()
          Returns the current Password text.  Normally used after calling the prompt() method.
 String getPasswordIcon()
          Returns the current Password label icon filename.
 String getPasswordLabel()
          Returns the current Password label text.  The default is "Password:" (with some additional HTML tags).
 int getPasswordPolicyMaximumLength()
          Gets the policy setting for the maximum Password length.
 int getPasswordPolicyMinimumLength()
          Gets the policy setting for the minimum Password length.
 String getPromptIcon()
          Returns the current Login Prompt window's icon filename.
 String getPromptTitle()
          Returns the Login Prompt window's title (default is "Login").
 boolean getReturnStatus()
          Returns "true" if the Login name and Password were correct, or "false" in all other circumstances (including the user choosing to "Exit").
 void keyPressed(java.awt.event.KeyEvent e)
          DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...
 void keyReleased(java.awt.event.KeyEvent e)
          DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...
 void keyTyped(java.awt.event.KeyEvent e)
          DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...
static void main(String[] args)
          DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...
static void mainCallbackHelpExample(String helpCode)
          Help call-back method parameter information.
static boolean mainCallbackLoginExample(String loginNameText, String passwordText)
          Login call-back method parameter information.
 void mouseClicked(java.awt.event.MouseEvent e)
          DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...
 void mouseEntered(java.awt.event.MouseEvent e)
          DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...
 void mouseExited(java.awt.event.MouseEvent e)
          DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...
 void mousePressed(java.awt.event.MouseEvent e)
          DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...
 void mouseReleased(java.awt.event.MouseEvent e)
          DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...
 boolean prompt()
          Display login prompt, wait for user input, then return a boolean to indicate success or failure for convenient use within loops (intended for simplifying the implementation of unsuccessful login retry attempts).
 String[] prompt(String controlString)
          Same as the prompt() method, except that, upon a successful return, the login credentials specified in the Control String will be returned in the resulting array.  The Control String is comprised of characters which have the following meanings (more codes may be added in future versions):
 Login setExitButtonIcon(String iconFilename)
          Sets the current Exit button icon filename.  The path to the filename is assumed to be relative to the current working directory.
 Login setExitButtonLabel(String buttonLabel)
          Sets the Exit button label.  The default is "Exit" (with some additional HTML tags).
 Login setHelpButtonIcon(String iconFilename)
          Sets the current Help button icon filename.  The path to the filename is assumed to be relative to the current working directory.
 Login setHelpButtonLabel(String buttonLabel)
          Sets the Help button label.  The default is "Help" (with some additional HTML tags).
 Login setHelpMethod(String className, String methodName)
          Defines a call-back method for the Help function.
 Login setLoginBanner(String imageFilename)
          Set the login banner image filename.  The path to the filename is assumed to be relative to the current working directory.
 Login setLoginButtonIcon(String iconFilename)
          Sets the current Login button icon filename.  The path to the filename is assumed to be relative to the current working directory.
 Login setLoginButtonLabel(String buttonLabel)
          Sets the Login button label.  The default is "Login" (with some additional HTML tags).
 Login setLoginMethod(String className, String methodName)
          Defines a call-back method for the Login function.
 Login setLoginName(String loginNameText)
          Sets the current Login name text.
 Login setLoginNameIcon(String iconFilename)
          Sets the current Login name icon filename.  The path to the filename is assumed to be relative to the current working directory.
 boolean setLoginNameLabel(String loginNameLabel)
          Sets the current Login name label (default is "Login name:" with some basic HTML formatting codes).
 Login setLoginNamePolicyMaximumLength(int maximumLength)
          Sets the policy for the maximum Login name length (default is 64).
 Login setLoginNamePolicyMinimumLength(int minimumLength)
          Sets the policy for the minimum Login name length (default is 1).  The "Login" button will not be usable while the length of the password is shorter than this value.
 Login setPassword(String passwordText)
          Sets the current Password text (only for the login prompt; nowhere else).
 Login setPasswordIcon(String iconFilename)
          Sets the current Password icon filename.  The path to the filename is assumed to be relative to the current working directory.
 boolean setPasswordLabel(String passwordLabel)
          Sets the current Password label (default is "Password:" with some basic HTML formatting codes).
 Login setPasswordPolicyMaximumLength(int maximumLength)
          Sets the policy for the maximum Password length (default is 127).
 Login setPasswordPolicyMinimumLength(int minimumLength)
          Sets the policy for the minimum Password length (default is 0).  The "Login" button will not be usable while the length of the password is shorter than this value.
 Login setPromptIcon(String iconFilename)
          Sets the current Login Prompt window's icon filename.  The path to the filename is assumed to be relative to the current working directory.
 Login setPromptTitle(String frameTitle)
          Sets the Login Prompt window's title.
 void windowActivated(java.awt.event.WindowEvent e)
          DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...
 void windowClosed(java.awt.event.WindowEvent e)
          DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...
 void windowClosing(java.awt.event.WindowEvent e)
          DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...
 void windowDeactivated(java.awt.event.WindowEvent e)
          DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...
 void windowDeiconified(java.awt.event.WindowEvent e)
          DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...
 void windowIconified(java.awt.event.WindowEvent e)
          DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...
 void windowOpened(java.awt.event.WindowEvent e)
          DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...
 
Methods inherited from class Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

VERSION

public static final String VERSION
Version number of this Package (read-only).

See Also:
Constant Field Values
Constructor Detail

Login

public Login()
Constructs a new Login object with default parameters.


Login

public Login(String title)
Constructs a new Login object with default parameters, except that here the title of the Login window may also be set (this is a convenience constructor that simplifies coding for developers).

Method Detail

actionPerformed

public void actionPerformed(java.awt.event.ActionEvent e)
DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...

Specified by:
actionPerformed in interface java.awt.event.ActionListener

finalize

protected void finalize()
Erases the characters (by replacing them with spaces) in the internal StringBuffer objects when this Login object is destroyed.  This is an important step because it ensures that the user's login name and password are not stored in RAM after the Login object is no longer needed.

Overrides:
finalize in class Object

getAction

public char getAction()
Provides information about the user's action after an unsuccessful login.

Although only three distinct characters are currently used, a default case should be defined (e.g., when a switch() is used for flow control) in order to accomodate possible future expansion.

E An Error occurred.  This should never happen, but should be handled as part of the default behaviour.
L Login was initiated.  The user clicked on the "Login" button using the mouse, or pressed the "Enter" key on the keyboard).  The most likely cause of failure in this case is an invalid login name and/or password, although this can only occur when a defined LoginMethod returns "false" (see @see "setLoginMethod()").
X Exit was initiated.  The user clicked on the "Exit" button using the mouse, pressed the "Esc(ape)" key on the keyboard, or the Operating System signalled a windowClose event.

Failed login attempts can easily be handled within a loop to provide the user with any number of chances to try again.  Since the policies on how failed login attempts are dealt with has a potential to vary greatly depending on a number of factors (including application specifications and organizational policies), a retry mechanism wasn't implemented.


getExitButtonIcon

public String getExitButtonIcon()
Returns the current Exit button icon filename.


getExitButtonLabel

public String getExitButtonLabel()
Returns the Exit button label.


getHelpButtonIcon

public String getHelpButtonIcon()
Returns the current Help button icon filename.


getHelpButtonLabel

public String getHelpButtonLabel()
Returns the Help button label.


getLoginBanner

public String getLoginBanner()
Returns the current login banner image filename.


getLoginButtonIcon

public String getLoginButtonIcon()
Returns the current Login button icon filename.


getLoginButtonLabel

public String getLoginButtonLabel()
Returns the Login button label.


getLoginName

public String getLoginName()
Returns the current Login name text.  Normally used after calling the prompt() method.


getLoginNameIcon

public String getLoginNameIcon()
Returns the current Login name label icon filename.


getLoginNameLabel

public String getLoginNameLabel()
Returns the current Login name label text.  The default is "Login name:" (with some additional HTML tags).


getLoginNamePolicyMaximumLength

public int getLoginNamePolicyMaximumLength()
Gets the policy setting for the maximum Login name length.


getLoginNamePolicyMinimumLength

public int getLoginNamePolicyMinimumLength()
Gets the policy setting for the minimum Login name length.


getPassword

public String getPassword()
Returns the current Password text.  Normally used after calling the prompt() method.


getPasswordIcon

public String getPasswordIcon()
Returns the current Password label icon filename.


getPasswordLabel

public String getPasswordLabel()
Returns the current Password label text.  The default is "Password:" (with some additional HTML tags).


getPasswordPolicyMaximumLength

public int getPasswordPolicyMaximumLength()
Gets the policy setting for the maximum Password length.


getPasswordPolicyMinimumLength

public int getPasswordPolicyMinimumLength()
Gets the policy setting for the minimum Password length.


getPromptIcon

public String getPromptIcon()
Returns the current Login Prompt window's icon filename.


getPromptTitle

public String getPromptTitle()
Returns the Login Prompt window's title (default is "Login").


getReturnStatus

public boolean getReturnStatus()
Returns "true" if the Login name and Password were correct, or "false" in all other circumstances (including the user choosing to "Exit").


keyPressed

public void keyPressed(java.awt.event.KeyEvent e)
DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...

Specified by:
keyPressed in interface java.awt.event.KeyListener

keyReleased

public void keyReleased(java.awt.event.KeyEvent e)
DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...

Specified by:
keyReleased in interface java.awt.event.KeyListener

keyTyped

public void keyTyped(java.awt.event.KeyEvent e)
DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...

Specified by:
keyTyped in interface java.awt.event.KeyListener

main

public static void main(String[] args)
DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...


mainCallbackHelpExample

public static void mainCallbackHelpExample(String helpCode)
Help call-back method parameter information.

At this point there are no parameters, but in the future this will change to receive a String to help "Help" help the user by being more sensitive to the context (e.g., if the user called for Help while the Password field had the cursor's focus, then by default the string passed through would be "Password" although this will be modifiable too in order to potentially simplify integration with different Help systems and/or languages).

Update:  One parameter is required now, a String, but be forwarned that it is not fully implemented yet.


mainCallbackLoginExample

public static boolean mainCallbackLoginExample(String loginNameText,
                                               String passwordText)
Login call-back method parameter information.

This method provides checks the validity of the Login name and Password and returns a boolean to indicate success or failure.  This method should not be used for any other purpose (except possibly logging, in which case the getAction() accessor should also be used in anticipation of future expansion which could potentially include a "Test account without logging in" function for advanced users; implementation timeframe not determined, depends on customer feedback to indicate demand).


mouseClicked

public void mouseClicked(java.awt.event.MouseEvent e)
DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...

Specified by:
mouseClicked in interface java.awt.event.MouseListener

mouseEntered

public void mouseEntered(java.awt.event.MouseEvent e)
DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...

Specified by:
mouseEntered in interface java.awt.event.MouseListener

mouseExited

public void mouseExited(java.awt.event.MouseEvent e)
DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...

Specified by:
mouseExited in interface java.awt.event.MouseListener

mousePressed

public void mousePressed(java.awt.event.MouseEvent e)
DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...

Specified by:
mousePressed in interface java.awt.event.MouseListener

mouseReleased

public void mouseReleased(java.awt.event.MouseEvent e)
DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...

Specified by:
mouseReleased in interface java.awt.event.MouseListener

prompt

public boolean prompt()
Display login prompt, wait for user input, then return a boolean to indicate success or failure for convenient use within loops (intended for simplifying the implementation of unsuccessful login retry attempts).


prompt

public String[] prompt(String controlString)
Same as the prompt() method, except that, upon a successful return, the login credentials specified in the Control String will be returned in the resulting array.  The Control String is comprised of characters which have the following meanings (more codes may be added in future versions):

The order in which Control String characters occurs is the order in which the respective data will be stored in the resulting String[] array.  If you specify a the same Control Character multiple times, then it will also be stored in the array multiple times (but in case you're thinking to use this for timing purposes, the time will not change).

Any unrecognized Control String characters will cause a NULL to be stored in the array.  This is done to support some possibility of upward compatibility, however unlikely this may be.  If your String is empty, the resulting array will be empty.

The following sample code shows how an example of how to use this method:

private String[] ary = new Login().prompt("rlpt");
if (ary[0] == null) System.exit(0); // The user chose to exit
System.out.println("Login name:  " + ary[1]);
System.out.println("  Password:  " + ary[2]);
System.out.println("      Time:  " + ary[3]);

Comparing ary[1] and ary[2] with data read from a password file, or as part of a database query, etc., is typically the next step in validating login information.  Since we have all the information we need, in this example the JVM automatically discards the Login() object's resources.


setExitButtonIcon

public Login setExitButtonIcon(String iconFilename)
Sets the current Exit button icon filename.  The path to the filename is assumed to be relative to the current working directory.

The "java.lang.ClassLoader.getSystemResource()" method is always used to access the file, thus also supporting storage within .JAR files.


setExitButtonLabel

public Login setExitButtonLabel(String buttonLabel)
Sets the Exit button label.  The default is "Exit" (with some additional HTML tags).


setHelpButtonIcon

public Login setHelpButtonIcon(String iconFilename)
Sets the current Help button icon filename.  The path to the filename is assumed to be relative to the current working directory.

The "java.lang.ClassLoader.getSystemResource()" method is always used to access the file, thus also supporting storage within .JAR files.


setHelpButtonLabel

public Login setHelpButtonLabel(String buttonLabel)
Sets the Help button label.  The default is "Help" (with some additional HTML tags).


setHelpMethod

public Login setHelpMethod(String className,
                           String methodName)
Defines a call-back method for the Help function.

If the user clicks on the "Help" button using the mouse, or presses the "F1" key on the keyboard, this method will be called.

The Help method should start only one instance of Help since this method can be called multiple times if the user double-clicks on "Help" or presses "F1" more than once.  The developer should keep in mind that the user may not realize that a separate Help window is already open (resulting from a previous request for Help) if they temporarily switched to an unrelated task that remained in front of the Help window.


setLoginBanner

public Login setLoginBanner(String imageFilename)
Set the login banner image filename.  The path to the filename is assumed to be relative to the current working directory.

The "java.lang.ClassLoader.getSystemResource()" method is always used to access the file, thus also supporting storage within .JAR files.


setLoginButtonIcon

public Login setLoginButtonIcon(String iconFilename)
Sets the current Login button icon filename.  The path to the filename is assumed to be relative to the current working directory.

The "java.lang.ClassLoader.getSystemResource()" method is always used to access the file, thus also supporting storage within .JAR files.


setLoginButtonLabel

public Login setLoginButtonLabel(String buttonLabel)
Sets the Login button label.  The default is "Login" (with some additional HTML tags).


setLoginMethod

public Login setLoginMethod(String className,
                            String methodName)
Defines a call-back method for the Login function.

If the user clicks on the "Login" button using the mouse, or presses the "Enter" or "Alt-L" keys on the keyboard, this method will be called to verify if the Login name and Password are valid.

Your defined login method must accept two String parameters (the first one is the Login name, and the second one is the Password).  Your defined login method must return a boolean value where "true" indicates a successful login, and "false" indicates an unsuccessful login. All errors and exceptions within your login method must be handled directly.


setLoginName

public Login setLoginName(String loginNameText)
Sets the current Login name text.

This is useful for setting a default login name in an application where the user has logged in previously, or the network login name can be detected and used, etc.


setLoginNameIcon

public Login setLoginNameIcon(String iconFilename)
Sets the current Login name icon filename.  The path to the filename is assumed to be relative to the current working directory.

The "java.lang.ClassLoader.getSystemResource()" method is always used to access the file, thus also supporting storage within .JAR files.


setLoginNameLabel

public boolean setLoginNameLabel(String loginNameLabel)
Sets the current Login name label (default is "Login name:" with some basic HTML formatting codes).

Returns "false" only if the label is invalid (e.g., null).


setLoginNamePolicyMaximumLength

public Login setLoginNamePolicyMaximumLength(int maximumLength)
Sets the policy for the maximum Login name length (default is 64).

Setting this value to 0 disables limit checking.


setLoginNamePolicyMinimumLength

public Login setLoginNamePolicyMinimumLength(int minimumLength)
Sets the policy for the minimum Login name length (default is 1).  The "Login" button will not be usable while the length of the password is shorter than this value.

Setting this value to 0 means that a blank Login name is acceptable.


setPassword

public Login setPassword(String passwordText)
Sets the current Password text (only for the login prompt; nowhere else).

In situations where security is not a high concern, this can be used to provide a "remembered" password.


setPasswordIcon

public Login setPasswordIcon(String iconFilename)
Sets the current Password icon filename.  The path to the filename is assumed to be relative to the current working directory.

The "java.lang.ClassLoader.getSystemResource()" method is always used to access the file, thus also supporting storage within .JAR files.


setPasswordLabel

public boolean setPasswordLabel(String passwordLabel)
Sets the current Password label (default is "Password:" with some basic HTML formatting codes).

Returns "false" only if the label is invalid (e.g., null).


setPasswordPolicyMaximumLength

public Login setPasswordPolicyMaximumLength(int maximumLength)
Sets the policy for the maximum Password length (default is 127).

Setting this value to 0 disables limit checking.


setPasswordPolicyMinimumLength

public Login setPasswordPolicyMinimumLength(int minimumLength)
Sets the policy for the minimum Password length (default is 0).  The "Login" button will not be usable while the length of the password is shorter than this value.

Setting this value to 0 means that blank a Password is acceptable.


setPromptIcon

public Login setPromptIcon(String iconFilename)
Sets the current Login Prompt window's icon filename.  The path to the filename is assumed to be relative to the current working directory.

The "java.lang.ClassLoader.getSystemResource()" method is always used to access the file, thus also supporting storage within .JAR files.


setPromptTitle

public Login setPromptTitle(String frameTitle)
Sets the Login Prompt window's title.


windowActivated

public void windowActivated(java.awt.event.WindowEvent e)
DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...

Specified by:
windowActivated in interface java.awt.event.WindowListener

windowClosed

public void windowClosed(java.awt.event.WindowEvent e)
DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...

Specified by:
windowClosed in interface java.awt.event.WindowListener

windowClosing

public void windowClosing(java.awt.event.WindowEvent e)
DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...

Specified by:
windowClosing in interface java.awt.event.WindowListener

windowDeactivated

public void windowDeactivated(java.awt.event.WindowEvent e)
DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...

Specified by:
windowDeactivated in interface java.awt.event.WindowListener

windowDeiconified

public void windowDeiconified(java.awt.event.WindowEvent e)
DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...

Specified by:
windowDeiconified in interface java.awt.event.WindowListener

windowIconified

public void windowIconified(java.awt.event.WindowEvent e)
DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...

Specified by:
windowIconified in interface java.awt.event.WindowListener

windowOpened

public void windowOpened(java.awt.event.WindowEvent e)
DO NOT USE!!!  WAITING FOR SUN TO IMPROVE JAVADOC TOOL...

Specified by:
windowOpened in interface java.awt.event.WindowListener