Java Server Faces User\'s Guide

$: Java Server Faces User\'s Guide$
J2X1-1200-01ENZ2(00)

JavaServer Faces User's Guide

Preface

Purpose

This manual explains how to design and develop business applications when JavaServer Faces is applied to Web application development. Readers can get an understanding of the configuration and development of JavaServer Faces applications.

Intended Readers

This manual is intended for application designers and those who implement applications. Readers are assumed to have knowledge of the following: · Creating applications using servlets and JSPs

Organization of This Manual The manual has the following sections: Overview of JavaServer Faces

This section explains features of JavaServer Faces applications.

JavaServer Faces Functions This section explains functions of JavaServer Faces.

Development Using JavaServer Faces Tags This section explains how to develop applications by using the standard tags provided by JavaServer Faces.

Development Using UJI Tags This section explains how to use UJI tags in JavaServer Faces applications.

Using Apcoordinator Functions This section explains how to use Apcoordinator functions in JavaServer Faces applications.

Related Manuals

Read also the following manuals as necessary: JavaServer Faces API Reference

For details on JavaServer Faces Java classes and Java interfaces, refer to this manual. JavaServer Faces Definition File Reference

For details on coding of the JavaServer Faces definition file (faces-config.xml), refer to this manual. JavaServer Faces Tag Reference

For details of the standard tags provided by JavaServer Faces, refer to this manual. Apcoordinator User's Guide

For details on each function of Apcoordinator, refer to this manual. UJI Tag Reference

For details of UJI tags, refer to this manual.

i

ii

Contents Chapter 1 Overview of JavaServer Faces ................................................................1

1.1 JavaServer Faces ....................................................................................................................... 1

Chapter 2 JavaServer Faces Functions....................................................................3 2.1 JavaServer Faces Applications and Lifecycle............................................................................. 3 2.2 Input-Output Pages and UIComponents..................................................................................... 4 2.3 Managed Beans .......................................................................................................................... 5 2.4 Value Binding Expression and Method Binding Expression ....................................................... 5 2.5 Event Processing ........................................................................................................................ 7 2.6 Page Transitions ......................................................................................................................... 8 2.7 Validators..................................................................................................................................... 9 2.8 Converters................................................................................................................................... 9

Chapter 3 Development of JavaServer Faces Applications .................................... 11 3.1 Creating a Managed Bean ........................................................................................................ 11 3.2 Creating an Input-Output Page ................................................................................................. 12 3.3 Creating an Event Listener........................................................................................................ 13 3.4 Creating a Validator................................................................................................................... 16 3.5 Creating a Converter................................................................................................................. 19 3.6 Creating a Page Transition Definition ....................................................................................... 21 3.7 Displaying Messages ................................................................................................................ 22 3.8 Character Encoding .................................................................................................................. 24

Chapter 4 Development Using JavaServer Faces Tags .........................................27

Chapter 5 Development Using UJI Tags.................................................................33 5.1 Available UJI Tags ..................................................................................................................... 33 5.2 Referring to the Properties of Managed Beans......................................................................... 34 5.3 Using Validators ........................................................................................................................ 35 5.4 Using Converters ...................................................................................................................... 37 5.5 Using Events ............................................................................................................................. 37

5.5.1 Using action methods ........................................................................................................................37 5.5.2 Using valueChangeListener..............................................................................................................38

Chapter 6 Using Apcoordinator Functions ..............................................................41 6.1 Binary File Send/Receive Function........................................................................................... 41

6.1.1 Uploading files...................................................................................................................................41 6.1.2 Downloading files ..............................................................................................................................43

6.2 Application Log Function ........................................................................................................... 43 6.3 EJB and Web Service Invocation Function............................................................................... 44

Chapter 7 Setting Up the Runtime Environment .....................................................47 7.1 Runtime File Mapping ............................................................................................................... 47

iii

iv

7.2 Files Required for Execution..................................................................................................... 48 7.3 Web Application Environment Definition File (web.xml)............................................................ 48

Appendix A UIComponents Corresponding to UJI Tags..........................................51 A.1 UIComponent Specifications .................................................................................................... 51 A.2 UIComponent Class Diagrams .................................................................................................53

Terms ....................................................................................................................61

Chapter 1 Overview of JavaServer Faces

1.1 JavaServer Faces

JavaServer Faces is a set of specifications drawn up as JSR-127 by the Java Community Process (JCP). It is an application framework for creating Web application user interfaces. JavaServer Faces has the following features: · User interfaces (UIs) developed with JavaServer Faces in a development environment can be used to

develop Web applications through a GUI. · JavaServer Faces supports an "event model" that implements processing on a server at the time that an

event that occurred on a client is received. · Original UIs can be developed using the JavaServer Faces framework. The figure below shows an outline of an application using JavaServer Faces.

As shown in the above figure, a JavaServer Faces application consists of the following components:

JSP A JSP page can use Apcoordinator UJI tags and JavaServer Faces tags. It defines event processing for buttons on the page and for changes in input data. For each event, the JavaServer Faces runtime engine invokes the corresponding event listener or Java class method.

Managed bean Bean for storing page values

faces-config.xml File with definitions of the JavaServer Faces environment. The environment that is defined includes page transitions, events to be invoked, and beans to be used.

Validator, value change listener, and action listener Processing components that are individually invoked when an applicable request is received from a client

The following sections explain how to develop the components, including a JSP page, managed beans, and faces-config.xml.

1

2

Chapter 2 JavaServer Faces Functions

2.1 JavaServer Faces Applications and Lifecycle

As with general Java Web applications, JavaServer Faces applications run on servlet containers by using JSP, Java Beans, and event listeners.

One of the unique functions of JavaServer Faces is the capability to use built-in and user-created UIComponents, event handlers, validators, and converters defined in an external environment definition file (faces-config.xml). This enables UI and event processing logic to be corrected separately, thereby improving productivity in fixing and adding new functions to an application.

The lifecycle of a JavaServer Faces application is explained below. The lifecycle means the processing flow from the time that the JavaServer Faces application receives a request until it returns a response. JavaServer Faces processes a request in the following processing flow:

The six phases indicated by solid arrows are processed sequentially unless a validation or conversion error occurs or event processing occurs. The dotted lines indicate error processing.

Restore View phase

The Restore View phase begins when a request is sent to a server by the clicking of a link or button. In this phase, JavaServer Faces creates a UIComponent tree for an input-output page and associates event processing and validators with the UIComponents. The created tree is saved to the FacesContext instance.

Apply Request Values phase

After UIComponents are created in the Restore View phase, the Apply Request Values phase begins to acquire and apply the values of a sent form. If value acquisition or application fails, an error message is set in the FacesContext instance, and the phase changes to the Render Response phase.

Process Validations phase

In this phase, all validators associated with the page to be displayed are processed. If any value is invalid, an error message is set in the FacesContext instance, and the phase changes to the Render Response phase.

Update Model Values phase

In this phase, the values of the associated model are updated after the values are checked for validity. If

3

updating of the model fails, an error message is set in the FacesContext instance, and the phase changes to the Render Response phase.

Invoke Application phase

In this phase, application level events such as page transitions are processed. If an error occurs, an error message is set in the FacesContext instance, and the phase changes to the Render Response phase.

Render Response phase

In this phase, a UIComponent tree is returned as a response in a format (e.g., HTML) that can be rendered by the client.

2.2 Input-Output Pages and UIComponents

JavaServer Faces composes a page by combining UIComponents.UIComponents are components such as forms, text fields, and buttons that make up a page.The corresponding JSP extension tags are provided for individual UIComponents so that a page can be created with JSP extension tags written in a JSP file. To display a UIComponent text field, for example, write the h:inputText tag in the JSP file. The JSP file used to create a page is called an input-output page.

The standard JSP extension tags provided by JavaServer Faces are classified into two types: tags in the JavaServer Faces component tag library and tags in the JavaServer Faces basic tag library.The component tags are the tags of user interface components such as text fields and command buttons. The basic tags include the f:view tag that encloses all the JavaServer Faces tags and the tags in which event listeners are set. Thus, the basic tags specify the configuration and operation of applications and pages.These tag libraries can be used in the same way as ordinary custom libraries.

This product provides a tag library called UJI tags in addition to the standard tags provided by JavaServer Faces. For details on UJI tags, refer to "Development Using UJI Tags".

A coding example of an input-output page is shown below.As indicated by comments, the example assigns a value, specifies a validator, and specifies event processing.

<HTML>

<HEAD> <TITLE>Sample1</TITLE> </HEAD>



<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>

<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>

<BODY>



<f:view>

<H2>Sample</H2>

<h:form>



<h:inputText value="#{myBean.userId}" >



<f:validateLength maximum="10"/>

</h:inputText>



4

<h:commandButton action="#{myBean.doAnyAction}" value="GO"/>

</h:form>

</f:view>

</BODY>

</HTML>

The UIComponents in the above coding are converted into HTML by the renderer prepared in advance, and the resulting display is as shown below.

