Portlet servant communication

Overview

The portlet servant API makes it possible to reuse portlet business logic within another portlet. A client-portlet gets a reference to a portlet servant proxy and calls its methods to incorporate the servant's content or exchange parameters/data. As soon as the inter-portlet communication gets standardized the concept of the portlet servant will probably reconsidered. At the moment the implemenation of the portlet servant API is container specific.

Portlet servant

If the portlet has important functions that could likely be reused by some other portlets it makes sense to use the servant mode. Based on the information received with the PortletRequest such portlets can distinguish the normal modes like VIEW,EDIT,HELP from the "servant" and perform different operations to interact with the client-portlet. To provide portlet-servant communication on the servant side ServantUtil class is used. In the following example the groups manager portlet gets the request attribute sent by the client-portlet in the servant mode:

GroupsManagerPortlet.java

if ( ServantUtil.isServantMode(portletRequest) ) {
   IGroupMember[] groupMembers = (IGroupMember[]) ServantUtil.getAttribute(portletRequest);
   ...
  if ( "Done".equals(request.getParameter("grpCommand") ) {
     // Return result to clients
     ServantUtil.setAttribute(req,getResults(portletRequest)); 
     // Notify clients that the servant is complete
     ServantUtil.setServantDone(portletRequest);
  }
}

Portlet servant locator

The portlet servant locator provides the client-portlet with the reference to IPortletServant instance, internally getting the portlet definition from the definition registry by a functional name and keeping track of client changes to the servant in the portlet session. The client-portlet obtains a reference to the locator by calling the static method of ServantLocatorAccessor utility-class.

Running portlet servant from another portlet

Portlet servant API

Servant interfaces

ServantLocatorAccessor.java

/**
 * Provides methods for accessing the portlet servant locator
 */
public final class ServantLocatorAccessor {

    /**
     * Creates a new IPortletServantLocator instance that will be used to locate portlet servants.
     **/
    public static IPortletServantLocator getPortletServantLocator(PortletContext portletContext) {
       return ((PortletContextWrapper)portletContext).getPortletServantLocator();
    }

    private ServantLocatorAccessor() { }
}

IPortletServantLocator.java

/**
 * Provides methods for locating portlet servants provided by uPortal.
 */
public interface IPortletServantLocator {

    /**
     * Gets a new IPortletServant instance for running the specified portlet as a servant.
     * @param functionalPortletName is a portlet functional name given during portlet publising
     * @param request a PortletRequest
     **/
    public IPortletServant locate(String functionalPortletName,PortletRequest request);

}

IPortletServant.java

/**
 * The PortletServant interface is a uPortal wrapper around a JSR-168 portlet that implements
 * the Portlet Servant mode. It provides methods for delegating rendering and action processing
 * to the servant portlet, exchanging attribute values with the Client Portlet, to watch for it's completion and to get the results of the servant's
 * operation.
 */
public interface IPortletServant {
/**
     * Returns the servant ID given by the portlet servant locator.
     * @return a <code>String</code> value
     */
    public String getId();
    
    /** Allows the Client Portlet to ascertain if the Servant has accomplished the requested task 
     * (Note that the way which a certain task is requested is not specified by this interface; 
     * normally it will be documented by a particular IPortletServant and require some particular 
     * configuration paramaters used to initialize the servant)
     * @return boolean value
     */    
    public boolean isComplete(PortletRequest request);
    
    public Object getServantData(PortletRequest request);

    public void setServantData(PortletRequest request,Object value);

    public void render(RenderRequest request, RenderResponse response) throws PortletException, IOException;
    
    public void processAction(ActionRequest request, ActionResponse response) throws PortletException, java.io.IOException;
}

Portlet Servant API