Handling Command Submissions

Inderjeet Singh, Jayashri Visvanathan

Problem Description

Web applications often need web pages that display a form to get input from a user. Command submission is the process of triggering an application-specific command or an action when a UICommand type component is activated by the user. One example is the submission of a web form when a user clicks the Submit button on a web page. This submission is typically used to take action on the server side. Other examples include logging in a user, and navigating a user to the next page.

A web page developer must decide how to handle these command submissions. The JavaServer[TM] Faces API provides two options: Action or ActionListener. This entry describes which strategy is good for each situation.

Some considerations for making this design choice include the following:

Solution

The following table summarizes the recommendations for handling command submissions.

Strategy Recommendation
Use Action For normal event handling of JavaServer Faces components
Use ActionListener For event handling of JavaServer Faces components only in cases where you need to identify the component that caused the event

Action listeners should generally be used when a component needs to have its state modified whenever another (UICommand) component is activated. For example, you might have a button on your form that switches between the "compact" version of a form (with only a few fields) and the "full" version of the form (with all possible fields). Although it is possible for the page author to register action listeners directly in the page, most of the time this could be done programmatically by the components themselves. Action listeners cannot directly influence navigation.

An action, on the other hand, should be considered the primary design element for invoking application actions that might potentially affect navigation, including any scenario where the command in question is the submit button on a form. The action method can return null to cause the current page to be redisplayed, or return an outcome string that can be mapped to a navigation rule to determine which page is to be displayed next.

While designing custom JavaServer Faces components, sometimes you need both behaviors. For example, consider a custom tree component for navigating a hierarchy of objects. If a button is clicked, you want other components to be notified, and you want to associate an outcome to a navigation rule. Here you can use action and action listener together. However, in most cases the registration of action listener could be transparent to the page author because the components register the action listeners themselves. A well-designed custom component avoids requiring a page author to explicitly register action listeners (with the <f:action_listener> tag), because it results in exposing implementation details of the component to the page author. One consequence to consider is that the resulting design primarily uses Action for handling most command submissions. The use of ActionListener is limited to the few cases where you need to extract information from the UI element that generated the event.

Using Actions

Action mappings are of two types: static and dynamic. The static mappings are used when it is clear what the next page will be, and no action method needs to be invoked on the backing bean. Code Example 1 illustrates how a static action mapping is specified:

  <b>User Name:</b> <h:inputText id="userName" value="#{CommandSubmissionsBean.userName}"/><br>
  <b>Password:</b> <h:inputText id="password" value="#{CommandSubmissionsBean.password}"/><br>
  <h:commandButton id="guest" action="success" value="Guest Login" />


Code Example 1: Static Action Mapping

For the button labeled Guest Login, the action mapping is specified to be success. This results in the invocation of the navigation rule corresponding to the success outcome from this page. Code Example 2 shows the corresponding definition of the navigation rule from the faces-config.xml file:

  <navigation-rule>   
    <from-view-id>/index.jsp</from-view-id>
    <navigation-case>
      <description>           
        Indicates to the NavigationHandler that the response.jsp view
        must be displayed if the Action referenced by a UICommand
        component on the index.jsp view returns the outcome
        "success".       
      </description>
      <from-outcome>success</from-outcome>
      <to-view-id>/response.jsp</to-view-id>   
    </navigation-case>
  </navigation-rule> 


Code Example 2: Navigation Rule for success Outcome in index.jsp

Note that multiple navigation cases can be defined with each corresponding to a different outcome.

The action mapping can also bedefined dynamically by specifying an action method instead of specifying the outome. The Code Example 3 illustrates how this can be done:

  <b>User Name:</b> <h:inputText id="userName" value="#{CommandSubmissionsBean.userName}"/><br>
  <b>Password:</b> <h:inputText id="password" value="#{CommandSubmissionsBean.password}"/><br>
  <h:commandButton id="submit" action="#{CommandSubmissionsBean.login}" value="Login" />


Code Example 3: Static Action Mapping

For the button labeled Login, the action mapping is to invoke the login method in the backing bean, CommandSubmissionBean. If the login method returns the success outcome, the response.jsp is invoked as per the navigation rule in Code Example 2.

Using Action Listeners

The page author can specify the action listeners for any standard component in the JavaServer Faces page itself. Code Example 4 illustrates how an action listener can be specified for a JavaServer Faces commandButton:

  <h:commandButton actionListener="#{CommandSubmissionsBean.detailsActionListener}" id="details" value="Show More Details"/>

Code Example 4: Specifying an Action Listener

For the button labeled Show More Details, the method detailsActionListener of the backing bean CommandSubmissionBean is specified as an action listener. This method is invoked whenever the button is pressed. This method can access all other components in the page and modify their state as needed.

References

For more information about this topic, refer to the following:
© Sun Microsystems 2005. All of the material in The Java BluePrints Solutions Catalog is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.