JASPER REPORTS TUTORIALS

WWW.jasperforge.org

ntroduction JasperReports is a powerful open source reporting tool that has the ability to deliver rich content onto the screen, to the printer, or into PDF, HTML, XLS, RTF, ODT, CSV, TXT and XML files. It is entirely written in Java and can be used in a variety of Java-enabled applications to generate dynamic content. Its main purpose is to help create page-oriented, ready-to-print documents in a simple and flexible manner.

API Overview JasperReports organizes data retrieved from a data source according to a report-design defined in a JRXML file. In order to fill a report with data, the report-design must be compiled first. The compilation of the JRXML file representing the report-design is performed by the compileReport() method exposed by the JasperCompileManager class. Through compilation, the report design is loaded into a report-design object that is then serialized and stored on disk ( JasperReport class). This serialized object is used when the application wants to fill the specified report-design with data. In fact, the compilation of a report-design implies the compilation of all Java expressions defined in the JRXML file representing the report design. Various verifications are made at compilation time, to check the report-design consistency. The result is a ready-to-fill report-design that will be used to generate documents on different sets of data. In order to fill a report-design, one can use the fillReportXXX() methods exposed by theJasperFillManager class. Those methods receive as a parameter the report-design object, or a file representing the specified report-design object, in a serialized form, and also a JDBC connection to the database from which to retrieve the data to fill the report with. The result is an object that represents a ready-to-print document ( JasperPrint class) and that can be stored on disk in a serialized form (for later use), can be delivered to the printer or to the screen, or can be exported into a PDF, HTML, XLS, RTF, ODT, CSV, TXT or XML document. As you can see, the main classes to use when working with JasperReports are: net.sf.jasperreports.engine.JasperCompileManager net.sf.jasperreports.engine.JasperFillManager net.sf.jasperreports.engine.JasperPrintManager net.sf.jasperreports.engine.JasperExportManager These classes represent a façade to the JasperReports engine. They have various static methods that simplify the access to the API functionality and can be used to compile an JRXML report design, to fill a report, to print it, or to export to other document formats (PDF, HTML, XML). In addition to these façade classes, you will also get to work directly with specific exporter classes, in case you need to export your reports to XLS, RTF, ODT, TXT or other document formats for which there is no corresponding helper method in the JasperExportManager, or when you need to configure the export process and adapt it to your specific needs. These exporter implementations can be found in the net.sf.jasperreports.engine.export package of the JasperReports library. If you need to display the report inside a Swing application, you can use the JRViewer component that is shipped with the library and consists of an embeddable and configurable javax.swing.JPanel component. The JasperViewer is a stand-alone Swing application that uses the JRViewer component to display reports in proprietary format (serialized JasperPrint objects) or in XML format. To help with the report design work, JasperReports provides a report design previewer in theJasperDesignViewer class.

Report Designs As mentioned, a report design represents a template that will be used by the JasperReports engine to deliver dynamic content to the printer, to the screen or to the Web. Data stored in the database is organized according to the report design to obtain ready to print, page oriented documents. The report designs are defined in JRXML files and must have a special structure. This structure is declared in a DTD file supplied with the JasperReports engine. The JRXML files are then compiled, in order to use them in report filling operations. To create a simple report design, we have to edit an XML file with the following structure: PUBLIC "-//JasperReports//DTD Report Design//EN" "http://jasperreports.sourceforge.net/dtds/jasperreport.dtd"> ...  To have a better understanding of the structure of a JRXML file, or of a report design in general, we recommend you to use the Quick Reference.

