Chapter 12. Portal API
Prev |  | Next

## Chapter 12. Portal API

### Julien Viet

`<julien@jboss.org>`

### Thomas Heute

`<theute@jboss.org>`

## 12.1. Introduction

JBoss Portal provides an Application Programming Interface (API) which allows to write code that interacts with the portal. The life time and validity of the API is tied to the major version which means that no changes should be required when code is written against the API provided by the JBoss Portal 2.x versions and used in a later version of JBoss Portal 2.x.

The Portal API package prefix is org.jboss.portal.api. All of the classes that are part of this API are prefixed with this package name except for the org.jboss.portal.Mode and org.jboss.portal.WindowState classes. These two classes were defined before the official Portal API framework was created and so the names have been maintained for backward compatibility.

The Portlet API defines two classes that represent a portion of the visual state of a Portlet which are javax.portlet.PortletMode and javax.portlet.WindowState. Likewise the Portal API defines similar classes named org.jboss.portal.Mode and org.jboss.portal.WindowState which offer comparable characteristics, the main differences are:

- Usage of factory methods to obtain instances.
- Classes implements the java.io.Serializable interface.

The Mode class

The WindowState class

### Note

In the Portal API, the Mode interface is named like this because it does represent the mode of some visual object. The Portlet API names it PortletMode because it makes the assumption that the underlying object is of type Portlet.

## 12.2. Portal URL

The Portal API defines the org.jboss.portal.api.PortalURL interface to represent URL managed by the portal.

The PortalURL interface

- The setAuthenticated(Boolean wantAuthenticated) methods defines if the URL requires the authentication of the user. If the argument value is true then the user must be authenticated to access the URL, if the argument value is false then the user should not be authenticated. Finally if the argument value is null then it means that the URL authenticated mode should reuse the current mode.
- The setSecure(Boolean wantSecure) methods defines the same as above but for the transport guarantee offered by the underlying protocol which means most of the time the secure HTTP protocol (HTTPS).
- The setRelative(boolean relative) defines the output format of the URL and whether the created URL will be an URL relative to the same web server or will be the full URL.
- The toString() method will create the URL as a string.

## 12.3. Portal session

The PortalSession interface

It is possible to have access to a portion of the portal session to store objects. The org.jboss.portal.api.session.PortalSession interface defines its API and is similar to the javax.servlet.http.HttpSession except that it does not offer methods to invalidate the session as the session is managed by the portal.

## 12.4. Portal runtime context

The PortalRuntimeContext interface

The org.jboss.portal.api.PortalRuntimeContext gives access to state or operations associated at runtime with the current user of the portal. The String getUserId() retrieve the user id and can return null if no user is associated with the context. It also gives access to the PortalSession instance associated with the current user. Finally it gives access to the NavigationalStateContext associated with the current user.

## 12.5. Portal nodes

The portal structure is a tree formed by nodes. It is possible to programmatically access the portal tree in order to

- discover the tree structure of the portal
- create URL that will render the different portal nodes
- access the properties of a specific node

The PortalNode interface

As usual with tree structures, the main interface to study is the org.jboss.portal.api.node.PortalNode. That interface is intentionally intended for obtaining useful information from the tree. It is not possible to use it to modify the tree shape because it is not intended to be a management interface.

    public interface PortalNode
    {
       int getType();
       String getName();
       String getDisplayName(Locale locale);
       Map getProperties();
       PortalNodeURL createURL(PortalRuntimeContext portalRuntimeContext);
       ...
    }

The interface offers methods to retrieve informations for a given node such as the node type, the node name or the properties of the node. The noticeable node types are:

- PortalNode.TYPE_PORTAL : the node represents a portal
- PortalNode.TYPE_PAGE : the node represents a portal page
- PortalNode.TYPE_WINDOW : the node represents a page window

