This package contains convenience implementations of menu trees that can be used out-of-the-box. The user can choose one of following implementations of the tree model,

• a static implementation that creates a tree from a XML file,
• a dynamic implementation where the tree structure is defined in the portlet code.

Static XMI tree

A programmer wants to write a portlet that reads the static menu tree configuration from a XML file. For convenience, the programmer is recommended to derive the portlet from the abstract class {@link com.ibm.wps.portlets.menu.XMIMenuTreePortlet} which uses the {@link com.ibm.wps.portletservice.portletmenu.XMIMenuService} interface internally. The path of the tree configuration XML file must be specified in the portlet deployment descriptor. Once the portal navigation displayed a static tree on a page, it will not change until either the portlet is deleted from the page, or the corresponding portlet application is updated or re-installed. The javadoc of {@link com.ibm.wps.portlets.menu.XMIMenuTreePortlet} is placed in the <WPS_HOME>/dev/samples/Javadoc directory.

Dynamic In-Memory tree

When a portlet implements the dynamic menu tree structure itself, it is recommended to derive the portlet from the abstract class {@link com.ibm.wps.portlets.menu.MemoryMenuTreePortlet} which takes {@link com.ibm.wps.portletservice.portletmenu.MemoryMenuService} interface internally. This service can create an In-Memory tree that either has only one unnamed root node or incorporates an existing tree model, which can be both static or dynamic. The javadoc of {@link com.ibm.wps.portlets.menu.MemoryMenuTreePortlet} is placed in the <WPS_HOME>/dev/samples/Javadoc directory.

The instance of the controller interface {@link com.ibm.wps.portlet.menu.MenuTreeTopologyCtrl}, which extends the tree model {@link com.ibm.wps.portlet.menu.MenuTree} enables adding or removing tree nodes and setting the scope of the root node. The scope of a node defines how often the Portal Framework needs to check whether the children of a specific node have changed and the tree has to be re-built from the tree model. The Portal Framework stores the menu entries and the tree topology in a cache to hasten up rendering. When the {@link com.ibm.wps.portletservice.portletmenu.MemoryMenuService} creates an instance of {@link com.ibm.wps.portlet.menu.MenuTree} and the method {@link com.ibm.wps.portlet.menu.MenuTreeTopologyCtrl#setScope} is used to change the scope of one {@link com.ibm.wps.portlet.menu.MenuNode}, the scope is simultaneously set for all nodes of the tree.

Note for programmers who implement the {@link com.ibm.wps.portlet.menu.MenuTree} interface: When the scope of the menu nodes is MenuNode.SCOPE_SESSION or MenuNode.SCOPE_GLOBAL, the {@link com.ibm.wps.portlet.menu.MenuTree} methods {@link com.ibm.wps.portlet.menu.MenuTree#getRoot} and {@link com.ibm.wps.portlet.menu.MenuTree#getChildren} have to return the same objects when the portlet receives the next request.

The controller interface {@link com.ibm.wps.portlet.menu.MenuTreeInfoCtrl}, which wraps the tree model {@link com.ibm.wps.portlet.menu.MenuTree} is used to set title and description of the node for different locales, and to add an URI action and one or more action parameters to the node.

To include an existing instance of {@link com.ibm.wps.portlet.menu.MenuTree} into an In-Memory tree, so that the new child of the In-Memory tree node refers to the root node of the tree to be included, the instance of the controller {@link com.ibm.wps.portletservice.portletmenu.MemoryMenuTreeTopologyCtrl} can be useful.