UIComponents and renderers used to display UIComponents are designed separately in JavaServer Faces.Accordingly, simply changing renderers enables UIComponents to be displayed in different modes.Renderers are created so that they display UIComponents in the appropriate formats for individual clients.In JavaServer Faces, Renderers that display UIComponent in HTML are prepared in advance.

For details on how to create input-output pages, refer to "Creating an Input-Output Page".

2.3 Managed Beans

Normally, JavaServer Faces applications store values to be displayed and data to be sent, while associating managed bean properties with UIComponents.Managed beans can define event processing, validation, and methods for page transitions.

To assign a managed bean value or an event processing method to a UIComponent, specify the managed bean property or method using the value binding expression or the method binding expression written in #{ }.An example of mapping with an input-output page is shown below.

[Example of using managed beans from an input-output page]



<h:inputText id="empNo"

value="#{EmployeeBean.userNumber}"

validator="#{EmployeeBean.validateNumber}" />

The procedure for using managed beans is as follows: 1. Create a Bean class. 2. Define the created Bean as a managed bean in the JavaServer Faces definition file (faces-config.xml). 3. Specify the property names and method names assigned to UIComponents on an input-output page. For details on how to create and use managed beans, refer to "Creating a Managed Bean".

2.4 Value Binding Expression and Method Binding Expression

This section explains the value binding expression and the method binding expression. The value binding expression is a notation method for associating a page with a property of a managed bean. The method binding expression is a notation method for associating a page with a method of a managed bean. Both expressions are mostly used for tag attributes. As in "#{mybean.myprop}", the value binding expression and the method binding expression must begin with "#{" and end with "}".

5

Value binding expression

Write a managed bean identifier and property name by concatenating them with "." (dot) in "#{ }". If beans are nested, as many beans as the number of nested beans can be concatenated using "." A sample JSP page is shown below.

<f:view>



<h:outputText value="#{mybean.myprop}" />



<h:outputText value="#{mybean1.mybean2.mybean3.myprop}" />

</f:view>

If the property is an array, java.util.List, java.util.Map, refer to the value by using "[]".

<f:view>



<h:outputText value="#{mybean.myArray[0]}" />



<h:outputText value="#{mybean.myList[3]}" />



<h:outputText value="#{mybean.myMap['mykey']}" />

</f:view>

Method binding expression

Write a managed bean identifier and method name by concatenating them with "." (dot) in "#{ }". As with referencing of values, if beans are nested, as many beans as the number of nested beans can be concatenated using "." A sample JSP page is shown below.

<f:view>

<h:form>



<h:inputText value="#{mybean.myprop}" validator="#{mybean.validate}" />

</h:form>

</f:view>

6

Reserved variables

The following reserved variables can be used in value binding expressions and method binding expressions.

Variable name Type Explanation

applicationScope java.util.Map Collection of all application scope

variables

cookie java.util.Map

Collection of cookies in a request. The Map key is a cookie name, and the value is the javax.servlet.http.Cookie instance.

facesContext javax.faces.context.FacesContext

javax.faces.context.FacesContext class instance

header java.util.Map Collection of all request headers. Individual values in Map are of the java.lang.String type.

headerValues java.util.Map Collection of all request headers. Individual values are arrays of the java.lang.String type.

initParam java.util.Map Collection of application initialization parameters

param java.util.Map Collection of request parameters. The value of the first request parameter of those corresponding to individual keys is stored.

paramValues java.util.Map Collection of request parameters. The request parameter corresponding to each key is stored in the java.lang.String array.

requestScope java.util.Map Collection of all request scope variables

sessionScope java.util.Map Collection of all session scope variables

view javax.faces.component.UIViewRoot

javax.faces.component.UIViewRoot class instance corresponding to the page being displayed

An example of use of a reserved variable is shown below.

<f:view>



<h:outputText value="#{param['paramKey']}" />

</f:view>

2.5 Event Processing

JavaServer Faces applications handle three types of events: ActionEvent, ValueChangeEvent, and PhaseEvent.

An event listener model of JavaServer Faces receives an event class using the listener interface and processes events occurring in UIComponents.

7

8

JavaServer Faces supports the following three types of events: · ActionEvent occurs at such times as when the user clicks a button or hyperlink component.This event

occurs in the Invoke Application or Apply Request Values phase. · ValueChangeEvent occurs when the user changes the value of a UIComponent. This event does not

occur at the time that a validation error is detected.This event occurs in the Process Validations or Apply Request Values phase.

· PhaseEvent can perform processing by causing an interrupt before or after a JavaServer Faces lifecycle phase.This event can be used for unified preprocessing and postprocessing of a business logic.

Applications can process these events as follows: · The application creates an event listener and assigns it to a UIComponent by using the

f:valueChangeListener tag or f:actionListener tag on an input-output page.In the case of the PhaseEvent listener, the application defines it in the JavaServer Faces definition file (faces-config.xml).

· The application uses the managed bean method to create event processing and specifies the method-binding expression in the appropriate attribute of a UIComponent.

For details on how to create and invoke individual events, refer to "Creating an Event Listener".

2.6 Page Transitions

Generally, each Web application, such as a JavaServer Faces application, consists of multiple input-output pages.Therefore, transitions between the pages must be defined and implemented when an application is created.

JavaServer Faces applications can easily define page transitions and which transition is executed according to event processing.Page transition is a series of rules to select the transition destination page when the user clicks a button or hyperlink.Define these rules by using the navigation-rule tag in the JavaServer Faces definition file (faces-config.xml) written in XML.Write transition source names, action results, and transition destination page names for the rules.

A coding example is shown below.

[Coding example of the JavaServer Faces definition file (faces-config.xml)]

<faces-config>

...

<navigation-rule>



<from-view-id>/input.jsp</from-view-id>



<navigation-case>

<from-outcome>success</from-outcome>

<to-view-id>/result.jsp</to-view-id>

</navigation-case>

<navigation-case>

<from-outcome>fail</from-outcome>

<to-view-id>/input.jsp</to-view-id>

</navigation-case>

</navigation-rule>

...

</faces-config>

9

The following methods can be used to specify rules for selections according to the type of user operation: · Specify the character string showing the action result for the value of the action attribute of a

UIComponent. · Specify the method that returns the action result by using the method binding expression as the value of

the action attribute of a UIComponent. For details on each method, refer to "Creating a Page Transition Definition".

2.7 Validators

JavaServer Faces supports a method for verifying data in UIComponents such as text fields in which users can enter data.Data in a UIComponent is verified before updated data is set in properties of the managed bean allocated to the UIComponent. If verification fails, properties of the managed bean are not updated.

JavaServer Faces defines the classes of a series of validators that implement standard data checks. In addition, it provides basic tags corresponding to the standard validators.

Developers of input-output pages can register validators in UIComponents. The standard validators provided by JavaServer Faces are available. In addition, custom validators can be created and used.

The procedure for using a validator is as follows: 1. Decide the validator to be used. - Use a standard validator if it satisfies the function requirements. - Otherwise, create and use a custom validator. 2. When using a custom validator, define it in the JavaServer Faces definition file (faces-config.xml). 3. Register the validator in a UIComponent on an input-output page. For details on the following points of validator development, refer to "Creating a Validator": · Standard validators provided by JavaServer Faces · Creating and registering a custom validator · Specifying a validator on an input-output page

2.8 Converters

When UIComponents are assigned to Bean properties, the data handled by JavaServer Faces is represented in the following two formats: · Format in which data is represented in data types, such as int and long, within a model · Format in which data is represented in such a way that users can read, enter, and correct it When a value on an input-output page is updated or when a Bean data value is changed by event processing, conversion processing between the two formats is performed.Data is automatically converted in standard mode unless otherwise specified. However, data may need to be converted to a specified format other than the standard format.For this reason, JavaServer Faces enables converters to be registered in UIComponents.The converters provided by JavaServer Faces can be used as well as custom converters created by users.

The procedure for using a converter is as follows: 1. Decide the converter to be used. - Use a standard converter if it satisfies the requirements. - Otherwise, create and use a custom converter. 2. Register the converter in a UIComponent on an input-output page. For details on the following points of converter development, refer to "Creating a Converter": · Standard converters provided by JavaServer Faces · Creating a custom converter · Specifying a converter on an input-output page

10

Chapter 3 Development of JavaServer Faces Applications

This section explains a standard development method using JavaServer Faces. An event model application has the following basic components:

Managed bean (model)

Input-output page (JSP)

Event listener (business logic)

Validator

Converter

Page transition definition (XML) Subsequent sections explain how to create these components.

3.1 Creating a Managed Bean

Create a Bean for storing values to be displayed or data to be sent. The Bean has values in its properties, and it also has accessor methods (Setter and Getter). In addition, it can implement event listeners.

For details, refer to "Creating an Input-Output Page". Registering the Bean as a managed bean enables the following types of operations through an input-output page: · Allocating input and output data to Bean properties · Allocating an input data validator to a Bean method · Allocating UIComponent event processing to a Bean method In the following example, a listener that operates when a value is updated and a listener that operates when a button is clicked are implemented.