The org.jboss.portal.api.node.PortalNodeURL is an extension of the PortalURL interface which adds additional methods useful for setting parameters on the URL. There are no guarantees that the portal node will use the parameters. So far portal node URL parameters are only useful for nodes of type PortalNode.TYPE_WINDOW and they should be treated as portlet render parameters in the case of the portlet is a local portlet and is not a remote portlet. The method that creates portal node URL requires as parameter an instance of PortalRuntimeContext.

The interface also offers methods to navigate the node hierarchy:

    public interface PortalNode
    {
       ...
       PortalNode getChild(String name);
       Collection getChildren();
       PortalNode getRoot();
       PortalNode getParent();
       ...
    }

## 12.6. Portal navigational state

The navigational state is a state managed by the portal that associates to each user the state triggered by its navigation. A well known part of the navigational state are the render parameters provided at runtime during the call of the method void render(RenderRequest req, RenderResponse resp). The portal API offers an interface to query and update the navigational state of the portal. For now the API only exposes mode and window states of portal nodes of type window.

The NavigationalStateContext interface

## 12.7. Portal events

Portal events are a powerful mechanism to be aware of what is happening in the portal at runtime. The base package for event is org.jboss.portal.api.event and it contains the common event classes and interfaces.

The PortalEvent class

The org.jboss.portal.api.event.PortalEvent abstract class is the base class for all kind of portal events.

The PortalEventContext interface

The org.jboss.portal.api.event.PortalEventContext interface defines the context in which an event is created and propagated. It allows retrieval of the PortalRuntimeContext which can in turn be used to obtain the portal context.

The PortalEventListener interface

The org.jboss.portal.api.event.PortalEventListener interface defines the contract that class can implement in order to receive portal event notifications. It contains the method void onEvent(PortalEvent event) called by the portal framework.

Listeners declaration requires a service to be deployed in JBoss that will instantiate the service implementation and register it with the service registry. We will see how to achieve that in the example section of this chapter.

### Note

The event propagation model uses one instance of a listener class to receive all portal events that may be routed to that class when appropriate. Therefore implementors needs to be aware of that model and must provide thread safe implementations.

### 12.7.1. Portal node events

Portal node events extend the abstract portal event framework in order to provide notifications about user interface events happening at runtime. For instance when the portal renders a page or a window, a corresponding event will be fired.

The portal node event class hierarchy

The org.jboss.portal.api.node.event.PortalNodeEvent class extends the org.jboss.portal.api.node.PortalEvent class and is the base class for all events of portal nodes. It defines a single method PortalNode getNode() which can be used to retrieve the node targetted by the event.

The org.jboss.portal.api.node.event.WindowEvent is an extension for portal nodes of type window. It provides access to the mode and window state of the window. It has 3 subclasses which represent different kind of event that can target windows.

The org.jboss.portal.api.node.event.WindowNavigationEvent is fired when the window navigational state changes. For a portlet it means that the window is targetted by an URL of type render.

The org.jboss.portal.api.node.event.WindowActionEvent is fired when the window is targetted by an action. For a portlet it means that the window is targetted by an URL of type action.

The org.jboss.portal.api.node.event.WindowRenderEvent is fired when the window is going to be rendered by the portal.

The org.jboss.portal.api.node.event.PageEvent is an extension for portal nodes of type page.

The org.jboss.portal.api.node.event.PageRenderEvent is fired when the page is going to be rendered by the portal.

#### 12.7.1.1. Portal node event propagation model

A portal node event is fired when an event of interest happens to a portal node of the portal tree. The notification model is comparable to the bubbling propagation model defined by the DOM specification. When an event is fired, the event is propagated in the hierarchy from the most inner node where the event happens to the root node of the tree.

The portal node event propagation model

#### 12.7.1.2. Portal node event listener

The org.jboss.portal.api.node.event.PortalNodeEventListener interface should be used instead of the too generic org.jboss.portal.api.event.PortalEventListener when it comes down of listening portal node events. Actually it does not replace it, the PortalEventListener interface semantic allows only traditional event delivering. The PortalNodeEventListener interface is designed to match the bubbling effect during an event delivery.

