com.adventnet.components.menuframework
Class MenuFramework

java.lang.Object
  |
  +--com.adventnet.components.menuframework.MenuFramework

public class MenuFramework

extends java.lang.Object

This is the Base Class of the Menu Framework which provides the highly customizable XML based MenuFramework service. This class provides API to create,insert,remove and replace the MenuBar, Menus & MenuItems. The MenuFramework takes an XML Document as input and constructs the MenuBar based on the attributes present in the XML File. The menuframe work defined the format in which the XML File has to be fed to the Framework.

This diagram depicts the extendable modules present in the MenuFramework. Action Handler module Renderer module Parser module File Reader module The developer can get the MenuFramework handle by using the getInstance() API. After getting the Framework handle user can construct the menubar using the API createMenuBar(). The following code snippet will help to achieve the same. try{ MenuFramework mfw = MenuFramework.getInstance(); }catch(MenuException mex){ System.err.println("Error occurred" +"while getting the API Handle"); } For the Popup related operation the user can use the getPopupMenuFramework() API to get the Popup menu framework handle. MenuFramework supports creation of JMenuBar from an xml file. User has to pass the xml Document ( org.w3c.dom.Document;) as the input to the MenuFramework. The format of the xml file is defined in the MenuFramework.dtd file. The MenuFramework also provide an utility to read the xml file from the specified URL or file.

org.w3c.dom.Document xmlDocument = MenuFrameworkUtils.getDocument("../resources/MyMenuBar.xml")
or
org.w3c.dom.Document xmlDocument = MenuFrameworkUtils.getDocument(new java.net.URL("http://localhost/resources/MyMenuBar.xml"))

JMenuBar menuBar = mfw.createMenuBar(xmlDocument);

All the MenuBar created are cached by the framework. removeMenuBarFromCache("<menu bar namei>") API can be used to remove the MenuBar from the Framework cache.

After creating the MenuBar user can use the other API's provided by the MenuFramework to insert,remove or replace the MenuItems and Menus. The MenuItems and Menus in a particular MenuBar can be addressed by giving menupath. The path that contains the menubar and the series of menus through which user have to move to reach the particular menu item is called the menupath.For Example, the menu-item

"File ----> Open -----> Project" present in the MenuBar named MyMenuBar can be addressed as
"MyMenuBar"+ mfw.getMenuPathSeparator() +"File" +mfw.getMenuPathSeparator() +"Open" +mfw.getMenuPathSeparator() +"Project". By default the menupath separator is "#" (which can be configured using setMenuPathSeparator() API) so the, above menupath can be redifined as "MyMenuBar#File#Open#Project". Menupath helps the MenuFramework to uniquely identify the Menu/MenuItem present in a MenuBar. The user can delete this Project menu-item by simply invoking

mfw.removeXMLMenuItem("MyMenuBar#File#Open#Project")

Action Handler Module

MenuFramework handles the EventListeners in two different ways. It supports both creation of multiple instance for the same EventListener and reusing the existing EventListeners across the MenuBar as well as the ToolBars. When the resueListener is set to "true" using the API setReuseListeners , the same instance of EventListeners is shared across. The framework doesn't instantiate a new EventListeners every time, when it creates the menu-item, instead the same instance of EventListener is added as the Listener to the newly created menu-items. Whereas, in other case a new EventListener is created for each and every menu-item and they were notified when an event occurs. The reuseListeners will come handy when your application want to handle all the events occurring over all/set of menu-item at one place. This also gives a provision to share all the EventListener created in MenuFramework by the ToolBarFramework and vice versa. i.e. the EventListener created in MenuFramework can be reused to listen for an action occurring over a toolbar-item. All the cached EventListener's can be got using the API getListenerList

Renderer Module

MenuFramework supports check box and radio button rendering in the Menu-items. All the menu-items should implement the MenuItemInterface

Parser Module

MenuFramework provides an efficient parser to translate the input Menu File(in xml) format to the corresponding Menu Bar and Menu Elements. The custom menu-parser can be set using the API setMenuParser

File Reader Module

MenuFramework needs images and xml files for the construction of menu-elements. This resources can be fetched from the resource pool in different ways. By default this resources are searched from the directory from were the application runs. The user can plugin the custom FileReader by using any of these setFileReaderClassName or setFileReader API's. For further details refer to the FileReaderInterface.

See Also:

XMLMenuItem, XMLMenu, PopupMenuFramework

Field Summary

protected static MenuFramework	menuFramework
protected boolean	menuOpertaionBegin
protected static java.lang.Character	menuPathSeparator
protected boolean	propagateToParent

Constructor Summary

protected

MenuFramework() Instantiate Menu Frame Work with the no argument.

Method Summary

