ActionManager.java

				
//**************************************
// Name: ActionManager.java
// Description:This is a JFC related class for managing actions in an
application or applet. Actions and components are tied
together via an action command string.
// By: M. J. Stam
//
// Inputs:This is a complete class, not a code fragment.
inputs are references to components and references to actions.
//
// Assumes:the relationship between registered values is as follows
String Action Command 1
Action 1
Components Unlimited
//
//This code is copyrighted and has// limited warranties.Please see http://www.Planet-Source-Code.com/vb/scripts/ShowCode.asp?txtCodeId=1665&lngWId=2//for details.//**************************************

/*
 **************************************************************************
 * @(#)ActionManager.java
 *
 * Copyright (c) 1999 HMRavens, Inc. All Rights Reserved.
 *
 * Permission to use, copy, modify, and distribute this software
 * and its documentation for NON-COMMERCIAL or COMMERCIAL purposes and
 * without fee is hereby granted. 
 * 
 * HMRAVENS MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF
 * THE SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
 * TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
 * PARTICULAR PURPOSE, OR NON-INFRINGEMENT. HMRAVENS SHALL NOT BE LIABLE FOR
 * ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
 * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES.
 * 
 * THIS SOFTWARE IS NOT DESIGNED OR INTENDED FOR USE OR RESALE AS ON-LINE
 * CONTROL EQUIPMENT IN HAZARDOUS ENVIRONMENTS REQUIRING FAIL-SAFE
 * PERFORMANCE, SUCH AS IN THE OPERATION OF NUCLEAR FACILITIES, AIRCRAFT
 * NAVIGATION OR COMMUNICATION SYSTEMS, AIR TRAFFIC CONTROL, DIRECT LIFE
 * SUPPORT MACHINES, OR WEAPONS SYSTEMS, IN WHICH THE FAILURE OF THE
 * SOFTWARE COULD LEAD DIRECTLY TO DEATH, PERSONAL INJURY, OR SEVERE
 * PHYSICAL OR ENVIRONMENTAL DAMAGE ("HIGH RISK ACTIVITIES"). HMRAVENS
 * SPECIFICALLY DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY OF FITNESS FOR
 * HIGH RISK ACTIVITIES.
 *
 *
 ***************************************************************************
 */