The PortalNodeEvent onEvent(PortalNodeEventContext context, PortalNodeEvent event) method declares a PortalNodeEvent as return type. Commonly the method returns null; however, a returned PortalNodeEvent replaces the event in the listeners subsequently called during the event bubbling process.

#### 12.7.1.3. Portal node event context

The PortalNodeEventContext interface

The org.jboss.portal.api.node.event.PortalNodeEventContext interface extends the PortalEventContext interface and plays an important role in the event delivery model explained in the previous section. That interface gives full control over the delivery of the event to ascendant nodes in the hierarchy, even more it gives the possibility to replace the current event being delivered by a new event that will be transformed into the corresponding portal behavior. However there are no guarantees that the portal will turn the returned event into a portal behavior, here the portal provides a best effort policy, indeed sometime it is not possible to achieve the substitution of one event by another.

Here the simplest implementation of a listener that does nothing except than correctly passing the control to a parent event listener if there is one.

    public PortalNodeEvent onEvent(PortalNodeEventContext context, PortalNodeEvent event)
    {
       return context.dispatch();
    }

The method PortalNode getNode() returns the current node being selected during the event bubbler dispatching mechanism.

### 12.7.2. Portal session events

The life cycle of the session of the portal associated with the user can also raise events. This kind of event is not bound to a portal node since it is triggered whenever a portal session is created or destroyed

The PortalSessionEvent class

There are two different types of events:

- org.jboss.portal.api.session.event.PortalSessionEvent.SESSION_CREATED, fired when a new portal session is created
- org.jboss.portal.api.session.event.PortalSessionEvent.SESSION_DESTROYED, fired when a new portal session is destroyed

### 12.7.3. Portal user events

The life cycle of the portal user can also raise events such as its authentication. A subclass of the wider scope UserEvent class is provided and triggers events whenever a user signs in or out. The UserEvent object gives access to the user name of the logged-in user through the method String getId().

The UserEvent class and UserAuthenticationEvent sub-classes

The UserAuthenticationEvent triggers two events that can be catched:

- org.jboss.portal.api.session.event.UserAuthenticationEvent.SIGN_IN, fired when a portal user signs in
- org.jboss.portal.api.session.event.UserAuthenticationEvent.SIGN_OUT, fired when a portal user signs out

Based on the UserEvent class other custom user related events could be added like one that would trigger when a new user is being registered

## 12.8. Examples

The events mechanism is quite powerful, in this section of the chapter we will see few simple examples to explain how it works.

### 12.8.1. UserAuthenticationEvent example

In this example, we will create a simple counter of the number of logged-in registered users. In order to do that we just need to keep track of Sign-in and Sign-out events.

First, let's write our listener. It just a class that will implement org.jboss.portal.api.event.PortalEventListener and its unique method void onEvent(PortalEventContext eventContext, PortalEvent event). Here is such an example:

    package org.jboss.portal.core.portlet.test.event;

    import[...]

    public class UserCounterListener implements PortalEventListener
    {

       /** Thread-safe long */
       private final SynchronizedLong counter = new SynchronizedLong(0);

       /** Thread-safe long */
       private final SynchronizedLong counterEver = new SynchronizedLong(0);

       public void onEvent(PortalEventContext eventContext, PortalEvent event)
       {
          if (event instanceof UserAuthenticationEvent)
          {
             UserAuthenticationEvent userEvent = (UserAuthenticationEvent)event;
             if (userEvent.getType() == UserAuthenticationEvent.SIGN_IN)
             {
                counter.increment();
                counterEver.increment();
             }
             else if (userEvent.getType() == UserAuthenticationEvent.SIGN_OUT)
             {
                counter.decrement();
             }
             System.out.println("Counter     : " + counter.get());
             System.out.println("Counter ever: " + counterEver.get());
          }
       }
    }