Compiling Report Designs A report design is represented by a JRXML file that has the structure defined in the jasperreport.dtdfile, or by an in-memory JasperDesign object. In order to generate reports according to such a report design, this needs to be compiled. Report design compilation can be done using the compileReportXXX() methods exposed by the JasperCompileManager class and results into a *.jasper file or a JasperReport object. When compiling a report design, the engine first performs a validation to ensure that the template (JasperDesign) is consistent and then transforms all the report expressions in a ready-to-evaluate form, storing them inside the resulting compiled report template (JasperReport or .jasper file). This transformation implies either the on-the-fly compilation of a Java class file that will be associated with the report template, or the generation of a Groovy or BeanShell script to use when evaluating report expressions during the report filling process, depending on the specified report expression language for the report (see the language property of a report template). Before reading more about report compilation, you should understand when do you need to compile your report templates and which is the best way to do it by reading the following FAQ: When should I compile my report templates and how?. To make report design compilation process as flexible as possible, a special interface calledJRCompiler was introduced. As seen above, there are several different types of classes implementing this interface shipped with the library: 1. Java creport compilers. These report compilers generate and compile a Java class containing the report expressions evaluating methods; \\ 2. The Groovy report compiler that generates a script for runtime report expressions evaluation. 3. The BeanShell report compiler that generates a script for runtime report expressions evaluation. For more details about report compilation, check The Definitive Guide to JasperReports. Ant task for compiling report designs Since the report design compilation process is more like a design-time job than a runtime one, an Ant task was provided with the library in order to simplify development. This Ant task is implemented by the JRAntCompileTask and is very similar to the Ant built-in task, as far as syntax and behavior are concerned. The report design compilation task can be declared like this, in a project's build.xml file: classname="net.sf.jasperreports.ant.JRAntCompileTask">     In the example above, the lib folder should contain the jasperreports-.jar file along with its required libraries (including the jdt-compiler-.jar, which is the recommended report compiler, in case you use Java as the report expression language). This user-defined Ant task can be then used to compile multiple JRXML report design files in a single operation, by specifying the root directory that contains those files or by selecting them using file patterns. Attributes of the report design compilation task: Attribute Description srcdir Location of the JRXML report design files to compile. Required unless nested elements are present. destdir Location to store the compiled report design files (the same as the source directory by default). compiler Name of the class that implements the JRCompiler interface (optional). xmlvalidation Flag to indicate if the XML validation should be performed on the source report design files (true by default). tempdir Location to store the temporary generated files (the current working directory by default). keepjava Flag to indicate if the temporary Java files generated on-the-fly should be kept and not deleted automatically (false by default). The report design compilation task supports nested and elements, just like the Ant built-in task. To see this in action, check the demo/samples/antcompile sample provided with the project source files. Viewing a report design Report designs can be viewed using the JasperDesignViewer application. In its main() method, it receives the name of the file which contains the report design to view. This can be the JRXML file itself, or the compiled report design (*.jasper file).

Filling Reports A compiled report design can be used to generate reports by calling the fillReportXXX() methods of the JasperFillManager class. There are two flavours of the fill methods in this façade class. Some receive a java.sql.Connection object as the third parameter, and the others receive a JRDataSource object instead. This is because most of the times reports are filled with data from a relational database to which we connect through JDBC and is very convenient to have the SQL query inside the report template itself. The JasperReports engine can use the connection passed in and execute the SQL query, thus producing a report data source for filling the report. In cases where data is available in other forms, the fill methods receiving a data source are to be used.

View, Print and Export Reports Generated reports can be viewed using the JasperViewer application. In its main() method, it receives the name of the file which contains the report to view. Generated reports can be printed using the printReport(), printPage() or printPages() static methods exposed by the JasperPrintManager class. After having filled a report, we can also export it in PDF, HTML or XML format using the exportReportXXX() methods of the JasperExportManager class.

Parameters Parameters are object references that are passed-in to the report filling operations. They are very useful for passing to the report engine data that it can not normally find in its data source. For example, we could pass to the report engine the name of the user that has launched the report filling operation if we want it to appear on the report, or we could dynamically change the title of our report. An important aspect is the use of report parameters in the query string of the report, in order to be able to further customize the data set retrieved from the database. Those parameters could act like dynamic filters in the query that supplies data for the report. Declaring a parameter in a report design is very simple and it requires specifying only its name and its class: There are two possible ways to use parameters in the query: 1. The parameters are used like normal java.sql.PreparedStatement parameters using the following syntax: SELECT * FROM Orders WHERE CustomerID = $P{OrderCustomer} 2. Sometimes is useful to use parameters to dynamically modify portions of the SQL query or to pass the entire SQL query as a parameter to the report filling routines. In such a case, the syntax differs a little, like in the following example: SELECT * FROM Orders ORDER BY $P!{OrderByClause} There are also the following built-in system parameters, ready to use in expressions: Parameter Name Description REPORT_PARAMETERS_MAP This parameter will contain a map with all user defined and built-in parameters REPORT_PARAMETERS_MAP This parameter will contain a map with all user defined and built-in parameters REPORT_CONNECTION A user supplied java.sql.Connection used for JDBC datasources REPORT_DATA_SOURCE A user supplied instance of JRDataSource representing either one of the built-in data source types or a user-defined one REPORT_MAX_COUNT An integer allowing users to limit the datasource size REPORT_SCRIPTLET A JRAbstractScriptlet containing an instance of the report scriptlet provided by the user REPORT_LOCALE A java.util.Locale instance containing the resource bundle desired locale REPORT_RESOURCE_BUNDLE The java.util.ResourceBundle containing localized messages REPORT_TIME_ZONE A java.util.TimeZone instance to use for date formatting REPORT_VIRTUALIZER The JRVirtualizer object to be used for page virtualization REPORT_CLASS_LOADER A java.lang.ClassLoader instance to be used during the report filling process to load resources such as images, fonts and subreport templates IS_IGNORE_PAGINATION If set to java.lang.Boolean.TRUE the report will be generated on one long page and page break will not occur