package mypkg;

import javax.faces.event.ActionEvent;

import javax.faces.event.ValueChangeEvent;

public class MyBean {

protected String message = "My Message";

public String getMessage() {

return this.message;

}

public void setMessage(String message) {

this.message = message;

}

public String getIdForNextPage() {

// Acquires a value for a page transition.

return "success";

11

}

public void messageChanged(ValueChangeEvent event) {

// Coding of the processing executed at the time that the message property value is updated

}

public void pushed(ActionEvent e) {

// Coding of the processing executed at the time that an associated button is clicked

}

}

Specify the name and scope of the created model in the JavaServer Faces definition file (faces-config.xml). In the following example, the mypkg.MyBean class is registered with the name myBean, and the scope is session.

<faces-config>

<managed-bean>

<managed-bean-name>myBean</managed-bean-name>

<managed-bean-class>mypkg.MyBean</managed-bean-class>

<managed-bean-scope>session</managed-bean-scope>

</managed-bean>

</faces-config>

Specify the scope by selecting none, application, session, or request.If no scope is specified, none is assumed, and the Bean is not saved to any scope, i.e., the Bean exists only while it is referenced.

3.2 Creating an Input-Output Page

To use JavaServer Faces UIComponents on a JSP page, use the JavaServer Faces component tag library and JavaServer Faces basic tag library.The component tags are user interface component tags. The basic tags specify application and page structures and operations.These tag libraries can be used in the same way as general custom tag libraries.

To use these tags on an input-output page, the beginning of the page must have a declaration as shown below.

<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %> <%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>

The uri attribute identifies a tag library. The prefix attribute identifies the tag library to which a tag belongs.The above example specifies that a component tag be preceded by h: and that a basic tag be preceded by f: .

The JavaServer Faces tags represent a tree of UIComponents. The root of the tree is the UIViewRoot component, which is represented by the f:view tag.

<f:view> Other JavaServer Faces tags </f:view>

HTML and JSP tags can be written outside the f:view tags, but JavaServer Faces tags must be written within

12

the scope enclosed by the f:view tags. And, f:view corresponding to one screen is only one.

For details on the standard tags provided by JavaServer Faces and the display resulting from each tag, refer to "Development Using JavaServer Faces Tags".

Using value binding expressions and method binding expressions, UIComponent tags can allocate Bean properties to UIComponents and specify event processing, validators, and converters for them. An example is shown below. Note that the example provides comments with  for explanations, but no comment can actually be written between the < and > of a tag.

<f:view>

<h:form>

<h:inputText



value="#{myBean.message}"



valueChangeListener="#{myBean.messageChanged}" >



<f:validateLength maximum="10"/>

</h:inputText>

<h:commandButton



action="#{myBean.getIdForNextPage}"

value="Send"



actionListener="#{myBean.pushed}" />

</h:form>

</f:view>

For details on how to specify the following processing definitions, refer to the respective sections indicated next to them: · Event listener - Creating an Event Listener · Converter - Creating a Converter · Validator - Creating a Validator · Page transition - Creating a Page Transition Definition

3.3 Creating an Event Listener

There are three types of events: ActionEvent, ValueChangeEvent, and PhaseEvent.

ActionEvent

The ActionEvent event occurs in a UIComponent that implements the javax.faces.component.ActionSource interface.This event occurs when an anchor or button is clicked.To use ActionEvent, use one of the following procedures: · Specify the managed bean method by writing a method binding expression in the actionListener

attribute of the UIComponent tag. The argument to the specified method must be an instance of the

13

javax.faces.event.ActionEvent class, and the return value must be void. The specified method is invoked when ActionEvent occurs.

· Create a class that implements the javax.faces.event.ActionListener interface. Write the f:actionListener tags within the UIComponent tags, specifying the implementation class of ActionListener. The processAction method of ActionListener is invoked when ActionEvent occurs.

Examples of use of the actionListener attribute are shown below.

[JSP coding example]

<h:commandButton value="Send" actionListener="#{myBean.pushed}" />

[Event listener coding example]

import javax.faces.event.ActionEvent;


public void pushed(ActionEvent event) {

// Coding of processing

}

}

ValueChangeEvent

This event occurs in the UIComponent that implements the javax.faces.component.EditableValueHolder interface.It occurs when the value of a tag (e.g., field, combo box) having an input value is changed.To use ValueChangeEvent, use one of the following procedures: · Specify the managed bean method by writing a method binding expression in the

valueChangeListener attribute of the UIComponent tag. The argument to the specified method must be an instance of the javax.faces.event.ValueChangeEvent class, and the return value must be void. The specified method is invoked when ValueChangeEvent occurs.

· Create a class that implements the javax.faces.event.ValueChangeListener interface. Write the f:valueChangeListener tags within the UIComponent tags, specifying the implementation class of ValueChangeListener. The processValueChange method of ValueChangeListener is invoked when ValueChangeEvent occurs.

Note that ValueChangeEvent occurs not at the moment a value on the page is changed but at the moment the request issued by the clicking of a button is sent to a server.

Examples of use of the f:valueChangeListener tag are shown below.


<h:inputText value="#{myBean.message}" >

<f:valueChangeListener type="mypkg.listeners.InputTextListener" />

</h:inputText>

14


package mypkg.listeners;


public class InputTextListener implements javax.faces.event.ValueChangeListener {

public void processValueChange(ValueChangeEvent event) {

// Coding of processing

}

}

PhaseEvent

A PhaseEvent listener can be used for processing by causing an interrupt before or after a JavaServer Faces phase. This event listener can be used for unified preprocessing and postprocessing of business logic.Examples of use are shown below.


import javax.faces.event.PhaseId;

public class MyFacesListener implements javax.faces.event.PhaseListener{

public void beforePhase(javax.faces.event.PhaseEvent event){

// Coding of preprocessing

}

public void afterPhase(javax.faces.event.PhaseEvent event){

// Coding of postprocessing

}

public PhaseId getPhaseId(){

// Specifies the interrupt phase.

return PhaseId.INVOKE_APPLICATION;

}

}

[Definitions in the JavaServer Faces definition file (faces-config.xml)]

<faces-config>

15

...

<lifecycle>

<phase-listener>mypkg.MyFacesListener</phase-listener>

</lifecycle>

...

</faces-config>

In the event coding example, the following can be specified for the return value of the getPhaseId method. javax.faces.event.PhaseId.ANY_PHASE Interrupts any phase.

javax.faces.event.PhaseId.RESTORE_VIEW Interrupts the Restore View phase. javax.faces.event.PhaseId.APPLY_REQUEST_VALUES Interrupts the Apply Request Values phase.

javax.faces.event.PhaseId.PROCESS_VALIDATIONS Interrupts the Process Validations phase. javax.faces.event.PhaseId.UPDATE_MODEL_VALUES Interrupts the Update Model Values phase.

javax.faces.event.PhaseId.INVOKE_APPLICATION Interrupts the Invoke Application phase. javax.faces.event.PhaseId.RENDER_RESPONSE Interrupts the Render Response phase.

3.4 Creating a Validator

As many validators as desired can be specified for the UIComponent that implements the javax.faces.component.EditableValueHolder interface. Validators can be used in three modes: use of standard validators that have already been prepared, use of method-binding, or use of custom validators created by users.

Standard validators

The following three standard validators are available:

LengthValidator This validator checks the length of value that is entered. It can check the minimum and maximum values of the length.

<f:validateLength minimum="5" maximum="9" />

DoubleRangeValidator This validator checks whether a numeric value that has been entered is within the specified range. It can check the maximum and minimum values. The specifiable value is the range of Double.

<f:validateDoubleRange minimum="10.00" maximum="999.99" />

LongRangeValidator This validator checks whether a numeric value that has been entered is within the specified range. It can check the maximum and minimum values. The specifiable value is the range of Long.

16

<f:validateLongRange minimum="10" maximum="1000" />

The corresponding tags are prepared for these standard validators. They can be used by writing them within the tags to be checked.

<h:inputText value="#{myBean.message}">

<f:validateLength minimum="5" maximum="9" />

</h:inputText>

Checking using method-binding

A managed bean method can be written in the validatorattribute of the tag to be checked. However, only one validator can be specified in this method. To specify multiple validators, use standard validators or custom validators.


<h:inputText value="#{myBean.message}" validator="#{myBean.validate}" />

[Validator coding example]

import javax.faces.application.FacesMessage;

import javax.faces.component.UIComponent;

import javax.faces.context.FacesContext;

import javax.faces.validator.ValidatorException;


...

public void validate(FacesContext context, UIComponent component, Object value){

// Coding of value check processing

String text = (String)value;

if(text.length() > 10){

throw new ValidatorException(new FacesMessage ("The number of characters exceeds 10."));

// The following method can be used alternatively:

/*

context.addMessage(component.getClientId(context),

new FacesMessage ("The number of characters exceeds 10."));

((UIInput)component).setValid(false);

*/

}

}