void	addSeparator(java.lang.String menuPath) Adds the Separator at the end of the specified JMenu.
protected java.lang.Boolean	addToMenuElementGroup(java.lang.String groupName, java.lang.Object menuElementObject) This API is used to add a menu or menu-item into the specified Menu Group.
javax.swing.JMenu	createMenu(org.w3c.dom.Document menuRootNode) Parse the given Document using the DefaultMenuParser and Returns the JMenu.
javax.swing.JMenu	createMenu(org.w3c.dom.Document menuRootNode, MenuParserInterface parser) Parse the given Document using the specified parser and Returns the JMenu.
javax.swing.JMenu	createMenu(org.w3c.dom.Document menuRootNode, java.lang.String parserClassName) Parse the given Document using the specified parser and Returns the JMenu.
javax.swing.JMenuBar	createMenuBar(org.w3c.dom.Document menuRootNode) Create a menu bar with the data available in the specified Document.
javax.swing.JMenuBar	createMenuBar(org.w3c.dom.Document menuRootNode, MenuParserInterface parser) Create a menu bar with the data available in the specified Document.
javax.swing.JMenuBar	createMenuBar(org.w3c.dom.Document menuRootNode, MenuParserInterface parser, java.lang.String menuBarNameToCache) Create a menu bar with the data available in the specified Document.
javax.swing.JMenuBar	createMenuBar(org.w3c.dom.Document menuRootNode, java.lang.String parserClassName) Create a menu bar with the data available in the specified Document.
protected MenuParserInterface	createMenuParser(java.lang.String className) This API is used to create the instance of MenuParserInterface.
boolean	doesTheMenuBarExist(java.lang.String menuBarName) Returns true if the menubar with the specified name is cached by the framework, else it returns false.
ActionHandlerInterface	getActionHandler() Returns the default action handler class.
java.lang.String	getActionHandlerClassName() Returns the default action handler class name.
java.util.Enumeration	getAllMenuBarNames() Returns the name of all cached menubars.
java.lang.String	getDefaultMenuParserClassName() Returns the class name of the Default Menu-Parser.
FileReaderInterface	getFileReader() Returns the fileReader instance which is presently used for reading the xml files and image files.
java.lang.String	getFileReaderClassName() Returns the currently used file reader class name which is used to read xml and image files.
static MenuFramework	getInstance() This API provides the MenuFramework handle using which the user can create MenuBar and manipulate the menus and/or menuitems.
javax.swing.JMenuItem	getJMenuItem(java.lang.String menuItemPath) Returns the JMenuItem if it exist at the specified menu path otherwise it returns null.
java.util.Hashtable	getListenerList() Returns the set of cached EventListeners.
javax.swing.JMenuBar	getMenuBar(java.lang.String menuBarName) Returns the menubar of the name specified.
MenuParserInterface	getMenuParser() Returns the MenuParser class instance which is presently used for parsing the xml documents to construct menu elements.
java.lang.String	getMenuParserClassName() Returns the MenuParser class name which is presently used for parsing the xml documents to construct menu elements.
char	getMenuPathSeparator() Returns the MenuPathSeparator.
static PopupMenuFramework	getPopupMenuFramework() This API provides the Popup MenuFramework handle using which the user can create Popup menus.
java.util.EventListener	getSingletonListenerInstance(java.lang.String listenerClassName) Returns an instance of EventListener for the specified classname.
static java.lang.String	getString(java.lang.String key)
XMLMenu	getXMLMenu(java.lang.String menuPathName) Returns XMLMenu from the Framework Cache.
XMLMenuItem	getXMLMenuItem(java.lang.String menuItemPath) Returns the XMLMenuItem which contains the JMenuItem, if it exist at the specified menu path otherwise it returns null.
protected java.util.Hashtable	getXMLMenuItemList() Returns all the menu and menu-items from all the cached Menu-bar.
java.util.Vector	getXMLMenus(java.lang.String menuBarName) Returns vector of top level JMenus (i.e the menus which are directly added in the menubar) present in the menubar.
protected static void	initializeFramework()
void	insertSeparatorAt(java.lang.String menuPath, int position) Inserts the Separator in the specified XMLMenu at the specified position.
boolean	insertXMLMenu(org.w3c.dom.Document rootNode, java.lang.String previousMenuPath) Inserts the XMLMenu at the specified path after constructing the XMLMenu from the input document.
boolean	insertXMLMenu(XMLMenu menu, java.lang.String previousMenuPath) Inserts the XMLMenu at the specified path.
boolean	insertXMLMenuAt(org.w3c.dom.Document rootNode, java.lang.String parentMenuPath, int position) Inserts the XMLMenu at the specified position after constructing the XMLMenu from the input document.
boolean	insertXMLMenuAt(XMLMenu menu, java.lang.String parentMenuPath, int position) Inserts the XMLMenu at the specified position.
boolean	insertXMLMenuItem(java.util.Hashtable menuItemAttributes, java.lang.String previousMenuItemPath) Construct a new XMLMenuItem from the given Hashtable and then Inserts the given XMLMenuItem after the specified menuitem.
boolean	insertXMLMenuItem(XMLMenuItem menuItem, java.lang.String previousMenuItemPath) Inserts the given XMLMenuItem after the specified menuitem.
boolean	insertXMLMenuItemAt(java.util.Hashtable menuItemAttributes, java.lang.String parentMenuPath, int position) Construct a new XMLMenuItem from the given Hashtable and then Inserts this menuitem in the given position of the parent jmenu.
boolean	insertXMLMenuItemAt(XMLMenuItem menuItem, java.lang.String parentMenuPath, int position) Inserts the given menuitem in the given position of the parent jmenu.
boolean	isActionPropagationAllowed() This returns true when the action handling is allowed to propagate to the topmost level(menbar level) until it is consumed by one of the ActionHandlers i.e when the handleAction() of the ActionHandlerInterface returns true.
protected boolean	putXMLMenuItem(java.lang.String menuItemPath, XMLMenuItem menuItem) API which updates the cache maintained by the Framework.
boolean	removeMenuBarFromCache(java.lang.String menuBarName) Clears the menuBar and all its traces from the menuframework cache.
void	removeMenuElementAt(java.lang.String parentMenuPath, int position) Removes the MenuElement( XMLMenu or XMLMenuItem or Separators) located at the specified position in the parentMenu.
void	removeSeparatorAt(java.lang.String menuPath, int position) Removes the Separator from the specified XMLMenu located at the specified position.
XMLMenu	removeXMLMenu(java.lang.String menuPath) Removes the XMLMenu frame the MenuBar.
XMLMenu	removeXMLMenuAt(java.lang.String parentMenuPath, int position) Removes the XMLMenu located at the specified position in the parentMenu.
XMLMenu	removeXMLMenuAt(XMLMenu parentMenu, int position) Removes the XMLMenu located at the specified position in the parentMenu.
void	removeXMLMenuItem(java.lang.String menuItemPath) Removes the specified XMLMenuItem from the menubar
void	removeXMLMenuItemAt(java.lang.String parentMenuPath, int position) Removes the MenuItem located at the specified position in the parent Menu.
boolean	replaceXMLMenu(org.w3c.dom.Document rootNode, java.lang.String menuPath) Replaces the XMLMenu at the specified path after creating new XMLMenu out of the specified document.
boolean	replaceXMLMenu(XMLMenu menu, java.lang.String menuPath) Replaces the XMLMenu at the specified path.
boolean	replaceXMLMenuAt(org.w3c.dom.Document rootNode, java.lang.String parentMenuPath, int position) Replaces the XMLMenu at the specified position after creating new XMLMenu out of the specified document.
boolean	replaceXMLMenuAt(XMLMenu menu, java.lang.String parentMenuPath, int position) Replaces the XMLMenu at the specified position.
void	replaceXMLMenuItem(java.util.Hashtable menuItemAttributes, java.lang.String menuItemPath) Replaces the MenuItem located at the specified menupath with the menuItem after creating it with specified attributes set.
void	replaceXMLMenuItem(java.util.Hashtable menuItemAttributes, XMLMenuItem oldMenuItem) Replaces the old menuItem with specified new menuitem created with the specified attributes.
void	replaceXMLMenuItem(XMLMenuItem item, java.lang.String menuItemPath) Replaces the MenuItem located at the specified menupath with the given menuItem.
void	replaceXMLMenuItem(XMLMenuItem newMenuItem, XMLMenuItem oldMenuItem) Replaces the old menuItem with specified new menuitem.
void	replaceXMLMenuItemAt(java.util.Hashtable menuItemAttributes, java.lang.String parentMenuPath, int position) Replaces the MenuItem located at the specified position in the parent Menu with the menuItem created using the given Hashtable.
void	replaceXMLMenuItemAt(XMLMenuItem item, java.lang.String parentMenuPath, int position) Replaces the MenuItem located at the specified position in the parent Menu with the given menuItem.
void	setActionHandler(ActionHandlerInterface actionhandlerinterface) Sets the specified Action Handler class as the Default Action Handler.
void	setActionHandlerClassName(java.lang.String s) Instantiate the ActionHandler for the specified class name and then sets this Action Handler class as the Default Action Handler.
void	setActionPropagation(boolean propagateToParent) Sets the propagation allowed property on or off.
void	setFileReader(FileReaderInterface filereaderinterface) Sets the fileReader instance which should be used for reading the xml and image files.
void	setFileReaderClassName(java.lang.String s) Instantiate the FileReader for the specified class name and then sets this File Reader class as the Default File Reader.
boolean	setMenuEnabled(java.lang.String menuItemPath, boolean enable) Enabels or Disables a particular Menu or MenuItem.
boolean	setMenuGroupEnabled(java.lang.String menuGroupName, boolean enable) Enables or Disables the group of menus.
void	setMenuParser(MenuParserInterface menuparserinterface) Sets the specified class as the Default Menu Parser.
void	setMenuParserClassName(java.lang.String s) Instantiate the MenuParser for the specified class name and then sets this Menu Parser class as the Default Menu Parser.
void	setMenuPathSeparator(char ch) Sets the given character as the menupath separator.
void	setResourceBundle(java.util.ResourceBundle pRBundle)
void	setReuseListeners(boolean reuseOfListeners) Sets the reuseListeners, which determines whether to create a new Instance of an EventListener including its subclass of EventListener or resuse the cached instance of EventListener.

