org.apache.click.extras.control
Class MenuFactory

java.lang.Object
  org.apache.click.extras.control.MenuFactory

All Implemented Interfaces:

Serializable

public class MenuFactory
extends Object
implements Serializable

Provides a Menu factory for creating application menus from configuration files.

Menu factory provides a variety of getRootMenu() methods for loading the menus. The default getRootMenu() method creates menus from the configuration file /WEB-INF/menu.xml, or the classpath resource /menu.xml if WEB-INF/menu.xml was not resolved.

Below is an example menu.xml configuration file:

 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <menu>
    <menu label="Home" path="user/home.htm" roles="tomcat, role1"/>
    <menu label="User" path="user/home.htm" roles="tomcat, role1">
        <menu label="User Page 1" path="user/user-1.htm" roles="tomcat, role1"/>
        <menu label="User Page 2" path="user/user-2.htm" roles="tomcat, role1"/>
    </menu>
    <menu label="Admin" path="admin/admin-1.htm" roles="role1">
        <menu label="Admin Page 1" path="admin/admin-1.htm" roles="tomcat, role1"/>
        <menu label="Admin Page 2" path="admin/admin-2.htm" roles="tomcat, role1"/>
    </menu>
 </menu> 

You can also specify an alternative configuration file name to load your menus from. Just use one of the getRootMenu methods that accept a configuration file name, for example getRootMenu(name, fileName).

MenuFactory Examples

Below is an example of a MenuFactory being used to set the rootMenu on a border page. Typically a border page will define a page template which contain the surrounding page chrome including the header and the application menu. Application page classes will subclass the BorderPage an inherit the application rootMenu.

 public abstract class BorderPage extends Page {

     private Menu rootMenu;

     public BorderPage() {
         MenuFactory menuFactory = new MenuFactory();
         rootMenu = menuFactory.getRootMenu();
         addControl(rootMenu);
     }

     @Override
     public String getTemplate() {
         return "/border-template.htm";
     }

 } 

Stateful pages

Please note if you use stateful pages that are serialized, you probably won't want your application menu being serialized to disk or across a cluster with your page as well. In these scenarios please follow the pattern below.

 public abstract class BorderPage extends Page {

     // Note the transient keyword
     private transient Menu rootMenu;

     @Override
     public void onInit() {
         super.onInit();

         MenuFactory menuFactory = new MenuFactory();
         rootMenu = menuFactory.getRootMenu();
         addControl(rootMenu);
     }

     @Override
     public void onDestroy() {
         if (rootMenu != null) {
             removeControl(rootMenu);
         }

         super.onDestroy();
     }

 } 

Caching

Loading Menus using getRootMenu() will automatically cache the menus for improved performance (technically the menus are only cached when Click is in production or profile mode).

If you want to manage Menu caching yourself, use one of the getRootMenu methods that accepts a boolean controlling whether or not the menus are cached.

A common use case for caching menus yourself is when you need to customize the menus based on the logged in user. For this scenario you would load the Menus using getRootMenu(false), customize the menus according to the user profile, and cache the menus in the HttpSession.

See Also:

Menu, Serialized Form

Field Summary

protected static Set<String>	DEFAULT_ATTRIBUTES The default Menu XML attributes loaded into menu properties.
protected static String	DEFAULT_CONFIG_FILE The menu configuration filename: "menu.xml".
static String	DEFAULT_ROOT_MENU_NAME The default root menu name: "rootMenu".
protected static Map<String,Menu>	MENU_CACHE The menu cache.

Constructor Summary

MenuFactory()

Method Summary

protected Menu	buildMenu(Element menuElement, AccessController accessController, Class<? extends Menu> menuClass) Build a new Menu from the given menu item XML Element and recurse through all the menu-items children.
protected void	cacheRootMenu(Menu menu) Cache the given menu in the menu cache.
protected Menu	createMenu(Class<? extends Menu> menuClass) Create a new menu instance of the given menu class.
protected Map<String,Menu>	getMenuCache() Return the map containing menus cached by name.
Menu	getRootMenu() Return cached root menu item defined in the WEB-INF/menu.xml or classpath menu.xml, creating menu items using the Menu class and the JEE RoleAccessController.
Menu	getRootMenu(AccessController accessController) Return root menu item defined in the WEB-INF/menu.xml or classpath menu.xml, creating menu items using the Menu class and the provided AccessController.
Menu	getRootMenu(boolean cached) Return root menu item defined in the WEB-INF/menu.xml or classpath menu.xml, creating menu items using the Menu class and the JEE RoleAccessController.
Menu	getRootMenu(Class<? extends Menu> menuClass) Return root menu item defined in the WEB-INF/menu.xml or classpath menu.xml, creating menu items using the provided menu class and the JEE RoleAccessController.
Menu	getRootMenu(String name, String fileName) Return root menu item defined by the given name and fileName under WEB-INF or the classpath, creating menu items using the Menu class and the JEE RoleAccessController.
Menu	getRootMenu(String name, String fileName, AccessController accessController, boolean cached, Class<? extends Menu> menuClass) Return root menu item defined by the given name and fileName under WEB-INF or the classpath, creating menu items using the provided menu class and AccessController.
protected Menu	loadFromMenuXml(String name, String fileName, AccessController accessController, Class<? extends Menu> menuClass) Return a copy of the Applications root Menu as defined by the configuration file.
protected Menu	retrieveRootMenu(String name) Return the cached root menu from the menu cache.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_ROOT_MENU_NAME