17

}

Specify void for the return value of the method specified in the validator attribute. Use three arguments as shown in the above coding example. Their contents are as follows: · FacesContext instance · UIComponent that specifies the validator attribute · Value to be verified For any error detected by the checking, error messages can be created and displayed with the javax.faces.application.FacesMessage class, as shown in the above example. For details on how to display it, refer to Displaying Messages.

Custom validators

A custom validator that implements arbitrarily defined check logic can be created. A custom validator can be created by implementing the javax.faces.validator.Validator interface. An example of a custom validator is shown below.

[Example of a custom validator]



import javax.faces.component.UIInput;



public class MyValidator implements javax.faces.validator.Validator {

public void validate(FacesContext context, UIComponent component, Object value)

throws ValidatorException {

String text = (String)value;

if(text.length() > 10){

throw new ValidatorException(new FacesMessage ("The number of characters exceeds 10."));

// The following method can be used alternatively:

/*

context.addMessage(component.getClientId(context),

new FacesMessage ("The number of characters exceeds 10."));

((UIInput)component).setValid(false);

*/

}

}

}

For any error detected by the checking, error messages can be created and displayed with the javax.faces.application.FacesMessage class, as shown in the above example. For details on how to display it, refer to Displaying Messages.

Assign a validator ID to the validator thus created, and save it to the JavaServer Faces definition file

18

(faces-config.xml). The validator ID myValidator is assigned to the validator in the following example.

<faces-config>

...

<validator>

<validator-id>myValidator</validator-id>

<validator-class>mypkg.MyValidator</validator-class>

</validator>

...

</faces-config>

Use the stored validator with a JSP page as shown below.

<h:inputText value="#{myBean.message}">

<f:validator validatorId="myValidator" />

</h:inputText>

3.5 Creating a Converter

A converter can be defined in the UIComponent that implements the javax.faces.component.ValueHolder interface. Converters can be used in two modes: use of standard converters that have already been prepared, or use of custom converters.

Standard converters

The following standard converters are available. BigDecimalConverter Conversion to java.math.BigDecimal BigIntegerConverter Conversion to java.math.BigInteger

BooleanConverter Conversion to java.lang.Boolean ByteConverter Conversion to java.lang.Byte

CharacterConverter Conversion to java.lang.Character DateTimeConverter Conversion to a pattern that can be specified for java.text.SimpleDateFormat

DoubleConverter Conversion to java.lang.Double FloatConverter Conversion to java.lang.Float

IntegerConverter Conversion to java.lang.Integer LongConverter Conversion to java.lang.Long

NumberConverter Conversion to a pattern that can be specified for java.text.DecimalFormat ShortConverter Conversion to java.lang.Short

To use a converter, specify the ID of the converter by using the tag converter attribute or the f:converter tag. To use a standard converter, specify "javax.faces.[converter name excluding Converter]" as the converter ID. For example, specify "javax.faces.BigDecimal".

Custom converters

A custom converter can be created to implement conversion to an arbitrarily specified object.Create a custom

19

converter by implementing the javax.faces.convert.Converter interface.

[Example of a custom converter]



public class MyConverter implements javax.faces.convert.Converter {

public Object getAsObject(FacesContext context, UIComponent component, String value) {

// Coding of the String -> Object conversion rules (upward conversion to the business logic)

}

public String getAsString(FacesContext context, UIComponent component, Object value) {

// Coding of the Object -> String conversion rules (downward conversion to the display)

}

}

Assign a converter ID to the converter thus created, and save it to the JavaServer Faces definition file (faces-config.xml).

<faces-config>

...

<converter>

<converter-id>myConverter</converter-id>

<converter-class>mypkg.MyConverter</converter-class>

</converter>

...

</faces-config>

Using a converter

To use a converter, specify the ID of the converter. Specify the converter ID by writing it in the tag converter attribute or using the f:converter tag. Coding examples are shown below.

[convert attribute]

<h:inputText value="#{myBean.bigDecimal}" converter="javax.faces.BigDecimalConverter" />

[f:converter tag]

<h:inputText value="#{myBean.bigDecimal}" >

20

<f:converter converterId="myConverter"/>

</h:inputText>

3.6 Creating a Page Transition Definition

To create a page transition definition, use the navigation-rule tag in the JavaServer Faces definition file (faces-config.xml).

[Sample JavaServer Faces definition file (faces-config.xml)]

<faces-config>

...

<navigation-rule>



<from-view-id>/input.jsp</from-view-id>



<navigation-case>



<from-outcome>success</from-outcome>

<to-view-id>/result.jsp</to-view-id>

</navigation-case>

<navigation-case>



<from-outcome>fail</from-outcome>

<to-view-id>/input.jsp</to-view-id>

</navigation-case>

</navigation-rule>

...

</faces-config>

The "action result" defined in the JavaServer Faces definition file (faces-config.xml) is the value of the action attribute of a button or anchor. The method of a page transition can be classified into the following two types according to how the action attribute is specified: static action and dynamic action.

Static action

Static action means that a fixed character string is specified as the value of the action attribute. Use this type of action when the page transition destination is fixed.

[Example of use of static action]

21

<h:commandButton action="success" value="Send" />

Dynamic action

Dynamic action means that a managed bean method is specified with a method binding expression for the action attribute value. The specified method is invoked when ActionEvent occurs, and its return value is the action result. The specified method must have no argument, and it must return String as the return value. Use dynamic action when the page transition destination varies depending on the processing result of the business logic.

[Coding example of a JSP page using dynamic action]

<h:commandButton action="#{myBean.getIdForNextPage}" value="Send" />

[Coding example of a managed bean using dynamic action]

package mypkg;


...

public String getIdForNextPage() {

// Changes the return value depending on the conditions.

if (...) {

return "success";

}

else {

return "fail";

}

}

}

3.7 Displaying Messages

JavaServer Faces has a function for displaying messages by associating them with UIComponents.The function is mainly used to display an error message at the time that an error is detected in a validator.For example, a form may be sent with an input-required text field that has been left blank. In this case, a message such as "This item must be specified" can be displayed immediately under the text field.

Associating messages with UIComponents

Associating messages according to validator processing For details on how to associate messages with UIComponents according to validator processing, refer to Custom Validators.

Associating messages with UIComponents according to processing other than validator processing Associate messages with UIComponents by using the addMessage method of the

22

javax.faces.context.FacesContext class.Use the javax.faces.application.FacesMessage class to render messages.An example of associating messages in an action method is shown below.

[Associating messages by using the addMessage method]




...

public String buyProduct() {

...

// Acquires FacesContext.

FacesContext context = FacesContext.getCurrentInstance();

// Acquires the UIComponent with which a message is to be associated.

// Here, the text field identified with id="productCodeField" is acquired from the form identified with id="myForm" is acquired.

UIComponent component = context.getViewRoot().findComponent("myForm:productCodeField");

// Acquires the client ID of the UIComponent.

String clientId = component.getClientId(context);

// Creates a message.

FacesMessage message = new FacesMessage ("The product code does not exist. Please check it.");

// Associates the message with the UIComponent.

context.addMessage(clientId, message);

...

}

Displaying the message associated with a UIComponent

To display such a message, use the h:message tag or h:messages tag on the input-output page.The h:message tag is used to display only the message of the specified UIComponent.The h:messages tag is used to display messages of all UIComponents.

An example of use of the h:message tag is shown below.To indicate the message to be displayed, specify the component ID of the UIComponent associated with the message. Specify the component ID in the for attribute.

[Displaying messages by using the h:message tag]

23

<f:view>

<h:form id="myForm">

Product code <h:inputText id="productCodeField" value="#{myBean.product}" /> <br>



<h:message for="productCodeField" /> <br>

Count <h:inputText id="countField" value="#{myBean.count}" /> <br>



<h:message for="countField" /> <br>

...

<h:commandButton action="#{myBean.buyProduct}" value="Buy"/>

</h:form>

</f:view>

To display all messages in one place, use the h:messages tag.

[Displaying messages by using the h:messages tag]

<f:view>

<h:form id="myForm">



<h:messages />

Product code <h:inputText id="productCodeField" value="#{myBean.product}" /> <br>

Count <h:inputText id="countField" value="#{myBean.count}" /> <br>

...

<h:commandButton action="#{myBean.buyProduct}" value="Buy"/>

</h:form>

</f:view>

3.8 Character Encoding

The character encoding of the response transmitted to a browser is specified by the contentType attribute of the page directive of JSP. The example when ISO-8859-1 is specified is as follows.

[Example of page directive described in JSP]

24

25

<%@ page contentType="text/html; charset=ISO-8859-1" %>

The character encoding of the request received from a browser is decided as follows. Therefore, the character encoding of the request need not be specified in the application. · When the Content-Type header exists in the HTTP request received from a browser, and the character

encoding is specified for the value, this character encoding is used. · The same character encoding that transmits the last request of the same session is used, except for the