Methods inherited from class java.lang.Object

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

Field Detail

menuFramework

protected static MenuFramework menuFramework

propagateToParent

protected boolean propagateToParent

menuPathSeparator

protected static java.lang.Character menuPathSeparator

menuOpertaionBegin

protected boolean menuOpertaionBegin

Constructor Detail

MenuFramework

protected MenuFramework()

Instantiate Menu Frame Work with the no argument.

Method Detail

initializeFramework

protected static void initializeFramework()
                                   throws MenuException

getInstance

public static MenuFramework getInstance()
                                 throws MenuFrameworkUnintializedException

This API provides the MenuFramework handle using which the user can create MenuBar and manipulate the menus and/or menuitems.

Returns:

a static instance of the MenuFramework

Throws:

MenuFrameworkUnintializedException - if an error occurs when the framework does not get initialized due to some class corruption or if the framework unable to find the required resources.

getPopupMenuFramework

public static PopupMenuFramework getPopupMenuFramework()
                                                throws MenuFrameworkUnintializedException

This API provides the Popup MenuFramework handle using which the user can create Popup menus.

Returns:

a static instance of the MenuFramework

Throws:

MenuFrameworkUnintializedException - if an error occurs while the

addToMenuElementGroup

protected java.lang.Boolean addToMenuElementGroup(java.lang.String groupName,
                                                  java.lang.Object menuElementObject)

This API is used to add a menu or menu-item into the specified Menu Group.

Parameters:

groupName - a String value of the groupName in which this menu/menu-item to be added.

menuElementObject - an menu or menu-item object which should be grouped.

Returns:

a Boolean value

See Also:

setMenuGroupEnabled()

createMenuBar

public javax.swing.JMenuBar createMenuBar(org.w3c.dom.Document menuRootNode)
                                   throws MenuException

Create a menu bar with the data available in the specified Document. It uses the DefaultMenuParser to parse the given document. MenuFramework cache this menu bar reference for further operation (like insert menu or menu item) .

Parameters:

menuRootNode - is a Document object.

Returns:

menuBar is a JMenuBar.

Throws:

MenuException - if an unrecoverable fatal error occurs

MenuException - is thrown when the framework unable to create menu-bar.

createMenuBar

public javax.swing.JMenuBar createMenuBar(org.w3c.dom.Document menuRootNode,
                                          java.lang.String parserClassName)
                                   throws MenuException

Create a menu bar with the data available in the specified Document. It uses the specified MenuParser to parse the given document. MenuFramework cache this menu bar reference for further operation (like insert menu or menu item) .

Parameters:

menuRootNode - is a Document object.

parserClassName - class name of the MenuParser which should be used for parsing the given document

Returns:

menuBar is a JMenuBar.

Throws:

MenuException - is thrown when the framework unable to create menu-bar.

createMenuBar

