Storing user settings

 

+

Search Tips   |   Advanced Search

 

 

JSR 168 Standard Portlet API User Settings

For standard portlets, user settings are stored, set, and retrieved using the PortletPreferences object, which represents name/value pairs in <preference/> elements of the portlet deployment descriptor.

Preferences can be marked read-only, in which case they can only be modified by someone with administrative privileges, typically using a configure mode. Otherwise, the portlets can be modified in any portlet mode.

In the following example, the userName preference is provided, but set to a null value. This preference is not marked read-only, so it can be changed by any user with edit access to the portlet. 

<portlet-preferences>
      <preference>
          <name>userName</name>
          <value></value>
      </preference>
</portlet-preferences>

Here is an example from the Bookmark portlet... 

<portlet-preferences>

    <preference>
        <name>IBM</name>
        <value>http://www.ibm.com</value>
    </preference>           

    <preference>
        <name>setgetweb</name>
        <value>http://www.setgetweb.com</value>
    </preference>           

</portlet-preferences>

The portlet retrieves a reference to an instance of PortletPreferences by calling the getPreferences() method of the PortletRequest object.

For example, from BookmarkPortletView.jsp... 

<%
   PortletPreferences prefs = renderRequest.getPreferences();
   Enumeration e = prefs.getNames();

   if (!e.hasMoreElements())   
   { 
      // no bookmarks 
%>    
      <p><fmt:message key="no_bookmarks"/></p>
<% 
   }  
   else
   {
%>  
      <p>
<% 
   }   
   while (e.hasMoreElements()) 
   {
      String name = (String)e.nextElement();
      String value = prefs.getValue(name,"<"+myText.getString("undefined")+">");
%>
      <a href=<%=value%> target="_blank"><%=name%></a><br />
<%
   }
%>

The Java Portlet Specification allows the portlet to define a preference validator in the portlet deployment descriptor. If one is defined, then the validator is called before any store() methods are performed.

The following example from jsrHelloUser.war builds on the jsrHelloJSP.war sample by adding the doEdit() and processAction() methods to allow the user to edit preferences. The getValue() method allows the portlet developer to designate a default value if the preference has not been set. 

package com.ibm.wps.samples.jsr;
 import javax.portlet.*; import java.io.*;
 public class HelloUser extends GenericPortlet 
{
  
   public void init(PortletConfig portletConfig) 
       throws UnavailableException, PortletException
   {
           
     // The default user name is obtained from the portlet configuration parameters
     super.init(portletConfig); 
   }

  public void doView(RenderRequest request, RenderResponse response)
      throws PortletException, IOException 
  {
    // set return content type
    response.setContentType("text/html");

    // Get the user's preferred name to display from preferences
    // If no value is available, set it to "User"
    String displayName = request.getPreferences().getValue("userName", "User");

    // Add the display string to the portlet request to make it accessible by the view JSP
    request.setAttribute("username", displayName);

    PortletContext context = getPortletContext();
    context.getRequestDispatcher("/jsp/View.jsp").include(request, response);
  }

  public void doEdit(RenderRequest request, RenderResponse response)
      throws PortletException, IOException
  {

    response.setContentType("text/html");

    // Create the return URL for the cancel link of the edit page
    PortletURL cancelUrl = response.createRenderURL();
    cancelUrl.setPortletMode(PortletMode.VIEW);

    // Preserve the Cancel URL in the request to make it accessible by the edit JSP
    request.setAttribute("cancelUrl",cancelUrl.toString());

    // For the "Save" button the return URI must include the "Save" action
    PortletURL saveUrl = response.createActionURL();
    saveUrl.setPortletMode(PortletMode.VIEW);
    saveUrl.setParameter("save","save");

    // Preserve the Save URL in the request to make it accessible by the edit JSP
    request.setAttribute("saveUrl",saveUrl.toString());

  String displayName = request.getPreferences().getValue("userName", "User");
  request.setAttribute("username", displayName);

    String jspName = getPortletConfig().getInitParameter("jspEdit");
    PortletRequestDispatcher rd = getPortletContext().getRequestDispatcher("/jsp/Edit.jsp");
    rd.include(request,response);

  }