Data Source JasperReports support various types of data sources using a special interface calledJRDataSource. There is a default implementation of this interface, the JRResultSetDataSource class, which wraps a java.sql.ResultSet object. It allows the use of any relational database through JDBC. When using a JDBC data source, you could pass a java.sql.Connection object to the report filling operations and specify the query in the report definition itself (see the element in the XML file) or could create a new instance of the JRResultSetDataSource by supplying the java.sql.ResultSet object directly. With other types of data sources, things should not be different and all you have to do is to implement the JRDataSource interface, or use one of the implemetations that are shipped with the JasperReports library to wrap in-memory collections or arrays of JavaBeans, CSV or XML files, etc.

Fields Report fields represent the only way to map data from the data source into the report generating routines. When the data source of the report is a java.sql.ResultSet, all fields must map to corresponding columns in the java.sql.ResultSet object. That is, they must have the same name as the columns they map and a compatible type. For example: If we want to generate a report using data retrieved from the table Employees, which has the following structure: Column Name Datatype Length EmployeeID int 4 LastName varchar 20 FirstName varchar 10 HireDate datetime 8 We can define the following fields in our report design: If we declare a field that does not have a corresponding column in the java.sql.ResultSet, an exception will be thrown at runtime. Columns present in the java.sql.ResultSet object that do not have corresponding fields in the report design do not affect the report filling operations, but they also won't be accessible.

Expressions Expressions are a powerful feature of JasperReports. They can be used for declaring report variables that perform various calculations, for data grouping on the report, to specify report text fields content or to further customize the appearance of objects on the report. Basically, all report expressions are Java expressions that can reference report fields and report variables. In an XML report design there are several elements that define expressions: , , , , and . In order to use a report field reference in an expression, the name of the field must be put between $F{ and } character sequences. For example, if we want to display in a text field, on the report, the concatenated values of two fields, we can define an expression like this one: $F{FirstName} + " " + $F{LastName} The expression can be even more complex: $F{FirstName} + " " + $F{LastName} + " was hired on " + (new SimpleDateFormat("MM/dd/yyyy")).format($F{HireDate}) + "." To reference a variable in an expression, we must put the name of the variable between $V{ and } like in the example below: "Total quantity : " + $V{QuantitySum} + " kg." There is an equivalent syntax for using parameters in expressions. The name of the parameter should be put between $P{ and } like in the following example: "Max Order ID is : " + $P{MaxOrderID}

Variables A Report variable is a special objects build on top of an expression. Variables can be used to simplify the report design by declaring only once an expression that is heavily used throughout the report design or to perform various calculations on the corresponding expressions. In its expression, a variable can reference other report variables, but only if those referenced variables were previously defined in the report design. So the order in which the variables are declared in a report design is important. As mentioned, variables can perform built-in types of calculations on their corresponding expression values like : count, sum, average, lowest, highest, variance, etc. A variable that performs the sum of the Quantity field should be declared like this: class="java.lang.Double" calculation="Sum"> $F{Quantity} For variables that perform calculation we can specify the level at which they are reinitialized. The default level is Report and it means that the variable is initialized only once at the beginning of the report and that it performs the specified calculation until the end of the report is reached. But we can choose a lower level of reset for our variables in order to perform calculation at page, column or group level. For example, if we want to calculate the total quantity on each page, we should declare our variable like this: resetType="Page" calculation="Sum"> $F{Quantity} new Double(0) Our variable will be initialized with zero at the beginning of each new page. There are also the following built-in system variables, ready to use in expressions: PAGE_NUMBER COLUMN_NUMBER REPORT_COUNT PAGE_COUNT COLUMN_COUNT GroupName_COUNT Documentation pending...

Report Sections When building a report design we need to define the content and the layout of its sections. The entire structure of the report design is based on the following sections:

GOOGLE

Google

JSF LIFE CYCLE PHASES

Fast menu Listen and debug JSF lifecycle phases Basic debug example The first call The form submit Add immediate="true" to UIInput only Add immediate="true" to UICommand only Add immediate="true" to UIInput and UICommand Conversion error Validation error Okay, when should I use the immediate attribute?