public javax.swing.JMenuBar createMenuBar(org.w3c.dom.Document menuRootNode,
                                          MenuParserInterface parser)
                                   throws MenuException

Create a menu bar with the data available in the specified Document. It uses the specified MenuParser to parse the given document. MenuFramework cache this menu bar reference for further operation (like insert menu or menu item) .

Parameters:

menuRootNode - is a Document object.

parser - instance of the MenuParser which should be used for parsing the given document

Returns:

menuBar is a JMenuBar.

Throws:

MenuException - is thrown when the framework unable to create menu-bar.

createMenuBar

public javax.swing.JMenuBar createMenuBar(org.w3c.dom.Document menuRootNode,
                                          MenuParserInterface parser,
                                          java.lang.String menuBarNameToCache)
                                   throws MenuException

Create a menu bar with the data available in the specified Document. It uses the specified MenuParser to parse the given document. MenuFramework cache this menu bar reference with the specified name for further operation (like insert menu or menu item) .

Parameters:

menuRootNode - is a Document object.

parser - instance of the MenuParser which should be used for parsing the given document

menuBarNameToCache - name in which the the created menubar to be cached.

Returns:

menuBar is a JMenuBar.

Throws:

MenuException - is thrown when the framework unable to create menu-bar.

getAllMenuBarNames

public java.util.Enumeration getAllMenuBarNames()

Returns the name of all cached menubars.

Returns:

an Enumeration value of all the cached menu-bar name.

getMenuBar

public javax.swing.JMenuBar getMenuBar(java.lang.String menuBarName)

Returns the menubar of the name specified. If the menubar does not exist, it returns null.

Parameters:

menuBarName - a String value representing the menu-bar name which is passes as an argument while creating the Menu-Bar or the "name attribute" present in the Menu-File.

Returns:

a JMenuBar instance corresponding to the specified menubar-name.

getXMLMenus

public java.util.Vector getXMLMenus(java.lang.String menuBarName)

Returns vector of top level JMenus (i.e the menus which are directly added in the menubar) present in the menubar.

Parameters:

menuBarName - a String value

Returns:

a Vector value

createMenu

public javax.swing.JMenu createMenu(org.w3c.dom.Document menuRootNode)
                             throws MenuException

Parse the given Document using the DefaultMenuParser and Returns the JMenu.

Parameters:

menuRootNode - a Document node which represent the Menu File.

Returns:

a JMenu value

Throws:

MenuException - if the framework unable to create JMenu instance due to some parsing error.

createMenu

public javax.swing.JMenu createMenu(org.w3c.dom.Document menuRootNode,
                                    java.lang.String parserClassName)
                             throws MenuException

Parse the given Document using the specified parser and Returns the JMenu.

Parameters:

menuRootNode - a Document node which represent the Menu File.

parserClassName - a String value

Returns:

a JMenu value

Throws:

MenuException - if the framework unable to create JMenu instance due to some

createMenu

public javax.swing.JMenu createMenu(org.w3c.dom.Document menuRootNode,
                                    MenuParserInterface parser)
                             throws MenuException

Parse the given Document using the specified parser and Returns the JMenu.

Parameters:

menuRootNode - a Document node which represent the Menu File.

parser - a MenuParserInterface which should be used to parse this particular Menu-File.

Returns:

a JMenu which is constructed from the specified

Throws:

MenuException - if the framework unable to create JMenu instance due to some

getXMLMenu

public XMLMenu getXMLMenu(java.lang.String menuPathName)

Returns XMLMenu from the Framework Cache. If the xmlmenu doesn't exist, it returns null.

Parameters:

menuPathName - a String that represents the menubar and the series of menus through which user have to move to reach the particular menu item/ menu.

Returns:

a XMLMenu value

insertXMLMenuItemAt

public boolean insertXMLMenuItemAt(XMLMenuItem menuItem,
                                   java.lang.String parentMenuPath,
                                   int position)
                            throws MenuException

Inserts the given menuitem in the given position of the parent jmenu. If position is less than 0 , the menu item is appended at the end.

Parameters:

menuItem - a XMLMenuItem instance which has to be inserted at the given location.

parentMenuPath - a String that represents the menubar and the series of menus through which user have to move to reach the parent menu.

position - an int value at which the user has to insert this particular menu-item.

Returns:

a true if the menu-item successfully added

Throws:

MenuException - if the framework unable to find the parent JMenu instance.

insertXMLMenuItemAt

public boolean insertXMLMenuItemAt(java.util.Hashtable menuItemAttributes,
                                   java.lang.String parentMenuPath,
                                   int position)
                            throws MenuException

Construct a new XMLMenuItem from the given Hashtable and then Inserts this menuitem in the given position of the parent jmenu. If position is less than 0 , the menuItem is appended at the end.

Parameters:

menuItemAttributes - a Hashtable value representing the attributes based on which XMLMenuItem has to be created.

parentMenuPath - a String that represents the menubar and the series of menus through which user have to move to reach the parent menu.

position - an int value at which the user has to insert this particular menu-item.

Returns:

a boolean value

Throws:

MenuException - if the framework unable to find the parent JMenu instance.

insertXMLMenuItem

public boolean insertXMLMenuItem(XMLMenuItem menuItem,
                                 java.lang.String previousMenuItemPath)
                          throws MenuException

Inserts the given XMLMenuItem after the specified menuitem.

Parameters:

menuItem - a XMLMenuItem value

previousMenuItemPath - a String value that represents the menubar and the series of menus through which user have to move to reach the previous menu.

Returns:

true when the menu-item is successfully inserted.

Throws:

MenuException - if the framework unable to find the previous menu-item

insertXMLMenuItem

public boolean insertXMLMenuItem(java.util.Hashtable menuItemAttributes,
                                 java.lang.String previousMenuItemPath)
                          throws MenuException

Construct a new XMLMenuItem from the given Hashtable and then Inserts the given XMLMenuItem after the specified menuitem.

Parameters:

menuItemAttributes - a Hashtable value representing the attributes based on which XMLMenuItem has to be created.

