Navigational state handling between the portlet container and the producer

Today we have 2 use cases :

1. Producer and consumer

2. Portal and portlet container

Also it is important to notice the terminology, in WSRP and JBoss Portal we name a concept navigational state. Although they represent the same idea, they are not exactly the same.

1. In WSRP the navigational state is an opaque string

2. In JBoss Portal NavigationalState object equals Mode + WindowState + Render parameters

Interactions between the consumer and the producer OR the portal and the portlet container

This is a generic description and the same behavior applies to both cases although there is a need for slightly adapting one to the other.

1. The portlet is rendered and no specific navigational state is provided. It returns its markup that contains encoded in the URLs a new navigational state, the url can be a render or an action.

2. The portlet is actionned and the mode/ws/parameters are provided (note that those are not the navigational state as we understand it here) to the portlet. The portlet perform some logic and set using the Portlet API a new navigational state. This state is piggy backed to the caller and it is the new navigational state that will have to be sent later to the portlet when it is invoked.

3. The portlet is rendered and the navigational state is provided so the rendition of the portlet can occur.

Example : let's say we have a portlet that can setup a render parameter (in the JSR 168 sense) called PARAM.

The portlet is invoked and it has a blank navigational state. The portlet provides 2 links, the action_link and the render_link. The first one triggers an action that will setup the render parameter PARAM and the second one triggers a render with the RENDER_PARAM encoded.

public class MyPortlet implements javax.portlet.Portlet
{

   public void processAction(ActionRequest req, ActionResponse resp)
   {
      resp.setWindowState(WindowState.MAXIMIZED);
      resp.setRenderParameter("RENDER_PARAM", "FROM_ACTION");
   }

   public void render(RenderRequest req, RenderResponse resp)
   {
      resp.setContentType("text/html");
      Writer writer = resp.getWriter();
      writer.write("PARAM =" + req.getParameter("PARAM");

      PortletURL renderURL = resp.createRenderURL();
      renderURL.setParameter("PARAM", "FROM_RENDER");
      writer.write("<a href=" + renderURL + ">render_link</a>");

      PortletURL actionURL = resp.createActionURL();
      writer.write("<a href=" + actionURL + ">action_link</a>");
   }

} 

1. If the end user clicks render_link then the portlet renderwill be invoked with the RENDER_PARAM value set to FROM_RENDER

2. If the end user cliks action_link then the portlet action will be invoked and it will set the RENDER_PARAM value to FROM_ACTION, then on the subsequent render the RENDER_PARAM will be FROM_ACTION

How it works in JBoss Portal when render is invoked

1. The InvokeWindowRenderCommand is created from the http url

2. The command executes and update the navigational state of the portlet window

3. The command forwards to the RenderPageCommand

4. The forwarded command render all windows and fetch the updated navigational state for that portlet

5. The forwarded command when it invokes that portlet provides the navigational state

How it works in JBoss Portal when action is invoked

1. The InvokeWindowActionCommand is created from the http url

2. The command executes and calls the portlet action

3. On the return of the call, the portlet has returned a RenderResult object which contains the new navigational state, this navigational state provided updates the current one

4. The command forwards to the RenderPageCommand which will render that portlet (among the other ones) with the correct navigational state

How it works with the WSRP when action is invoked

1. The producer receive a PerformBlockInteraction and call the portlet container

2. It receives a RenderResult from the container and it translates that object into an BlockingInteractionResponse. As part of this object there is the  UpdateResponse object that contains the triplet (mode/ws/navstate) that is fetched from the RenderResult.getNavigationalState().

3. The consumer receives that response and will provides on all the subsequent GetMarkup the same triplet (mode/ws/navstate) unless it is updated from another ProcessBlockingInteraction or a render URL.

4. The producer receives the GetMarkup and call the portlet container with the provided triplet (mode/ws/navstate) and translates that into the JBoss Portal NavigationalState.

How it works with the WSRP when render is invoked

Trivial if you read the 3 explanations above.

Things to notice

When the WSRP nav state and JBP nav state are converted, the JBP render parameters have to be converted back and forth between its opaque representation in WSRP. Using java serialization in base 64 would be an acceptable first implementation.