Listen and debug JSF lifecycle phases

The JSF lifecycle will be explained and debugged here using the "poor man's debugging" approach with sysout's. We'll also check what happens if you add immediate="true" to the UIInput and UICommand and what happens when a ConverterException and ValidatorException will be thrown.



Well, you probably already know that the JSF lifecycle contains 6 phases:



1.Restore view

2.Apply request values

3.Process validations

4.Update model values

5.Invoke application

6.Render response

You can use a PhaseListener to trace the phases of the JSF lifecycle and execute some processes where required. But you can also use a "dummy" PhaseListener to debug the phases to see what is happening in which phase. Here is a basic example of such a LifeCycleListener:



Note: if you don't have a JSF playground environment setup yet, then you may find this tutorial useful as well: JSF tutorial with Eclipse and Tomcat.



package mypackage;



import javax.faces.event.PhaseEvent;

import javax.faces.event.PhaseId;

import javax.faces.event.PhaseListener;



public class LifeCycleListener implements PhaseListener {



public PhaseId getPhaseId() {

return PhaseId.ANY_PHASE;

}



public void beforePhase(PhaseEvent event) {

System.out.println("START PHASE " + event.getPhaseId());

}



public void afterPhase(PhaseEvent event) {

System.out.println("END PHASE " + event.getPhaseId());

}



}Add the following lines to the faces-config.xml to activate the LifeCycleListener.





mypackage.LifeCycleListener

This produces like the following in the system output:



START PHASE RESTORE_VIEW 1

END PHASE RESTORE_VIEW 1

START PHASE APPLY_REQUEST_VALUES 2

END PHASE APPLY_REQUEST_VALUES 2

START PHASE PROCESS_VALIDATIONS 3

END PHASE PROCESS_VALIDATIONS 3

START PHASE UPDATE_MODEL_VALUES 4

END PHASE UPDATE_MODEL_VALUES 4

START PHASE INVOKE_APPLICATION 5

END PHASE INVOKE_APPLICATION 5

START PHASE RENDER_RESPONSE 6

END PHASE RENDER_RESPONSE 6





Back to top

Basic debug example

To trace all phases of the JSF lifecycle, here is some sample code which represents simple JSF form with a "dummy" converter and validator and the appropriate backing bean. The code sample can be used to give us more insights into the phases of the JSF lifecycle, to understand it and to learn about it.



The minimal contents of the test JSF file: test.jsp











"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">



The dummy converter: MyConverter.java

binding="#{myBean.inputComponent}"

value="#{myBean.inputValue}"

valueChangeListener="#{myBean.inputChanged}">









value="submit"

action="#{myBean.action}" />



binding="#{myBean.outputComponent}"

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













package mypackage;



import javax.faces.component.UIComponent;

import javax.faces.context.FacesContext;

import javax.faces.convert.Converter;



public class MyConverter implements Converter {



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

System.out.println("MyConverter getAsObject: " + value);

return value;

}



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

System.out.println("MyConverter getAsString: " + value);

return (String) value;

}



}The dummy validator: MyValidator.java



package mypackage;



import javax.faces.component.UIComponent;

import javax.faces.context.FacesContext;

import javax.faces.validator.Validator;

import javax.faces.validator.ValidatorException;



public class MyValidator implements Validator {



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

throws ValidatorException

{

System.out.println("MyValidator validate: " + value);

}



}The backing bean: MyBean.java



package mypackage;



import javax.faces.component.html.HtmlInputText;

import javax.faces.component.html.HtmlOutputText;

import javax.faces.event.ValueChangeEvent;



public class MyBean {



// Init ----------------------------------------------------------------------------------------



private HtmlInputText inputComponent;

private String inputValue;

private HtmlOutputText outputComponent;

private String outputValue;



// Constructors -------------------------------------------------------------------------------



public MyBean() {

log("constructed");

}



// Actions ------------------------------------------------------------------------------------



public void action() {

outputValue = inputValue;

log("succes");

}



// Getters ------------------------------------------------------------------------------------



public HtmlInputText getInputComponent() {

log(inputComponent);

return inputComponent;

}



public String getInputValue() {

log(inputValue);

return inputValue;

}



public HtmlOutputText getOutputComponent() {

log(outputComponent);

return outputComponent;

}



public String getOutputValue() {

log(outputValue);

return outputValue;

}



// Setters ------------------------------------------------------------------------------------



public void setInputComponent(HtmlInputText inputComponent) {

log(inputComponent);

this.inputComponent = inputComponent;

}



public void setInputValue(String inputValue) {

log(inputValue);

this.inputValue = inputValue;

}



public void setOutputComponent(HtmlOutputText outputComponent) {

log(outputComponent);

this.outputComponent = outputComponent;

}



// Listeners ----------------------------------------------------------------------------------



public void inputChanged(ValueChangeEvent event) {

log(event.getOldValue() + " to " + event.getNewValue());

}



// Helpers ------------------------------------------------------------------------------------



private void log(Object object) {

String methodName = Thread.currentThread().getStackTrace()[2].getMethodName();

System.out.println("MyBean " + methodName + ": " + object);

}

}