previousMenuItemPath - a String value that represents the menubar and the series of menus through which user have to move to reach the previous menu.

Returns:

true when the menu-item is successfully inserted.

Throws:

MenuException - if the framework unable to find the previous menu-item

replaceXMLMenuItemAt

public void replaceXMLMenuItemAt(XMLMenuItem item,
                                 java.lang.String parentMenuPath,
                                 int position)
                          throws MenuException

Replaces the MenuItem located at the specified position in the parent Menu with the given menuItem.

Parameters:

item - a XMLMenuItem which has to be replaced.

parentMenuPath - a String value that represents the menubar and the series of menus through which user have to move to reach the parent menu.

position - an int value at which the menu-item has to replaced, present in the parent menu.

Throws:

MenuException - if the framework unable to find the parent menu-item

replaceXMLMenuItemAt

public void replaceXMLMenuItemAt(java.util.Hashtable menuItemAttributes,
                                 java.lang.String parentMenuPath,
                                 int position)
                          throws MenuException

Replaces the MenuItem located at the specified position in the parent Menu with the menuItem created using the given Hashtable.

Parameters:

menuItemAttributes - a Hashtable value representing the attributes based on which XMLMenuItem has to be created.

parentMenuPath - a String that represents the menubar and the series of menus through which user have to move to reach the particular parent menu.

position - an int value at which the menu-item has to replaced, present in the parent menu.

Throws:

MenuException - if an error occurs

replaceXMLMenuItem

public void replaceXMLMenuItem(XMLMenuItem item,
                               java.lang.String menuItemPath)
                        throws MenuException

Replaces the MenuItem located at the specified menupath with the given menuItem.

Parameters:

item - a XMLMenuItem instance which has to be replaced in place of given menuItemPath.

menuItemPath - a String that represents the menubar and the series of menus through which user have to move to reach the particular menu item/ menu.

Throws:

MenuException - if the framework unable to find the specified menu-item at the specified menu-path.

replaceXMLMenuItem

public void replaceXMLMenuItem(java.util.Hashtable menuItemAttributes,
                               java.lang.String menuItemPath)
                        throws MenuException

Replaces the MenuItem located at the specified menupath with the menuItem after creating it with specified attributes set.

Parameters:

menuItemAttributes - a Hashtable value representing the attributes based on which XMLMenuItem has to be created. through which user have to move to reach the particular menu item/ menu.

menuItemPath - a String that represents the menubar and the series of menus through which user have to move to reach the particular menu item/ menu.

Throws:

MenuException - if the framework unable to find the specified menu-item at the specified menu-path.

replaceXMLMenuItem

public void replaceXMLMenuItem(java.util.Hashtable menuItemAttributes,
                               XMLMenuItem oldMenuItem)
                        throws MenuException

Replaces the old menuItem with specified new menuitem created with the specified attributes.

Parameters:

menuItemAttributes - a Hashtable value representing the attributes based on which XMLMenuItem has to be created.

oldMenuItem - a XMLMenuItem instance which has to be repalced with the new menu-item (constructed out of the menuItemAttributes) specified.

Throws:

MenuException - if an error occurs while replacing the XMLMenuItem

replaceXMLMenuItem

public void replaceXMLMenuItem(XMLMenuItem newMenuItem,
                               XMLMenuItem oldMenuItem)
                        throws MenuException

Replaces the old menuItem with specified new menuitem.

Parameters:

newMenuItem - a XMLMenuItem instance which should replace the old one existing in the menu-bar.

oldMenuItem - a XMLMenuItem instance which has to be repalced with the new menu-item specified.

Throws:

MenuException - if an error occurs while replacing the XMLMenuItem

removeXMLMenuItemAt

public void removeXMLMenuItemAt(java.lang.String parentMenuPath,
                                int position)
                         throws MenuException

Removes the MenuItem located at the specified position in the parent Menu.

Parameters:

parentMenuPath - a String that represents the menubar and the series of menus * through which user have to move to reach the particular parent menu.

position - an int of the menu-item which has to removed.

Throws:

MenuException - if an error occurs

removeMenuElementAt

public void removeMenuElementAt(java.lang.String parentMenuPath,
                                int position)
                         throws MenuException

Removes the MenuElement( XMLMenu or XMLMenuItem or Separators) located at the specified position in the parentMenu.

Parameters:

parentMenuPath - a String that represents the menubar and the series of menus * through which user have to move to reach the particular parent menu.

position - an int of the menu-item/menu which has to removed.

Throws:

MenuException - if an error occurs

removeXMLMenuAt

public XMLMenu removeXMLMenuAt(java.lang.String parentMenuPath,
                               int position)
                        throws MenuException

Removes the XMLMenu located at the specified position in the parentMenu.

Parameters:

parentMenuPath - a String that represents the menubar and the series of menus * through which user have to move to reach the particular parent menu.

position - an int of the menu-item/menu which has to removed.

Returns:

a XMLMenu instance which is removed from the menubar.

Throws:

MenuException - if an error occurs

removeXMLMenuAt

public XMLMenu removeXMLMenuAt(XMLMenu parentMenu,
                               int position)
                        throws MenuException

Removes the XMLMenu located at the specified position in the parentMenu.

Parameters:

parentMenu - a XMLMenu in whcih the XMLMenu to be replaced, exists.

position - an int of the menu-item/menu which has to removed.

Returns:

a XMLMenu instance which is removed from the menubar.

Throws:

MenuException - if an error occurs

removeXMLMenu

public XMLMenu removeXMLMenu(java.lang.String menuPath)
                      throws MenuException

Removes the XMLMenu frame the MenuBar.

Parameters:

menuPath - a String that represents the menubar and the series of menus through which user have to move to reach the particular menu item/ menu.

Returns:

a XMLMenu instance which is removed from the menubar.

Throws:

MenuException - if an error occurs

doesTheMenuBarExist

public boolean doesTheMenuBarExist(java.lang.String menuBarName)

Returns true if the menubar with the specified name is cached by the framework, else it returns false.

