Ajax Best Practice in Portlets

Since the time AJAX has come into picture and with various new AJAX frameworks (like DOJO, JQuery, Yahoo UI Library, Google Web Tollkit etc), most of the websites now-a-days are enriched with AJAX to provide Outstanding and Stunning GUI features to the users.  With Portals and Portlet technologies, the web development has become even better than ever before.

This being said, definitely there are plenty of scenarios where we would like to use AJAX with Portlets too. Now this is a bit tricky. There is a subtle difference in implementation (processing user request, serving web response, maintaining state, maintaining lifecycle of server side components like servlets, jsp etc) between regular web applications and portlet based applications.  This difference makes AJAX implementation a bit tricky when it comes to Portlets.

Here, I will explain how to implement AJAX in both JSR 168 and JSR 286 Portlets.

Let's start understanding it with the difference I described above.  Web applications don't have states/modes similar to Portlets (View Mode, Edit Mode etc).

Following is a lifecycle diagram of a java based web application.

Life cycle Of A Servlet Based Web Application

Here as we see, all the request (be it a normal web request or an AJAX request) are processed by only 1 method: service method of the servlet. Also there is no need of generated markup (output HTML, XML etc by service method) aggregation as there is only 1 application running at a time.

Now, moving to Portlets from Web Application, the scenario is a bit different.  In case of portlets, there are multiple web-applications (called portlets) which runs in small i-frame like windows on a single web page. All of these portlets run under a Portal application (controller by portal container) which controls multiple aspects of the entire application like user-interaction with individual portlets, their window states (Minimized, Maximized etc), entire web-page output (which is eventually aggregation of markup generated by individual portlets) etc.  Following block diagram illustrates how overall portal application works:

Portal Web Application

When user interacts with a particular portlet, portal container makes sure request is passed to appropriate portlet, and generated output (markup) is aggregated appropriately with entire web page output without affecting other portlets.

Following diagram shows how request are processed in a portlet based application.

Here we can see that web requests are divided into two categories: 

RenderRequest:  These are the requests when portlets are in view mode and being rendered (e.g. when the first time users requests a web page via HTTP GET or POST URL request)

ActionRequest:  These are HTTP GET or POST requests initiated due to user interaction with portlet (e.g. clicking any URL on the page, submitting form etc).

Here if we see, every request - be it a render request or action request, goes through render phase (doView() method).  This means, Portlet URLs enable window state changes and mode changes that require a subsequent render request to the portal or portlet container. The result? The response contains not only the content for the target portlet, but also that for the entire portal, including all the other rendered portlets. This is true in case of AJAX request too.  Following figure shows an example of a Sample JSR168 Portlet that made an asynchronous call with actionURL, causing the entire portal page to be embedded in the portlet window as a part of AJAX response. This is obviously what we don't want.

AJAX Implementation in JSR-168 using processAction() method

In above figure, we are supposed to get only "AJAX Response using Portlet 1.0 Spec - processAction() method ..." as AJAX response, however along with that, we got entire HTML of the portlet which got appended to the response by doView() method after request was processed by processAction() method. 

To resolve this problem, we have two solutions depending on which portlet spec. you are using. 

For JSR-168 based portlets, there is no provision in the portlet specification which says how to deal with AJAX requests. 

So for JSR-168 portlets, we have to follow a trick.  Well, what's that ? 

Answer to this question lies in Portlet Specification 1.0 (JSR-168). 

Following is the snippet from Portlet Specification 1.0 : 

"A Portlet Application is also a Web Application. The Portlet Application may contain servlets and JSPs in addition to portlets. Portlets, servlets and JSPs may share information through their session.

The PortletSession must store all attributes in the HttpSession of the portlet application. A direct consequence of this is that data stored in the HttpSession by servlets or JSPs is accessible to portlets through the PortletSession in the portlet application scope. Conversely, data stored by portlets in the PortletSession in the portlet application scope is accessible to servlets and JSPs through the HttpSession."

This means, we can divide our logic into two pieces: 

For regular portlet requests, we can extend GenericPortlet class and implement doView() and processAction() methods in the normal way we always do. 

For Ajax requests, we can write a separate Servlet which will handle ajax requests like normal web applications do. 

Following figure shows what exactly I am talking about. 

Ajax Implementation Best Practice for JSR-168 Portlet

So what all we need to do is: 

1. Write a class extending GenericPortlet (or any other portlet like MVCPortlet in Liferay etc) for regular general portlet request processing.  

2. Write a servlet to handle ajax requests like following:

public class AjaxServlet extends HttpServlet {

protected void doPost(HttpServletRequest request,

HttpServletResponse response) throws ServletException, IOException {

              //Write your business logic for Ajax processing here

}

protected void doGet(HttpServletRequest request,

HttpServletResponse response) throws ServletException, IOException {

doPost(request, response);

}

}

3. Write javascript functions to implement ajax call (preferably using some good javascript/ajax library like jquery, dojo etc). 

Following in an example of such a javascript function using jquery. 

function <portlet:namespace/>_callAjax()

{

    var url='<%=(request.getContextPath() + "/AjaxServlet")%>';

 

    //Make ajax call

    

    $.ajax({

    type : "POST",

    url : url,

    cache:false,

    dataType: "text",

    success : function(data) 

    {

          //Write you success logic here

    },

    error : function(XMLHttpRequest, textStatus, errorThrown) 

    {

          //Write you error-handling logic here

    }

  });

}; 

That's it. You are done :)

Now, lets's move to JSR-286 Portlets (Portlet Specification 2.0).  Here, the situation is better in a way that we don't have to worry about writing a separate servlet for Ajax requests.  Portlet itself provides special method called serveResource(ResourceRequest request, ResourceResponse response) to do this. 

Requests made using ResourceRequest (generated by resourceURL tags provided by portlet taglib), are served by serveResource() methods. 

Following figure shows how it works:

Ajax Implementation in JSR-286 Portlet

Following is a sample PortletClass (extending GenericPortlet) showing how to do it. 

package com.jsr286.portlets;

import java.io.IOException;

import javax.portlet.ActionRequest;

import javax.portlet.ActionResponse;

import javax.portlet.GenericPortlet;

import javax.portlet.PortletException;

import javax.portlet.PortletRequestDispatcher;

import javax.portlet.RenderRequest;

import javax.portlet.RenderResponse;

import javax.portlet.ResourceRequest;

import javax.portlet.ResourceResponse;

import com.liferay.portal.util.PortalUtil;

public class TestPortlet extends GenericPortlet {

protected String viewJSP;

public void init() throws PortletException 

{ 

viewJSP = getInitParameter("view-jsp");

}

protected void doView(RenderRequest request, RenderResponse response)

throws PortletException, IOException {

System.out.println("########### Inside com.jsr286.portlets.TestPortlet ... doView() method.....");

include(viewJSP, request, response);

}

public void processAction(ActionRequest request, ActionResponse response)

throws PortletException, IOException {

System.out.println("########### Inside com.jsr286.portlets.TestPortlet ... processAction() method.....");

HttpServletResponse httpResp = PortalUtil.getHttpServletResponse(response);

        httpResp.setContentType("text");

        httpResp.getWriter().print("AJAX Response using Portlet 2.0 Spec - processAction() method .... ");

        httpResp.flushBuffer();

        return;

}

protected void include(String path, RenderRequest renderRequest,RenderResponse renderResponse) throws IOException, PortletException 

{

PortletRequestDispatcher portletRequestDispatcher = getPortletContext().getRequestDispatcher(path);

if (portletRequestDispatcher == null) 

{ 

System.out.println(path + " is not a valid include");

} else 

{ 

portletRequestDispatcher.include(renderRequest, renderResponse);

}

}

public void serveResource(ResourceRequest request, ResourceResponse response) throws PortletException,IOException

{

System.out.println("########### Inside com.jsr286.portlets.TestPortlet ... serveResource() method.....");

        response.setContentType("text");

        response.resetBuffer();

        response.getWriter().print("Correct Ajax Resopnse from Portlet 2.0 Spec - serveResource() method .... ");

        response.flushBuffer();

}

}

And following is a JSP fragment showing how to place AJAX call using resourceURL. 

<%@ taglib uri="http://java.sun.com/portlet_2_0" prefix="portlet" %>

<portlet:defineObjects />

<portlet:resourceURL var="ajaxResourceUrl"/>

<script type="text/javascript">

function <portlet:namespace/>_callAjax()

{

    var url = <%=ajaxResourceUrl%>';

    //Make ajax call 

    

    $.ajax({

    type : "POST",

    url : url,

    cache:false,

    dataType: "text",

    success : function(data) 

    {

          //Write you success logic here

    },

    error : function(XMLHttpRequest, textStatus, errorThrown) 

    {

          //Write you error-handling logic here

    }

  });

};

</script>

That's it on how to implement AJAX in both JSR-168 and JSR-286 portlets.  

Please provide your valuable comments/suggestions.