The minimal faces configuration: faces-config.xml





myConverter

mypackage.MyConverter





myValidator

mypackage.MyValidator





myBean

mypackage.MyBean

request

Back to top

The first call

The first call in a freshly started webapplication with a fresh session should output at least:



START PHASE RESTORE_VIEW 1

END PHASE RESTORE_VIEW 1

START PHASE RENDER_RESPONSE 6

MyBean : constructed

MyBean getInputComponent: null

MyBean setInputComponent: javax.faces.component.html.HtmlInputText@2a9fca57

MyBean getInputValue: null

MyBean getOutputComponent: null

MyBean setOutputComponent: javax.faces.component.html.HtmlOutputText@13bbca56

MyBean getOutputValue: null

END PHASE RENDER_RESPONSE 6





1. Restore view.

As the session is fresh, there's no means of any UIViewRoot to restore, so nothing to see here.



2. Apply request values.

This phase is skipped because there is no form submit.



3. Process validations.

This phase is skipped because there is no form submit.



4. Update model values.

This phase is skipped because there is no form submit.



5. Invoke application.

This phase is skipped because there is no form submit.



6. Render response.

The bean is constructed. Behind the scenes a new UIViewRoot is created and stored in the session. If the component binding getters returns precreated components (precreated in e.g. the constructor) and not null, then those will be used, otherwise JSF will create new components. The components will be stored in the UIViewRoot and the bounded components are set in the component bindings. The values to be shown are retrieved from the value binding getters in the backing bean. If the values aren't set yet, they defaults to null. The component bindings are not required by the way. Only use them if you actually need the component in the backing bean for other means than getting/setting the value. In this article they are included just to demonstrate what all happens in the lifecycle.



Back to top

The form submit

The form submit with the value "test" entered should output at least:



START PHASE RESTORE_VIEW 1

MyBean : constructed

MyBean setInputComponent: javax.faces.component.html.HtmlInputText@2a9fca57

MyBean setOutputComponent: javax.faces.component.html.HtmlOutputText@13bbca56

END PHASE RESTORE_VIEW 1

START PHASE APPLY_REQUEST_VALUES 2

END PHASE APPLY_REQUEST_VALUES 2

START PHASE PROCESS_VALIDATIONS 3

MyConverter getAsObject: test

MyValidator validate: test

MyBean getInputValue: null

MyBean inputChanged: null to test

END PHASE PROCESS_VALIDATIONS 3

START PHASE UPDATE_MODEL_VALUES 4

MyBean setInputValue: test

END PHASE UPDATE_MODEL_VALUES 4

START PHASE INVOKE_APPLICATION 5

MyBean action: succes

END PHASE INVOKE_APPLICATION 5

START PHASE RENDER_RESPONSE 6

MyBean getInputValue: test

MyConverter getAsString: test

MyBean getOutputValue: test

END PHASE RENDER_RESPONSE 6





1. Restore view.

The bean is constructed. The UIViewRoot is restored from session and the bounded components are set in the component bindings.



2. Apply request values.

Nothing to see here. Behind the scenes the submitted form values are obtained as request parameters and set in the relevant components in the UIViewRoot, for example inputComponent.setSubmittedValue("test").



3. Process validations.

The submitted values are passed through the converter getAsObject() method and validated by the validator. If the conversion and validation succeeds, then the initial input value will be retrieved from the value binding getter and behind the scenes the inputComponent.setValue(submittedValue) and inputComponent.setSubmittedValue(null) will be executed. If the retrieved initial input value differs from the submitted value, then the valueChangeListener method will be invoked.



4. Update model values.

The converted and validated values will now be set in the value binding setters of the backing bean. E.g. myBean.setInputValue(inputComponent.getValue()).



5. Invoke application.

The real processing of the form submission happens here.



6. Render response.

The values to be shown are retrieved from the value binding getters in the backing bean. If a converter is definied, then the value will be passed through the converter getAsString() method and the result will be shown in the form.