package com.hmravens.util;
import java.lang.reflect.* ;
import java.util.* ;
import java.awt.event.* ;
import java.beans.* ;
import com.sun.java.swing.* ;
/**
 * This class organizes actions and related components.
 * 
 * Entries are organized by action command. Each action
 * command can have one and only one action associated with
 * it. It may have an unlimited number of object associcated
 * with it.
 *
 * All commands are organized by action command.
 *
 * This class automatically updates the states of the registered
 * objects whenever the state of the action changes.
 * 
 * It also allows you to set a tooltip for an action command and
 * have that tooltip reflected in all of the registered objects.
 * 
 * To get the singleton instance of this class call the static
 * method getActionManager()
 *
 *ActionManager myRef = ActionManager.getActionManager()
 *
 * To add an AbstractAction 
 *
 *try 
 *{ 
 * myRef.addAction( strActionCommand , myAbstractAction ) ;
 *}
 *catch( ActionCanNotBeAddedException )
 *{
 *// If this happens you tried to add a second action to the
 *// same action command.
 *}
 *
 *
 * To add an object
 *
 *try 
 *{ 
 * myRef.addAction( strActionCommand , myAbstractAction ) ;
 *}
 *catch( ObjectCanNotBeAddedException )
 *{
 *// If this happens you tried to add an object which does not implement
 *// addActionListener. This is a requirement for adding an object.
 *}
 *
 *
 * To enable an action and its components
 * Note: if an object is added without a setEnabled method its
 *state will not change when this method is called.
 *
 *myRef.setEnabled( strActionCommand , true ) ;
 *
 * To set the Tool Tip
 * Note: if an object is added without a setToolTipText method no
 *tooltip will be associated with that object.
 *
 *myRef.setToolTipText( strActionCommand , strToolTipText ) ;
 *
 * @author mstam
 *
 * @version 1.0
 *
 */
 public final class ActionManager extends Object
 {
 /** Singleton reference to the action manager */ 
 private static ActionManager m_actionManager = null ;
 
 /** Where we store everything */
 private Hashtablem_hashStorage= null ;
 
/**
 *
 * This is where you get a reference to the ActionManager
 *
 * @return a reference to the ActionManager
 *
 */
 public static ActionManager getActionManager()
 {
 // No manager, make one
 if ( null == m_actionManager )
 m_actionManager = new ActionManager() ;
 
 return m_actionManager ;
 
 } // END getActionManager
 
/**
 *
 * Default Constructor
 *
 * Called only by getActionManager of this class.
 *
 */
 private ActionManager()
 {
 
m_hashStorage = new Hashtable() ; 
 } // END Constructor
/**
 * Add an action to for an action command.
 * This with throw an exception if called more then once for the same action command string.
 *
 * @param p_strActionCommand the action command used as a string
 *
 * @param p_Action the action to be associated with the string.
 *
 * @exception ActionCanNotBeAddedException
 *
 */
 public void addAction( String p_strActionCommand , AbstractAction p_Action )
 throws ActionCanNotBeAddedException
 {
 icHashEntry Entry = (icHashEntry) m_hashStorage.get( p_strActionCommand ) ;
 
 // No Entry, Make one and store it. 
 if ( null == Entry )
 {
// Entry created 
Entry = new icHashEntry() ;
// Save entry
m_hashStorage.put( p_strActionCommand , Entry ) ;
 }
 
 // Add Action
 Entry.addAction( p_Action ) ;
 
 } // END addAction
 
/**
 * Associate an oject with an action command string. the object must have
 * an addActionListener method.
 *
 * @param p_strActionCommand the action command string
 *
 * @param p_Object the object to be added, must have an addActionListerer method.
 *
 * @exception ObjectCanNotBeAddedException
 *
 */
 public void add( String p_strActionCommand , Object p_Object )
 throws ObjectCanNotBeAddedException
 {
 icHashEntry Entry = (icHashEntry) m_hashStorage.get( p_strActionCommand ) ;
 
 // No Entry make one
 if ( null == Entry )
 {
// Create entry 
Entry = new icHashEntry() ;
// Save entry
m_hashStorage.put( p_strActionCommand , Entry ) ;
 
 }
 
 // Add object 
 Entry.add( p_Object ) ;
 
 } // END addAction
 
/**
 * @param p_strActionCommand the action command string.
 *
 * @param p_Object An Object which should no longer be associated with
 * the command string.
 */
 public void remove( String p_strActionCommand, Object p_Object )
 {
 icHashEntry Entry = (icHashEntry) m_hashStorage.get( p_strActionCommand ) ;
 
 // No entry, no complaint just exit.
 if ( null == Entry )
 {
 return ;
 }
 
 // Remove object from entry list
 Entry.remove( p_Object ) ;
 
 }
 
/**
 * Change the state of the abstract action and by inference ( propertyChange )
 * reset the state of all associated objects
 *
 * @param p_strActionCommand the action command key
 *
 * @param p_bEnable the new state for the action and its objects.
 *
 */
 public void setEnabled( String p_strActionCommand , boolean p_bEnabled ) 
 {
 icHashEntry Entry = (icHashEntry) m_hashStorage.get( p_strActionCommand ) ;
 
 // No entry, get out
 if ( null == Entry )
 {
 return ;
 }
 // Pass request to inner class
 Entry.setEnabled( p_bEnabled ) ;
 } // END setEnabled
 
 
 
/**
 * Set the tool tip value on any objects added ( add ) which support the
 * setToolTipText method.
 *
 *
 * @param p_strActionCommand the action command key
 *
 * @param p_strToolTipText the new tool tip text
 *
 */
 public void setToolTipText( String p_strActionCommand , String p_strToolTipText ) 
 {
 icHashEntry Entry = (icHashEntry) m_hashStorage.get( p_strActionCommand ) ;
 
 if ( null == Entry )
 {
 return ;
 }
 
 // This will update the individual objects. 
 Entry.setToolTipText( p_strToolTipText ) ;
 
 } // END setToolTipText
 
 
 
/*
*************
INNER CLASSES
*************
*/
/**
* Used to store relationships between actions and components
*
* Adds itself to the AbstractAction as a propertyChangeListener
* Adds itself to the objects as an ActionListener
*
*/
private class icHashEntry extends Object
implements PropertyChangeListener, ActionListener
{
 /** Needed be reflection call in the add method */
 icHashEntry[] m_arrayofthis = { this } ;
 
 /** Registered Abstract Action */
 AbstractAction m_action= null ;
 
 /** Registered objects. Registered objects must implement
 * addActionListener. In addition, they should implement
 * setEnabled and setToolTipText. This is not a requirement 
 */
 Vector m_objects = new Vector() ;
 
 String m_strToolTipText= null ;
 
/**
 * Constructor
 */
 private icHashEntry()
 {
 }
/**
 *
 * Add an AbstractAction to the entry.
 *
 * @param p_NewAction the action command associated with the string.
 *
 * @exception ActionCanNotBeAddedException
 *
 */
 private void addAction( AbstractAction p_NewAction )
 throws ActionCanNotBeAddedException
 {
 if ( null != m_action )
 {
throw new ActionCanNotBeAddedException() ;
 }
 
 m_action = p_NewAction ;
 
 m_action.addPropertyChangeListener( this ) ;
 // Spin through the objects and if possible
 // update their states.
 updateAllStates( m_action.isEnabled() ) ;
 
 } // END addAction
 
/**
 *
 * Add an object to the manager associated with a specific action command.
 * Object must implement addActionListener 
 * 
 * @param p_Object an object to be associated with the action.
 * Object must implement public void addActionListener( ActionListener )
 */
 private void add( Object p_Object )
 throws ObjectCanNotBeAddedException
 {
 // Reference to addActionListener on the object 
 Method methodAddActionListener = null ;
 
 // Needed for the call to get the addActionListener method
 Class[] addActionListenerArg= new Class[ 1 ] ;
 
// Need a reference to ActionListener for this to work
try
{
addActionListenerArg[ 0 ] = Class.forName("java.awt.event.ActionListener") ;
}
catch( ClassNotFoundException Except )
{
throw new ObjectCanNotBeAddedException() ;
}
// Get a reference to the addActionListener method on the object
try 
{
methodAddActionListener = 
 p_Object.getClass().getMethod( "addActionListener" , addActionListenerArg ) ;
}
catch( NoSuchMethodException Except )
{
// No method, complain 
throw new ObjectCanNotBeAddedException() ; 
}
catch( SecurityException Except )
{
// Can not access method, complain 
throw new ObjectCanNotBeAddedException() ; 
}
// Add this class as an action listener for the object.
try 
{
methodAddActionListener.invoke( p_Object , m_arrayofthis ) ;
}
catch( InvocationTargetException Except )
{
// Failed add this as a listener, complain 
throw new ObjectCanNotBeAddedException() ;
}
catch( IllegalAccessException Except )
{
// Failed add this as a listener, complain 
throw new ObjectCanNotBeAddedException() ;
}
// All is well in the world, register the object. 
m_objects.addElement( p_Object ) ;
// Sychronize the object with the action
if ( null != m_action )
 enableObject( p_Object , m_action.isEnabled() ) ; 
// If tool tip exists apply it to new object
if ( null != m_strToolTipText )
 setToolTipTextOnObject( p_Object, m_strToolTipText ) ;
 
 } // END add
 
 
 
/**
 * @param p_Object the object to be disassociated with the action.
 */
 private void remove( Object p_Object )
 {
m_objects.removeElement( p_Object ) ;
 }
 
/**
 * Change the state of the action and 
 * through the invocation of the propertyChange
 * interface change the state of those objects
 * which implement the setEnabled method.
 *
 */
 private void setEnabled( boolean p_bEnabled )
 {
 if ( null != m_action )
 m_action.setEnabled( p_bEnabled ) ;
 
 } // END setEnabled
 
/**
 * Update the Tool Tip Text on all registered objects.
 *
 * @param p_strToolTipText the new tooltip text
 *
 */
 private void setToolTipText( String p_strToolTipText )
 {
 int iSize = m_objects.size() ;
 // Spin through the objects and if possible
 // update their states.
 for ( int iEntry = 0 ; iEntry < iSize ; ++iEntry )
 {
 Object objToReceiveTip = m_objects.elementAt( iEntry ) ;
 
 // Change the state an object.
 setToolTipTextOnObject( objToReceiveTip , p_strToolTipText ) ;
 }
 } // END setToolTipText
 
/*
 ***************************
 IMPLEMENTATION OF LISTENERS 
 ***************************
 */
 
/**
 * Implementation of PropertyChangeListener interface.
 * Hooks the action and updates the objects.
 *
 * @param p_ChangeEvent a property change event from the action.
 */
 public void propertyChange( PropertyChangeEvent p_ChangeEvent )
 {
 // Paranoid, should not be possible.
 if ( null == m_action )
 {
return ;
 }
 
 int iSize = m_objects.size() ;
 // Spin through the objects and if possible
 // update their states.
 updateAllStates( m_action.isEnabled() ) ;
 } // END propertyChange
 
 
/**
 * Updates the states of all registered objects (add)
 * 
 * @param p_bEnabled the new state for all objects.
 */
 private void updateAllStates( boolean p_bEnabled )
 {
 int iSize = m_objects.size() ;
 // Spin through the objects and if possible
 // update their states.
 for ( int iEntry = 0 ; iEntry < iSize ; ++iEntry )
 {
 Object objToEnable = m_objects.elementAt( iEntry ) ;
 
 // Change the state an object.
 enableObject( objToEnable , p_bEnabled ) ;
 }
 } // END updateAllState
 
/**
 * Called from propertyChange to update the state of an object
 *
 * @param p_Object the object on which setEnabled should be called.
 *
 * @param p_bEnabled the new state
 *
 */
 private void enableObject( Object p_Object , boolean p_bEnabled )
 {
 Class[] classArrayForCall = { Boolean.TYPE } ;
 Object[] objArrayForCall = { new Boolean( p_bEnabled ) } ;
 
 // reference to the setEnabled method on the object 
 Method methodSetEnabled = null ;
 
// Get a reference to the setEnabled method on the object
try 
{
 
methodSetEnabled = 
 p_Object.getClass().getMethod( "setEnabled" , classArrayForCall ) ;
}
catch( NoSuchMethodException Except )
{
// Object does not support setEnabled 
return ;
}
catch( SecurityException Except )
{
// Objects setEnabled is not public
return ;
}
// Call setEnabled
try 
{
methodSetEnabled.invoke( p_Object , objArrayForCall ) ;
}
catch( InvocationTargetException Except )
{
// Should not happen because we just got the method
// from the object a minute ago.
return ;
}
catch( IllegalAccessException Except )
{
// Not a public method
return ;
}
 
 
 
 
 } // END enableObjects
 
/**
 * Set the tool tip on objects which support the setToolTipText method
 *
 * @param p_Object the object on which setToolTipText should be called.
 *
 * @param p_strToolTipText the text of the tool tip
 *
 */
 private void setToolTipTextOnObject( Object p_Object, String p_strToolTipText )
 {
 Class[] classArrayForCall = new Class[ 1 ] ;
 Object[] objArrayForCall = { p_strToolTipText } ;
 
 // reference to the setEnabled method on the object 
 Method methodSetToolTipText = null ;
 
 // Need a reference to ActionListener for this to work
try
{
classArrayForCall[ 0 ] = Class.forName("String") ;
}
catch( ClassNotFoundException Except )
{
return ;
}
// Get a reference to the setEnabled method on the object
try 
{
 
methodSetToolTipText = 
 p_Object.getClass().getMethod( "setToolTipText", classArrayForCall ) ;
}
catch( NoSuchMethodException Except )
{
// Object does not support setToolTipText
return ;
}
catch( SecurityException Except )
{
// Objects setToolTipText is not public
return ;
}
// Call setToolTipText
try 
{
methodSetToolTipText.invoke( p_Object , objArrayForCall ) ;
}
catch( InvocationTargetException Except )
{
// Should not happen because we just got the method
// from the object a minute ago.
return ;
}
catch( IllegalAccessException Except )
{
// Not a public method
return ;
}
 
 
 
 
 } // END setToolTipTextOnObject
 
 
/**
 * Implementation of ActionListener hooked to every object
 * added. This passes through to the action. It was done to
 * side step the issue of when the action is added in relation
 * to the objects which are added.
 *
 * @param p_ActionEvent an action event from one of the 
 * added Objects 
 *
 */
 public void actionPerformed( ActionEvent p_ActionEvent )
 {
 if ( null != m_action )
 {
 m_action.actionPerformed( p_ActionEvent ) ;
 }
 }
 
} // END icHashEntry
 
 
 } // END ActionManager