com.ccg.awt
Class LoginPanel

java.lang.Object
  java.awt.Component
      java.awt.Container
          java.awt.Panel
              com.ccg.awt.LoginPanel

All Implemented Interfaces:

ActionListener, ImageObserver, MenuContainer, Serializable, EventListener, Accessible

public class LoginPanel
extends Panel
implements ActionListener

A simple Login panel. Seems like one is always running across the condition where a simple login/password screen is required. This object attempts to create the panel in a generic means that can be used by many applications. It provides the following:

• A TextField for the user to enter their login ID in (as well as a Label to appear next to the text field).
• A TextField for the user to enter their login password in (as well as a Label to appear next to the text field).
• A button for the user to press when they want to try and login.
• A button for the user to press if they want to cancel the login.
• Two methods which derived classes can override, authenticate() and cancel(), which allow one to authenticate the ID/password entered by the user or perform any special actions when the user cancel's the login process.
• The ability for ActionListener objects to monitor when the user enters a valid login/password or gives up (by pressing cancel).
• All labels can be specifically set/localized.

It should be noted that the default "authentication" provided by this class is to simply return "true". Almost all implementations will want to override this default behavior with whatever authentication protocol they want to use. Some applications, may choose to live with this and simply authenticate the ID/password after the window has been closed (and then maybe pop it back up if they are unable to verify the ID/password).

The example program LoginDemo.java has been provided which demonstrates how one could use this class. It demonstrates the following:

• How to extend the class to implement your own authentication by overriding the authenticate() method. The authentciation rule used by this demo should not be used in practice.
• How external ActionListener objects can detect when the user has entered a valid password/login combination or given up and pressed the cancel button.

Since:

1.0

Version:

$Revision: 1.9 $

Author:

$Author: pkb $

See Also:

LoginDemo.java, Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class java.awt.Panel

Panel.AccessibleAWTPanel

Nested classes/interfaces inherited from class java.awt.Container

Container.AccessibleAWTContainer

Nested classes/interfaces inherited from class java.awt.Component

Component.AccessibleAWTComponent, Component.BltBufferStrategy, Component.FlipBufferStrategy

Field Summary

(package private) int	_authenticateCnt
(package private) int	_cancelCnt
(package private) boolean	_cancelLogin
(package private) boolean	_isAuthenticated

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

LoginPanel()
Default constructor for the object.

Method Summary

void	actionPerformed(ActionEvent e) This routine handles the events from the GUI.
void	addActionListener(ActionListener al) Register a ActionListener to be notified of action events.
protected boolean	authenticate() Verify that the login ID/password are valid.
protected boolean	cancel() Should the user be allowed to "cancel" the login process.
void	doSmartFocus() Attempt to put the text focus in a "smart" position.
int	getCancelAttempts() Get number of attempts user tried to cancel login.
int	getLoginAttempts() Get number of attempts user attempted to login.
String	getLoginId() Get the login ID the user currently has specified on the panel.
String	getPassword() Get the login password the user currently has specified on the panel.
boolean	isAborting() Does the user want to "abort" the login process.
boolean	isAuthenticated() Indicates whether the user has successfully logged in.
void	removeActionListener(ActionListener al) Register a ActionListener to be notified of action events.
void	setLoginId(String val) Set the login ID to show on the panel.
void	setPassword(String val) Set the password for the panel.
void	setProperties(TagLookup from) Set the text properties associated with the object.
boolean	showDialog(Frame owner, String title, boolean modal) Easy way to present a pop-up window that waits for valid login or abort.
void	zero() Reset counters/flags.

Methods inherited from class java.awt.Panel

addNotify, getAccessibleContext

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getAlignmentX, getAlignmentY, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getInsets, getLayout, getListeners, getMaximumSize, getMinimumSize, getMousePosition, getPreferredSize, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paint, paintComponents, paramString, preferredSize, print, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, removeNotify, setComponentZOrder, setFocusCycleRoot, setFocusTraversalKeys, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setFont, setLayout, transferFocusBackward, transferFocusDownCycle, update, validate, validateTree

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphics, getGraphicsConfiguration, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, printAll, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, reshape, resize, resize, setBackground, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeysEnabled, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setMinimumSize, setName, setPreferredSize, setSize, setSize, setVisible, show, show, size, toString, transferFocus, transferFocusUpCycle

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