Back to top

Add immediate="true" to UIInput only

Extend the h:inputText in the test.jsp with immediate="true":



...



binding="#{myBean.inputComponent}"

value="#{myBean.inputValue}"

valueChangeListener="#{myBean.inputChanged}"

immediate="true">

...The form submit with the value "test" entered should output at least:



START PHASE RESTORE_VIEW 1

MyBean : constructed

MyBean setInputComponent: javax.faces.component.html.HtmlInputText@2a9fca57

MyBean setOutputComponent: javax.faces.component.html.HtmlOutputText@13bbca56

END PHASE RESTORE_VIEW 1

START PHASE APPLY_REQUEST_VALUES 2

MyConverter getAsObject: test

MyValidator validate: test

MyBean getInputValue: null

MyBean inputChanged: null to test

END PHASE APPLY_REQUEST_VALUES 2

START PHASE PROCESS_VALIDATIONS 3

END PHASE PROCESS_VALIDATIONS 3

START PHASE UPDATE_MODEL_VALUES 4

MyBean setInputValue: test

END PHASE UPDATE_MODEL_VALUES 4

START PHASE INVOKE_APPLICATION 5

MyBean action: succes

END PHASE INVOKE_APPLICATION 5

START PHASE RENDER_RESPONSE 6

MyBean getInputValue: test

MyConverter getAsString: test

MyBean getOutputValue: test

END PHASE RENDER_RESPONSE 6





1. Restore view.

The bean is constructed. The UIViewRoot is restored from session and the bounded components are set in the component bindings.



2. Apply request values.

Behind the scenes the submitted form values are obtained as request parameters and set in the relevant components in the UIViewRoot, for example inputComponent.setSubmittedValue("test"). The submitted values are immediately passed through the converter getAsObject() method and validated by the validator. If the conversion and validation succeeds, then the initial input value will be retrieved from the value binding getter and behind the scenes the inputComponent.setValue(submittedValue) and inputComponent.setSubmittedValue(null) will be executed. If the retrieved initial input value differs from the submitted value, then the valueChangeListener method will be invoked. This all happens in this phase instead of the Process validations phase due to the immediate="true" in the h:inputText.



3. Process validations.

Nothing to see here. The conversion and validation is already processed in the Apply request values phase, before the values being put in the components. This is due to the immediate="true" in the h:inputText.



4. Update model values.

The converted and validated values will now be set in the value binding setters of the backing bean. E.g. myBean.setInputValue(inputComponent.getValue()).



5. Invoke application.

The real processing of the form submission happens here.



6. Render response.

The values to be shown are retrieved from the value binding getters in the backing bean. If a converter is definied, then the value will be passed through the converter getAsString() method and the result will be shown in the form.



Note for other components without immediate: any other UIInput components inside the same form which don't have immediate="true" set will just continue the lifecycle as usual.



Back to top

Add immediate="true" to UICommand only