On this method we simply filter down to UserAuthenticationEvent then depending on the type of authentication event we update the counters. counter keeps track of the registered and logged-in users, while counterEver only counts the number of times people logged-in the portal.

Now that the Java class has been written we need to register it so that it can be called when the events are triggered. To do so we need to register it as an MBean. It can be done by editing the sar descriptor file: YourService.sar/META-INF/jboss-service.xml so that it looks like the following:

    <?xml version="1.0" encoding="UTF-8"?>
    <server>
       <mbean
          code="org.jboss.portal.core.event.PortalEventListenerServiceImpl"
          name="portal:service=ListenerService,type=counter_listener"
          xmbean-dd=""
          xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean">
          <xmbean/>
          <depends
             optional-attribute-name="Registry"
             proxy-type="attribute">portal:service=ListenerRegistry</depends>
          <attribute name="RegistryId">counter_listener</attribute>
          <attribute name="ListenerClassName">
          	org.jboss.portal.core.portlet.test.event.UserCounterListener
          </attribute>
       </mbean>
    </server>

This snippet can be kept as it is, providing you change the values:

- name: Must follow the pattern: portal:service=ListenerService,type={{UNIQUENAME}}
- RegistryId: Must match the type (here: counter_listener)
- ListenerClassName: Full path to the listener (here: org.jboss.portal.core.portlet.test.event.UserCounterListener).

That's it - we now have a user counter that will display it states each time a user logs-in our logs-out.

### 12.8.2. Achieving Inter Portlet Communication with the events mechanism

The first version of the Portlet Specification (JSR 168), regretfully, did not cover interaction between portlets. The side-effect of diverting the issue to the subsequent release of the specification, has forced portal vendors to each craft their own proprietary API to achieve inter portlet communication. Here we will see how we can use the event mechanism to pass parameters from one portlet to the other (and only to the other portlet).

The overall scenario will be that Portlet B will need to be updated based on some parameter set on Portlet A. To achieve that we will use a portal node event.

Portlet A is a simple Generic portlet that has a form that sends a color name:

    public class PortletA extends GenericPortlet
    {
       protected void doView(RenderRequest request, RenderResponse response)
          throws PortletException, PortletSecurityException, IOException
       {
          response.setContentType("text/html");
          PrintWriter writer = response.getWriter();
          writer.println("<form action=\"" + response.createActionURL() + "\" method=\"post\">");
          writer.println("<select name=\"color\">");
          writer.println("<option>blue</option>");
          writer.println("<option>red</option>");
          writer.println("<option>black</option>");
          writer.println("</select>");
          writer.println("<input type=\"submit\"/>");
          writer.println("</form>");
          writer.close();
       }
    }

The other portlet (Portlet B) that will receive parameters from Portlet A is also a simple Generic portlet:

    public class PortletB extends GenericPortlet
    {

       public void processAction(ActionRequest request, ActionResponse response)
                  throws PortletException, PortletSecurityException, IOException
       {
          String color = request.getParameter("color");
          if (color != null)
          {
             response.setRenderParameter("color", color);
          }
       }

       protected void doView(RenderRequest request, RenderResponse response)
              throws PortletException, PortletSecurityException, IOException
       {
          String color = request.getParameter("color");
          response.setContentType("text/html");
          PrintWriter writer = response.getWriter();
          writer.println("<div" +
             (color == null ? "" : " style=\"color:" + color + ";\"") +
             ">some text in color</div>");
          writer.close();
       }

       // Inner listener explained after
    }