above-mentioned.

26

Chapter 4 Development Using JavaServer Faces Tags

JavaServer Faces supports the tags listed below. For details on each tag, refer to the JavaServer Faces Tag Reference.

Basic tags Tag name Function

f:actionListner Registers an action listener for the parent UIComponent.

f:valueChangeListner Registers a value change listener for the parent UIComponent.

f:attribute Specifies an attribute that can be specified for the parent UICompnent.

f:converter Registers a converter in the parent UIComponent.

f:convertDateTime Registers a DateTime converter in the parent UIComponent.

f:convertNumber Registers a Number converter in the parent UIComponent.

f:facet Assigns a special name (e.g., a table header, footer) by enclosing it in this tag.

f:loadBundle Loads text from a resource file. f:param Adds a parameter.

f:selectItem Displays the item from the UISelectOne or UISelectMany component.

f:selectItems Displays multiple items from the UISelectOne or UISelectMany component.

f:subview Loads another JSP page containing JavaServer Faces tags.

f:validateDoubleRange Registers DoubleRangeValidator in a UIComponent.

f:validateLength Registers LengthValidator in a UIComponent.

f:validateLongRange Registers LongRangeValidator in a UIComponent.

f:validator Registers a custom validator in a UIComponent.

f:verbatim Creates a UIOutput component that acquires the contents of this tag.

f:view Encloses all of the JavaServer Faces tags on a page.

HTML tags Tag name Function Coding example Display

h:column

is used in combination with h:dataTable to display one

Use this tag in combination with h:dataTable (refer to Examples of combinations).

Refer to Examples of combinations.

27

Tag name Function Coding example Display column of data in a table.

h:commandButton Button used to send form data to a server

<h:commandButton value="Send" action="send"/>

Button (HTML <input> tag; the type is submit, reset, or image):

h:commandLink Hyperlink used to send form data to a server

<h:commandLink action="send">

<h:outputText value="Send"/>

</h:commandLink>

Hyperlink (HTML <a href> tag):

h:dataTable Displays a table based on a set (e.g., array) of data.

Use this tag in combination with h:column (refer to Examples of combinations).

Refer to

Examples of combinations.

h:form Creates a form.

<h:form>

...

</h:form>

Form (HTML <form> tag)

h:graphicImage Displays an image.

<h:graphicImage

id="picture" url="/images/my_picture.gif"/>

Image (HTML <img> tag)

h:inputHidden Creates hidden send data of a form.

<h:inputHidden

id="hidden" value="#{myBean.hiddenPassword}"/>

No display (HTML <input type=hidden> tag)

h:inputSecret Text field for a password

<h:inputSecret value="#{myBean.secretPassword}"/>

Text field for password (HTML <input type=password> tag):

h:inputText Text field

<h:inputText value="#{myBean.inputText}"/>

Text field (HTML <input type=text> tag):

h:inputTextarea Multi-line text field

<h:inputTextarea value="#{myBean.inputTextare

Multi-line text field (HTML <textarea> tag):

28

Tag name Function Coding example Display a}"/>

h:message Displays the message of a specific UIComponent.

<h:message for="someComponentId"/>

Message

h:messages Displays the messages of all UIComponents.

<h:messages/>

Messages

h:outputLabel Displays a label that identifies an input field.

<h:outputLabel for="userId">

<h:outputText id="userId" value="#{myBean.userid}"/>

</h:outputLabel>

Label (HTML <label> tag)

h:outputLink Hyperlink to another page that creates no action event

<h:outputLink value="http://someHost/">

<h:outputText value="someHost"/>

</h:outputLink>

Hyperlink (HTML <a href> tag):

h:outputFormat

Creates text by inserting parameters into it according to the format and then displays it.

<h:outputFormat value="Total is {0}">

<f:param value="#{mybean.total}"/>

</h:outputFormat>

Text:

Total is 123

h:outputText Displays text.

<h:outputText value="Hello world!"/>

Text:

Hello world!

h:panelGrid Displays a table.

<h:panelGrid columns="2" border="1">

<f:facet name="header">

<h:outputText value="table title"/>

</f:facet>

<h:outputText value="value1" />


</h:panelGrid>

table title

value1 value2

29

Tag name Function Coding example Display

h:panelGroup Groups UIComponents.

Use this tag in combination with h:panelGrid (refer to Examples of combinations).

Refer to Examples of combinations.

h:selectBooleanCheckbox

Single check box

<h:selectBooleanCheckbox

value="#{myBean.selectBooleanCheckbox}" />

Check box (HTML <input type=checkbox> tag):

h:selectManyCheckbox

Multiple check boxes

<h:selectManyCheckbox

value="#{myBean.selectManyCheckbox1}">

<f:selectItem itemLabel="Option 1" itemValue="check1"/>

<f:selectItem itemLabel="Option 2" itemValue="check2"/>

</h:selectManyCheckbox>

Multiple check boxes (HTML <input type=checkbox> tag):

h:selectManyListbox

List box from which multiple options can be selected

<h:selectManyListbox value="#{myBean.selectManyListbox}">

<f:selectItem itemLabel="List1" itemValue="List1"/>

<f:selectItem itemLabel="List2" itemValue="List2"/>

</h:selectManyListbox>

List box (HTML <select> tag):

h:selectManyMenu

List box with height 1 from which multiple options can be selected

<h:selectManyMenu value="#{myBean.selectManyMenu}">

<f:selectItems value="#{selectManyList}"/>

</h:selectManyMenu>


h:selectOneListbox

List box from which a single option can be selected

<h:selectOneListbox value="#{myBean.selectOneListbox}">


30

Tag name Function Coding example Display <f:selectItems value="#{selectManyList}"/>

</h:selectOneListbox>

h:selectOneMenu Combo box from which a single option can be selected

<h:selectOneMenu value="#{myBean.selectOneMenu}">


</h:selectOneMenu>

Combo box (HTML <select> tag):

h:selectOneRadio Multiple radio buttons

<h:selectOneRadio value="#{myBean.selectOneRadio}">


</h:selectOneRadio>

Multiple radio buttons (HTML <input type=radio> tag):

[Examples of combinations]

Combination tags Coding example Display

h:dataTable h:column

<h:dataTable value="#{myBean.items}" var="item" border="1">

<h:column>


<h:outputText value="name"/>

</f:facet>

<h:outputText value="#{item.name}" />

</h:column>

<h:column>


<h:outputText value="value"/>

</f:facet>

<h:outputText value="#{item.value}" />

</h:column>

name value

tableData1 memory1

tableData2 memory2

tableData3 memory3

31

32

Combination tags Coding example Display

</h:dataTable>

h:panelGrid h:panelGroup

<h:panelGrid columns="2" border="1">


<h:outputText value="table title"/>

</f:facet>



<h:panelGroup>


<h:outputText value="(*)" />

</h:panelGroup>


</h:panelGrid>

table title

value1 value2

value3(*) value4

Chapter 5 Development Using UJI Tags

5.1 Available UJI Tags

JavaServer Faces applications can use the UJI tags listed below. For details of the UJI tags, refer to the UJI Tag Reference.

Basic tags Tag name Explanation

uji:getProperty Outputs values of managed bean properties to the page.

uji:resourceText Outputs the character strings defined in a resource file.

Screen part tags Tag name Explanation uji:list

uji:listRenderer Expands data in the form of a list.

uji:table

uji:tableRenderer Expands data in the form of a table.

uji:tree

uji:treeRenderer Expands data in the form of a tree.

uji:switch

uji:case Displays a different page depending on the conditions.

uji:composite

uji:compositeRenderer Operates managed beans in the composite bean format.

uji:value Value of the current object

uji:name Input-output item name of the current object

uji:compositeName Input-output item name of the current object within uji:composite

uji:children Expands subordinate structures in the format for screen part tag expansion.

Client script tags Tag name Explanation uji:action Coding of client script corresponding to an event

uji:validate Coding of an item check corresponding to an event

uji:form Used in place of the HTML form tag.

uji:input Used in place of the HTML input tag. uji:textarea Used in place of the HTML textarea tag.

uji:select Used in place of the HTML select tag.

Component tags (field tags) Tag name Explanation uji:fieldString Character string input field

33

Tag name Explanation uji:fieldLong Integer input field

uji:fieldDouble Real number input field uji:fieldBigInteger Decimal integer input field

uji:fieldBigDecimal Decimal fraction input field uji:fieldDate Date/time input field uji:fieldTextArea Multiple-line text input field

uji:checkBox Check box uji:radioButton Radio button

uji:pushButton Pushbutton uji:anchor Anchor

uji:label Label

Component tags (collection tags) Tag name Explanation uji:comboBox Option items in the form of a combo box

uji:listBox Option items in the form of a list box uji:buttonList Pair of buttons

uji:recordView Pair of input items in the form of a record uji:tableView Table

uji:treeView Table with a tree

Component tags (layout tags) Tag name Explanation uji:borderLayout