Extend the h:commandButton in the test.jsp with immediate="true" (don't forget to remove from h:inputText):



...



value="submit"

action="#{myBean.action}"

immediate="true" />

...The form submit with the value "test" entered should output at least:



START PHASE RESTORE_VIEW 1

MyBean : constructed

MyBean setInputComponent: javax.faces.component.html.HtmlInputText@2a9fca57

MyBean setOutputComponent: javax.faces.component.html.HtmlOutputText@13bbca56

END PHASE RESTORE_VIEW 1

START PHASE APPLY_REQUEST_VALUES 2

MyBean action: succes

END PHASE APPLY_REQUEST_VALUES 2

START PHASE RENDER_RESPONSE 6

MyBean getOutputValue: null

END PHASE RENDER_RESPONSE 6





1. Restore view.

The bean is constructed. The UIViewRoot is restored from session and the bounded components are set in the component bindings.



2. Apply request values.

The real processing of the form submission happens here. This happens in this phase instead of the Invoke application phase due to the immediate="true" in the h:commandButton. The UIInput components which don't have immediate="true" set will not be converted, validated nor updated, but behind the scenes the inputComponent.setSubmittedValue(submittedValue) will be executed before the action() method will be executed.



3. Process validations.

This phase is skipped due to the immediate="true" in the h:commandButton.



4. Update model values.

This phase is skipped due to the immediate="true" in the h:commandButton.



5. Invoke application.

This phase is skipped due to the immediate="true" in the h:commandButton.



6. Render response.

The values to be shown are retrieved from the value binding getters in the backing bean, expect for the UIInput components which don't have immediate="true" set. Behind the scenes those will be retrieved from the components in the UIViewRoot, e.g. inputComponent.getSubmittedValue().



Note for all components without immediate: as the Update model values phase is skipped, the value bindings aren't been set and the value binding getters will return null. But the values are still available as submitted value of the relevant components in the UIViewRoot. In this case you can retrieve the non-converted and non-validated input value from inputComponent.getSubmittedValue() in the action() method. You could even change it using inputComponent.setSubmittedValue(newValue) in the action() method.



Back to top

Add immediate="true" to UIInput and UICommand

Extend the h:inputText as well as the h:commandButton in the test.jsp with immediate="true":



...



binding="#{myBean.inputComponent}"

value="#{myBean.inputValue}"

valueChangeListener="#{myBean.inputChanged}"

immediate="true">

...



value="submit"

action="#{myBean.action}"

immediate="true" />

...The form submit with the value "test" entered should output at least:



START PHASE RESTORE_VIEW 1

MyBean : constructed

MyBean setInputComponent: javax.faces.component.html.HtmlInputText@2a9fca57

MyBean setOutputComponent: javax.faces.component.html.HtmlOutputText@13bbca56

END PHASE RESTORE_VIEW 1

START PHASE APPLY_REQUEST_VALUES 2

MyConverter getAsObject: test

MyValidator validate: test

MyBean getInputValue: null

MyBean inputChanged: null to test

MyBean action: succes

END PHASE APPLY_REQUEST_VALUES 2

START PHASE RENDER_RESPONSE 6

MyConverter getAsString: test

MyBean getOutputValue: null

END PHASE RENDER_RESPONSE 6





1. Restore view.

The bean is constructed. The UIViewRoot is restored from session and the bounded components are set in the component bindings.



2. Apply request values.

Behind the scenes the submitted form values are obtained as request parameters and set in the relevant components in the UIViewRoot, for example inputComponent.setSubmittedValue("test"). The submitted values are immediately passed through the converter getAsObject() method and validated by the validator. If the conversion and validation succeeds, then the initial input value will be retrieved from the value binding getter and behind the scenes the inputComponent.setValue(submittedValue) and inputComponent.setSubmittedValue(null) will be executed. If the retrieved initial input value differs from the submitted value, then the valueChangeListener method will be invoked. This all happens in this phase instead of the Process validations phase due to the immediate="true" in the h:inputText. Finally the real processing of the form submission happens here. This happens in this phase instead of the Invoke application phase due to the immediate="true" in the h:commandButton.



3. Process validations.

This phase is skipped due to the immediate="true" in the h:commandButton.



4. Update model values.

This phase is skipped due to the immediate="true" in the h:commandButton.



5. Invoke application.

This phase is skipped due to the immediate="true" in the h:commandButton.



6. Render response.

The values to be shown are retrieved from the value binding getters in the backing bean. If a converter is definied, then the value will be passed through the converter getAsString() method and the result will be shown in the form.



Note for all components with immediate: as the Update model values phase is skipped, the value bindings aren't been set and the value binding getters will return null. But the values are still available by the relevant components in the UIViewRoot. In this case you can retrieve the input value from inputComponent.getValue() in the action() method. The new input value is also available by the ValueChangeEvent in the inputChanged() method. You could even change it using inputComponent.setValue(newValue) in the action() method.



Note for other components without immediate: any other UIInput components inside the same form which don't have immediate="true" set will not be converted, validated nor updated, but behind the scenes the inputComponent.setSubmittedValue(submittedValue) will be executed before the action() method will be executed. You can retrieve the non-converted and non-validated input value from inputComponent.getSubmittedValue() in the action() method. You could even change it using inputComponent.setSubmittedValue(newValue) in the action() method.



Back to top

Conversion error

Let's see what happens if a conversion error will occur. Change the getAsObject() method of MyConverter.java as follows (and remove the immediate="true" from the test.jsp file):



package mypackage;



import javax.faces.component.UIComponent;

import javax.faces.context.FacesContext;

import javax.faces.convert.Converter;

import javax.faces.convert.ConverterException;



public class MyConverter implements Converter {



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

System.out.println("MyConverter getAsObject: " + value);

throw new ConverterException("Conversion failed.");

}



...

}The form submit with the value "test" entered should output at least:



START PHASE RESTORE_VIEW 1

MyBean : constructed

MyBean setInputComponent: javax.faces.component.html.HtmlInputText@2a9fca57

MyBean setOutputComponent: javax.faces.component.html.HtmlOutputText@13bbca56

END PHASE RESTORE_VIEW 1

START PHASE APPLY_REQUEST_VALUES 2