Parameters:

menuBarName - a String value representing the menu-bar name which is passes as an argument while creating the Menu-Bar or the "name attribute" present in the Menu-File.

Returns:

a true when the menu-bar of specified name exist in the cache.

removeXMLMenuItem

public void removeXMLMenuItem(java.lang.String menuItemPath)
                       throws MenuException

Removes the specified XMLMenuItem from the menubar

Parameters:

menuItemPath - a String that represents the menubar and the series of menus through which user have to move to reach this particular menu item.

Throws:

MenuException - if the framework unable to find the specified menu-item

insertXMLMenuAt

public boolean insertXMLMenuAt(XMLMenu menu,
                               java.lang.String parentMenuPath,
                               int position)
                        throws MenuException

Inserts the XMLMenu at the specified position.

Parameters:

menu - a XMLMenu instance which has to be inserted.

parentMenuPath - a String that represents the menubar and the series of menus through which user have to move to reach the particular parent menu.

position - an int value at which the menu-item has to inserted.

Returns:

a true when insert succeeds.

Throws:

MenuException - if the framework unable to find the parent menu-item

insertXMLMenuAt

public boolean insertXMLMenuAt(org.w3c.dom.Document rootNode,
                               java.lang.String parentMenuPath,
                               int position)
                        throws MenuException

Inserts the XMLMenu at the specified position after constructing the XMLMenu from the input document.

Parameters:

rootNode - a Document value which should be used to construct the XMLMenu.

parentMenuPath - a String that represents the menubar and the series of menus through which user have to move to reach the particular parent menu.

position - an int value at which the menu has to be inserted in the parent menu.

Returns:

a true when the insertion succeeds.

Throws:

MenuException - if an error occurs

insertXMLMenu

public boolean insertXMLMenu(org.w3c.dom.Document rootNode,
                             java.lang.String previousMenuPath)
                      throws MenuException

Inserts the XMLMenu at the specified path after constructing the XMLMenu from the input document.

Parameters:

rootNode - a Document value which should be used to construct the XMLMenu.

previousMenuPath - a String that represents the menubar and the series of menus through which user have to move to reach the previous menu after which the specified menu is going to be inserted.

Returns:

a true when the insertion succeeds.

Throws:

MenuException - if an error occurs

insertXMLMenu

public boolean insertXMLMenu(XMLMenu menu,
                             java.lang.String previousMenuPath)
                      throws MenuException

Inserts the XMLMenu at the specified path.

Parameters:

menu - a XMLMenu which has to be inserted.

previousMenuPath - a String that represents the menubar and the series of menus through which user have to move to reach the particular menu.

Returns:

a true if insertion succeeds.

Throws:

MenuException - if an error occurs

replaceXMLMenuAt

public boolean replaceXMLMenuAt(XMLMenu menu,
                                java.lang.String parentMenuPath,
                                int position)
                         throws MenuException

Replaces the XMLMenu at the specified position.

Parameters:

menu - a XMLMenu which has to be replaced.

parentMenuPath - a String that represents the menubar and the series of menus through which user have to move to reach the parent menu under which this menu-item has to be replaced.

position - an int value at which the menu-item has to replaced, present in the parent menu.

Returns:

a true when replace succeeds.

Throws:

MenuException - if an error occurs

replaceXMLMenuAt

public boolean replaceXMLMenuAt(org.w3c.dom.Document rootNode,
                                java.lang.String parentMenuPath,
                                int position)
                         throws MenuException

Replaces the XMLMenu at the specified position after creating new XMLMenu out of the specified document.

Parameters:

rootNode - a Document value which should be used to construct the XMLMenu.

parentMenuPath - a String that represents the menubar and the series of menus through which user have to move to reach the parent menu under which this menu-item has to be replaced.

position - an int value at which the menu-item has to replaced, present in the parent menu.

Returns:

a true when replace succeeds.

Throws:

MenuException - if an error occurs

replaceXMLMenu

public boolean replaceXMLMenu(XMLMenu menu,
                              java.lang.String menuPath)
                       throws MenuException

Replaces the XMLMenu at the specified path.

Parameters:

menu - a XMLMenu instance which has to be used to replace the older menu .

menuPath - a String that represents the menubar and the series of menus through which user have to move to reach the this menu which item has to be replaced.

Returns:

a true when replace succeeds.

Throws:

MenuException - if an error occurs

replaceXMLMenu

public boolean replaceXMLMenu(org.w3c.dom.Document rootNode,
                              java.lang.String menuPath)
                       throws MenuException

Replaces the XMLMenu at the specified path after creating new XMLMenu out of the specified document.

Parameters:

rootNode - a Document value which should be used to construct the XMLMenu.

menuPath - a String that represents the menubar and the series of menus through which user have to move to reach the particular menu item/ menu.

Returns:

a true when replace succeeds.

Throws:

MenuException - if an error occurs

isActionPropagationAllowed

public boolean isActionPropagationAllowed()

This returns true when the action handling is allowed to propagate to the topmost level(menbar level) until it is consumed by one of the ActionHandlers i.e when the handleAction() of the ActionHandlerInterface returns true. By default it is turned on.

Returns:

true if the Action propagation is allowed.

setActionPropagation

public void setActionPropagation(boolean propagateToParent)

Sets the propagation allowed property on or off. When it is on the action handling is allowed to propagate to the topmost level(menbar level) until it is consumed by one of the ActionHandlers i.e when the handleAction() of the ActionHandlerInterface returns true.

Parameters:

propagateToParent - a boolean value

setMenuGroupEnabled

public boolean setMenuGroupEnabled(java.lang.String menuGroupName,
                                   boolean enable)

Enables or Disables the group of menus.

Parameters:

menuGroupName - a String name which represent the "group_name" specified in the menu-file which is used to construct menu-bar.

enable - a boolean to enable the group of menu and/or menu-item.

Returns:

a true if this enabling operation succeeds.

setMenuEnabled

public boolean setMenuEnabled(java.lang.String menuItemPath,
                              boolean enable)