  public void processAction(ActionRequest request, ActionResponse response)
      throws PortletException, IOException
  {

    PortletContext context = getPortletContext();

    try
    {
      String save = request.getParameter("save");
      if (save != null)
      {
        PortletPreferences prefs = request.getPreferences();
        prefs.setValue("userName",request.getParameter("username"));
        prefs.store();
      }
    }
    catch (IOException ioe )
    {
       context.log("An IO error occurred when trying to save the name.");    
    }
    catch (PortletException pe ) 
    {
       context.log("A portlet exception was thrown when trying to save the name.");    
    }    

  }

}

 

IBM Portlet API User Settings

For IBM portlets, user settings are saved, retrieved, or deleted using the PortletData object. Portlets can store values in the PortletData object only when the portlet is in edit mode.

If the portlet is on a group page, then information saved in PortletData is available to all users of the portlet. The portlet retrieves a reference to an instance of PortletData by calling the getData() method of the PortletRequest object. The store() method saves the information PortletData. Only data of the Java String type can be saved in the PortletData object.

PortletData is used in the ibmHelloUser.war sample to allow users to edit and save their names in which they are addressed in the greeting. This sample builds on the ibmHelloJSP sample by adding the doEdit() and the actionPerformed() methods, thus allowing users to edit the greeting and save their preferences.

Figure 3. Example: Java source for Hello User portlet (IBM) 

package com.ibm.wps.samples;
 import org.apache.jetspeed.portlet.*; import org.apache.jetspeed.portlet.event.*; import java.io.*;
 public class HelloUser extends PortletAdapter implements ActionListener
{

  private String defaultString;
  private String displayName;

  public void doView(PortletRequest request, PortletResponse response) 
      throws PortletException, IOException 
  {
    //Get the user's name to display from persistent storage
    displayName = (String) request.getData().getAttribute("userName");
    defaultString = request.getPortletSettings().getAttribute("defaultUserName");

    // If user's preferred name is not found, display the default
    if (displayName == null) 
    {
        // set default string
        displayName = defaultString;   
    }

    // Add the display string to the portlet request to make it accessible by the view JSP
    request.setAttribute("userName", displayName);

    getPortletConfig().getContext().include("/jsp/View.jsp", request, response);
  }

  public void doEdit(PortletRequest request, PortletResponse response) 
      throws PortletException, IOException 
  {

    // Create the return URI for the cancel link of the edit page
    PortletURI cancelURI = response.createReturnURI();

    // Preserve the Cancel URI in the request to make it accessible by the edit JSP
    request.setAttribute("cancelURI", cancelURI.toString());


    // For the "Save" button the return URI must include the "Save" action

    // so the Action Listener for this portlet will be invoked
    PortletURI saveURI = response.createReturnURI();
    saveURI.addAction("save");

    // Preserve the Save URI in the request to make it accessible by the edit JSP
    request.setAttribute("saveURI", saveURI.toString());


    //Get the user's name to display from persistent storage
    displayName = (String) request.getData().getAttribute("userName");
    defaultString = request.getPortletSettings().getAttribute("defaultUserName");

    // If user's preferred name is not found, display the default
    if (displayName == null) 
    {
       // none found, set default string
       displayName = defaultString;    
    }

    // Add the display string to the request to make it accessible by the edit JSP
    // as an initial value of the input field on the edit form
    request.setAttribute("userName", displayName);

    getPortletConfig().getContext().include("/jsp/Edit.jsp", request, response);

  }

  public void actionPerformed(ActionEvent event) 
  {

    String action = event.getActionString();
    PortletLog log = getPortletLog();

    // If this is a save action, then see if the user specified a name
    if (action!=null ) 
    {
      if (action.equals("save") ) 
      {

        PortletRequest request = event.getRequest();

        PortletData portData = request.getData();
        String userName = request.getParameter("userName");

        try 
        {
          // Save the name specified by the user
          if (userName != null ) 
          {
            portData.setAttribute("userName", userName);
            portData.store();
          }
        } 
        catch (AccessDeniedException ade ) 
        {
        } 
        catch (IOException ioe ) 
        {
          log.error("<i><b>Couldn't write the user data to " );
          log.error("persistence because an I/O Error occurred.</b></i>" );
        }
      }
    }
  }  

}

An ActionListener is implemented by HelloUser to process the save action. The user enters a name on the edit page and the actionPerformed() method of the ActionListener obtains the user-specified string from the PortletRequest object for storing in the user's persistent storage. The ActionListener is invoked prior to returning to the doView() method of the portlet, thus if the user failed to enter a name, the ActionListener can force the portlet to remain in edit mode, waiting for input from the user.

 

Related information

 

Parent topic

Understanding the basics