END PHASE APPLY_REQUEST_VALUES 2

START PHASE PROCESS_VALIDATIONS 3

MyConverter getAsObject: test

END PHASE PROCESS_VALIDATIONS 3

START PHASE RENDER_RESPONSE 6

MyBean getOutputValue: null

END PHASE RENDER_RESPONSE 6





1. Restore view.

The bean is constructed. The UIViewRoot is restored from session and the bounded components are set in the component bindings.



2. Apply request values.

Nothing to see here. Behind the scenes the submitted form values are obtained as request parameters and set in the relevant components in the UIViewRoot, for example inputComponent.setSubmittedValue("test").



3. Process validations.

The submitted values are passed through the converter getAsObject() method, where a ConverterException is thrown. The validator and the valueChangeListener are bypassed. Also the inputComponent.setValue(submittedValue) won't take place. The lifecycle will proceed to the Render response phase immediately.



4. Update model values.

This phase is skipped due to the ConverterException.



5. Invoke application.

This phase is skipped due to the ConverterException.



6. Render response.

The values to be shown are retrieved from the value binding getters in the backing bean, expecting the values for which a ConverterException has occurred. Behind the scenes those will be retrieved from the components in the UIViewRoot, e.g. inputComponent.getSubmittedValue().



Note: any other UIInput components inside the same form which don't throw a ConverterException will continue the lifecycle as usual, only the invoke application phase will still be skipped.



Back to top

Validation error

Let's see what happens if a validation error will occur. Change the validate() method of MyValidator.java as follows (and remove the immediate="true" from the test.jsp file and revert MyConverter.java back to original):



package mypackage;



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 MyValidator implements Validator {



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

throws ValidatorException

{

System.out.println("MyValidator validate: " + value);

throw new ValidatorException(new FacesMessage("Validation failed."));

}



}The form submit with the value "test" entered should output at least:



START PHASE RESTORE_VIEW 1

MyBean : constructed

MyBean setInputComponent: javax.faces.component.html.HtmlInputText@2a9fca57

MyBean setOutputComponent: javax.faces.component.html.HtmlOutputText@13bbca56

END PHASE RESTORE_VIEW 1

START PHASE APPLY_REQUEST_VALUES 2

END PHASE APPLY_REQUEST_VALUES 2

START PHASE PROCESS_VALIDATIONS 3

MyConverter getAsObject: test

MyValidator validate: test

END PHASE PROCESS_VALIDATIONS 3

START PHASE RENDER_RESPONSE 6

MyBean getOutputValue: null

END PHASE RENDER_RESPONSE 6





1. Restore view.

The bean is constructed. The UIViewRoot is restored from session and the bounded components are set in the component bindings.



2. Apply request values.

Nothing to see here. Behind the scenes the submitted form values are obtained as request parameters and set in the relevant components in the UIViewRoot, for example inputComponent.setSubmittedValue("test").



3. Process validations.

The values are retrieved as objects from the components, passed through the converter getAsObject() method and validated by the validator, where a ValidatorException is thrown. The valueChangeListener is bypassed. Also the inputComponent.setValue(submittedValue) won't take place. The lifecycle will proceed to the Render response phase immediately.



4. Update model values.

This phase is skipped due to the ValidatorException.



5. Invoke application.

This phase is skipped due to the ValidatorException.



6. Render response.

The values to be shown are retrieved from the value binding getters in the backing bean, expect of the values for which a ValidatorException has occurred. Behind the scenes those will be retrieved from the components in the UIViewRoot, e.g. inputComponent.getSubmittedValue().



Note: any other UIInput components inside the same form which don't throw a ValidatorException will continue the lifecycle as usual, only the invoke application phase will still be skipped.



Back to top

Okay, when should I use the immediate attribute?

If it isn't entirely clear yet, here's a summary, complete with real world use examples when they may be beneficial:



•If set in UIInput(s) only, the process validations phase will be taken place in apply request values phase instead. Use this to prioritize validation for the UIInput component(s) in question. When validation/conversion fails for any of them, the non-immediate components won't be validated/converted.

•If set in UICommand only, the apply request values phase until with update model values phases will be skipped for any of the UIInput component(s). Use this to skip the entire processing of the form. E.g. "Cancel" or "Back" button.

•If set in both UIInput and UICommand components, the apply request values phase until with update model values phases will be skipped for any of the UIInput component(s) which does not have this attribute set. Use this to skip the processing of the entire form expect for certain fields (with immediate). E.g. "Password forgotten" button in a login form with a required and immediate username field and a required but non-immediate password field.