Enabels or Disables a particular Menu or MenuItem.

Parameters:

menuItemPath - a String that represents the menubar and the series of menus * through which user have to move to reach the particular menu item/ menu.

enable - a boolean to enable the menu or menu-item.

Returns:

a true if this enabling operation succeeds.

getMenuPathSeparator

public char getMenuPathSeparator()

Returns the MenuPathSeparator. The MenuFramework uniquely identifies the MenuItem using their MenuPath. MenuPath represents the menubar and the series of menus through which user have to move to reach the particular menu item/ menu. If a menu item called Open exist under the Menu File of the DefaultMenuBar it is addressed as "DefaultMenuBar"+getMenuPathSeparator()+"File"+getMenuPathSeparator()+"Open" By Default the MenuPathSeparator is "#" which can be modified before the creation of MenuBar,so the menupath will be "DefaultMenuBar#File#Open"

Returns:

a charrepresenting the MenuPathSeparator

addSeparator

public void addSeparator(java.lang.String menuPath)

Adds the Separator at the end of the specified JMenu.

Parameters:

menuPath - a String that represents the menubar and the series of menus through which user have to move to reach the particular menu, after which this separator should be added.

removeSeparatorAt

public void removeSeparatorAt(java.lang.String menuPath,
                              int position)

Removes the Separator from the specified XMLMenu located at the specified position.

Parameters:

menuPath - a String that represents the menubar and the series of menus through which user have to move to reach the particular parent menu where this separator reside.

position - an int value at which this separator resides.

insertSeparatorAt

public void insertSeparatorAt(java.lang.String menuPath,
                              int position)

Inserts the Separator in the specified XMLMenu at the specified position.

Parameters:

menuPath - a String that represents the menubar and the series of menus through which user have to move to reach the particular parent menu where this separator has to be inserted.

position - an int value at which the separator has to nserted.

putXMLMenuItem

protected boolean putXMLMenuItem(java.lang.String menuItemPath,
                                 XMLMenuItem menuItem)

API which updates the cache maintained by the Framework.

Parameters:

menuItemPath - a String value

menuItem - a XMLMenuItem value

Returns:

a boolean value

getXMLMenuItem

public XMLMenuItem getXMLMenuItem(java.lang.String menuItemPath)

Returns the XMLMenuItem which contains the JMenuItem, if it exist at the specified menu path otherwise it returns null.

Parameters:

menuItemPath - a String that represents the menubar and the series of menus * through which user have to move to reach the particular menu item/ menu.

Returns:

a XMLMenuItem instance which resides at this specified location.

getJMenuItem

public javax.swing.JMenuItem getJMenuItem(java.lang.String menuItemPath)

Returns the JMenuItem if it exist at the specified menu path otherwise it returns null.

Parameters:

menuItemPath - a String that represents the menubar and the series of menus * through which user have to move to reach the particular menu item/ menu.

Returns:

a JMenuItem instance which resides at the specified location.

getFileReaderClassName

public java.lang.String getFileReaderClassName()

Returns the currently used file reader class name which is used to read xml and image files. The Default implementation of the file reader will read from the urls if starts with "http://" or by prepending the working directory i.e. the directory from which the application is invoked to the filename.

Returns:

a String representing the fully qualified class name of the FileReaderInterface which is presently by the framework to read the resources(images).

See Also:

DefaultFileReader, setFileReaderClassName(java.lang.String)

setFileReaderClassName

public void setFileReaderClassName(java.lang.String s)
                            throws MenuException

Instantiate the FileReader for the specified class name and then sets this File Reader class as the Default File Reader. File Reader is used to read the xml files and image files which can be read from different resources and in different fashion. The Default implementation of the file reader will read from the urls if starts with "http://" or by prepending the working directory i.e. the directory from which the application is invoked to the filename.

Parameters:

s - a String value representing the fully qualified class name which should be used to fetch the resources such as images and XML Documents.

Throws:

MenuException - if an error occurs while instantiating the specified Class which implements FileReaderInterface

See Also:

DefaultFileReader, getFileReaderClassName()

getFileReader

public FileReaderInterface getFileReader()

Returns the fileReader instance which is presently used for reading the xml files and image files. The Default implementation of the file reader will read from the urls if starts with "http://" or by prepending the working directory i.e. the directory from which the application is invoked to the filename.

See Also:

DefaultFileReader, setFileReader(com.adventnet.components.projectworkspace.FileReaderInterface)

setFileReader

public void setFileReader(FileReaderInterface filereaderinterface)

Sets the fileReader instance which should be used for reading the xml and image files. The Default implementation of the file reader will read from the urls if starts with "http://" or by prepending the working directory i.e. the directory from which the application is invoked to the filename.

Parameters:

filereaderinterface - a FileReaderInterface instance which can be used to fetch the resources need to construct the menu-bar.

See Also:

DefaultFileReader, getFileReader()

setMenuParserClassName

public void setMenuParserClassName(java.lang.String s)
                            throws MenuException

Instantiate the MenuParser for the specified class name and then sets this Menu Parser class as the Default Menu Parser. Menu Parser is used to translate the xml nodes into the corresponding XML menus and/or XML menuitems.

Parameters:

s - a String value representing fully qualified classname of the parser class which has to be used for parsing the specified XML Document to construct the menubar.

Throws:

MenuException - if an error occurs while instantiating the parser class.

See Also:

DefaultMenuParser, getMenuParserClassName()

getMenuParserClassName

public java.lang.String getMenuParserClassName()

Returns the MenuParser class name which is presently used for parsing the xml documents to construct menu elements.

Returns:

a String value representing fully qualified classname of the parser class which is presently used for parsing the specified XML Document to construct the menubar.

See Also:

DefaultMenuParser, setMenuParserClassName(java.lang.String)

setMenuParser

public void setMenuParser(MenuParserInterface menuparserinterface)

Sets the specified class as the Default Menu Parser. This Menu Parser is used to translate the xml nodes into the corresponding XML menus and/or XML menuitems.

