Download
FAQ History |
![]() ![]() ![]() |
API
Search Feedback |
Navigating Between Pages
As explained in section Navigation Model (page 805), this release of JavaServer Faces technology includes a new navigation model that eliminates the need to define navigation rules programmatically with an
ApplicationHandler
.Now you define page navigation rules in a centralized XML file called the application configuration resource file. See Application Configuration (page 807) for more information on this file.
Any additional processing associated with navigation that you might have included in an
ApplicationHandler
you now include in anAction
class. AnAction
object is referenced by theUICommand
component that triggers navigation. TheAction
object returns a logical outcome based on the results of its processing. This outcome describes what happened during the processing. The Action that was invoked and the outcome that is returned are two criteria a navigation rule uses for choosing which page to navigate to.This rest of this section explains:
What is Navigation?
Navigation is a set of rules for choosing the next page to be displayed after a button or hyperlink is clicked. The selection of the next page is determined by:
A single navigation rule defines how to navigate from one particular page to any number of other pages in an application. The JavaServer Faces implementation chooses the proper navigation rule according to what page is currently displayed.
Once the proper navigation rule is selected, the choice of which page to access next from the current page depends on the
Action
that was invoked and the outcome that was returned.The
UICommand
component either specifies an outcome from itsaction
property or refers to anAction
object with itsactionRef
property. TheAction
object performs some processing and returns a particular outcome string.The outcome can be anything the developer chooses, but Table 21-17 on page 891 lists some outcomes commonly used in Web applications.
Usually, the
Action
class performs some processing on the form data of the current page. For example, theAction
class might check if the username and password entered in the form match the username and password on file. If they match, theAction
returns the outcome "success". Otherwise, it returns the outcome "failure". As this example demonstrates, both theAction
and the outcome are necessary to determine the proper page to access.Here is a navigation rule that could be used with the example
Action
class processing described in the previous paragraph:<navigation-rule> <from-tree-id>logon.jsp</from-tree-id> <navigation-case> <from-action-ref>LogonForm.logon</from-action-ref> <from-outcome>success</from-outcome> <to-tree-id>/storefront.jsp</to-tree-id> </navigation-case> <navigation-case> <from-action-ref>LogonForm.logon</from-action-ref> <from-outcome>failure</from-outcome> <to-tree-id>/logon.jsp</to-tree-id> </navigation-case> </navigation-rule>This navigation rule defines the possible ways to navigate from
logon.jsp
. Eachnavigation-case
element defines one possible navigation path fromlogon.jsp
. The firstnavigation-case
says that ifLogonForm.logon
returns an outcome of "success",storefront.jsp
will be accessed. The secondnavigation-case
says thatlogon.jsp
will be re-rendered ifLogonForm.logon
returns "failure".For a complete description of how to define navigation rules, see Configuring Navigation Rules in faces-config.xml.
The next section describes what happens behind the scenes when navigation occurs.
How Navigation Works
As section The Lifecycle of a JavaServer Faces Page (page 791) explains, a JavaServer Faces page is represented by a component tree, which is comprised of all of the components on a page. To load another page, the JavaServer Faces implementation accesses a component tree identifier and stores the tree in the
FacesContext
. The new navigation model determines how this tree is selected.Any
UICommand
components in the tree are automatically registered with the defaultActionListenerImpl
. When one of the components is activated--such as by a button click--anActionEvent
is emitted. If the Invoke Application phase is reached, the defaultActionListenerImpl
handles this event.The
ActionListenerImpl
retrieves an outcome--such as "success" or "failure"--from the component generating the event. TheUICommand
component either literally specifies an outcome with itsaction
property or refers to a JavaBeans component property of typeAction
with itsactionRef
property. Theinvoke
method of theAction
object performs some processing and returns a particular outcome string.After receiving the outcome string, the
ActionListenerImpl
passes it to the defaultNavigationHandler
. Based on the outcome, the currently displayed page, and theAction
object that was invoked, theNavigationHandler
selects the appropriate component tree by consulting the application configuration file (faces-config.xml
).The next section explains how to define navigation rules for your application in the
faces-config.xml
file.Configuring Navigation Rules in faces-config.xml
An application's navigation configuration consists of a set of navigation rules. Each rule is defined by the
navigation-rule
element in thefaces-config.xml
file. See Setting Up The Application Configuration File for information on how to set up thefaces-config.xml
file for use in your application.Here are two example navigation rules:
<navigation-rule> <from-tree-id>/more.jsp</from-tree-id> <navigation-case> <from-outcome>success</from-outcome> <to-tree-id>/buy.jsp</to-tree-id> </navigation-case> <navigation-case> <from-outcome>out of stock</from-outcome> <from-action-ref>CarOptionServer.carBuyAction
</from-action-ref> <to-tree-id>/outofstock.jsp</to-tree-id> </navigation-case> </navigation-rule> <navigation-rule> <navigation-case> <from-outcome>error</from-outcome> <to-tree-id>/error.jsp</to-tree-id> </navigation-case> </navigation-case>The first navigation rule in this example says that the application will navigate from
more.jsp
to:The second navigation rule says that the application will navigate from any page to
error.jsp
if the application encountered an error.Each
navigation-rule
element corresponds to one component tree identifier, defined by the optionalfrom-tree-id
element. This means that each rule defines all the possible ways to navigate from one particular page in the application. If there is nofrom-tree-id
element, the navigation rules defined in thenavigation-rule
element apply to all the pages in the application. Thefrom-tree-id
element also allows wildcard matching patterns. For example, thisfrom-tree-id
element says the navigation rule applies to all the pages in thecars
directory:As shown in the example navigation rule, a
navigation-rule
element can contain zero or morenavigation-case
elements. Thenavigation-case
element defines a set of matching criteria. When these criteria are satisfied, the application will navigate to the page defined by theto-tree-id
element contained in the samenavigation-case
element.The navigation criteria are defined by optional
from-outcome
andfrom-action-ref
elements.The
from-outcome
element defines a logical outcome, such as "success". Thefrom-action-ref
element refers to a bean property that returns anAction
object. TheAction
object'sinvoke
method performs some logic to determine the outcome and returns the outcome.The
navigation-case
elements are checked against the outcome and theAction
parameters in this order:
- Cases specifying both a
from-outcome
value and afrom-action-ref
value. Both of these elements can be used if theAction
'sinvoke
method returns different outcomes depending on the result of the processing it performs.- Cases specifying only a
from-outcome
value. Thefrom-outcome
element must match either the outcome defined by theaction
attribute of theUICommand
component or the outcome returned by theAction
object referred to by theUICommand
component.- Cases specifying only a
from-action-ref
value. This value must match theAction
instance returned by theUICommand
component.Once any of these cases are matched, the component tree defined by the
to-tree-id
element will be selected for rendering.The section Referencing An Action From a Component explains how to write the tag corresponding to the
UICommand
component to return an outcome.Referencing An Action From a Component
The
command_button
andcommand_hyperlink
tags have two attributes used to specify an outcome, which is matched against thefrom-outcome
elements in the application configuration file in order to select the next page to be rendered. These attributes are:This
command_button
tag could be used with the example navigation rule from the previous section:<h:command_button id="buy2" key="buy" bundle="carDemoBundle" commandName="buy" actionRef="CarServer.carBuyAction">The
actionRef
attribute refers toCarOptionServer.carBuyAction
, a bean property that returns anAction
object, whoseinvoke
method returns the logical outcome.If the outcome matches an outcome defined by a
from-outcome
element in application configuration file the component tree specified in that navigation case is selected for rendering if one of these is true:Suppose that the buy2
command_button
tag used theaction
attribute instead of theactionRef
attribute:<h:command_button id="buy2" key="buy" bundle="carDemoBundle" commandName="buy" action="out-of-stock">If this outcome matches an outcome defined by a
from-outcome
element in the application configuration file, the component tree corresponding to this navigation case is selected for rendering, regardless of whether or not the same navigation case also contains afrom-action-ref
element.The next section explains how to write the bean and the
Action
class.Using an Action Object With a Navigation Rule
It's common for applications to have a choice of pages to navigate to from a given page. You usually need to provide some application-specific processing that determines which page to access in a certain situation. The processing code goes into the
invoke
method of anAction
object. Here is theAction
bean property and theAction
implementation used with the examples in the previous two sections:import javax.faces.application.Action; ... public class CurrentOptionServer extends Object{ ... public Action getCarBuyAction() { if (carBuyAction == null) { carBuyAction = new CarBuyAction(); return carBuyAction; } class CarBuyAction extends Action { public String invoke() { if (carId == 1 && currentPackageName.equals("Custom") && currentPackage.getSunRoofSelected()) { currentPackage.setSunRoofSelected(false); return "out of stock"; } else { return "success" } } }The
CarBuyAction.invoke
method checks if the first car is chosen, the Custom package is chosen and the sunroof option is selected. If this is true, thesunroof
checkbox component value is set to false, and the method returns the outcome, "out of stock". Otherwise, the outcome, "success" is returned.As shown in the example in section Configuring Navigation Rules in faces-config.xml, when the NavigationHandler receives the "out-of-stock" outcome, it selects the
/outofstock.jsp
component tree.As shown in the example code in this section, it's a good idea to include your
Action
class inside the same bean class that defines the property returning an instance of theAction
. This is because theAction
class will often need to access the bean's data to determine what outcome to return. Section Combining Component Data and Action Objects discusses this concept in more detail.
Download
FAQ History |
![]() ![]() ![]() |
API
Search Feedback |
All of the material in The Java(TM) Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.