uji:borderLayoutRenderer Layout comprising four areas (top, bottom, left, and right)

uji:gridLayout

uji:gridLayoutRenderer Layout for aligning items to a grid

uji:tabbedLayout

uji:tabbedLayoutRenderer

Layout that can be switched by tabbing (not available for Netscape 4.x)

The tag which specifies a color name Tag name Explanation

uji:colorMap Assigns a name to each color.

5.2 Referring to the Properties of Managed Beans

To refer to properties of managed beans by using UJI tags, specify a bean ID defined in the JavaServer Faces definition file (faces-config.xml) in the bean attribute, and specify a bean property name in the property attribute. A sample JavaServer Faces definition file (faces-config.xml) and sample JSP are shown below.

[Sample JavaServer Faces definition file (faces-config.xml)]

<faces-config>

<managed-bean>

<managed-bean-name>myBean</managed-bean-name>

34

<managed-bean-class>mypkg.MyBean</managed-bean-class>

<managed-bean-scope>request</managed-bean-scope>

</managed-bean>

</faces-config>

[Sample JSP using uji:list]

<f:view>

<uji:form name="myform" >

<uji:list bean="myBean" property="listModel" >

<uji:listRenderer type="list" >

<ul><uji:children /></ul>

</uji:listRenderer>

<uji:listRenderer type="element" >

<li><input name="<uji:name/>" value="<uji:value/>"></li>

</uji:listRenderer>

</uji:list>

<uji:pushButton label="Send" />

</uji:form>

</f:view>

5.3 Using Validators

Validators can be used with the following UJI tags.

Tag name Standard validators(*1) Object type passed to the validator

uji:name uji:compositeName uji:input uji:textarea uji:select

java.lang.String

uji:recordView Array of java.lang.String

uji:tableView com.fujitsu.uji.faces.collect.TableValue

uji:treeView com.fujitsu.uji.faces.collect.TreeValue

uji:fieldBigDecimal uji:fieldBigInteger uji:fieldDate uji:fieldDouble uji:fieldLong uji:fieldString uji:fieldTextArea

java.lang.String

35

(*1)This is shown to be able to use standard validators of JavaServer Faces.

Validators can be used in the same way as the standard validators of JavaServer Faces. An example is shown below.

[Example of use of a validator with uji:fieldString]

<f:view>


<uji:fieldString bean="myBean" property="fieldString" validator="#{myBean.validate}" />


</uji:form>

</f:view>

[Sample validator]






public void validate(FacesContext context, UIComponent component, Object value) {

if(value == null || value.toString().length() == 0){

throw new ValidatorException(new FacesMessage("A value needs to be input."));

}

}

}

An exception message defined by a validator is displayed using the h:message tag or h:messages tag.

<f:view>


<uji:fieldString bean="myBean" property="fieldString"

validator="#{myBean.validate}"id ="fieldString1"/>

<h:message for="fieldString1" />


</uji:form>

</f:view>

36

5.4 Using Converters

Converters can be used with the following UJI tags.

Tag name getAsObject(*1) getAsString(*2) Standard converters(*3) Note

uji:name uji:value uji:compositeName uji:input uji:textarea uji:getProperty uji:resourceText

uji:select

The return value of getAsObject method should be the same as property type of bean. The type of the third argument of getAsString method is property type of bean.

uji:fieldBigDecimal uji:fieldBigInteger

uji:fieldDate uji:fieldDouble uji:fieldLong

uji:fieldString

uji:fieldTextArea

The return value of getAsObject method should be String. The type of the third argument of getAsString method is String.

(*1)This is shown to be able to use only when a request is set in a model (getAsObject of javax.faces.convert.Converter interface). (*2)This is shown to be able to use only when UIComponent values are displayed (getAsString of javax.faces.convert.Converter interface). (*3)This is shown to be able to use standard converters of JavaServer Faces.

Converters can be used in the same way as the standard converters of JavaServer Faces. An example is shown below.

[Example of use of a converter with uji:getProperty]

<f:view>

<uji:getProperty bean="myBean" property="mypros">

<f:convertNumber pattern="#,##0.00" />

</uji:getProperty>

</f:view>

5.5 Using Events

5.5.1 Using action methods

uji:pushButton can specify an action method by using the action attribute. uji:anchor can specify an action method by using the actionValue attribute. An example of specifying an action method with uji:pushButton is shown below.

37

<f:view>


...

<uji:pushButton label="Send" action="#{mybean.doAction}" />

</uji:form>

</f:view>

If the selectedValue attribute is used, such as for one page that has multiple buttons, the button that has been clicked can be specified in a managed bean. Code a value binding expression for the selectedValue attribute. In this case, the value of the item class specified by the bean and property attributes is set in the property specified by selectedValue.

<f:view>


...

<uji:pushButton label="Send" bean="myBean" property="pushButton"

action="#{mybean.doAction}"

selectedValue="#{mybean.selectedValue}" />

</uji:form>

</f:view>

To use a button or anchor with the uji:tableView or uji:treeView tag, specify aButton (for a button) or aLink (for an anchor) in the column attribute. For aButton or aLink, use a method binding expression following a colon ":" to specify the action to be invoked. An example is shown below.

<f:view>


...

<uji:tableView bean="myBean" property="tableView"

dataCellType="data;data;aButton:#{mybean.doAction}" />

</uji:form>

</f:view>

5.5.2 Using valueChangeListener

valueChangeListener can be used with the following tags.

-uji:name tag -uji:fieldBigDecimal tag

-uji:compositeName tag -uji:fieldBigInteger tag

-uji:input tag -uji:fieldDate tag

-uji:textarea tag -uji:fieldDouble tag

38

-uji:select tag -uji:fieldLong tag

-uji:recordView tag -uji:fieldString tag

-uji:tableView tag -uji:fieldTextArea tag

-uji:treeView tag -uji:buttonList tag

-uji:listBox tag -uji:checkBox tag

-uji:radioButton tag -uji:comboBox tag

valueChangeListener can be used in the same way as the standard tags of JavaServer Faces. An example is shown below.

[Example of use of valueChangeListener with uji:fieldString]

<f:view>


<uji:fieldString bean="myBean" property="fieldString"

valueChangeListener="#{myBean.valueChanged}" />


</uji:form>

</f:view>

[Sample valueChangeListener]



public void valueChanged(ValueChangeEvent event) {

// Coding of processing that is executed at the time that a value is changed

}

}

In this case, the type of object acquired by the getNewValue or getOldValue method of the ValueChangeEvent class varies depending on the tag.

Object type tag name

java.lang.String

-uji:fieldBigDecimal tag -uji:comboBox tag

-uji:fieldBigInteger tag -uji:name tag

-uji:fieldDate tag -uji:compositeName tag

-uji:fieldDouble tag -uji:input tag

-uji:fieldLong tag -uji:textarea tag

-uji:fieldString tag -uji:select tag

-uji:fieldTextArea tag -uji:recordView tag

39

40

Object type tag name

-uji:buttonList tag -uji:listBox tag

-uji:checkBox tag

java.lang.String array

If multipleMode is true with the following tags:

-uji:listBox tag

-uji:buttonList tag

-uji:select tag com.fujitsu.uji.faces.collect.TableValue -uji:tableView tag

com.fujitsu.uji.faces.collect.TreeValue -uji:treeView tag

The uji:radioButton tag varies depending on the pickUpMode value as follows:

The value of is ject: pickUpMode obObject type specified by the selectedBean and selectedProperty attributes

The value of pickUpMode is st: lijava.lang.Integer type

The value of pickUpMode is table: com.fujitsu.uji.compo.TableCoord type

Chapter 6 Using Apcoordinator Functions

JavaServer Faces applications can use the following Apcoordinator functions:

Binary file send/receive function

Application log function

EJB and Web service invocation function

6.1 Binary File Send/Receive Function

6.1.1 Uploading files

To upload a file, add the com.fujitsu.uji.faces.FacesMimeSource type property to the managed bean.

import com.fujitsu.uji.faces.FacesMimeSource;


protected FacesMimeSource file;

public FacesMimeSource getFile(){

return file;

}

public void setFile(FacesMimeSource file){

this.file = file;

}

}

Next, add enctype="multipart/form-data" to the uji:form tag. The uploaded file is stored at the location specified by the bean attribute and property attribute.

<f:view>

<uji:form name="myform" method="post" enctype="multipart/form-data" >

<uji:input type="file" bean="myBean" property="file" />

<uji:pushButton label="Send" action="#{mybean.doAction}"/>

</uji:form>

</f:view>

The action method can retrieve streams and files from FacesMimeSource.To store them on a server, specify the absolute path to the server.

import java.io.InputStream;

.....

public String doAction() {

String fileName = null;

41

InputStream is = null;

if (file != null) {

fileName = file.getFileName();

is = file.getInputStream();

}

....

}

.....

Use an application class and initialization parameters to specify file transfer parameters. The maximum transfer size and the size of memory used for transfer (a work file is used if the memory size is exceeded) can be specified by overriding methods of the application class as shown below. The default maximum transfer size is 16 MB, and the default memory size is 1 MB.