Parameters:

menuparserinterface - a MenuParserInterface value of the parser class which is presently used for parsing the specified XML Document to construct the menubar.

See Also:

DefaultMenuParser, getMenuParser()

getMenuParser

public MenuParserInterface getMenuParser()

Returns the MenuParser class instance which is presently used for parsing the xml documents to construct menu elements.

Returns:

a MenuParserInterface value of the parser class which is presently used for parsing the specified XML Document to construct the menubar.

See Also:

DefaultMenuParser, setMenuParser(com.adventnet.components.menuframework.MenuParserInterface)

getActionHandlerClassName

public java.lang.String getActionHandlerClassName()

Returns the default action handler class name. Default ActionHandler is an action handler which is invoked when none of the menitem specific ActionHandler handle the action.

Returns:

a String value representing the Action handler class name which presently handles the default actions which are not handled by the menu specific Action handlers and Action Listeners.

See Also:

DefaultActionHandler, getActionHandlerClassName()

setActionHandlerClassName

public void setActionHandlerClassName(java.lang.String s)
                               throws MenuException

Instantiate the ActionHandler for the specified class name and then sets this Action Handler class as the Default Action Handler. Default ActionHandler is an action handler which is invoked when none of the menitem specific ActionHandler handle the action.

Parameters:

s - a String value representing the Action handler class name which should be used to handle the default actions which are not handled by the menu specific Action handlers and Action Listeners.

Throws:

MenuException - if an error occurs

See Also:

DefaultActionHandler, setActionHandlerClassName(java.lang.String)

getActionHandler

public ActionHandlerInterface getActionHandler()

Returns the default action handler class. Default ActionHandler is an action handler which is invoked when none of the menitem specific ActionHandler do not handle the action.Default ActionHandler is an action handler which is invoked when none of the menitem specific ActionHandler handle the action.

Returns:

a ActionHandlerInterface value representing the Action handler class which presently handles the default actions which are not handled by the menu specific Action handlers and Action Listeners.

See Also:

getActionHandler(), DefaultActionHandler

setActionHandler

public void setActionHandler(ActionHandlerInterface actionhandlerinterface)

Sets the specified Action Handler class as the Default Action Handler.

Parameters:

actionhandlerinterface - a String value representing the Action handler class which should be used to handle the default actions which are not handled by the menu specific Action handlers and Action Listeners.

Throws:

MenuException - if an error occurs

See Also:

DefaultActionHandler, setActionHandler(com.adventnet.components.projectworkspace.ActionHandlerInterface)

setMenuPathSeparator

public void setMenuPathSeparator(char ch)
                          throws MenuException

Sets the given character as the menupath separator. This should be specified before any of the Menu Operation begin i.e it should be the first statement after getting the MenuFramework instance.

Parameters:

ch - a char value that represents the MenuPath Separator.

Throws:

MenuException - if an error occurs

getXMLMenuItemList

protected java.util.Hashtable getXMLMenuItemList()

Returns all the menu and menu-items from all the cached Menu-bar.

Returns:

a Hashtable with the keys as menu-path and values as the XMLMenu and/or XMLMenuItem

getDefaultMenuParserClassName

public java.lang.String getDefaultMenuParserClassName()

Returns the class name of the Default Menu-Parser.

Returns:

a String value "com.adventnet.components.menuframework.DefaultMenuParser"

createMenuParser

protected MenuParserInterface createMenuParser(java.lang.String className)
                                        throws MenuException

This API is used to create the instance of MenuParserInterface.

removeMenuBarFromCache

public boolean removeMenuBarFromCache(java.lang.String menuBarName)

Clears the menuBar and all its traces from the menuframework cache. It doesn't remove the assosiated EventListeners from the listener list cache which should to be cleaned up manually.

Parameters:

menuBarName - a String value represnting the name of the menu-bar which is specified at the time of menu-bar creation or in the XML File.

Returns:

a true if the menu-bar exist in the cache and the framework is able to remove it successfully.

setReuseListeners

public void setReuseListeners(boolean reuseOfListeners)

Sets the reuseListeners, which determines whether to create a new Instance of an EventListener including its subclass of EventListener or resuse the cached instance of EventListener. This comes handy when a single ActionListener class listens for multiple menuitems and the user don't want to create a different instance for each and every menuitem. By default it is set to true i.e. the same instance of an listner is shared by all the menuitems. Note that this reuseListener boolean is shared between the MenuFramework and ToolBarFramework An EventListener(ActionListener) created in the MenuFramework were reused in the ToolBar framework, since most of the applications will have some common functionalities which the menu-item and toolbar-item as to do.

Parameters:

reuseOfListeners - if it set to "true" then multiple instance of same listener is not created

See Also:

getSingletonListenerInstance(java.lang.String), getListenerList()

getListenerList

public java.util.Hashtable getListenerList()

Returns the set of cached EventListeners. It returns the instance of EventListeners which are created only when the reuse listener is set to true. When the reuse listener is set to false, it either returns "null" or set of old EventListeners which are created when the reuse listeners is set to true previously. Note that this set of EventListeners list is shared between the MenuFramework and ToolBarFramework

Returns:

a hashtable with key as class name and value as the instance of that EventListener class

See Also:

getSingletonListenerInstance(java.lang.String), setReuseListeners(boolean)

getSingletonListenerInstance

public java.util.EventListener getSingletonListenerInstance(java.lang.String listenerClassName)

Returns an instance of EventListener for the specified classname. When the reuseListeners is set to true the framework searches for the EventListener in the Cache and returns it, if it doesn't exist in the cache it creates a new instance of this class and updates the cache. Else it creates and returns new Instance everytime. Note that this API updates the cache which is shared by both MenuFramework and ToolBarFramework

Parameters:

listenerClassName - Class name of the EventListener

Returns:

instance of EventListener

See Also:

setReuseListeners(boolean)

setResourceBundle

public void setResourceBundle(java.util.ResourceBundle pRBundle)

getString

public static java.lang.String getString(java.lang.String key)