Since it's been some time since we've last discussed the Public API, I wanted to at least give a quick look at the recent work that has been done with the API and more specifically Navigation. As always you can view the code on github at https://github.com/gatein/gatein-api-java and javadoc here http://gatein.github.com/gatein-api-java/.

PortalRequest

The PortalRequest object contains data relative to the current request of the portal. It can be retrieved by the following:

PortalRequest portalRequest = PortalRequest.getInstance();

Portal

The Portal object is the main interface of the public API which is used to obtain specific information of the portal. It can be obtained from the PortalRequest object

Portal portal = portalRequest.getPortal();

Navigation

The navigation object is scoped to a specific site and can be used to retreive, delete, and save navigation nodes. It can be obtained either by the current request or specifically from the Portal object.

Navigation navigation = portalRequest.getNavigation(); // navigation of the current request
Navigation adminNav = portal.getNavigation(new SiteId(new Group("platform", "administrators")); // navigation of the /platform/administrators group

Node

The node is a detached object representing the state of the node and the relationship of it's parent and children at the time of retrieval.

Node homeNode = navigation.getNode("home");
Node appRegNode = adminNav.getNode("administration", "registry");

NodeVisitor

The number of nodes that are loaded are controlled entirely by the user through the NodeVisitor object. For the most part, the NodeVisitor's that are available via the Nodes class are typically enough.

Node rootNode = navigation.loadNodes(Nodes.visitChildren()); // Returns the root node with it's children loaded
Node rootNode = navigation.loadNodes(Nodes.visitNodes(2)); // Returns the root node with it's children and children's children loaded.

Node adminNode = adminNav.getNode(NodePath.path("administration"), Nodes.visitChildren()); // Returns the administration node with it's children loaded

If any child operation is performed and the node does not have it's children loaded, an IllegalStateException will be thrown. It's very important to call isChildrenLoaded prior to accessing the children of a node.

if (!adminNode.isChildrenLoaded())
{

     navigation.loadChildren(adminNode);

}

Node appRegNode = adminNode.getChild("registry");

DisplayName & Localization

The node object has a displayName which can be used to display the node in a navigation menu. The displayName can be localized in order to display different text depending on the locale.

LocalizedString displayName = homeNode.getDisplayName();
boolean localized = displayName.isLocalized();

String en = displayName.getValue(Locale.ENGLISH);

String fr = displayName.getValue(Locale.FRENCH);

To automatically resolve the proper display name depending on the current request's locale, if it's localized (extended), or even for resource values such as #{my.nav.name} you can just do

String resolved = homeNode.resolveDisplayName();

These are just some quick examples of the navigation part of the public API. Look for more information around the public API in the future as we continue to develop this feature for GateIn.