// Maximum size for a file transfer in bytes. 0 indicates infinite.

public long getMimeTransferSizeLimit() {

// Specifies 32 MB as the maximum transfer size.

return 32*1024*1024;

}

// Size of memory to be prepared for file transfer in bytes

public int getMimeTransferMemorySize() {

// Specifies 1 MB as the memory size.

return 1024*1024;

}

The maximum size for a request parameter analysis can be specified with an initialization parameter (uji.mimeParseSizeLimit). The default value is five times the maximum size for a file transfer. If a file exceeding the maximum transfer size is uploaded, file data is abandoned, but request parameter analysis continues until the maximum size for a request parameter analysis is reached.



<context-param>

<param-name>uji.mimeParseSizeLimit</param-name>

<param-value>41943040</param-value>

</context-param>

The following quantitative limits apply to file uploading: · The upload header length must not exceed 1024 bytes.

42

The information contained in the upload header includes the file name and item names. Depending on the browser used, about 970 bytes can be specified as the total length of the file name and item names. If the upload header length exceeds 1024 bytes, the UUIRuntimeException exception wrapped around IOException is thrown.

· The default maximum size for an upload file is 16 MB (16*1024*1024 bytes). As explained above, this size can be changed by overriding the getMimeTransferSizeLimit method of the application class. If the maximum size for an upload file is exceeded, the streams acquired from FacesMimeSource become null.

· The default maximum size for a request parameter analysis is 80 MB (16*1024*1024*5 bytes). As explained above, this size can be changed by specifying an initialization parameter (uji.mimeParseSizeLimit). If the size of the request parameter exceeds the upper limit, the UUIRuntimeException exception wrapped around IOException is thrown.

6.1.2 Downloading files

To download a file, add an action method that implements downloading to the managed bean, and execute the fillResponse method of the com.fujitsu.uji.faces.FacesMimeSupport class.

import java.io.File;

import com.fujitsu.uji.faces.FacesMimeSupport;


.....

public String download() {

// Acquires the file to be downloaded.

File file = getDownloadFile();

try {

// Executes downloading.

FacesMimeSupport.fillResponse(file);

} catch(Exception e) {

e.printStackTrace();

}

return "ok";

}

.....

}

<f:view>


<uji:pushButton bean="myBean" property="button"

label="download" action="#{mybean.download}"/>

</uji:form>

</f:view>

6.2 Application Log Function

LogComposer can be used when an application class is acquired using

43

com.fujitsu.uji.faces.FacesFactory.


import com.fujitsu.uji.faces.FacesFactory;

import com.fujitsu.uji.ApplicationProfile;

import com.fujitsu.uji.log.LogComposer;


public String doAction(){

ApplicationProfile ap = FacesFactory.getApplicationProfile();

LogComposer logComposer = ap.getLogComposer();

// Coding of log output processing

}

}

For details on how to create and use an application class, refer to the Apcoordinator User's Guide.

6.3 EJB and Web Service Invocation Function

If the unified remote interface is used, EJB and Web services developed using Apcoordinator as well as general EJB and Web services can be invoked through the same interface. For details on the unified remote interface, refer to the Apcoordinator User's Guide.

In order for a JavaServer Faces application to use the unified remote interface, acquire the CallFactory object using the com.fujitsu.uji.ext.InitialCallFactory class.

import javax.faces.context.ExternalContext;


import javax.servlet.ServletContext;

import com.fujitsu.uji.ext.Call;

import com.fujitsu.uji.ext.CallFactory;

import com.fujitsu.uji.ext.InitialCallFactory;

import com.fujitsu.uji.ResponseBean;


public String doAction(){

...

try{

FacesContext fc = FacesContext.getCurrentInstance();

ExternalContext ec = fc.getExternalContext();

ServletContext sc = (ServletContext)ec.getContext();

CallFactory factory = (CallFactory)InitialCallFactory.createFactory(sc, this.getClass().getClassLoader());

Call call = factory.createCall("myejb");

ResponseBean responseBean = (ResponseBean)call.invoke(dataBean, "verb");

44

} catch(Throwable e){

...

}

...

}

}

The unified remote interface invokes an EJB or Web service by using an extended Bean of com.fujitsu.uji.DataBean (hereafter referred to as a data Bean) as an argument. Therefore, the following is recommended: before using the unified remote interface, create a managed bean as a data Bean.

45

46

Chapter 7 Setting Up the Runtime Environment 7.1 Runtime File Mapping

The following figure shows the standard file mapping when JavaServer Faces applications are running.

JSP files Allocate these files into the application folder or a subfolder in the folder.

User files Similar to JSP files, allocate static documents such as images into the application folder or a subfolder.

Environment definition files (web.xml, faces-config.xml) Allocate the web.xml and faces-config.xml files immediately inside the WEB-INF folder.

Tag library file (ujijsf.tld) When using UJI tags, allocate ujijsf.tld immediately inside the WEB-INF folder.

User classes Allocate user-defined class files in the WEB-INF¥classes folder, preserving their package hierarchy. For example, place MyBean.class of the mypkg package in WEB-INF¥classes¥mypkg.

JavaServer Faces jar files Allocate the jar files required for execution of JavaServer Faces immediately inside the WEB-INF¥lib folder. See the above figure for the required jar files.

User-defined jar files If user-defined class files are packaged to a jar file, allocate it into the WEB-INF¥lib folder.

47

7.2 Files Required for Execution

Tag library file

When using UJI tags, copy the following file to the WEB-INF folder.

Tag library name Function

ujijsf.tld Tag library file required for use of UJI tags by JavaServer Faces applications

Runtime libraries

The following JAR files are required for JavaServer Faces applications.

JAR file name Method of use

jsf-api.jar Specify this file in the container classpath.

jsf-impl.jar

jstl.jar

commons-beanutils.jar

commons-collections.jar

commons-digester.jar

commons-logging.jar

Copy these files to the WEB-INF¥lib folder.

The following files are required for use of UJI tags.

File name Method of use

uji.jar

ujijsf.jar Specify these files in the container classpath.

ujijsf.tld Copy this file to the WEB-INF folder.

Installation folder

The installation folder of the tag library file and runtime libraries is as follows.

Platform Default installation folder

Windows C:¥Interstage¥APC¥lib¥

Solaris OE

Linux /opt/FJSVwebc/lib/

7.3 Web Application Environment Definition File (web.xml)

Define the following components in the Web application environment definition file (web.xml).

Component to be defined Explanation

JavaServer Faces servlet

Define this servlet by using the servlet tag and servlet-mapping tag. This component is always required for JavaServer Faces applications.

Apcoordinator factory class name

Define the class name by using an initialization parameter (factory). This class name is always required for creating application classes.

Tag library file for UJI tags This library file is always required for use of UJI tags.

A sample web.xml is shown below.

48

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE web-app

PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"

"http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app>

<context-param>

<param-name>factory</param-name>

<param-value>mypkg.MyFactory</param-value>

</context-param>

<servlet>

<servlet-name>Faces Servlet</servlet-name>

<servlet-class>javax.faces.webapp.FacesServlet</servlet-class>

<load-on-startup>1</load-on-startup>

</servlet>

<servlet-mapping>

<servlet-name>Faces Servlet</servlet-name>

