JavaServer Faces technology supports a mechanism for validating the data of editable components. Each component in JavaServer Faces, created Error Messages during the life cycle of JSF and attached them to FacesContext object. Hence each message is attached to a component in the component tree and the message is displayed into the view at the end of JSF life cycle.

Showing Error Messages on View

JSF provides different tags to handle and display messages on the view. There are two message tags in SUN’s reference implementation of JSF HTML library:

<h:message />
<h:messages />

h:messages is used to display all messages at once. You can place h:messages tag in start of your form. You may need to display only global messages using h:messages tag. For displaying only global messages set globleOnly attribute of h:messages to true.

<h:messages globalOnly="true" />

Use h:message to display message attached to one component. An attibute for=”" can be used to specify the id of a component whose error messages we need to display. h:message is used to display error message next to the component that generated the error. If more then one message is attached to that component, h:message will display the last message.

...
<h:inputText id="userName" value="#{userBean.userName}" />
<h:message for="userName" />
...

Each message can have a summary description and a detailed description. When using the h:message tag, the default is to show the detail message. When using the h:messages tag, the default is to display the summary descriptions. To change the defaults, modify the boolean showSummary and showDetail attributes.

<h:message for="userName" showSummary="true"/>
<h:messages showDetail="true"/>

You can also enable component’s detail message to appear as a tooltip. To do so, set tooltip attribute of message tag to true. Note that for enabling this option, showDetail and showSummary must be set to true.

There are four forms of JSF validation:
1. Built-in validation components
2. Application level validations
3. Custom validation components using Validator interface
4. Validation methods in backing beans

Built-in validation components

The SUN’s reference implementation of JSF provides some default validation components that can be leveraged to implement validation of any user inputs. The JSF’s core library provides tags to validate input. Following are few tags that can be used to validate the input.

f:validateDoubleRange : This tag checks the value of component within specified range. The value must be convertible to floating-point type or a floating-point itself.

f:validateLength : This tag checks the length of a value and restrict it within a specified range. The value must be of type java.lang.String.

f:validateLongRange : Checks is component value is within a specified range. The value must be of numeric type or string convertible to a long.
Example:

<h:inputText id="Username" value="#{UserBean.userName}">
	<f:validateLength minimum="6" maximum="15"/>
</h:inputText>
....
<h:inputText id="Age" value="#{UserBean.age}">
	<f:validateLongRange minimum="1" maximum="120"/>
</h:inputText>

Validation using Backing Bean methods

A backing bean method can be used for doing validation of any input field. First we need to create the backing bean method that will get called during validation process. The signature of the method can be:

public void <METHOD_NAME> (FacesContext context, UIComponent component, Object value) { .. }

Once a backing bean method is ready we can bind it with a component using f:validator tag.

<h:inputText value="#{userBean.name}" validator="#{userBean.checkUsername}">
</h:inputText>

In above snippet, we have bind checkUsername() method of userBean to component inputText. It is possible to bind more than one validators to one component.

Backing bean method of validation is easy to implement, but this method is specific for one application and may not be reused for different application. To create generic validators which can be used in different application, Validator interface can be used.

Custom validation components using Validator interface

Validator interface can be extended and a custom validator can be created which can be reused across different applications in JSF. To create a custom validator, we need to create a Java class that implements javax.faces.validator.Validator interface. Validator interface provides a method validate () that needs to be implemented. Following is the signature of validate() method.

import javax.faces.component.UIComponent;
import javax.faces.context.FacesContext;
import javax.faces.validator.Validator;
import javax.faces.validator.ValidatorException;
...
...
public void validate(FacesContext context, UIComponent component, Object value)
		throws ValidatorException {
}

Once the Validator is implemented, we need to register this validator in faces-config.xml file. To do so copy following code in faces-config.xml assuming that our validator class name is net.viralpatel.jsf.helloworld.EmailValidator.

<validator>
	<validator-id>emailValidator</validator-id>
	<validator-class>net.viralpatel.jsf.helloworld.EmailValidator</validator-class>
</validator>

We can bind this validator with any component using f:validator tag.

<h:inputText id="Email" value="#{userBean.email}" required="true">
	<f:validator validatorId="emailValidator" />
</h:inputText>

Note that in above code snippet, validatorId attribute of f:validator tag points to the validator’s ID that is registered in faces-config.xml file.
For validating email address we can create a Validator class as:

package net.viralpatel.jsf.helloworld;

import javax.faces.application.FacesMessage;
import javax.faces.component.UIComponent;
import javax.faces.context.FacesContext;
import javax.faces.validator.Validator;
import javax.faces.validator.ValidatorException;

public class EmailValidator implements Validator{
	public void validate(FacesContext context, UIComponent component, Object value)
			throws ValidatorException {

		String email = (String) value;

		if(!email.contains("@")) {
			FacesMessage message = new FacesMessage();
			message.setSeverity(FacesMessage.SEVERITY_ERROR);
			message.setSummary("Email is not valid.");
			message.setDetail("Email is not valid.");
			context.addMessage("userForm:Email", message);
			throw new ValidatorException(message);
		}
	}
}

