+

Search Tips   |   Advanced Search

Storing user settings


Use a sample portlet as an example, learn how user settings can be stored and retrieved in portlets.

This topic describes how user settings can be stored and retrieved in portlets. Examples in this topic build off of the HelloJSP samples described in Generating output. All sample portlets are available from the portlet catalog by searching for navcode 1WP10017Z. See Sample portlets for more information.

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 descriptors. 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>          

The portlet retrieves a reference to an instance of PortletPreferences by calling the getPreferences() method of the PortletRequest object. The store() method saves the information PortletData. The Java Portlet Specification allows the portlet to define a preference validatar in the portlet deployment descriptors. If one is defined, then the validatar is called before the store operation is 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.

Figure 1. Example: Java source for Hello User portlet (standard)

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
   {
     super.init(portletConfig); 
     // The default user name is obtained from the portlet configuration parameters    
   }

  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.");    
  }    

  }

}

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) {
        displayName = defaultString;    // set default string     }

    // 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) {
       displayName = defaultString;    // none found, set default string     }
    // 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>" );
        }
      }
    }
  } 

}

As mentioned previously, 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


Parent: Understand the basics