<url-pattern>/faces/*</url-pattern>

</servlet-mapping>

<taglib>

<taglib-uri>ujijsf-taglib</taglib-uri>

<taglib-location>/WEB-INF/ujijsf.tld</taglib-location>

</taglib>

</web-app>

JavaServer Faces specification says thatthe state of UI components is saved on the server side or on the client side.To specify where the state of UI components is saved,set the javax.faces.STATE_SAVING_METHOD context parameter to client (which means that the state is saved on the client side) or server (which means that the state is saved on the saver side.)The default is server.When the state is saved on the client side,there will be the following security problemsbecause the state of UI components is serialized and a HTML document includes a hidden parameter whose value is the serialized state of UI components.So, it is recommended that the javax.faces.STATE_SAVING_METHOD context parameter is omitted, or set to server.

· A malicious user can get values which are entered in a Web page by getting the page in a Web browser cache, and decoding a hidden parameter in the Web page.

· A malicious user can create any UI component tree on the server by making a serialized

49

50

data and sending it to the server as a request parameter.

Appendix A UIComponents Corresponding to UJI Tags

A.1 UIComponent Specifications

The table below lists the UIComponent classes corresponding to UJI tags. When coding programs using JavaServer Faces APIs, refer to this information for casting a UIComponent to the javax.faces.component package class or interface. The name of each UIComponent class corresponding to a UJI tag is "UUI" + "Tag name (beginning with an uppercase letter)". (Example: The class name of the UIComponent corresponding to the uji:form tag is UUIForm.) No UIComponent corresponds to the uji:colorMap tag.

In the "Implemented interface" columns in the table below, "O" indicates that a UIComponent implements one of the following interfaces: · javax.faces.component.ValueHolder · javax.faces.component.EditableValueHolder · javax.faces.component.ActionSource · javax.faces.component.NamingContainer The "value type" column in the table lists the type of the value acquired by getValue when a UIComponent implements the ValueHolder interface.

Implemented interface UIComponent class ValueH

older EditableValu

eHolder ActionS

ource NamingCo

ntainer Value type

com.fujitsu.uji.faces.script.UUIAction - - - - -

com.fujitsu.uji.faces.model.UUIAnchor O (*1) - O - Any (*6)

com.fujitsu.uji.faces.layout.UUIBorderLayout - - - - -

com.fujitsu.uji.faces.layout.UUIBorderLayoutRenderer - - - - -

com.fujitsu.uji.faces.collect.UUIButtonList O (*1) O (*2) - - String[] (*7)

com.fujitsu.uji.faces.model.UUICase - - - - -

com.fujitsu.uji.faces.field.UUICheckBox O (*1) O (*2) - - String

com.fujitsu.uji.faces.model.UUIChildren - - - - -

com.fujitsu.uji.faces.collect.UUIComboBox O (*1) O (*2) - - String[] (*7)

com.fujitsu.uji.faces.model.UUIComposite - - - O -

com.fujitsu.uji.faces.model.UUICompositeName O O (*3) - - Any (*8)

com.fujitsu.uji.faces.model.UUICompositeRenderer - - - - -

com.fujitsu.uji.faces.field.UUIFieldBigDecimal O O (*3) - - String

com.fujitsu.uji.faces.field.UUIFiel O O (*3) - - String

51


older EditableValu

eHolder ActionS

ource NamingCo

ntainer Value type

dBigInteger

com.fujitsu.uji.faces.field.UUIFieldDate O O (*3) - - String

com.fujitsu.uji.faces.field.UUIFieldDouble O O (*3) - - String

com.fujitsu.uji.faces.field.UUIFieldLong O O (*3) - - String

com.fujitsu.uji.faces.field.UUIFieldString O O (*3) - - String

com.fujitsu.uji.faces.field.UUIFieldTextArea O O (*3) - - String

com.fujitsu.uji.faces.script.UUIForm - - - O -

com.fujitsu.uji.faces.basic.UUIGetProperty O - - - Any (*8)

com.fujitsu.uji.faces.layout.UUIGridLayout - - - - -

com.fujitsu.uji.faces.layout.UUIGridLayoutRenderer - - - - -

com.fujitsu.uji.faces.script.UUIInput O O (*3) - - Any (*9)

com.fujitsu.uji.faces.layout.UUILabel - - - - -

com.fujitsu.uji.faces.model.UUIList - - - O -

com.fujitsu.uji.faces.collect.UUIListBox O (*1) O (*2) - - String[] (*7)

com.fujitsu.uji.faces.model.UUIListRenderer - - - - -

com.fujitsu.uji.faces.model.UUIName O O (*3) - - Any (*10)

com.fujitsu.uji.faces.collect.UUIPushButton O (*1) - O - Any (*6)

com.fujitsu.uji.faces.collect.UUIRadioButton O (*1) O (*2) - - Any (*11)

com.fujitsu.uji.faces.collect.UUIRecordView O (*1) O (*3) - - String[] (*12)

com.fujitsu.uji.faces.basic.UUIResourceText O (*4) - - - String

com.fujitsu.uji.faces.script.UUISelect O O (*3) - - Any (*8)

com.fujitsu.uji.faces.model.UUISwitch - - - - -

com.fujitsu.uji.faces.layout.UUITabbedLayout - - - - -

com.fujitsu.uji.faces.layout.UUITa - - - - -

52


older EditableValu

eHolder ActionS

ource NamingCo

ntainer Value type

bbedLayoutRenderer

com.fujitsu.uji.faces.model.UUITable - - - O -

com.fujitsu.uji.faces.model.UUITableRenderer - - - - -

com.fujitsu.uji.faces.collect.UUITableView O (*1) O (*3) O (*5) - com.fujitsu.uji.faces.

collect.TableValue

com.fujitsu.uji.faces.script.UUITextarea O (*1) O (*3) - - Any (*8)

com.fujitsu.uji.faces.model.UUITree - - - O -

com.fujitsu.uji.faces.model.UUITreeRenderer - - - - -

com.fujitsu.uji.faces.collect.UUITreeView O (*1) O (*3) O (*5) - com.fujitsu.uji.faces.

collect.TreeValue

com.fujitsu.uji.faces.script.UUIValidate - - - - -

com.fujitsu.uji.faces.model.UUIValue O - - - Any (*10)

*1 The setConverter method cannot be used. *2 The setValidator, addValidator, and setRequired methods cannot be used. *3 The setRequired method cannot be used. *4 The setValue method cannot be used. *5 The setAction method cannot be used. *6 This is the property value specified by the selectedValue attribute. *7 The array element is the value of the selected option. If no option is selected, the array length is 0. *8 This is the property value specified by the bean or property attribute. *9 If a value is specified in the value attribute, this is the specified value. Otherwise, it is the value specified by the bean or property attribute. *10 This is the value of the current object. *11 This is the property value specified by the selectedBean or selectedProperty attribute. *12 The ith element of the array is the value of the getValueAt(i) of the item class.

A.2 UIComponent Class Diagrams

The following figure shows the correspondence between the UIComponent classes and UJI tags.

53

Basic tags

54

Client script tags

55

Screen part tags

56

Component tags (field)

57

Component tags (collection)

58

Component tags (layout)

59

60

Terms

ActionEvent

An event which occurs at such times as when the user clicks a button or anchor. To utilize the ActionEvent, specify the actionListener attribute to a tag or specify the f:actionListener tag in the content of a tag.

action listener method

A method to process actions which occur in JavaServer Faces tags. The actionListener attribute of a JavaServer Faces tag specifies an action listener method using a method binding expression.

action method

A method to process actions which occur in JavaServer Faces tags. The action attribute of a JavaServer Faces tag specifies an action method using a method binding expression.

Apply Request Values phase

A phase to acquire and apply values of a submitted form.

component family

An identifier which is used to create an instance of a renderer corresponding to the UIComponent.

component tree

A set of Java objects representing hierarchy of JavaServer Faces tags in an input-output page. The component tree is on the server side.

component type

An identifier which is used to create an instance of the UIComponent.

converter

A converter converts between a model data object and the String representation of the model data object, i.e., from an object to String and from String to an object. String representation is used to display the model data.

61

event

There are three types of events, the ActionEvent, the ValueChangeEvent, and the PhaseEvent.

Invoke Application phase

A phase in which application level events such as page transitions are processed.

JavaServer Faces

JavaServer Faces is a set of specifications drawn up as JSR-127 by the Java Community Process (JCP). It is an application framework for creating Web application user interfaces.

JavaServer Faces definition file (faces-config.xml)

A file to configure the environment of JavaServer Faces. The JavaServer Faces definition file defines page transitions, events to be invoked, and beans used in an application.

lifecycle

A sequence of processes, which starts with receiving a request by a JavaServer Faces application, and which ends with returning a response.

managed bean

A bean to store values which is displayed on the screen or submitted by a web browser. The bean has properties and accessor methods (i.e., setter and getter methods) to store and get values. The bean may have event listeners.

method binding expression

A description which relates a JavaServer Faces tag to a method of a managed bean. A method binding expression must begin with "#{" and end with "}".

navigation rule

A rule defining a next view based on the view ID of the current view. Navigation rules are described in the JavaServer Faces definition file using the navigation-rule tag.

PhaseEvent

The PhaseEvent enables an application to interrupt before or after a JavaServer Faces phase and execute a process.

62

Process Validations phase

A phase in which all validators associated with the page to be displayed are processed.

RenderKit

A RenderKit is a collection of renderer instances. A RenderKit recognizes a suitable representation of UIComponent instance for a specific type of client.

Render Response phase

A phase in which a UIComponent tree is returned as a response in a format (e.g., HTML) that can be rendered by the client.

Restore View phase

The Restore View phase begins when a request is sent to a server by the clicking of a link or button. In this phase, JavaServer Faces creates a UIComponent tree for an input-output page and associates event processing and validators with the UIComponents. The created tree is saved to the FacesContext instance.

UIComponent

A base class of all user interface components of JavaServer Faces.

Update Model Values phase

A phase in which the values of the associated model are updated after the values are checked for validity.

validator

A method or a class which verifies values in a submitted form. The validator is invoked in the Process Validations phase in the lifecycle.

value binding expression

A description which relates a JavaServer Faces tag to a property of a managed bean. A value binding expression must begin with "#{" and end with "}".

63

64

ValueChangeEvent

An event which occurs in the UIComponent that implements the javax.faces.component.EditableValueHolder interface. It occurs when the value of a tag (e.g., field, combo box) having an input value is changed.

Java Server Faces User\'s Guide

Documents

Transcript of Java Server Faces User\'s Guide