_cancelCnt

int _cancelCnt

_authenticateCnt

int _authenticateCnt

_isAuthenticated

boolean _isAuthenticated

_cancelLogin

boolean _cancelLogin

Constructor Detail

LoginPanel

public LoginPanel()

Default constructor for the object. This method creates the object and its AWT components. All fields will be initialized with default String settings (which you can override/localize).

Since:

1.0

See Also:

addActionListener(java.awt.event.ActionListener), setProperties(com.ccg.util.TagLookup)

Method Detail

zero

public void zero()

Reset counters/flags. Since you can re-use a LoginPanel object, it is possible that you will want to clear/reset/zero out its internal counters and flags before presenting it back to the user. This method clears all internal counters and most developers will want to invoke it prior to displaying the panel to the user. However, doing so is optional.

Since:

1.0

addActionListener

public void addActionListener(ActionListener al)

Register a ActionListener to be notified of action events.

Use this method to register a ActionListener to be notified any time the user attempts to login or cancel a login attempt. Your action listener can use the isAuthenticated() and/or isAborting() methods to determine what the user wants to do. Its possible that both of these will return false (if the user entered a login ID/password that wasn't valid according to authenticate()).

Parameters:

al - Listener you want to have notified when login attempts/aborts are done by the user.

Since:

1.0

See Also:

removeActionListener(java.awt.event.ActionListener)

removeActionListener

public void removeActionListener(ActionListener al)

Register a ActionListener to be notified of action events. Use this method to register a ActionListener to be notified any time the user attempts to login or cancel a login attempt. Your action listener can use the isAuthenticated() and/or isAborting() methods to determine what the user wants to do. Its possible that both of these will return false (if the user entered a login ID/password that wasn't valid according to authenticate()).

Parameters:

al - Listener you want to have notified when login attempts/aborts are done by the user.

Since:

1.0

See Also:

addActionListener(java.awt.event.ActionListener)

authenticate

protected boolean authenticate()

Verify that the login ID/password are valid. This method is invoked whenever the user presses the "Login" button or hits the enter key on either the login ID or password field. The job of this method is to verify that the login ID/password entered by the user is valid.

IMPORTANT: This default implementation always returns true indicating that the login ID/password look OK as far as this object is concerned. This leaves a developer the following choices as to how to do real authentication:

• Derive a new object from LoginPanel and implement a real authenticate() method. This is the preferred solution.
• Have your action listener (which was registered via addActionListener(java.awt.event.ActionListener)) do the authentication itself by checking the login ID/password which the object contains (using the values returned by getLoginId() and getPassword() methods).

Returns:

true - indicating that this object considers the login ID/password as valid (you will need to override this method if you want to do your authentication here and return false on failure).

Since:

1.0

See Also:

cancel()

isAuthenticated

public boolean isAuthenticated()

Indicates whether the user has successfully logged in.

This method indicates whether this object considers the user as successfully logged in. In order for this to occur, the user must have performed a action that they wanted to login (such as pressing the "Login" button), and the authenticate() method must have validated that the users login was valid. This method is typically used by action listeners who are monitoring this object.

It should be noted that both isAuthenticated() and isAborting() will return false for the following situations:

• The object has been initially constructed.
• The object has recently been zeroed/reset/cleared.
• The user attempted a login, but the authenticate() method rejected the user's login ID/password.

Returns:

true - if the user attempted to login and authenticate() indicated it was OK.

Since:

1.0

See Also:

isAborting()

isAborting

public boolean isAborting()

Does the user want to "abort" the login process. This method returns the result of the last time the cancel() method was invoked. If it returns true, it indicates that the user wants to cancel the login process and the cancel() method allowed the cancellation. This means that the user has NOT been authenticated.

Returns:

true - if user wants to cancel login and the object is allowing the user to cancel.

Since:

1.0

See Also:

isAuthenticated()

cancel

protected boolean cancel()

Should the user be allowed to "cancel" the login process. This method is invoked when the user tries to abort the login process (by pressing the "Cancel" button). This default implementation always returns true indicating that the "Cancel" was accepted. For most developers, this default implementation will prove sufficient.

If you want the option to reject a user from being able to cancel the login window (which I would not recommend), you can return false.

Returns:

true to indicate that you will allow the user to cancel.

Since:

1.0

See Also:

authenticate()

actionPerformed

public void actionPerformed(ActionEvent e)

This routine handles the events from the GUI. When the user clicks on one of the buttons, such as the login or cancel button, or presses the "Enter" key on either the login or password field, this method will be invoked and perform the following:

• Update internal counts reflecting the number of times authentication/canceling was attempted by the user.
• Invoke either the authenticate() or cancel() method (depending on what the user pressed). This in turn will update internal flags indicating whether the object isAuthenticated() or isAborting().
• Then trigger all of the registered ActionListeners notifying them that the user has attempted/succeeded/canceled the login process.

Specified by:

actionPerformed in interface ActionListener

Parameters:

e - Event which occurred

See Also:

authenticate(), cancel(), addActionListener(java.awt.event.ActionListener)

getLoginId

public String getLoginId()

Get the login ID the user currently has specified on the panel.

Returns:

Login ID currently specified (won't return null - but may return "").

Since:

1.0

setLoginId

public void setLoginId(String val)

Set the login ID to show on the panel.

Parameters:

val - Set the login ID to show in the panel (you can pass null, but it will be changed to "").

Since:

1.0

getPassword

public String getPassword()

Get the login password the user currently has specified on the panel.

Returns:

Login password currently specified (won't return null - but may return "").

Since:

1.0

setPassword

public void setPassword(String val)

Set the password for the panel.

Parameters:

val - Set the password to show in the panel (you can pass null, but it will be changed to "").

Since:

1.0

getLoginAttempts

public int getLoginAttempts()

Get number of attempts user attempted to login.

Returns:

Number of times user has submitted login/password for authentication since the last time zeroed.

Since:

1.0

getCancelAttempts

public int getCancelAttempts()

Get number of attempts user tried to cancel login.

Returns:

Number of times user has tried to cancel authentication since the last time zeroed.

Since:

1.0

setProperties

public void setProperties(TagLookup from)

Set the text properties associated with the object. This method provides the preferred method for assigning strings to the various fields the object contains. The best way to get a feel for how it works is to look at the LoginDemo.java example program and its associated LoginDemoStrings.properties resource bundle this example demonstrates how to use this method to create a localizable login panel.

The following properties are loaded into the object (they are all optional):

id.label

Label to precede the Login ID text field area.

id.text

Text for the default Login ID (typically empty).

pwd.label

Label to precede the Login Password text field area.

pwd.text

Text for the default Login Password (typically empty).

button.login

Label for login button

button.cancel

Label for cancel button

background

The background color of the components.

foreground

The foreground color of the components.

Parameters:

props - Where to look up setting for the object.

Since:

1.0

showDialog

public boolean showDialog(Frame owner,
                          String title,
                          boolean modal)

Easy way to present a pop-up window that waits for valid login or abort. If you derive your own LoginPanel class, this method is a very simple way to pop-up a window to the user and wait until the user enters a valid login/password combination (as determined by your implementation of authenticate()) or the user gives up and cancels attempting to login.

Refer to the LoginDemo.java example program which demonstrates how to use this method.

Don't forget that this method doesn't return until the user enters a vaild login/password, or gives up and presses the "Cancel" button (or the window manager's close action for the window is invoked).

Parameters:

owner - The parent Frame to associate with the Login dialog box.

title - Title to set for the window frame used to present the login panel with (may be null if you don't want to set a title).

modal - Set to true (typical setting) to cause the method to wait until the user enters a valid ID/password or gives up and presses the "Cancel" button. Set to "false" if you don't want to be blocked waiting for the user to login (you'll want to monitor the state using addActionListener(java.awt.event.ActionListener) in this case).

Returns:

true if user is authenticated/false if not. This return code should only be used when the 'modal' parameter is set to true (if you don't return immediately).

Since:

1.0

See Also:

LoginDemo.java

doSmartFocus

public void doSmartFocus()

Attempt to put the text focus in a "smart" position. This method will attempt to determine the best place to put the "focus". It uses the following rules:

• If the login ID hasn't been set, then the focus will be put on this field to allow the user to enter their login ID first.
• If the login ID has already been set, then the focus wull be put on the password entry field (assuming that the user probably won't need to edit their login ID).

It should be noted that you can not invoke this method until the login panel is visible. Typically you will call this method from the windowOpened(WindowEvent) method of a listener associated with the Frame containing the LoginPanel.

Since:

1.0