With those two portlets in hands, we just want to pass parameters from Portlet A to Portlet B (the color in as a request parameter in our case). In order to achieve this goal, we will write an inner Listener in Portlet B that will be triggered on any WindowActionEvent of Portlet A. This listener will create a new WindowActionEvent on the window of Portlet B.

    public static class Listener implements PortalNodeEventListener
    {
       public PortalNodeEvent onEvent(PortalNodeEventContext context, PortalNodeEvent event)
       {
          PortalNode node = event.getNode();
          // Get node name
          String nodeName = node.getName();
          // See if we need to create a new event or not
          WindowActionEvent newEvent = null;
          if (nodeName.equals("PortletAWindow") && event instanceof WindowActionEvent)
          {
             // Find window B
             WindowActionEvent wae = (WindowActionEvent)event;
             PortalNode windowB = node.resolve("../PortletBWindow");
             if (windowB != null)
             {
                // We can redirect
                newEvent = new WindowActionEvent(windowB);
                newEvent.setParameters(wae.getParameters());

                newEvent.setMode(wae.getMode());
                newEvent.setWindowState(WindowState.MAXIMIZED);

                // Redirect to the new event
                return newEvent;
             }
          }
          // Otherwise bubble up
          return context.dispatch();
       }
    }

It is important to note here some of the important items in this listener class. Logic used to determine if the requesting node was Portlet A.:

    nodeName.equals("PortletAWindow")

Get the current window object so we can dispatch the event to it:

    PortalNode windowB = node.resolve("../PortletBWindow");

Set the original parameter from Portlet A, so Portlet B can access them in its processAction():

    newEvent.setParameters(wae.getParameters());

We still need to register our listener as an mbean:

    <mbean
       code="org.jboss.portal.core.event.PortalEventListenerServiceImpl"
       name="portal:service=ListenerService,type=test_listener"
       xmbean-dd=""
       xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean">
       <xmbean/>
       <depends
          optional-attribute-name="Registry"
          proxy-type="attribute">portal:service=ListenerRegistry</depends>
       <attribute name="RegistryId">test_listener</attribute>
       <attribute name="ListenerClassName">
          org.jboss.portal.core.samples.basic.event.PortletB$Listener
       </attribute>
    </mbean>

For node events, we also need to declare on which node we want to listen, this is done by modifying the `*-object.xml` that defines your portal nodes. In this example we want to trigger the listener each time the window containing the portlet A is actioned. We can add the `listener` tag to specify that out listener with `RegistryId`=test_listener should be triggered on events on the embedding object.

    ...
       <window>
          <window-name>PortletAWindow</window-name>
          <instance-ref>PortletAInstance</instance-ref>
          <region>center</region>
          <height>0</height>
          <listener>test_listener</listener>
       </window>
    ...

Of course we could have added it at the page level instead of the window level. Note that a unique listener can be specified, the event mechanism is primarily done to let the developer change the navigation state of the portal, this example being a nice side-effect of this feature.

### Note

The portlet 2.0 specification (JSR 286) will cover Inter Portlet Communication so that portlets using it can work with different portal vendors.

### 12.8.3. Link to other pages

Linking to some other pages or portals is also out of the scope of the portlet specification. As seen previously JBoss Portal offers an API in order to create links to other portal nodes. The JBoss request gives access to the current window node from which we can navigate from.

    // Get the ParentNode. Since we are inside a Window, the Parent is the Page
    PortalNode thisNode = req.getPortalNode().getParent();

    // Get the Node in the Portal hierarchy tree known as "../default"
    PortalNode linkToNode = thisNode.resolve("../default");

    // Create a RenderURL to the "../default" Page Node
    PortalNodeURL pageURL = resp.createRenderURL(linkToNode);

    // Output the Node's name and URL for users
    html.append("Page: " + linkToNode.getName() + " -> ");
    html.append("<a href=\"" + pageURL.toString() + "\">" + linkToNode.getName() + "</a>");

From this, it is easy to create a menu or sitemap, the List getChildren() method will return all the child nodes on which the user has the view right access.

### Samples

Those examples are available in the core-samples package in the sources of JBoss Portal. There are more examples of events usage in the samples delivered with JBoss Portal. One of them shows the usage of a portal node event to only have one window in normal mode at a time in a region. Anytime another window is being put in normal mode, all the other windows of the same regions are automatically minimized.

Prev | Up | Next
Chapter 11. Portlet Modes | Home | Chapter 13. Clustering Configuration