public static final String DEFAULT_ROOT_MENU_NAME

The default root menu name: "rootMenu".

See Also:

Constant Field Values

DEFAULT_CONFIG_FILE

protected static final String DEFAULT_CONFIG_FILE

The menu configuration filename: "menu.xml".

See Also:

Constant Field Values

DEFAULT_ATTRIBUTES

protected static final Set<String> DEFAULT_ATTRIBUTES

The default Menu XML attributes loaded into menu properties.

MENU_CACHE

protected static final Map<String,Menu> MENU_CACHE

The menu cache.

Constructor Detail

MenuFactory

public MenuFactory()

Method Detail

getRootMenu

public Menu getRootMenu()

Return cached root menu item defined in the WEB-INF/menu.xml or classpath menu.xml, creating menu items using the Menu class and the JEE RoleAccessController.

Returns:

the cached root menu item defined in the WEB-INF/menu.xml file or menu.xml in the root classpath

See Also:

RoleAccessController

getRootMenu

public Menu getRootMenu(Class<? extends Menu> menuClass)

Return root menu item defined in the WEB-INF/menu.xml or classpath menu.xml, creating menu items using the provided menu class and the JEE RoleAccessController.

Parameters:

menuClass - the menu class to create new Menu instances from

Returns:

the cached root menu item defined in the WEB-INF/menu.xml file or menu.xml in the root classpath

getRootMenu

public Menu getRootMenu(AccessController accessController)

Return root menu item defined in the WEB-INF/menu.xml or classpath menu.xml, creating menu items using the Menu class and the provided AccessController.

Parameters:

accessController - the menu access controller

Returns:

the root menu item defined in the WEB-INF/menu.xml file or menu.xml in the root classpath

getRootMenu

public Menu getRootMenu(boolean cached)

Return root menu item defined in the WEB-INF/menu.xml or classpath menu.xml, creating menu items using the Menu class and the JEE RoleAccessController. The cached option specifies whether the loaded menus will be cached or not.

Parameters:

cached - return the cached menu if in production or profile mode, otherwise create and return a new root menu instance

Returns:

the root menu item defined in the WEB-INF/menu.xml file or menu.xml in the root classpath

getRootMenu

public Menu getRootMenu(String name,
                        String fileName)

Return root menu item defined by the given name and fileName under WEB-INF or the classpath, creating menu items using the Menu class and the JEE RoleAccessController.

Parameters:

name - the name of the root menu

fileName - the fileName defining the menu definitions

Returns:

the root menu item defined by the fileName under WEB-INF or the classpath

getRootMenu

public Menu getRootMenu(String name,
                        String fileName,
                        AccessController accessController,
                        boolean cached,
                        Class<? extends Menu> menuClass)

Return root menu item defined by the given name and fileName under WEB-INF or the classpath, creating menu items using the provided menu class and AccessController. The cached option specifies whether the loaded menus will be cached or not.

Example usage:

 public void onInit() {
     MenuFactory factory = new MenuFactory();
     String menuName = "mymenu";
     String fileName = "mymenu.xml";
     AccessController accessController = new RoleAccessController();
     boolean cached = true;

     factory.getRootMenu(menuName, fileName, accessController, cached, MyMenu.class);
 } 

Parameters:

name - the name of the root menu

fileName - the fileName defining the menu definitions

accessController - the menu access controller

cached - return the cached menu if in production or profile mode, otherwise create and return a new root menu instance

menuClass - the menu class to create new Menu instances from

Returns:

the root menu item defined by the fileName under WEB-INF or the classpath

buildMenu

protected Menu buildMenu(Element menuElement,
                         AccessController accessController,
                         Class<? extends Menu> menuClass)

Build a new Menu from the given menu item XML Element and recurse through all the menu-items children. If the menuClass is specified, menus will be created of that type, otherwise an instance of Menu will be created.

Parameters:

menuElement - the menu item XML Element

accessController - the menu access controller

menuClass - the menu class to instantiate

Returns:

new Menu instance for the given XML menuElement

createMenu

protected Menu createMenu(Class<? extends Menu> menuClass)

Create a new menu instance of the given menu class.

Parameters:

menuClass - the menu class to instantiate

Returns:

a new menu instance of the given menu class

loadFromMenuXml

protected Menu loadFromMenuXml(String name,
                               String fileName,
                               AccessController accessController,
                               Class<? extends Menu> menuClass)

Return a copy of the Applications root Menu as defined by the configuration file.

If the fileName starts with a '/' character it is assumed to be an absolute path and Click will attempt to load the file from the Servlet context path and if not found from the classpath.

If the fileName does not start with a '/' character it is assumed to be a relative path and Click will load the file from the Servlet context by prefixing the fileName with '/WEB-INF'. If not found the file will be loaded from the classpath.

The returned root menu is always selected.

Parameters:

name - the name of the root menu

fileName - the configuration fileName defining the menu definitions

accessController - the menu access controller

menuClass - the menu class to instantiate

Returns:

a copy of the application's root Menu

getMenuCache

protected Map<String,Menu> getMenuCache()

Return the map containing menus cached by name.

Returns:

the map containing menus cached by name

retrieveRootMenu

protected Menu retrieveRootMenu(String name)

Return the cached root menu from the menu cache.

Parameters:

name - the name of the root menu to retrieve

Returns:

the cache root menu from the menu cache

cacheRootMenu

protected void cacheRootMenu(Menu menu)

Cache the given menu in the menu cache.

Parameters:

menu - the menu to store in the cache