Thus by using JSF Validation framework, it is possible to validate user input easily. We saw different ways of validation in JSF: Default validators, backing bean methods and validation through validator interface.

Let me know your comments about this tutorial.

<< PREVIOUS: Tutorial: Creating JavaServer Faces JSF application in Eclipse.

1. JDK 1.5 above (download)
2. Tomcat 5.x above or any other container (Glassfish, JBoss, Websphere, Weblogic etc) (download)
3. Eclipse 3.2.x above (download)
4. Sun Reference Implementation of JSF: (download). Following are the list of JAR files required for this application.
   • jsf-impl.jar
   • jsf-api.jar
   • jstl.jar
   • common-logging.jar
   • common-beanutils.jar
   • common-collections.jar
   • common-chain.jar
   • common-digester.jar

We will implement a JSF application with an Add User screen with two fields, ID and User Name. Once user enter these values and press submit, she will be redirected to a welcome page displaying the user name.

Let us start with our first JSF based web application.

Step 1: Create Dynamic Web project

Open Eclipse and goto File -> New -> Project and select Dynamic Web Project in the New Project wizard screen.

Select Dynamic Web application and click Next.

Write the name of the project HelloWorldJSF. Once this is done, select the target runtime environment (e.g. Apache Tomcat v6.0). This is to run the project inside Eclipse environment. In configuration select JavaServer Faces v1.2 Project and press Next.

On Project Facets window, select Java 5 and JSF 1.2 and press Next.

Skip Web module window and press Next.

Select JSF component library. Click New in Component Libraries and add jstl.jar, jsf-api.jar and jsf-impl.jar. In URL Mapping Patterns add /faces/* and then click Finish.

Once the project is created, you can see its structure in Project Explorer.

Step 2: Create Package and Managed bean

Create a package net.viralpatel.jsf.helloworld in the source folder and create a Java file UserBean.java. Copy following content into UserBean.java.

package net.viralpatel.jsf.helloworld;

public class UserBean {
	private int id;
	private String name;

	//Action method to add user
	public String addUser() {

		return "success";
	}
	public int getId() {
		return id;
	}
	public void setId(int id) {
		this.id = id;
	}
	public String getName() {
		return name;
	}
	public void setName(String name) {
		this.name = name;
	}
}

Above Java class is a User bean that we will use to store our user’s information. This class acts like a form bean and action class. The addUser() method will get called when we click Add button on our Add User page.

Step 3: Create JSP files

Create two JSP files: AddUser.jsp and ListUser.jsp in WebContent folder. Copy following content in each of these files.

AddUser.jsp

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

<html>
<head>
	<title>Add New User Form</title>
</head>
<body>
<f:view>
		<p>
			<h:message id="errors" for="User_ID" style="color:red"/>
		</p>
	<h:form>
		<h:panelGrid border="1" columns="2">
			<h:outputText value="ID"></h:outputText>
			<h:inputText id="User_ID" value="#{userBean.id}" required="true">
				<f:validateLongRange minimum="1" maximum="500"/>
			</h:inputText>
			<h:outputText value="Name"></h:outputText>
			<h:inputText value="#{userBean.name}"></h:inputText>
			<h:commandButton action="#{userBean.addUser}"
				value="Add Customer"></h:commandButton>
		</h:panelGrid>
	</h:form>
</f:view>
</body>
</html>

We have added a validation rule for ID using f:validateLongRange tag and required=”true” attribute. The ID must be in between 1 and 500.

ListUser.jsp

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

<html>
<head>
	<title>List of Users</title>
</head>
<body>
<f:view>
	<h:form>
		<h:outputText value="User #{userBean.name} is added successfully.">
		</h:outputText>
	</h:form>
</f:view>
</body>
</html>

Step 4: Modify faces-config.xml file

Open faces-config.xml from WebContent -> WEB-INF folder and copy following content into it.

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

<faces-config xmlns="http://java.sun.com/xml/ns/javaee"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-facesconfig_1_2.xsd"
	version="1.2">
	<managed-bean>
		<managed-bean-name>userBean</managed-bean-name>
		<managed-bean-class>
			net.viralpatel.jsf.helloworld.UserBean
		</managed-bean-class>
		<managed-bean-scope>session</managed-bean-scope>
	</managed-bean>
	<navigation-rule>
		<display-name>AddUser</display-name>
		<from-view-id>/AddUser.jsp</from-view-id>
		<navigation-case>
			<from-outcome>success</from-outcome>
			<to-view-id>/ListUser.jsp</to-view-id>
		</navigation-case>
	</navigation-rule>
</faces-config>

In faces config we have defined a managed bean UserBean with scope session and mapping from AddUser.jsp to ListUser.jsp.

Step 5: Execute and run the project

Final step is to execute the project and view it in browser.
For this, right click on Project Name in Project Explorer -> Run As -> Run on Server (Shortcut Alt+Shift+X, R).

Once you enter ID and Username and press Add User, following success screen will appear.

Download complete WAR file with source

Download WAR with Source (1.48 MB)

Next >> JavaServer Faces JSF Validation Tutorial: Error Handling in JSF.