Introduction

Develop astonishing JSF applications by combining the ultimate UI framework for Java EE and the most comprehensive JSF utility library. The source code of this book is available for download here.

",{"_380":381,"_43":44,"_47":48,"_45":46,"_65":66,"_382":383,"_468":378},"previewContent","

\n Author\n
\n Contributor\n
\n Introduction\n
\n Chapter 1: Working with faces messages\n
- \n Faces messages with multiple client IDs in the for attribute\n
- \n Show a single custom global message\n
- \n Highlight invalid inputs via custom CSS\n
\n
\n Chapter 2: Working with links and request parameters\n
\n
\n Chapter 3: Working with JavaScript/CSS resources\n
\n
\n Chapter 4: Initializing PrimeFaces components via view parameters\n
- \n Suppressing the invocation of the setter/converter/validator at each postback\n
- \n Supply a label for messages\n
- \n Supply a default value\n
- \n Suppressing invocation of the converter regardless the null values\n
- \n Support bean validation and triggering validate events on null value\n
\n
\n Chapter 5: Referencing, rendering and moving PrimeFaces components\n
- \n Access a component by using a reference to it\n
- \n Controlling the rendering of components\n
- \n Moving components, facets and behaviors at runtime to a target component\n
\n
\n Chapter 6: Working with media content\n
- \n Working with images\n
- \n Loading external media content\n
- \n Check if the current request is a PrimeFaces dynamic resource request\n
\n
\n Chapter 7: Including Servlets/JSP output in JSF page\n
- \n Including a Servlet output in a PrimeFaces component\n
- \n Decorating the Servlet output\n
\n
\n Chapter 8: Working with forms\n
- \n Introducing OmniFaces Form component\n
- \n Preserving query string over postbacks\n
- \n Preserving view parameters over postbacks\n
- \n Quick look at useRequestURI attribute\n
- \n Ignoring validation failures in <o:form/>\n
\n
\n Chapter 9: Import constants, interfaces, enums and public static methods\n
- \n Import constants/interfaces via PrimeFaces and OmniFaces\n
- \n Import enums via PrimeFaces and OmniFaces\n
- \n Import public static methods with OmniFaces\n
\n
\n Chapter 10: Let’s convert data with PrimeFaces and OmniFaces\n
\n
\n Chapter 11: Let’s validate data with PrimeFaces and OmniFaces\n
- \n Display the label of the component where a constraint violation originated from\n
- \n Customize the PrimeFaces client-side bean validation error messages\n
- \n “Force” the user to tick a checkbox\n
- \n Passing through validation only the modified values\n
- \n Validating unique column in UIData\n
- \n Validation control and cross-field validation (class level validation)\n
- \n Multiple field validators\n
- \n Working with a validator in an iterating component (e.g. <p:dataTable/>)\n
- \n Discussing validators dependency injection\n
- \n Entirely skip validation\n
- \n Handling view parameters validation failure\n
\n
\n Chapter 12: Boost <f:event/> and <f:viewAction/>\n
- \n The <f:event/> and preInvokeAction/postInvokeAction event types\n
- \n Boost <f:viewAction/> via <o:viewAction/>\n
\n
\n Chapter 13: Caching aspects in PrimeFaces and OmniFaces\n
- \n JSF cient-side caching aspects\n
- \n PrimeFaces and OmniFaces server-side caching aspects\n
- \n Caching HTML markup via PrimeFaces and EHCache\n
- \n Caching HTML markup via PrimeFaces and Hazelcast\n
- \n Caching HTML markup via OmniFaces\n
- \n Add a header with given a name and value to the HTTP response\n
- \n Facelets default non-hot reload in production\n
- \n Further readings\n
\n
\n Chapter 14: Handling exceptions\n
- \n Handling AJAX exceptions\n
- \n Handling non-AJAX exceptions\n
- \n PrimeFaces vs OmniFaces exception handlers\n
- \n Report exceptions as global FATAL faces messages\n
\n
\n Chapter 15: Final word\n

Author

$\"\"$ Anghel Leonard is an autodidact senior Java developer with many years of experience in Java SE, Java EE, and related frameworks. He has written and published a significant number of articles about Java technologies as well as tips and tricks for many programming-dedicated websites. In addition, he has reviewed several books, JavaOne articles, and top-rated dissertations about Java. He has written two books about XML and Java (one for beginners and one for advanced developers) for Albastra, a Romanian publisher; four books for Packt Publishing, Jboss Tools 3 Developer Guide, JSF 2.0 Cookbook, JSF 2.0 Cookbook LITE, and Mastering JavaServer Faces 2.2; and the Rapid PrimeFaces video course; two books for Apress, Pro Java 7 NIO 2 and Pro Hibernate and MongoDB and Mastering OmniFaces book for Glasnevin. Currently, he is developing web applications using the latest Java technologies on the market such as WebServices, JMS, EJB, CDI, JSF (PrimeFaces, OmniFaces and RichFaces frameworks), Struts, Vaadin, Hibernate, and so on.

\n\n

Contributor

$\"\"$ Tyler Durden is a java enthusiast who has been researching Java for several years. Besides Java core, Tyler is also interested in java web frameworks, obtaining a deeper understand of JavaServer Faces and related libraries/frameworks (e.g. PrimeFaces, OmniFaces). He lives in Dallas, TX where he runs his own business; in his free time he enjoys going to the movies and restaurant hopping.

\n\n

Introduction

\n\n

\n\n\n

Chapter 1: Working with faces messages

\n\n

In this chapter, you will see several approaches for combining the rich looking PrimeFaces messages with OmniFaces techniques for obtaining more flexible faces messages and less verbose code. Among others, we will discuss about specifying multiple client ID in the for attribute and about generating a global single message whenever validation fails. Basically, we will exemplify on ERROR type messages.

\n\n

Faces messages with multiple client IDs in the `for` attribute

\n\n

In order to display faces messages, PrimeFaces comes with <p:messages/> and <p:message/>. Typically, when you want to display all messages, you use <p:messages/>, as below (display all error messages):

\n\n

<h:form>          \n <h:panelGrid id=\"gridId\" columns=\"1\" cellpadding=\"2\">\n\n  <p:messages/>\n\n  <p:outputLabel for=\"nameId\" value=\"Name:\" />\n  <p:inputText id=\"nameId\" required=\"true\" />     \n      \n  <p:outputLabel for=\"emailId\" value=\"E-mail:\" />\n  <p:inputText id=\"emailId\" required=\"true\" /> \n\n  <p:outputLabel for=\"phoneId\" value=\"Phone:\" />\n  <p:inputText id=\"phoneId\" required=\"true\" /> \n  \n </h:panelGrid>\n\n <p:commandButton id=\"submitButtonId\" value=\"Register\" update=\"gridId\" />\n</h:form>\n

\n\n\n\n

In the below figure, you can see the error messages caused by the fact that we didn’t fill any of the above inputs (this is the effect of the built-in required validator):

\n\n\n

\n\n\n

But, if you want to display messages for a certain component or a certain group of components, you use <p:message/> with for attribute, as below (display error messages only for nameId and emailId, but not for phoneId):

\n\n

<h:form>          \n <h:panelGrid id=\"gridId\" columns=\"1\" cellpadding=\"2\">\n\n  <p:message for=\"nameId\" />\n  <p:message for=\"emailId\" />                    \n\n  <p:outputLabel for=\"nameId\" value=\"Name:\" />\n  <p:inputText id=\"nameId\" required=\"true\" />               \n\n  <p:outputLabel for=\"emailId\" value=\"E-mail:\" />\n  <p:inputText id=\"emailId\" required=\"true\" /> \n\n  <p:outputLabel for=\"phoneId\" value=\"Phone:\" />\n  <p:inputText id=\"phoneId\" required=\"true\" />\n\n </h:panelGrid>\n\n <p:commandButton id=\"submitButtonId\" value=\"Register\" update=\"gridId\" />\n</h:form>\n

\n\n\n\n\n

\n\n\n\n\n

In such a case, we can use OmniFaces, <o:messages/>. Among other features, this component allows multiple client IDs space separated in the for attribute. For example, the above code can be re-written as below (notice that we tried to keep as much as possible from PrimeFaces error messages styles):

\n\n

<h:form>          \n <h:panelGrid id=\"gridId\" columns=\"1\" cellpadding=\"2\">\n\n  <o:messages for=\"nameId emailId\" \n              errorClass=\"ui-message ui-message-error ui-widget ui-corner-all\"\n              errorStyle=\"margin:5px;\" />\n                    \n  <p:outputLabel for=\"nameId\" value=\"Name:\" />\n  <p:inputText id=\"nameId\" required=\"true\" />               \n\n  <p:outputLabel for=\"emailId\" value=\"E-mail:\" />\n  <p:inputText id=\"emailId\" required=\"true\" /> \n\n  <p:outputLabel for=\"phoneId\" value=\"Phone:\" />\n  <p:inputText id=\"phoneId\" required=\"true\" />\n\n </h:panelGrid>\n\n <p:commandButton id=\"submitButtonId\" value=\"Register\" update=\"gridId\" />\n</h:form>\n

\n\n\n\n\n

\n\n\n\n\n

But, if we want to obtain the same look as in PrimeFaces, we need to exploit another feature of <o:messages/>. This component supports the var attribute which sets the current FacesMessage in the request scope and disables the default table/list rendering. This practically allows us to loop through the faces messages list in a completely stateless fashion (the faces messages list is accessible in the page via, facesContext.messageList) and output them as we want. For example, after we inspect the HTML code of an a PrimeFaces error message, we can do this:

\n\n

<h:form>          \n <h:panelGrid id=\"gridId\" columns=\"1\" cellpadding=\"2\">\n\n  <o:messages for=\"nameId emailId\" var=\"msgs\">\n   <div class=\"ui-message ui-message-error ui-widget ui-corner-all\" \n        aria-live=\"polite\" \n        style=\"margin:5px;\">\n\n    <span class=\"ui-messages-error-icon\" style=\"height:16px; width:16px; \n                 margin-top:0; background-position:0 -96px;\" />\t    \n\n    <span class=\"ui-message-error-detail\">#{msgs.detail}</span>\n   </div>\n  </o:messages>\n\n  <p:outputLabel for=\"nameId\" value=\"Name:\" />\n  <p:inputText id=\"nameId\" required=\"true\" /> \t\n\n  <p:outputLabel for=\"emailId\" value=\"E-mail:\" />\n  <p:inputText id=\"emailId\" required=\"true\" /> \n\n  <p:outputLabel for=\"phoneId\" value=\"Phone:\" />\n  <p:inputText id=\"phoneId\" required=\"true\" />\n\n </h:panelGrid>\n <p:commandButton id=\"submitButtonId\" value=\"Register\" update=\"gridId\" />\n</h:form>\n

\n\n\n\n\n

\n\n\n

The complete application is named, MultipleForComponents.

\n\n

So, in our hypothetical case with eight inputs, we have:

\n\n

<o:messages for=\"input1 input2 input3 input4 input5 input6 input7 input8\"\n            errorClass=\"ui-message ui-message-error ui-widget ui-corner-all\"\n            errorStyle=\"margin: 5px;\">\n</o:messages>                \n

\n\n\n\n

\n\n

<o:messages for=\"input1 input2 input3 input4 input5 input6 input7 input8\" \n            var=\"msgs\">\n\n <div class=\"ui-message ui-message-error ui-widget ui-corner-all\" \n      aria-live=\"polite\" \n      style=\"margin:5px;\">\n\n  <span class=\"ui-messages-error-icon\" style=\"height:16px; width:16px; \n               margin-top:0; background-position:0 -96px;\"/>\t \n\n  <span class=\"ui-message-error-detail\">#{msgs.detail}</span>\n </div>\n</o:messages>\n

\n\n\n\n

You can use <o:messages/> to refer to non-input components, which in turn contain input components. For example:

\n\n

<h:form>          \n <h:panelGrid id=\"gridId\" columns=\"1\" cellpadding=\"2\">\n\n  <o:messages for=\"inputs\" \n              errorClass=\"ui-message ui-message-error ui-widget ui-corner-all\" \n              errorStyle=\"margin:5px;\"/>\n\n  <p:outputLabel for=\"nameId\" value=\"Name:\" />\n  <p:inputText id=\"nameId\" required=\"true\" />               \n\n  <h:panelGroup id=\"inputs\">\n   <h:panelGrid id=\"subgridId\" columns=\"1\">\n    <p:outputLabel for=\"emailId\" value=\"E-mail:\" />\n    <p:inputText id=\"emailId\" required=\"true\" /> \n\n    <p:outputLabel for=\"phoneId\" value=\"Phone:\" />\n    <p:inputText id=\"phoneId\" required=\"true\" />         \n   </h:panelGrid>\n  </h:panelGroup> \n </h:panelGrid>\n\n <p:commandButton id=\"submitButtonId\" value=\"Register\" update=\"gridId\" />   \n</h:form>\n

\n\n\n\n

You can also combine non-input components that contain inputs with other input components:

\n\n

<h:form>          \n <h:panelGrid id=\"gridId\" columns=\"1\" cellpadding=\"2\">\n\n  <o:messages for=\" nameId inputs\" \n              errorClass=\"ui-message ui-message-error ui-widget ui-corner-all\" \n              errorStyle=\"margin:5px;\"/>\n\n  <p:outputLabel for=\"nameId\" value=\"Name:\" />\n  <p:inputText id=\"nameId\" required=\"true\" />               \n\n  <h:panelGroup id=\"inputs\">\n   <h:panelGrid id=\"subgridId\" columns=\"1\">\n    <p:outputLabel for=\"emailId\" value=\"E-mail:\" />\n    <p:inputText id=\"emailId\" required=\"true\" /> \n\n    <p:outputLabel for=\"phoneId\" value=\"Phone:\" />\n    <p:inputText id=\"phoneId\" required=\"true\" />         \n   </h:panelGrid>\n  </h:panelGroup> \n </h:panelGrid>\n\n <p:commandButton id=\"submitButtonId\" value=\"Register\" update=\"gridId\" />      \n</h:form>\n

\n\n\n\n

Show a single custom global message

\n\n

Aside from the fact that faces messages are component specific; lets assume that we want to render a custom message that displays Sorry, you have some validation issues!. This intended message would appear, if at least one input component value does not pass the validation phase.

\n\n\n\n

An easy approach consists of using the <o:messages/>. Notice below how we pass the client ID of the form to the for attribute.

\n\n

<h:form id=\"formId\">                     \n <h:panelGrid id=\"gridId\" columns=\"1\" cellpadding=\"2\">              \n               \n  <o:messages for=\"formId\"  \n              style=\"color: red;\"                         \n              message=\"Sorry, you have some validation issues !\"/>\n                \n  <p:outputLabel for=\"nameId\" value=\"Name:\" />\n  <p:inputText id=\"nameId\" required=\"true\" />  \n  <p:message for=\"nameId\"/>\n\n  <p:outputLabel for=\"emailId\" value=\"E-mail:\" />\n  <p:inputText id=\"emailId\" required=\"true\" /> \n  <p:message for=\"emailId\"/>\n\n  <p:outputLabel for=\"phoneId\" value=\"Phone:\" />\n  <p:inputText id=\"phoneId\" required=\"true\" />         \n  <p:message for=\"phoneId\"/>\n </h:panelGrid>\n\n <p:commandButton id=\"submitButtonId\" value=\"Register\" update=\"gridId\" />      \n</h:form>\n

\n\n\n\n

In the below figure you can see how the global error message appears (you can add to it any style that you like). On the left side, you can see the global error message caused by the missing phone number. On the right side, the form was completely filled, so no error messages occured.

\n\n\n

\n\n\n

The complete application is named, SingleGlobalCustomMessage.

\n\n

Highlight invalid inputs via custom CSS

\n\n

When a PrimeFaces form contains invalid inputs we see the corresponding error messages and those fields are highlighted via default PrimeFaces styles:

\n\n

<h:form id=\"formId\">                      \n <h:panelGrid id=\"gridId\" columns=\"1\" cellpadding=\"2\">\n  <p:outputLabel for=\"nameId\" value=\"Name:\" />\n  <p:inputText id=\"nameId\" required=\"true\" /> \n  <p:message for=\"nameId\"/>\n\n  <p:outputLabel for=\"emailId\" value=\"E-mail:\" />\n  <p:inputText id=\"emailId\" required=\"true\" /> \n  <p:message for=\"emailId\"/>\n\n  <p:outputLabel for=\"messId\" value=\"Your message:\" />\n  <p:inputTextarea id=\"messId\" required=\"true\" />\n\n  <p:message for=\"messId\"/>\n </h:panelGrid>\n\n <p:commandButton id=\"submitButtonId\" value=\"Send\" ajax=\"false\" />            \n</h:form>\n

\n\n\n\n\n

\n\n\n\n\n

Alter CSS directly

\n\n

The easiest approach consists of identifying the PrimeFaces CSS used to highlight invalid inputs and alter it accordingly. The below CSS overrides the default one (basically, we override the .ui-state-error which is the PrimeFaces default selector applied to the error messaging container elements):

\n\n

/* style invalid inputs */\n.ui-state-error, .ui-widget-content .ui-state-error, \n.ui-widget-header .ui-state-error {\n background-color: #ff8080;              \n}\n        \n/* style labels of invalid inputs */\n.ui-outputlabel.ui-state-error{\n border: none;\n background-color: #ffffff; \n color: #ff8080;\n}\n

\n\n\n\n

This approach should work in most cases. The complete application is named, OverridePFInvalidInputsCSS.

\n\n

Use OmniFaces `Highlight` component

\n\n

Another approach consists of adding the OmniFaces Highlight component. OmniFaces provides the Highlight (<o:highlight/>) component which was especially designed for highlighting the invalid UIInputs and the associated labels. Additionally (by default), it also places the focus on the first invalid UIInput component. Basically, all we need to do is to pass our CSS to the <o:highlight/> tag via its optional styleClass attribute. The simple use case implies placing the <o:highlight> somewhere on your page (as long as there’s only one instance of it), like this:

\n\n

<o:highlight/>

\n\n

This will use the default CSS class named, error:

\n\n

 label.error {\n  color: #c66;\n }\n\n input.error, select.error, textarea.error {\n  background-color: #fee;\n }\n

\n\n\n\n

This CSS class is used when you do not specify your class via styleClass attribute, as below:

\n\n

<o:highlight styleClass=\"highlight\" />

\n\n

And, the highlight class can be:

\n\n

 label.highlight {\n  color: #ff8080;\n }\n\n input.highlight, select.highlight, textarea.highlight {\n  background-color: #ff8080; \n  border:3px solid black;\n }\n

\n\n\n\n

By default, Highlight will place the focus on the first invalid input component, but you can disable this via the focus attribute:

\n\n

<o:highlight styleClass=\"highlight\" focus=\"false\" />\n<h:form id=\"formId\">                      \n ...\n</h:form>\n

\n\n\n\n

Of course, you can disable focus and use the default CSS class also:

\n\n

<o:highlight focus=\"false\" />\n<h:form id=\"formId\">                      \n ...\n</h:form>\n

\n\n\n\n

So, in our use case, we can do this:

\n\n

<o:highlight styleClass=\"highlight\" />\n<h:form id=\"formId\">                      \n...\n</h:form>\n

\n\n\n\n\n

\n\n\n

The complete application is named, HighlightInvalidInputs.

\n\n\n\n

One more thing here (special thanks to Bauke Scholtz (aka BalusC) for contributing to this chapter:

\n\n\n\n

<o:highlight styleClass=\"highlight\" />\n<h:form id=\"formId\">     \n <p:focus context=\"formId\" />\n ...\n <p:commandButton id=\"submitButtonId\" value=\"Send\" update=\"@form\" />\n</h:form>\n

\n\n\n\n

Chapter 2: Working with links and request parameters

\n\n

In this chapter, we will discuss about several gaps of UIParameter. This component is exposed to JSF page authors via the <f:param/> tag, and it is usually used for attaching extra request parameters to links (<p:link/>), external URLs (<h:outputLink/>), command buttons/links (<p:commandButton/> and <p:commandLink/>) and formatted output (<h:outputFormat/>). Among others, we will focus on passing object into generated links and creating complex labels.

\n\n

Use `<p:link/>` and `<o:param/>` to pass objects into generated link

\n\n

In order to generate a link (HTML <a href>), PrimeFaces comes with <p:link/>. If you check the PrimeFaces Showcase, you can see a simple example (listed below):

\n\n

<p:link outcome=\"productDetail\" value=\"Bookmark\">\n <f:param name=\"productId\" value=\"10\" />\n</p:link>\n

\n\n\n\n

As you can see, the generated link contains a request parameter also. The productId request parameter is “attached” to the generated link via the <f:param> tag.

\n\n\n\n

For example, let’s suppose that we collect from the end user a 10 digit phone number, as below:

\n\n

<p:outputLabel for=\"phone\" value=\"Phone Number: \" />\n<p:inputText id=\"phone\" required=\"true\" value=\"#{dataBean.number}\" />\n

\n\n\n\n

Let’s assume that a 10 digit phone number is composed as follows:

\n\n

the first three numbers are the area code, called the national destination code (NDC)
the following three numbers known as the exchange
the last four numbers at the end of a 10 digits number are the subscriber number

\n\n

Knowing this, we will now create a POJO class to represent these phone number parts (notice the toString()):

\n\n

public class PhoneNumber implements Serializable {\n\n private static final long serialVersionUID = 1L;\n\n private String areacode;\n private String exchange;\n private String subscriber;\n\n public PhoneNumber(String areacode, String exchange, String subscriber) {\n  this.areacode = areacode;\n  this.exchange = exchange;\n  this.subscriber = subscriber;\n }\n\n // getters and setters\n\n // equals() and hashCode()\n\n @Override\n public String toString() {\n  return \"PhoneNumber{\" + \"areacode=\" + areacode + \", exchange=\"\n                        + exchange + \", subscriber=\" + subscriber + \"}\";\n }\n}\n

\n\n\n\n

Instances of this POJO are used via a simple bean named, DataBean (for brevity, we skip its source code). The property that stores the instance is named, number (e.g. #{dataBean.number}).

\n\n

In order to split the provided phone number and represent it as an instance of the PhoneNumber class, we need to attach a converter (for brevity, we skip the converter source code):

\n\n

<p:inputText id=\"phone\" required=\"true\" \n             value=\"#{dataBean.number}\" \n             converter=\"phoneNumberConverter\"/>\n

\n\n\n\n

After the user submits the 10 digits phone number, we want to display a link of type: Dial Phone Number. The HTML behind this link is an <a> tag (of course, the number request parameter should reflect the provided phone number):

\n\n

<a href=\"/.../dial.xhtml?number=0727890877\">\n Dial Phone Number\n</a>\n

\n\n\n\n

In the browser address bar it will appear as:

\n\n

http://.../dial.xhtml?number=0727890877\n

\n\n\n\n

So, this link should be created like below:

\n\n

<p:link value=\"Dial Phone Number\" outcome=\"dial\">\n <f:param name=\"number\" value=\"#{dataBean.number}\"/>               \n</p:link>\n

\n\n\n\n

But, this will generate the following link (notice the effect of invoking toString()):

\n\n

http://.../dial.xhtml?number=PhoneNumber%7Bareacode%3D072%2C+exchange%3D789%2C+s\\\nubscriber%3D0877%7D\n

\n\n\n\n

Well, this link is definitely not the desired one! In order to obtain the desired link, we can write a proper toString() implementation or to break down the DRY principle. But, even better is to use the OmniFaces <o:param/>. This component allows us to pass an object as a request parameter into a link. Practically, <o:param> allows us to indicate the needed converter via the converter attribute, as below:

\n\n

<p:link value=\"Dial Phone Number\" outcome=\"dial\">\n <o:param name=\"number\" value=\"#{dataBean.number}\"\n          converter=\"phoneNumberConverter\"/>               \n</p:link>\n

\n\n\n\n

You can see the result in the below figure:

\n\n\n

\n\n\n

The complete application is named, PassingObjectsInLinkWithoParam.\t

\n\n

Use `<p:commandButton/Link/>` and `<o:param/>` to pass objects into managed beans

\n\n

Commonly, the <f:param/> tag is used inside the <p:commandButton/> and <p:commandLink/> tags for sending request parameters to a managed bean. When the passed parameter is an object (e.g. PhoneNumber) we fall into the similar trappings such as the one mentioned in the above section. In order to avoid such cases, we can simply use <o:param/> with the necessary converter. For example, we can pass our PhoneNumber stored in a DataBean to another bean named, AgendaBean as below:

\n\n

<p:commandButton value=\"Add Phone Number In Your Agenda\" \n                 action=\"#{agendaBean.addInAgenda()}\"\n                 update=\":agendaId\">\n <o:param name=\"number\" value=\"#{dataBean.number}\" \n          converter=\"phoneNumberConverter\"/>               \n</p:commandButton>\n\n<h:panelGroup id=\"agendaId\">\n Agenda: #{agendaBean.agenda}\n</h:panelGroup>\t\t  \n

\n\n\n\n

And the AgendaBean source code is:

\n\n

@Named\n@ViewScoped\npublic class AgendaBean implements Serializable {\n\n private static final long serialVersionUID = 1L;\n\n private List<String> agenda;\n\n public AgendaBean() {\n  agenda = new ArrayList();\n }\n\n public List<String> getAgenda() {\n  return agenda;\n }\n\n public void setAgenda(List<String> agenda) {\n  this.agenda = agenda;\n }\n\n public void addInAgenda() {\n  // native JSF API\n  FacesContext fc = FacesContext.getCurrentInstance();\n  Map<String, String> params = fc.getExternalContext().getRequestParameterMap();\n  agenda.add(params.get(\"number\"));\n        \n  // or using OmniFaces shortcut\n  agenda.add(Faces.getRequestParameter(\"number\"));\n }\n}\n

\n\n\n\n

The complete application is named, PassingObjectsInMBWithoParam.

\n\n

Create complex labels

\n\n

The <f:param/> cannot supply JSF/HTML in parameterized messages (<h:outputFormat/>). Let’s suppose that we want to use a link as a parameter of an un−escaped <h:outputFormat/>, which is nested in a <p:outputLabel/>, as below:

\n\n

<h:form>\n <h:panelGrid columns=\"4\">\n  <p:outputLabel for=\"zipCodeId\">\n   <h:outputFormat value=\"#{msg['ZIPCODE']} ({0}):\" escape=\"false\">\n    <f:param>\n     <p:link value=\"see samples\" \n             outcome=\"#{view.locale eq 'en' ? 'sample_en':'sample_fr'}\">\n      <f:param name=\"locale\" value=\"#{view.locale}\" />\n     </p:link>\n    </f:param>                    \n   </h:outputFormat>\n  </p:outputLabel>\n  <p:inputText id=\"zipCodeId\" required=\"true\" />\n  <p:message for=\"zipCodeId\" />\n  <p:commandButton value=\"Dial\"/>\n </h:panelGrid>\n</h:form>\n

\n\n\n\n

So we have a label that contains a simple text and a link. The link gets modified (points different outcomes) depending on the selected language (English or French). The above code will produce the following output (left side - English, right side - French):

\n\n\n

\n\n\n\n\n

The problem can be solved by replacing the <f:param/> with OmniFaces’ <o:param>. The <o:param/> allows the use of JSF and HTML as parameter values.

\n\n

<h:form>\n <h:panelGrid columns=\"4\">\n  <p:outputLabel for=\"zipCodeId\">\n   <h:outputFormat value=\"#{msg['ZIPCODE']} ({0}):\" escape=\"false\">\n    <o:param>\n     <p:link value=\"see samples\" \n             outcome=\"#{view.locale eq 'en' ? 'sample_en':'sample_fr'}\">\n      <o:param name=\"locale\" value=\"#{view.locale}\" />\n     </p:link>\n    </o:param>                    \n   </h:outputFormat>\n  </p:outputLabel>\n  <p:inputText id=\"zipCodeId\" required=\"true\" />\n  <p:message for=\"zipCodeId\" />\n  <p:commandButton value=\"Dial\"/>\n </h:panelGrid>\n</h:form>\n

\n\n\n\n

This time the result will be like this (everything looks fine for both, English and French):

\n\n\n

\n\n\n

The complete application is named, ComplexLabelsWithOutputFormat.

\n\n

Using `<h:outputFormat/>` output as input parameter

\n\n

Let’s suppose that we want to use the output of <h:outputFormat/> as a tooltip for multiple commands (command links and buttons).

\n\n\n\n

In other words, you cannot write something like this:

\n\n

<p:commandLink ... title=\"<h:outputFormat value=\"...\">\n                           <f:param value=\"...\"/>\n                          </h:outputFormat>\"\n/>\n

\n\n\n\n

It is practically pretty hard to obtain the desired result. However, OmniFaces provides an extension to<h:outputFormat/> that is capable of accomplishing such tasks. This component is exposed to JSF page authors via <o:outputFormat/> tag. More precisely, this component has the ability to capture the <h:outputFormat> output and expose it in the request scope under a variable specified as the value of the var attribute. Let’s see how to use <h:outputFormat/> output as an input/parameter:

\n\n

<h:form>\n <o:outputFormat value=\"#{msg['ZIPCODE']}, {0}\" var=\"_zip\">\n  <f:param value=\"#{view.locale eq 'en' ? 'UK':'France'}\" />                \n </o:outputFormat>\n <p:commandLink value=\"#{msg['ZIPCODE']}\" title=\"#{_zip}\" />\n <p:commandButton value=\"#{msg['ZIPCODE']}\" title=\"#{_zip}\" />\n</h:form>\n

\n\n\n\n

Notice that the variable name is prefixed with underscore character (_). This is an OmniFaces recommendation for avoiding possible conflicts with other variables in the page. Below you can see the output of this case:

\n\n\n

\n\n\n

The complete application is named, OutputFormatAsInputParameter.

\n\n

Chapter 3: Working with JavaScript/CSS resources

\n\n

Working in JSF with JavaScript resources seems to be a pretty simple task. Starting with JSF 2.0, all the web resources, such as CSS, JavaScript, and images are loaded from a folder named resources, present under the root of your web application or from /META-INF/resources in JAR files. A folder under the resources folder is known as a library or theme, which is like a collection of client artifacts (e.g. your company name). After we build the resources folder structure and add the JavaScript resources, we simply plug in the <h:outputScript/> tag into the XHTML page.

\n\n

In this chapter we will “dissect” this topic a little bit more. Among other things, we will discuss how to execute a snippet of JavaScript after each request (AJAX/non-AJAX), how to encapsulate AJAX requests in JavaScript functions placed in the JavaScript global scope in such way that we can simply call them by name, how to load resources from CDN URLs, how to combine JavaScript resources for achieving optimal performance, how to obtain unmapped resources and how to deffer JavaScript resources loading after the page has been completely loaded.

\n\n

Executing a JavaScript snippet after each AJAX/non-AJAX request

\n\n

Let’s suppose that we want to execute a piece of JavaScript code after each request in a page (AJAX, non-AJAX). Requests are typically fired via command buttons (<p:commandButton/>) and command links (<p:commandLink/>). By default, these commands fire AJAX requests (the default value of the ajax attribute is true), so let’s take a look at this first case:

\n\n

Executing a JavaScript snippet after each AJAX request

\n\n

PrimeFaces commands provide an attribute named, oncomplete. The value of this attribute represents the client side callback to be executed when the AJAX request is completed. We can practically do this:

\n\n

<h:body>\n <h:form>\n  <p:commandButton value=\"Generate Random\"                     \n     oncomplete=\"document.getElementById('panelId').innerHTML=Math.random();\"/>\n </h:form>\n   \n <h:panelGroup id=\"panelId\"/>\n</h:body>\n

\n\n\n\n

Or, we can wrap the JavaScript code into a function, as below:

\n\n

<h:head>\n <script type='text/javascript'>\n  function generateRandom(){\n   document.getElementById('panelId').innerHTML=Math.random();\n  }\n </script>\n</h:head>\n\n<h:body>\n <h:form>\n  <p:commandButton value=\"Generate Random\" oncomplete=\"generateRandom();\"/>\n </h:form>\n       \n <h:panelGroup id=\"panelId\"/>\n</h:body>\n

\n\n\n\n

Notice that in both cases the execution of the JavaScript code is tied up in the command button. For example, if we have more command buttons/links in this page and each of them causes the execution of this snippet of JavaScript code then we would need to duplicate the JavaScript code or the JavaScript method invocation in the oncomplete attribute. We can however, provide other custom approaches such as using the update attribute to point to a component that contains the JavaScript code. On a separate note we could also exploit the jsf.ajax.addOnEvent but this is another subject. The following example causes the execution of the JavaScript only at initial request (at POST−AJAX, the JavaScript code will not be executed!):

\n\n

<h:body>\n <h:form>\n  <p:commandButton value=\"Generate Random\"/>\n </h:form>\n\n <h:panelGroup id=\"panelId\"/>\n \n <script type='text/javascript'>\n  document.getElementById('panelId').innerHTML = Math.random();\n </script>\n</h:body>\n

\n\n\n\n

Executing a JavaScript snippet after each non-AJAX request

\n\n

In the case of a non-AJAX requests, the view is re-rendered, so the JavaScript code is executed after each non-AJAX request. The only thing we have to keep in mind is to place the JavaScript code at the end of the </body>. This is needed to ensure that the entire DOM tree of the page is populated and safe to be referenced from the JavaScript code. For example, the case below will not work (upon the firing of each request, it will cause an error like: TypeError: document.getElementById(...) is null; this occurs because when the JavaScript code is executed the DOM tree doesn’t contain the HTML code corresponding to the panelId ID):

\n\n

<head>\n <script type='text/javascript'>\n  document.getElementById('panelId').innerHTML = Math.random();\n </script>\n</h:head>\n\n<h:body>\n <h:form>\n  <p:commandButton value=\"Generate Random\" ajax=\"false\"/>\n </h:form>\n   \n <h:panelGroup id=\"panelId\"/>        \n</h:body>\n

\n\n\n\n

But, this will have the desired effect:

\n\n

<h:body>\n <h:form>\n  <p:commandButton value=\"Generate Random\" ajax=\"false\"/>\n </h:form>\n   \n <h:panelGroup id=\"panelId\"/>            \n <script type='text/javascript'>\n  document.getElementById('panelId').innerHTML = Math.random();\n </script>\n</h:body>\n

\n\n\n\n\n\n

Using the OmniFaces OnloadScript component

\n\n

A quick and general approach consists of using the OmniFaces OnloadScript component. This component is exposed to JSF page authors via <o:onloadScript/> tag. Basically, you nest the JavaScript code that should be executed in the <o:onloadScript/> tag and OmniFaces will take care of the rest. It doesn’t matter where in page you place the <o:onloadScript/>, because OmniFaces will take care of rendering and executing it at the end of the </body> after each AJAX/non-AJAX request. For example, both commands below (AJAX and non-AJAX) will cause the execution of the JavaScript code nested in <o:onloadScript/>, while the JavaScript placed in the oncomplete attribute of the AJAX based command is executed only at the end of such request:

\n\n

<h:head>\n <o:onloadScript>\n  document.getElementById('panelId').innerHTML = Math.random();\n </o:onloadScript>\n</h:head>\n\n<h:body>\n <h:form>\n  <p:commandButton value=\"Generate Random (non-AJAX)\" ajax=\"false\"/>\n </h:form>\n\n <h:form>\n  <p:commandButton value=\"Generate Random (AJAX)\" \n                   oncomplete=\"alert('AJAX request complete!');\"/>\n </h:form>\n\n <h:panelGroup id=\"panelId\"/>                        \n</h:body>\n

\n\n\n\n

The complete application is named, ExecuteScriptAfterEachRequest.

\n\n

Fire AJAX requests from plain JavaScript functions

\n\n

Most JSF developers are familiar with JSF‐AJAX combination exposed via the <p:ajax/> and <f:ajax/> tags. There are many articles about using JSF and AJAX, AJAX based components (e.g. PrimeFaces components), fine‐grained AJAX controls, AJAX callbacks, AJAX trackers etc. The AJAX mechanism used by JSF is encapsulated in a JavaScript file named jsf.js while PrimeFaces uses the jQuery AJAX mechanism.

\n\n

When we using the <f:ajax/>, JSF (e.g. Mojarra), may generate a JavaScript call like this:

\n\n

onclick=\"mojarra.ab(...);return false\"\n

\n\n\n\n

On the other hand, PrimeFaces may generate something such as below via its <p:ajax/>:

\n\n

onchange=\"PrimeFaces.ab(...);\"\t\n

\n\n\n\n

In both cases of (JSF and PrimeFaces), the AJAX request was encapsulated in a “hidden” JavaScript function, whose call is generated and attached by JSF (or explicitly written) to a JavaScript event, like onclick, onchange, etc. Sometimes, however, it may be useful to encapsulate the AJAX requests in JavaScript functions placed in the JavaScript global scope in a such way that we can simply call them by name and without arguments, or with arguments that represent the data that should be passed to the server‐side via the encapsulated AJAX request. Obviously the jsf.ajax.request(), mojarra.ab() and PrimeFaces.ab() functions donʹt allow us to accomplish this, but as you will see, OmniFaces provides a component that nests the jsf.ajax.request() call in a JavaScript global scoped function that can be easily called by its name. Whereas PrimeFaces provides a component that nests the PrimeFaces.ab() call for accomplishing the same goal.

\n\n\n\n

OmniFaces fills this JSF-AJAX gap with a powerful component named CommandScript, which can be used by the page authors via the <o:commandScript/> tag. PrimeFaces also provides a powerful component named RemoteCommand which can be used via <p:remoteCommand/> tag. Both components extend the UICommand (<h:commandXxx/>) which means that they inherit the major features of JSF commands such as action, actionListener, immediate, <f:actionListener/> etc. Nevertheless, you have to know that CommandScript also supports nested <f:param/>/<o:param/> and <f:setPropertyActionListener/>, while RemoteCommand doesn’t.

\n\n

Fire AJAX requests from plain JS functions without arguments

\n\n

Let’s have some examples! Basically, let’s see how we can use both approaches for encapsulating the AJAX requests in JavaScript functions in such a way that we can simply call them by name without arguments. For both, we will use the below simple managed bean:

\n\n

@Named\n@RequestScoped\npublic class HelloBean {\n    \n public void hello() {\n  // JSF approach\n  FacesContext.getCurrentInstance().addMessage(null, \n   new FacesMessage(FacesMessage.SEVERITY_INFO, \"Hello! How are you ?\", null));\n\n  // or use the OmniFaces API shortcut        \n  Messages.addGlobalInfo(\"Hello! How are you ?\");\n }    \n} \n

\n\n\n\n\n\n

So, the idea is pretty simple. We need a JavaScript function that wraps an AJAX request capable of invoking the hello() action method. This JavaScript method will be called by its name when we press a button of type button. The PrimeFaces approach involves the code below:

\n\n

<h5>AJAX request fired from plain JS (PrimeFaces - jQuery AJAX API)</h5>       \n<h:form>\n <p:remoteCommand name=\"hello_pf\" update=\"msgs\"  \n                  onstart=\"alert('I will fire an AJAX request via PrimeFaces!')\" \n                  oncomplete=\"alert('AJAX request via PrimeFaces complete!')\"\n                  actionListener=\"#{helloBean.hello}\" />\n\n <p:growl id=\"msgs\" />\n <p:commandButton type=\"button\" onclick=\"hello_pf();\" \n                  value=\"Hello PrimeFaces!\" icon=\"ui-icon-refresh\" />\n</h:form>\n

\n\n\n\n

When we click on the Hello PrimeFaces! button (notice that this is not a command button!) the AJAX request nested in the JavaScript hello_pf() function will be fired. Before the AJAX request is fired, you will see the effect of onstart attribute; after the AJAX request completes (successfully or not!), you will see the effect of oncomplete attribute. These attributes are optional, and in our example they just point to JavaScript alerts, but you can use them to accomplish different kinds of tasks before/after the AJAX request. Finally, you will see PrimeFaces’ Growl that contains the faces message attached via the hello() action method.

\n\n\n

\n\n\n

The JavaScript code rendered by the PrimeFaces RemoteCommand can be seen in the page source code and can be something like this:

\n\n

<script type=\"text/javascript\">hello_pf = function() {PrimeFaces.ab({s:\"j_idt6:j\n_idt7\",f:\"j_idt6\",u:\"j_idt6:msgs\",onst:function(cfg){alert('I will fire an AJAX \nrequest via PrimeFaces!');},onco:function(xhr,status,args){alert('AJAX request v\nia PrimeFaces complete!');},pa:arguments[0]});}</script>\n

\n\n\n\n

Now, from OmniFaces perspective we have the following code with similar result as RemoteCommand:

\n\n

<h5>AJAX request fired from plain JS (OmniFaces - standard JSF AJAX API)</h5>\n<h:form>\n <o:commandScript name=\"hello_of\" execute=\"@form\" \n                  onbegin=\"alert('I will fire an AJAX request via OmniFaces!')\" \n                  oncomplete=\"alert('AJAX request via OmniFaces complete!')\"\n                  render=\"msgs\" action=\"#{helloBean.hello}\" />\n <p:growl id=\"msgs\" />\n <p:commandButton type=\"button\" onclick=\"hello_of();\" \n                  value=\"Hello OmniFaces!\" icon=\"ui-icon-refresh\" />\n</h:form>\n

\n\n\n\n

The JavaScript code rendered by the OmniFaces CommandScript can be seen in the page source code and can be something like this:

\n\n

<script type=\"text/javascript\">var hello_of=function(o){var o=(typeof o==='objec\nt')&&o?o:{};o['javax.faces.behavior.event']='action';o.execute='@form';o.render=\n'j_idt10:msgs';o.onevent=function(data){if(data.status=='begin'){alert('I will f\nire an AJAX request via OmniFaces!')}if(data.status=='success'){alert('AJAX requ\nest via OmniFaces complete!')}};jsf.ajax.request('j_idt10:j_idt11',null,o)}</scr\nipt>\n

\n\n\n\n

The complete application is named, AJAXFiredFromPlainJS.

\n\n

Fire AJAX requests from plain JS functions with arguments

\n\n

This time let’s complicate things a little. So far, the hello() method returns a simple message, Hello! How are you ?. Furthermore, we want to return a customized message such as Hello PrimeFaces! How are you Cagatay Civici ?. Moreover, the PrimeFaces and Cagatay Civici will be parameters sent via JavaScript function and received in a managed bean via a request parameter map. For this, we will use the below adapted managed beans:

\n\n

@Named\n@RequestScoped\npublic class HelloBean {\n\n public void hello() {\n  // JSF approach\n  Map<String, String> params = FacesContext.getCurrentInstance().\n                      getExternalContext().getRequestParameterMap();\n  FacesContext.getCurrentInstance().addMessage(null,\n   new FacesMessage(FacesMessage.SEVERITY_INFO, \"Hello, \" + \n    params.get(\"product\") +\"! How are you \" + \n    params.get(\"contact\") + \"?\", null));\n\n  // or use the OmniFaces API shortcuts   \n  String HELLO_MSG = \"Hello {0}! How are you {1} ?\";\n  Messages.addGlobalInfo(HELLO_MSG, Faces.getRequestParameter(\"product\"), \n                         Faces.getRequestParameter(\"contact\"));\n }\n}\n

\n\n\n\n\n\n

So, the PrimeFaces code will be:

\n\n

<h5>AJAX request fired from plain JS (PrimeFaces - jQuery AJAX API)</h5>       \n<h:form>\n <p:remoteCommand name=\"hello_pf\" update=\"msgs\"  \n                  onstart=\"alert('I will fire an AJAX request via PrimeFaces!')\" \n                  oncomplete=\"alert('AJAX request via PrimeFaces complete!')\"\n                  actionListener=\"#{helloBean.hello}\" />\n\n <p:growl id=\"msgs\" />\n <p:commandButton type=\"button\"  \n                  onclick=\"hello_pf([{name: 'product', value: 'PrimeFaces'}, \n                                  {name: 'contact', value: 'Cagatay Civici'}]);\"\n                  value=\"Hello PrimeFaces!\" icon=\"ui-icon-refresh\" />\n</h:form>\n

\n\n\n\n\n\n

The Growl will reveal the below imagine:

\n\n\n

\n\n\n

The OmniFaces approach requires to wrap the JavaScript call into a global JavaScript function, as below:

\n\n

<h5>AJAX request fired from plain JS (OmniFaces - standard JSF AJAX API)</h5>\n<h:outputScript>\n function hello_of_wrapper() {\n  hello_of({product: 'OmniFaces',\n            contact: 'Bauke Scholtz and Arjan Tijms'});\n }\n</h:outputScript>\n\n<h:form>\n <o:commandScript name=\"hello_of\" execute=\"@form\" \n                  onbegin=\"alert('I will fire an AJAX request via OmniFaces!')\" \n                  oncomplete=\"alert('AJAX request via OmniFaces complete!')\"\n                  render=\"msgs\" action=\"#{helloBean.hello}\" />\n <p:growl id=\"msgs\" />\n <p:commandButton type=\"button\" onclick=\"hello_of_wrapper();\" \n                  value=\"Hello OmniFaces!\" icon=\"ui-icon-refresh\" />\n</h:form>\n

\n\n\n\n\n\n

This time the Growl will reveal the below imagine:

\n\n\n

\n\n\n

The complete application is named, AJAXFiredFromPlainJSWithAdditionalParams.

\n\n

Fire AJAX requests from plain JS functions on page load (autorun)

\n\n

Both RemoteCommand and CommandScript allow us to defer loading and rendering to a window onload event (auto invoke the global scoped JavaScript function). In both cases, we have a flag attribute (default false). For RemoteCommand this is named autoRun and in CommandScript it is named autorun.

\n\n

<p:remoteCommand name=\"hello_pf\" autoRun=\"true\" update=\"msgs\"\n                 actionListener=\"#{helloBean.hello}\" />\n

\n\n\n\n

<o:commandScript name=\"hello_of\" autorun=\"true\" execute=\"@form\"\n                 render=\"msgs\" action=\"#{helloBean.hello}\" />\n

\n\n\n\n

Some differences between PrimeFaces and OmniFaces approaches

\n\n

Since PrimeFaces and OmniFaces supports this feature, you may ask when to use one or the other? Well, in this section you will experience several differences between these two that will help you choose according to your needs.

\n\n

The `RemoteCommand` supports a bunch of attributes not available in `CommandScript`\n

\n\n

The RemoteCommand support onsuccess (allows us to indicate a JavaScript handler to execute when AJAX request succeeds), onerror (allows us to indicate a JavaScript handler to execute when AJAX request fails), async (allows us to indicate that AJAX requests shouldn’t be queued), delay (execute AJAX requests with delay), form (point the form to serialize for an AJAX request), global (AJAX requests are listened by ajaxStatus component), ignoreAutoUpdate (components which autoUpdate=\"true\" will not be updated for this request), partialSubmit, partialSubmitFilter, timeout, process and resetValues.

\n\n\n\n

The `CommandScript` supports nested `<f:param/>` and `<o:param/>`\n

\n\n

The CommandScript supports nesting of <f:param/>/<o:param/>, while RemoteCommand doesn’t. We can practically re-write the above example to pass the parameters as seen below:

\n\n

<o:commandScript name=\"hello_of\" execute=\"@form\" \n                 onbegin=\"alert('I will fire an AJAX request via OmniFaces!')\" \n                 oncomplete=\"alert('AJAX request via OmniFaces complete!')\"\n                 render=\"msgs\" action=\"#{helloBean.hello}\">\n <f:param name=\"product\" value=\"OmniFaces\"/>\n <f:param name=\"contact\" value=\"Bauke Scholtz and Arjan Tijms\"/>\n</o:commandScript>\n<p:growl id=\"msgs\" />\n<p:commandButton type=\"button\" onclick=\"hello_of();\" \n                 value=\"Hello OmniFaces!\" icon=\"ui-icon-refresh\" />\n

\n\n\n\n\n\n

The complete application is named, CommandScriptAndfparam.

\n\n

The `CommandScript` supports `<f:setPropertyActionListener/>`\n

\n\n

As you probably know, The <f:setPropertyActionListener/> tag uses an action listener (created by the framework) to directly set a value into a managed bean property; it is placed within a component derived from the ActionSource class. The target attribute indicates the managed bean property, while the value attribute indicates the value of the property. This is supported only by CommandScript as in the below example:

\n\n

<h:form>\n <o:commandScript name=\"hello_of\" execute=\"@form\" \n                  onbegin=\"alert('I will fire an AJAX request via OmniFaces!')\" \n                  oncomplete=\"alert('AJAX request via OmniFaces complete!')\"\n                  render=\"msgs\" action=\"#{helloBean.hello}\">\n  <f:setPropertyActionListener target=\"#{helloBean.product}\" value=\"OmniFaces\"/>\n  <f:setPropertyActionListener target=\"#{helloBean.contact}\" \n                               value=\"Bauke Scholtz and Arjan Tijms\"/>\n </o:commandScript>\n\n <p:growl id=\"msgs\" />\n <p:commandButton type=\"button\" onclick=\"hello_of();\" \n                  value=\"Hello OmniFaces!\" icon=\"ui-icon-refresh\" />\n</h:form>\n

\n\n\n\n

Of course the HelloBean was modified accordingly as you can see in the complete application named, CommandScriptAndfsetPropertyActionListener.

\n\n

Combining PrimeFaces resources in a single resource

\n\n

The CombinedResourceHandler claims to considerably improve page loading. This is achieved implementing the following:

\n\n

Removing all the separate script and stylesheet resources which have the target attribute set to head from the UIViewRoot.
Creating a combined one for all scripts and another combined one for all stylesheets. So, instead of firing a GET request per resource, the browser will fire a single GET request for all scripts, and another one for all stylesheets. Furthermore, the CombinedResourceHandler is responsible for sequentially returning all the resources combined in these requests. Visually speaking, something like below (let’s suppose that our PrimeFaces page requires the following CSS and JavaScript resources):

\n\n

<!-- stylesheets -->\n<h:outputStylesheet name=\"css/style.css\" />\n<h:outputStylesheet name=\"css/page.css\" />\n<h:outputStylesheet name=\"css/custom.css\" />\n\n<!-- scripts -->\n<h:outputScript library=\"default\" name=\"js/my_js.js\" target=\"head\"/>\n<h:outputScript library=\"custom\" name=\"js/custom1.js\" target=\"head\"/>\n<h:outputScript library=\"custom\" name=\"js/custom2.js\" target=\"head\"/>\n<h:outputScript library=\"custom\" name=\"js/custom3.js\" target=\"head\"/>\n\n<!-- deferred scripts (presented later in this chapter) -->\n<o:deferredScript library=\"custom\" name=\"js/custom2.js\"/>\n<o:deferredScript library=\"default\" name=\"js/js2.js\"/>\n

\n\n\n\n

will become,

\n\n

<!-- stylesheets -->\n<link type=\"text/css\" rel=\"stylesheet\"\n      href=\"/MyApp/faces/javax.faces.resource/eNpLLi7WLy6pzEnVSy4urgFi_dxKEBMAdq\n      IJcg.css?ln=omnifaces.combined&amp;v=1433659201062\" />\n\n<!-- scripts -->\n<script type=\"text/javascript\"\n        src=\"/MyApp/faces/javax.faces.resource/eNrLz83LTEtMTi22yoex9LKKa1JS0xJLc0\n        qssor1s4oNgSIARRYPcA.js?ln=omnifaces.combined&amp;v=1433659204389\"/>\n\n<!-- deferred scripts -->\n<script type=\"text/javascript\">\nOmniFaces.DeferredScript.add('/MyApp/faces/javax.faces.resource/eNpLSU1LLM0pscoq1\n        s8qNtLLKgYAOn0GRg.js?ln=omnifaces.combined&v=1433659201450');\n</script>\n

\n\n\n\n

Configuring `CombinedResourceHandler`\n

\n\n

In order to use the CombinedResourceHandler, you need to keep in mind that:

\n\n

In case of the <h:outputScript/>, always specify the target=\"head\".
In the below context, the “resource identifier” represents the unique combination of library name and resource name, separated by a colon; not the\nRESOURCE_IDENTIFIER.\nIf you want them to appear after any auto‐included resources of standard JSF implementation or JSF component libraries, then move the declarations to top of the </h:body>.
\norg.omnifaces.COMBINED_RESOURCE_HANDLER_CACHE_TTL ‐ You can optionally activate server side caching of the combined resource content by specifying this context parameter while the JSF project’s stage is not set to Development as per Faces#isDevelopment() utility method (based on Application#getProjectStage()). This should be set to a value greater than 0 (default is 0, means no cache).
\norg.omnifaces.COMBINED_RESOURCE_HANDLER_EXCLUDED_RESOURCES ‐ If you need to exclude resources in the <h:head/> from being combined, then provide a\ncomma separated string of their “resource identifiers” via this context parameter (e.g. <param-value>default:my_js.js, javax.faces:jsf.js, css/page.css</param-value>).
\norg.omnifaces.COMBINED_RESOURCE_HANDLER_SUPPRESSED_RESOURCES ‐ If you need to suppress and remove the resources in the <h:head/> from being combined, then provide a comma separated string of their “resource identifiers” via this context parameter.
\norg.omnifaces.COMBINED_RESOURCE_HANDLER_INLINE_CSS ‐ Set to true if you want to render the combined CSS resources inline (embedded in HTML) instead\nof as a resource.
\norg.omnifaces.COMBINED_RESOURCE_HANDLER_INLINE_JS ‐ Set to true if you want to render the combined JS resources inline (embedded in HTML) instead of as a resource.
\norg.omnifaces.COMBINED_RESOURCE_HANDLER_DISABLED ‐ Use this context parameter if you want to conditionally disable the combined resource handler\n(supports EL expressions).
If youʹre also using the CDNResourceHandler or, at least, have configured its context parameter org.omnifaces.CDN_RESOURCE_HANDLER_URLS, then those\nCDN resources will automatically be added to the set of excluded resources.
To get it to run, this handler needs to be registered in faces-config.xml as follows:

\n\n

<application>\n <resource-handler> \n  org.omnifaces.resourcehandler.CombinedResourceHandler\n </resource-handler>\n</application>\n

\n\n\n\n

More details and examples on these features are in OmniFaces Showcase.

\n\n

Combining PrimeFaces resources

\n\n

Let’s suppose that we have a PrimeFaces page that implicitly requires the below CSS (theme.css, primefaces.css and colorpicker.css) and JavaScript resources (jquery.js, jquery-plugins.js, primefaces.js, touchswipe.js and colorpicker.js). You can also see these in the source page:

\n\n\n

\n\n\n

Notice that for each CSS and JavaScript resource there is a GET request. Furthermore, we can combine all CSS resources in a single GET request and all JavaScript resources in another single GET request. To achieve this, simply register the CombinedResourceHandler in faces-config.xml. Now, instead of the above figure we obtain this:

\n\n\n

\n\n\n

The complete application is named, PrimeFacesCombinedResources.

\n\n

Combining PrimeFaces themes

\n\n

You have probably already noticed from the above figure that theme.css wasn’t automatically combined with the rest of CSS resources. In order to combine the PrimeFaces theme you need to follow two simple steps. First, prevent loading the theme by setting the primefaces.THEME context parameter to none in web.xml:

\n\n

<context-param>\n <param-name>primefaces.THEME</param-name>\n <param-value>none</param-value>\n</context-param>\n

\n\n\n\n

Second, add the theme explicitly in the page via <h:outputStylesheet/>:

\n\n

<h:outputStylesheet library=\"primefaces-aristo\" name=\"theme.css\"/>\n

\n\n\n\n

This time the theme.css is also combined:

\n\n\n

\n\n\n

The complete application is named, PrimeFacesCombinedTheme.

\n\n

Providing external (CDN) URLs instead of the default local URLs for JSF resources

\n\n

The OmniFaces CDNResourceHandler was primarily designed to move auto‐included JSF resources to a CDN host (e.g. jsf.js or PrimeFaces jquery.js, etc). For local resources this is unnecessary and can just be done via a “plain HTML” <script/> tag. The CDNResourceHandler allows the developer to provide CDN URLs instead of the default local URLs for JSF resources as provided by <h:outputScript/>, <h:outputStylesheet/>, <o:deferredScript/> (presented later in this chapter) and <p|o|h:graphicImage/>. As you know, by default, these artifacts do not allow CDN URLs (e.g. Google Hosted Libraries). The only approach is to download the resource and store it locally, or to use the <script/>, <link/> or <img/> instead of JSF artifacts.

\n\n

Let’s start with a didactic example meant to understand CDNResourceHandler features. Let’s say that you need to load jQuery and jQuery UI resources from a CDN. They are available in Google Hosted Libraries under the following URLs:

\n\n

https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js
https://ajax.googleapis.com/ajax/libs/jqueryui/1.11.4/jquery-ui.min.js
https://ajax.googleapis.com/ajax/libs/jqueryui/1.11.4/themes/smoothness/jquery-ui.css

\n\n

In order to use the CDNResourceHandler, you need to accomplish several steps:

\n\n

1.Since this is a didactic example, it was especially designed to expose all CDNResourceHandler features. The only drawback consists of the fact that we must “fool” the JSF default resource handler that the resources that being loaded from CDN repository are available locally in the /resources folder. We avoid the imminent RES_NOT_FOUND error by providing empty resources with the same names as the resources from CDN. As you will see later in a real example, this step is not necessary. But, for this example, we have shaped the folder’s structure from the figure below (the JavaScript and CSS files are empty - you can even consider this example as a bad practice of using CDNResourceHandler, because normally, you can rely on “plain HTML” <script/> tag instead of CDNResourceHandler):

\n\n\n

\n\n\n

2.Configure the CDNResourceHandler in your faces-config.xml - this is needed to tell JSF to use this resource handler:

\n\n

<application>\n <resource-handler>\n  org.omnifaces.resourcehandler.CDNResourceHandler\n </resource-handler>\n</application>\n

\n\n\n\n

3.Add the resources names (and libraries) with their corresponding CDN URLs in web.xml (or web-fragment.xml) via org.omnifaces.CDN_RESOURCE_HANDLER_URLS context parameter. Notice how we specify the resources libraries, names and CDN URLs:

\n\n

<context-param>\n <param-name>\n  org.omnifaces.CDN_RESOURCE_HANDLER_URLS\n </param-name>\n <param-value>\n  jquery:jquery.min.js=https://ajax.googleapis.com/ajax/libs/\n         jquery/1.11.3/jquery.min.js,\n  jquery:js/jquery-ui.min.js=https://ajax.googleapis.com/ajax/libs/\n         jqueryui/1.11.4/jquery-ui.min.js,\n  jquery:css/jquery-ui.css=https://ajax.googleapis.com/ajax/libs/\n         jqueryui/1.11.4/themes/smoothness/jquery-ui.css\n </param-value>\n</context-param>\n

\n\n\n\n\n\n

4.Add the resources in the JSF page via <h:outputStylesheet/> and <h:outputScript/>:

\n\n

<h:outputStylesheet library=\"jquery\" name=\"css/jquery-ui.css\"/>\n<h:outputScript library=\"jquery\" name=\"jquery.min.js\" />\n<h:outputScript library=\"jquery\" name=\"js/jquery-ui.min.js\" />\n

\n\n\n\n

The complete application is named, CDNResourceHandlerDidacticExample.

\n\n

After you run this application, you notice in the page source code the following <script/> and <link/> tags:

\n\n

<link type=\"text/css\" rel=\"stylesheet\" \n                      href=\"https://ajax.googleapis.com/ajax/libs/\n                      jqueryui/1.11.4/themes/smoothness/jquery-ui.css\" />\n<script type=\"text/javascript\" src=\"https://ajax.googleapis.com/ajax/libs/\n                      jquery/1.11.3/jquery.min.js\" />\n<script type=\"text/javascript\" src=\"https://ajax.googleapis.com/ajax/libs/\n                      jqueryui/1.11.4/jquery-ui.min.js\" />\n

\n\n\n\n

Wildcard configuration

\n\n

The CDNResourceHandler supports the * wildcard that can be used to map every single resource of a specific library to a common CDN URL. For example, we have three resources in the same library, jqueryand for each of them we have a key=value configuration where the value has the same CDN URL root, https://ajax.googleapis.com/ajax/libs/. Using the * wildcard we can re-write this configuration like below:

\n\n

<context-param>\n <param-name>\n  org.omnifaces.CDN_RESOURCE_HANDLER_URLS\n </param-name>\n <param-value>            \n  jquery:*=https://ajax.googleapis.com/ajax/libs/*\n </param-value>\n</context-param>\n

\n\n\n\n\n\n

Furthermore, refer to the resource accordingly:

\n\n

<h:outputStylesheet library=\"jquery\" \n                    name=\"jqueryui/1.11.4/themes/smoothness/jquery-ui.css\"/>\n<h:outputScript library=\"jquery\" name=\"jquery/1.11.3/jquery.min.js\" />\n<h:outputScript library=\"jquery\" name=\"jqueryui/1.11.4/jquery-ui.min.js\" />\n

\n\n\n\n

Again, since this is not a real case, you have to avoid the RES_NOT_FOUND error by reflecting the libraries and names of resources locally as in figure below (empty resources):

\n\n\n

\n\n\n

The complete application is named, CDNResourceHandlerWildcardConfig.

\n\n

EL expessions in the CDN URL

\n\n

The CDN resource handler supports evaluating EL expessions (on a per-request basis) in the CDN URL. For example, we can provide the CDN URL root like below:

\n\n

<context-param>\n <param-name>\n  org.omnifaces.CDN_RESOURCE_HANDLER_URLS\n </param-name>\n <param-value>            \n  jquery:*=#{myCDNBean.urlRoot}/*\n </param-value>\n</context-param> \n

\n\n\n\n

The MyCDNBean is very simple in this case:

\n\n

@Named\n@RequestScoped\npublic class MyCDNBean {\n    \n private final String urlRoot = \"https://ajax.googleapis.com/ajax/libs\";\n\n public String getUrlRoot() {\n  return urlRoot;\n }        \n}\n

\n\n\n\n

The complete application is named, CDNResourceHandlerEL.

\n\n\n\n

<context-param>\n <param-name>\n  org.omnifaces.CDN_RESOURCE_HANDLER_DISABLED\n </param-name> \n <param-value>\n  #{facesContext.application.projectStage eq 'Development'}\n </param-value>\n</context-param>\n

\n\n\n\n

Real case - delegate PrimeFaces jQuery to CDN

\n\n

As you probably know, PrimeFaces internally uses jQuery library. This means that PrimeFaces requires jQuery as a resource. You can easily see this by checking the scripts loaded in an application that uses PrimeFaces. Among other JavaScript resource, you will notice something like this:

\n\n

<script type=\"text/javascript\" src=\"/.../javax.faces.resource/jquery/jquery.js? \n ln=primefaces&amp;v=5.3\">\n

\n\n\n\n

Or, via a specialized tool like Firebug:

\n\n\n

\n\n\n

In order to configure a CDN for a resource, you need to correctly identify the resource library, path and name (you can in a similar way push your static resources to CDN). This can be achieved easily by visually inspecting the path (typically this is a path built with respect to the JSF standard resource handler - details here). The value of the ln request parameter points to the library of the resource (e.g. primefaces) and the substring between the resource identifier (JSF identify a resource by the presence in path of the javax.faces.resource string) and the query string delimitator, ?, points to the resource path and name (e.g. jquery/jquery.js). Once you know the library and the resource path and name, you can easily compose the key=value pair and pass it to CDNResourceHandler via the org.omnifaces.CDN_RESOURCE_HANDLER_URLS context parameter:

\n\n

<context-param>\n <param-name>\n  org.omnifaces.CDN_RESOURCE_HANDLER_URLS\n </param-name>\n <param-value>\n  primefaces:jquery/jquery.js=https://ajax.googleapis.com/ajax/libs/\n  jquery/1.11.3/jquery.min.js\n </param-value>\n</context-param>\n

\n\n\n\n

The complete application is named, DelegatePrimeFacesjQuerytoCDN.

\n\n

JSF resource lookup issues

\n\n

When you are delegating PrimeFaces static resources to CDN you may notice that the JSF resource lookup (via #{resource[]}) may not work properly. Actually, this is true for any static resource that uses JSF resource lookup (not necessarily from PrimeFaces), below you can see three examples extracted from primefaces.css:

\n\n

background:url(\"#{resource['primefaces:datascroller/images/loading.gif']}\");\nbackground-image:url(\"#{resource['primefaces:spacer/dot_clear.gif']}\");\nbackground:transparent url(\"#{resource['primefaces:forms/password-meter.png']}\");\n

\n\n\n\n

So, if you put the primefaces.css to a CDN, then the JSF resource lookup will not act as expected because the resources pointed to via #{resource[]} will not be loaded. The solution consists of replacing all #{resource[]} with simple CSS paths, as below:

\n\n

background: url(\"datascroller/images/loading.gif\");\nbackground-image: url(\"spacer/dot_clear.gif\");\nbackground: transparent url(\"forms/password-meter.png\");\n

\n\n\n\n

Of course, there are many such modifications needed. Fortunately, they are already available for download for PrimeFaces 5.1, 5.2 and 5.3. Read further details here.

\n\n\n\n

Defer loading and parsing of JavaScript resources

\n\n

There was a time when JavaScript snippets were very small and nobody cared that the scripts were fetched and executed immediately, before the browser continues parsing the page. Well, many things have changed since then. Today deferring JavaScript has become a priority and an important criterion for optimization of web applications. By “deferring”, we mean that an approach delays the loading of JavaScript code, or more precisely, allows a web page to fully load first. Accomplishing this task, however, is one of those issues on the web that give us real headaches.

\n\n

Many developers have learned about deferred scripts after they pass their web application through the Google PageSpeed Tools or notice how Bootstrap places its resources at the end of the </body>. A message like the ones shown in the figures below has a big impact on self‐confidence. You probably have never seen these messages before, but sooner or later, you will! If you are a JSF developer and you have loaded your JavaScript resources via <h:outputScript/> then this kind of message will place you in an unpleasant situation. If the <h:outputScript/> has the target set to body, and you still see the above messages, then you are in trouble!

\n\n\n

\n\n\n\n

\n\n\n

<h:body>\n <h3>After 5 seconds you will see a cool message ...</h3>\n <a id=\"msgId\" href=\"https://jsf-showcase.zeef.com/anghel.leonard\"></a>\n\n <h:outputScript library=\"default\" name=\"js/sample.js\"/>\n</h:body>\n

\n\n\n\n

And the sample.js is a simple JavaScript code that “sleeps” for 5 seconds before it pushes a cool message in the <a/> tag:

\n\n

function sleep(ms) {\n var dt = new Date(); \n dt.setTime(dt.getTime() + ms);\n while (new Date().getTime() < dt.getTime())\n       ;\n}\n\nsleep(5000);\n\ndocument.getElementById('msgId').innerHTML = \"OmniFaces and PrimeFaces Rocks!\";\n

\n\n\n\n

This doesnʹt actually mean that the script is deferred until after the entire page is fully loaded. For example,the Firebug tool will reveal this in the Timeline section ‐ the magical 5 seconds of sleep should not be there, not in the page loading time! Just check out the figure below:

\n\n\n

\n\n\n

Dig further, and you will discover the defer and async flag attributes. Of course, you can use these attributes only if you switch from the <h:outputScript/> to the <script/> tag. The effort involved in this switch is not justified, as the magical 5 seconds will still be present in the page loading time. Inline JavaScript will reveal the same thing. A pure working JavaScript solution comes from Google and is presented in the complete application named, FakeDeferredScript. The effect of it can be seen in the image below:

\n\n\n

\n\n\n

So the myth of placing the code before the </body>, inline in the JavaScript code, using defer and async is busted. The Google recommendation really defers the code! It is time to see how PrimeFaces and OmniFaces defers JavaScript code loading.

\n\n

Defer loading and parsing of JavaScript resources via PrimeFaces

\n\n

When we talk about deferring something (NOT only JavaScript resources) in PrimeFaces we need to focus on the <p:outputPanel/> component. As its name suggests, the <p:outputPanel/> component is a panel component that can be rendered as a <div/> or <span/> HTML component.The <p:outputPanel/> component supports deferred loading, where the content of the panel is loaded after the page is loaded. The panel renders a loading animation while loading its contents. For example, we can defer the loading of sample.js like this:

\n\n

<h:body>\n <h3>After 5 seconds you will see a cool message ...</h3>\n <a id=\"msgId\" href=\"https://jsf-showcase.zeef.com/anghel.leonard\"></a>\n\n <p:outputPanel deferred=\"true\">\n  <script src=\"resources/default/js/sample.js\"></script>\n </p:outputPanel>        \n</h:body>\n

\n\n\n\n

A possible result is in the figure below:

\n\n\n

\n\n\n

The complete application is named, PrimeFacesDeferredScript.

\n\n\n\n\n\n

Defer loading and parsing of JavaScript resources via OmniFaces

\n\n

While PrimeFaces comes with <p:outputPanel/> component OmniFaces comes with a dedicated custom component for deferring JavaScript resources. The given script resource is only loaded when the window has completely finished loading. This component is named DeferredScript and can be used in page via the <o:deferredScript/> tag. For example, letʹs focus on loading our sample.js in a deferred manner via <o:deferredScript/>. It is “embarrassingly” simple to use this!

\n\n

<h:head>\n <o:deferredScript library=\"default\" name=\"js/sample.js\"/>\n</h:head>\n<h:body>\n <h3>After 5 seconds you will see a cool message ...</h3>\n <a id=\"msgId\" href=\"https://jsf-showcase.zeef.com/anghel.leonard\"></a>\n</h:body>\n

\n\n\n\n

A possible result is in the figure below:

\n\n\n

\n\n\n

The complete application is named, OmniFacesDeferredScript.

\n\n\n\n

Defer loading and parsing of PrimeFaces resources via OmniFaces

\n\n

If you have ever checked the source code of a page that uses PrimeFaces, then you would have noticed several JavaScript resources loaded especially for PrimeFaces. The number of these resources varies depending on the type of PrimeFaces artifacts present in the page. For example, let’s suppose that we have the below snippet of dummy code:

\n\n

<h:form>\n <h:panelGrid columns=\"3\">\n  <h:outputText value=\"Keyup: \" />\n  <p:inputText id=\"counter\">\n   <p:ajax event=\"keyup\" update=\"out\"/>\n  </p:inputText>\n  <h:outputText id=\"out\"/>\n </h:panelGrid>\n</h:form>\n

\n\n\n\n

In order to work, this code will need the following JavaScript resources (these are basically the most common JavaScript resources in a PrimeFaces application):

\n\n

<script type=\"text/javascript\" \n  src=\"/.../javax.faces.resource/jquery/jquery.js?ln=primefaces&amp;v=5.3\"/>\n<script type=\"text/javascript\" \n  src=\"/.../javax.faces.resource/primefaces.js?ln=primefaces&amp;v=5.3\">\n<script type=\"text/javascript\"    \n  src=\"/.../javax.faces.resource/jquery/jquery-plugins.js?\n  ln=primefaces&amp;v=5.3\">\n

\n\n\n\n

Or, shortly we need the libraries and the names:

\n\n

Library: primefaces; Name: jquery/jquery.js\n
Library: primefaces; Name: primefaces.js\n
Library: primefaces; Name: jquery/jquery-plugins.js\n

\n\n

Other resources may consist of (not needed here):

\n\n

Library: primefaces; Name: layout/layout.js\n
Library: primefaces; Name: fileupload/fileupload.js\n
…

\n\n\n\n

Well, you may think that the above three resources can be deferred like this:

\n\n

<o:deferredScript library=\"primefaces\" name=\"jquery/jquery.js\" />\n<o:deferredScript library=\"primefaces\" name=\"primefaces.js\" />\n<o:deferredScript library=\"primefaces\" name=\"jquery/jquery-plugins.js\" />\t\n

\n\n\n\n

Actually, things are a little bit more complicated because PrimeFaces uses several inline scripts that will cause errors in the above approach. In order to solve these issues, we need to adopt the following two bullets:

\n\n

write a helper script capable of deferring the PrimeFaces.xxx() calls (e.g. PrimeFaces.ab(), PrimeFaces.cw(), PrimeFaces.focus(), etc)
don’t defer jquery.js (this can be loaded via CDN as you saw earlier in this chapter)

\n\n

Writing the helper script in not an easy task, but fortunately BalusC has already done this for the community, so here it’s the BalusC helper script (of course, you can use a minified version of it):

\n\n

/* BalusC script for deferring PrimeFaces inline scripts (ab(), cw(), focus()) */\nDeferredPrimeFaces = function() {\n var deferredPrimeFaces = {};\n var calls = [];\n var primeFacesLoaded = !!window.PrimeFaces;\n\n function defer(name, args) {\n  calls.push({ name: name, args: args });\n }\n\n deferredPrimeFaces.begin = function() {\n  if (!primeFacesLoaded) {\n      delete window.PrimeFaces;\n  }\n };\n\n deferredPrimeFaces.apply = function() {\n  if (window.PrimeFaces) {\n      for (var i = 0; i < calls.length; i++) {\n           window.PrimeFaces[calls[i].name].\n            apply(window.PrimeFaces, calls[i].args);\n      }\n  }\n\n  delete window.DeferredPrimeFaces;\n };\n\n if (!primeFacesLoaded) {\n     window.PrimeFaces = {\n      ab: function() { defer(\"ab\", arguments); },\n      cw: function() { defer(\"cw\", arguments); },\n      focus: function() { defer(\"focus\", arguments); }\n     };\n }\n\n return deferredPrimeFaces;\n}();\n

\n\n\n\n

You can place this script in the /resources folder (e.g. /resources/app/scripts/primefaces.deferred.js). Further, load this script in page via <h:outputScript/> (not deferred).

\n\n\n\n

So, we can finally glue this information and obtain the below code:

\n\n

<h:head>\n <h:outputScript library=\"app\" name=\"scripts/primefaces.deferred.js\" \n                 target=\"head\" />                \n <o:deferredScript library=\"primefaces\" name=\"primefaces.js\" \n                   onbegin=\"DeferredPrimeFaces.begin()\"/>               \n <o:deferredScript library=\"primefaces\" name=\"jquery/jquery-plugins.js\" \n                   onsuccess=\"DeferredPrimeFaces.apply()\" />              \n</h:head>  \n

\n\n\n\n

The complete application is named, DeferringPrimeFacesScript.

\n\n

Or, another hypothetical example:

\n\n

<h:outputScript library=\"app\" name=\"scripts/primefaces.deferred.js\" \n                target=\"head\" />        \t\n<o:deferredScript library=\"primefaces\" name=\"primefaces.js\" \n                  onbegin=\"DeferredPrimeFaces.begin()\"/>\n<o:deferredScript library=\"primefaces\" name=\"jquery/jquery-plugins.js\" />\n<o:deferredScript library=\"primefaces\" name=\"layout/layout.js\" />\n<o:deferredScript library=\"primefaces\" name=\"fileupload/fileupload.js\" \n                  onsuccess=\"DeferredPrimeFaces.apply()\" />             \n

\n\n\n\n

Pay attention to the correct approach

\n\n

Before you apply the above approach, make sure you identify the PrimeFaces JavaScript resources of your application (check page source code;\nuse Firebug for Mozilla, or any other similar tool). Afterwards, check if there are more PrimeFaces.xxx() functions that need to be deferred (by\ndefault, the BalusC approach defers PrimeFaces.ab(), PrimeFaces.cw(), PrimeFaces.focus()). If there are such functions, then add them manually inside window.PrimeFaces = {}. Finally, load the primefaces.deferred.js via <h:outputScript target=\"head\" />, don’t defer jquery.js and\nproduce the corresponding <o:deferredScript/> entries in the same order as you have identified the resources. Don’t forget to call the\nDeferredPrimeFaces.begin() in onbegin of <o:deferredScript name=\"primefaces.js\"/> and DeferredPrimeFaces.apply() in onsuccess of the\nlast <o:deferredScript library=\"primefaces\"/>.

\n\n

Having a quick test will reveal the performances obtained via deferring PrimeFaces specific JavaScript resources. Also try to compare the numbers that speak for themselves.

\n\n

Without deferring:

\n\n\n

\n\n\n

With deferring:

\n\n\n

\n\n\n

This is helpful for mobile devices that render HTML relatively slow and touch events that are fully blocked until the DOM content is loaded.

\n\n

Read further here.

\n\n

Using `CombinedResourceHandler` with `<o:deferredScript/>`\n

\n\n

Earlier in this chapter we talked about CombinedResourceHandler, so there is no need to introduce it again. The topic of this section is focused on using CombinedResourceHandler with <o:deferredScript/>. The CombinedResourceHandler will transparently recognize and combine the deferred script resources into a single resource as well. So once you set up the CombinedResourceHandler in your faces-config.xml the OmniFaces will do the rest. For example, let’s consider our deferred scripts from the previous section:

\n\n

<h:head>\n <h:outputScript library=\"app\" name=\"scripts/primefaces.deferred.js\" \n                 target=\"head\" />                \n <o:deferredScript library=\"primefaces\" name=\"primefaces.js\" \n                   onbegin=\"DeferredPrimeFaces.begin()\"/>               \n <o:deferredScript library=\"primefaces\" name=\"jquery/jquery-plugins.js\" \n                   onsuccess=\"DeferredPrimeFaces.apply()\" />              \n</h:head>  \n

\n\n\n\n

Now, the effect of the CombinedResourceHandler can be seen in the figure below (you can compare this figure with the above one):

\n\n\n

\n\n\n

The complete application is named, OmniFacesCombinedDeferredScript.

\n\n\n\n

<!-- three deferred scripts will be combined in a single resource -->\n<o:deferredScript group=\"foo\" ... />\n<o:deferredScript group=\"foo\" ... />\n<o:deferredScript group=\"foo\" ... />\n...\n<!-- two deferred scripts will be combined in another single resource -->\n<o:deferredScript group=\"buzz\" ... />\n<o:deferredScript group=\"buzz\" ... />\n

\n\n\n\n\n\n

Testimonial of BalusC about combining deferred scripts on StackOverflow:\nAs a live example, check the bottom of </body> of the ZEEF site. All essential PrimeFaces-related scripts and some site-specific scripts are combined in the first deferred script and all non-essential social media related scripts are combined in the second deferred script. As to performance improvement of ZEEF, on a test JBoss EAP server on modern hardware, the time to DOMContentLoaded went from ~3s to ~1s.

\n\n

Using `CDNResourceHandler` with `<o:deferredScript/>`\n

\n\n

Supposing that you are already familiar with CDNResourceHandler and the following mapping from CDNResourceHandlerDidacticExample application:

\n\n

<context-param>\n <param-name>\n  org.omnifaces.CDN_RESOURCE_HANDLER_URLS\n </param-name>\n <param-value>\n  jquery:jquery.min.js=https://ajax.googleapis.com/ajax/libs/\n  jquery/1.11.3/jquery.min.js,\n  jquery:js/jquery-ui.min.js=https://ajax.googleapis.com/ajax/libs/\n  jqueryui/1.11.4/jquery-ui.min.js,\n  jquery:css/jquery-ui.css=https://ajax.googleapis.com/ajax/libs/\n  jqueryui/1.11.4/themes/smoothness/jquery-ui.css\n </param-value>\n</context-param>\n

\n\n\n\n

Now, we can combine CDNResourceHandler with <o:deferredScript/> in order to defer jquery-ui.min.js like this (notice that the jquery.min.js is not deferred):

\n\n

<h:outputStylesheet library=\"jquery\" name=\"css/jquery-ui.css\"/>\n<h:outputScript library=\"jquery\" name=\"jquery.min.js\" />\n<o:deferredScript library=\"jquery\" name=\"js/jquery-ui.min.js\" />\n

\n\n\n\n\n

\n\n\n

So, you can use the CDNResourceHandler to defer resources loaded from CDN repositories. The complete application is named, CDNResourceHandlerAndDeferredScript.

\n\n

Reference relative URLs to images in CSS files without `#{resource}`\n

\n\n

The main goal of the OmniFaces UnmappedResourceHandler is to allow developers to reference relative URLs to images in CSS files without using the #{resource}. Letʹs assume that we want to apply some global CSS to a PrimeFaces page (e.g. smaller font/components and a background image). This CSS can look like below:

\n\n\n

\n\n\n

.ui-widget {\n  font-family: Rockwell, 'Courier Bold', Courier, \n   Georgia, Times, 'Times New Roman', serif;\n  font-size: 12px;\n  font-style: normal;\n  font-variant: normal;\n  font-weight: 400;\n  line-height: 20px;\n  background: url(\"#{resource['css/images/qatar.jpg']}\");\n} \n

\n\n\n\n

This CSS file is named style.css and is loaded in page via <h:outputStylesheet/>:

\n\n

<h:outputStylesheet name=\"css/style.css\" />\n

\n\n\n\n

As you can see, the qatar.jpg background image is loaded via #{resource}. In certain situations, you may need to load it via relative URL, like this:

\n\n

background: url(\"images/qatar.jpg\");\n

\n\n\n\n

Well, this is not working in native JSF. In order to obtain this functionality you can use the OmniFaces UnmappedResourceHandler. First, the UnmappedResourceHandler must be configured in faces-config.xml, like this:

\n\n

<application>\n <resource-handler>\n  org.omnifaces.resourcehandler.UnmappedResourceHandler\n </resource-handler>\n</application>\n

\n\n\n\n

Second, the FacesServlet needs to have an additional mapping /javax.faces.resource/* in web.xml. For example, assuming that you already have a mapping on *.xhtml:

\n\n

<servlet-mapping>\n <servlet-name>Faces Servlet</servlet-name>\n <url-pattern>*.xhtml</url-pattern>\n <url-pattern>/javax.faces.resource/*</url-pattern>\n</servlet-mapping>\n

\n\n\n\n

The complete application is named, UnmappedResourceHandlerExample.

\n\n\n\n\n\n

Chapter 4: Initializing PrimeFaces components via view parameters

\n\n

View parameters (UIViewParameter) were introduced in JSF 2.0. They appear nested in the metadata section (<f:metadata>) and their main goal is to allow the developer to provide bookmarkable URLs. Although it is not mandatory, they are initialized via request parameters. As you will see in this chapter, view parameters can be used to transform a query string (the part after ? in an URL) into managed bean properties used to initialize PrimeFaces components. A quick code sketch will look like this:

\n\n

// page A.xhtml\n<h:link outcome=\"B.xhtml\"...>\n <f:param name=\"myParamName\" value=\"myParamValue\"/>\n</h:link>\n\n// page B.xhtml\n<f:metadata>\n // myProperty is initialized via myParamValue and it will further initialize\n // PrimeFaces component property\n <f:viewParam name=\" myParamName \" value=\"#{myBean.myProperty}\"/>\n</f:metadata>\n

\n\n\n\n

View parameters are stateful and this raises several issues, of which will be the discussion of this chapter.

\n\n\n\n

Suppressing the invocation of the setter/converter/validator at each postback

\n\n

Again to reiterate, view parameters are stateful and hence they need to be initialized only once. This is a good thing from the perspective of availability. A stateful component is available in the current view over postbacks, and in the case of view parameters, this is true even if they no longer appear in the URL (they may appear only at initial request). But, there are a few drawbacks of this behavior:

\n\n\n\n\n\n\n\n\n\n\n\n

In order to highlight these issues, let’s have the following scenario: we want to initialize the PrimeFaces Mindmap component via a query string of type: ...?nodes=root|node_A|node_B. This should produce the below figure (for simplicity we use a mindmap with a single level):

\n\n\n

\n\n\n

We have multiple approaches for accomplishing this, but obviously, we will choose to use view parameters for transforming the request parameters into mindmap nodes. The root, node_A, and node_B are strings, whereas mindmap relies on MindmapNode class. \nIn order to transform the query string into a MindmapNode instance, we will use a custom converter (NodesConverter) and in order to ensure that we do it right, we will use a custom validator (NodesValidator). But, let’s see some code lines (notice that the request parameter and the view parameter have the same name nodes):

\n\n

<f:metadata>             \n <f:viewParam name=\"nodes\" value=\"#{mindmapViewBean.root}\" required=\"true\"\n              converter=\"nodesConverter\" validator=\"nodesValidator\"/>\n</f:metadata>\n\n<h:body>\n <h:panelGrid columns=\"2\">\n  <p:messages/>\n  <h:form>\n   <p:commandButton value=\"Reset Mindmap\" \n                    action=\"#{mindmapViewBean.resetMindMap()}\" ajax=\"false\"/>\n  </h:form>\n </h:panelGrid>\n <p:mindmap value=\"#{mindmapViewBean.root}\" \n            style=\"width: 450px; height: 400px; border: 1px solid black;\">\n  <p:ajax event=\"select\" listener=\"#{mindmapViewBean.onNodeSelect}\" />\n </p:mindmap>            \n <h:form>\n  <p:commandButton value=\"Unrelated to Mindmap\" ajax=\"false\"/>\n </h:form>\n</h:body>\n

\n\n\n\n

The MindmapViewBean is responsible of storing the mindmap (nodes). Keeping up with simplicity and in order to highlight the issues at hand we implement a few logs:

\n\n

@Named\n@ViewScoped\npublic class MindmapViewBean implements Serializable {\n\n private static final Logger LOG = \n         Logger.getLogger(MindmapViewBean.class.getName());\n\n private MindmapNode root;\n    \t\n public MindmapViewBean() {\n  LOG.info(\"MindmapViewBean#constructor ...\");        \n }              \n\n public MindmapNode getRoot() {\n  return root;\n }\n\n public void setRoot(MindmapNode root) {\n  LOG.info(\"MindmapViewBean#setter ...\");  \n  this.root = root;\n }     \n    \n public String resetMindMap(){\n  LOG.info(\"MindmapViewBean#resetMindMap() ...\");\n  return \"index?faces-redirect=true&includeViewParams=true\";\n }\n    \n public void onNodeSelect(SelectEvent event) {\n  LOG.info(\"MindmapViewBean#onNodeSelect() ...\");    \n }\n}  \n

\n\n\n\n

The root is populated from a custom converter. This is responsible of splitting the root|node_A|node_B string and creating the mindmap (getAsObject()) and viceversa (getAsString()). The code is pretty simple:

\n\n

@FacesConverter(\"nodesConverter\")\npublic class NodesConverter implements Converter {\n\n private static final Logger LOG = \n         Logger.getLogger(NodesConverter.class.getName());\n\n @Override\n public Object getAsObject(FacesContext context, \n               UIComponent component, String value) {\n\n  LOG.info(\"NodesConverter#getAsObject() ...\");\n\n  if ((value != null) && (!value.isEmpty())) {\n\n       String[] nodes = value.split(\"\\\\|\");\n\n       // create mindmap root            \n       MindmapNode root = new \n                   DefaultMindmapNode(nodes[0], nodes[0], \"FFCC00\", false);\n\n       // add children to root\n       if (nodes.length > 1) {\n           for (int i = 1; i < nodes.length; i++) {\n                root.addNode(new DefaultMindmapNode(nodes[i],\n                             nodes[i], \"6e9ebf\", true));\n           }\n       }\n       return root;\n  }\n\n  return null;\n }\n\n @Override\n public String getAsString(FacesContext context, \n               UIComponent component, Object value) {\n\n  LOG.info(\"NodesConverter#getAsString() ...\");\n \t\n  if (value != null) {\n      String queryString = ((DefaultMindmapNode) value).getLabel() + \"|\";\n      List<MindmapNode> nodes = ((DefaultMindmapNode) value).getChildren();\n      for (MindmapNode node : nodes) {\n           queryString = queryString + node.getLabel() + \"|\";\n      }\n      return queryString;\n  }\n  return \"\";\n }\n}\n

\n\n\n\n

Besides the built-in required validator, you might in some cases need a validator. We can add a custom validator that would ensure that our mindmap has children. Furthermore, we will not accept a mindmap that contains only the root. Obviously, you could accomplish this check by using the above converter. But remember that we need to expose all the issues of view parameters, including calling valdiators at each postback. Moreover, the application is “shaped” for revealing what may happen if we don’t correctly understand how view parameters works. So the custom validator looks like this:

\n\n

@FacesValidator(\"nodesValidator\")\npublic class NodesValidator implements Validator {\n\n private static final Logger LOG = \n         Logger.getLogger(NodesValidator.class.getName());\n\n @Override\n public void validate(FacesContext context, UIComponent component, \n                      Object value) throws ValidatorException {\n\n  LOG.info(\"NodesValidator#validate() ...\");\n\n  if (((MindmapNode)value).getChildren().isEmpty()) {\n      throw new ValidatorException(new FacesMessage(FacesMessage.SEVERITY_ERROR, \n        \"You cannot have a mindmap only with a root !\", null));\n  }\n }\n}\n

\n\n\n\n

Assuming we have some hypothetical cases where the URLs are bookmarked:

\n\n

URL without query string (http://localhost:8080/SuppressViewParamInvocations/). In this case, we see the error message caused by the built-in required validator, j_idt1: Validation Error: Value is required.. This is the expected behavior:

\n\n\n

\n\n\n

Now, let’s focus on what happens if we press the Reset Mindmap button. When this button is pressed, we simply call a managed bean method that performs some tasks (not relevant) and redirect to the same view by including the view parameters. At postback, you see the same error message caused by the required built-in validator. This is normal since we never provided a query string. But the thing that may look strange (even if it shouldn’t) is the fact that this is not a redirect (the resetMindMap() method is not called). Since the required view parameter is not provided, each postback will “stop” in the Process Validation phase, and “jump” to the Render Response phase. The fact that the validators/converters are invoked at each postback (even if there is no query string) is also suggested by the logs:

\n\n

// initial request - validation fails via 'required' built-in validator\n[beans.MindmapViewBean] (default task-93) MindmapViewBean#constructor ...\n[beans.NodesConverter] (default task-93) NodesConverter#getAsString() ...\n\n// postback 1 - validation fails via 'required' built-in validator\n[beans.NodesConverter] (default task-112) NodesConverter#getAsObject() ...\n[beans.NodesConverter] (default task-112) NodesConverter#getAsString() ...\n

\n\n\n\n

So, instead of being redirected and seeing the required built-in validator error message again, we just see this message without redirection. The resetMindMap() method is not called. This is happening for the Unrelated to Mindmap button also (dummy button to fire POST via forward mechanism). Let’s examine the second use case.

\n\n

URL with wrong query string (http://.../SuppressViewParamInvocations/?nodes=root). In this case, we see the error message caused by the custom validator, You cannot have a mindmap only with a root !. This is the expected behavior:

\n\n\n

\n\n\n

Since we provide a value for the view parameter, the built-in required validator is successfully passed at initial request. But, the validation fails in our custom validator, which doesn’t accept a mindmap that contains only the root. This means that the flow “jumps” in Render Response phase, and the view parameter is not set in state. At postback (fired via Reset Mindmap button) we will receive the built-in required validator error message, j_idt1: Validation Error: Value is required.. This in normal since at initial request the view parameter was not set in state, and at postback the query string is not available, so there is no view parameter. The fact that the validators/converters are invoked at each postback (even if there is no query string) is suggested by the logs also:

\n\n

// initial request - no setter is called because validation fails\n// in the custom validator\n[beans.NodesConverter] (default task-54) NodesConverter#getAsObject() ...\n[beans.NodesValidator] (default task-54) NodesValidator#validate() ...\n[beans.MindmapViewBean] (default task-54) MindmapViewBean#constructor ...\n[beans.NodesConverter] (default task-54) NodesConverter#getAsString() ...\n\n// postback 1 - validation fails via 'required' built-in validator\n[beans.NodesConverter] (default task-76) NodesConverter#getAsObject() ...\n[beans.NodesConverter] (default task-76) NodesConverter#getAsString() ...\n

\n\n\n\n

Again instead of being redirected, we keep seeing the required built-in validator error message without redirection. The resetMindMap() method is not called. This is happening to the Unrelated to Mindmap button also (dummy button to fire POST via forward mechanism). Let’s examine the third use case.

\n\n

URL with valid query string (http://.../?nodes=root|node_A|node_B). This query string will successfully pass through conversion and validation and the mindmap will be displayed on to screen. This is the expected behavior:

\n\n\n

\n\n\n

If we press the Reset Mindmap button, then everything will act as expected. The mindmap will be reset to the initial status via the query string attached due to the effect of the includeViewParams=true (see resetMindMap() method). But, if we click on one of the nodes (which fires an AJAX select event) and continue by pressing the Reset Mindmap button, then we will see the error message from the built-in required validator, j_idt1: Validation Error: Value is required.. This is an unexpected behavior. Click again on Reset Mindmap button and everything works fine.

\n\n

Moreover, let’s press the Unrelated Mindmap button and check the logs. Even if this is a postback, there is no query string and this action is not even related to mindmap, the converters, validators and setters are still invoked at each request:

\n\n

// initial request\n[beans.NodesConverter] (default task-61) NodesConverter#getAsObject() ...\n[beans.NodesValidator] (default task-61) NodesValidator#validate() ...\n[beans.MindmapViewBean] (default task-61) MindmapViewBean#constructor ...\n[beans.MindmapViewBean] (default task-61) MindmapViewBean#setter ...\n[beans.NodesConverter] (default task-61) NodesConverter#getAsString() ...\n\n// postback 1 - press the 'Unrelated Mindmap' button\n[beans.NodesConverter] (default task-119) NodesConverter#getAsObject() ...\n[beans.NodesValidator] (default task-119) NodesValidator#validate() ...\n[beans.MindmapViewBean] (default task-119) MindmapViewBean#setter ...\n[beans.NodesConverter] (default task-119) NodesConverter#getAsString() ...  \n

\n\n\n\n

So, in the above three cases we have identified several issues that disqualify view parameters for this job. But, if we add the OmniFaces namespace (xmlns:o=\"http://omnifaces.org/ui\") in the XHTML page and replace the stateful <f:viewParam/> with the stateless <o:viewParam/> then all the issues will disappear like magic:

\n\n

<f:metadata>             \n <o:viewParam name=\"nodes\" value=\"#{mindmapViewBean.root}\" required=\"true\" \n              converter=\"nodesConverter\" validator=\"nodesValidator\"/>\n</f:metadata>\n

\n\n\n\n

Now, let’s see what happens in our three use cases:

\n\n

URL without the query string (http://.../SuppressViewParamInvocations/). In this case, we see the error message caused by the built-in required validator nodes: Validation Error: Value is required.. This is the expected behavior. This time, when you press the Reset Mindmap button, the logs reveal that the redirect take place; the constructor of MindmapViewBean is invoked after each press and the built-in required validator fails each time at initial request. The resetMindMap() method is called as expected:

\n\n

// initial request\n[beans.NodesConverter] (default task-77) NodesConverter#getAsObject() ...\n[beans.MindmapViewBean] (default task-77) MindmapViewBean#constructor ...\n\n// postback 1 - press the 'Reset Mindmap' button\n[beans.MindmapViewBean] (default task-97) MindmapViewBean#resetMindMap() ...\n[beans.NodesConverter] (default task-95) NodesConverter#getAsObject() ...\n[beans.MindmapViewBean] (default task-95) MindmapViewBean#constructor ...\n

\n\n\n\n

URL with the wrong query string (http://.../SuppressViewParamInvocations/?nodes=root). In this case, at the initial request, we see the error message caused by our custom validator, You cannot only have a mindmap with a root !. This is the expected behavior. Since the view parameter doesn’t pass the validation process it will not be set in state. At postbacks when you press the Reset Mindmap button, you will see the effect of the built-in required validator. But, the resetMindMap() method is called as expected and the redirection takes place:

\n\n

// intial request\n[beans.NodesConverter] (default task-38) NodesConverter#getAsObject() ...\n[beans.NodesValidator] (default task-38) NodesValidator#validate() ...\n[beans.MindmapViewBean] (default task-38) MindmapViewBean#constructor ...\n\n// postback 1 - press the 'Reset Mindmap' button\n[beans.MindmapViewBean] (default task-3) MindmapViewBean#resetMindMap() ...\n[beans.NodesConverter] (default task-19) NodesConverter#getAsObject() ...\n[beans.MindmapViewBean] (default task-19) MindmapViewBean#constructor ...\n

\n\n\n\n

This is confirmed by the Unrelated Mindmap button also. This button fires a POST requests via forward mechanism, but the required validator is not invoked!

\n\n

Suppressing `required=true` on postback

\n\n

The above behavior shows that the OmniFaces <o:viewParam/> suppresses (skips) on postbacks the effect of\nrequired=true, but it works on the initial request (on GET) as expected. This is normal since the <o:viewParam/>\nrepresents stateless view parameters. This allows view parameters to not exist on postbacks. Obviously, the weight of\nkeeping track of a view parameter value beyond a postback now has to be carried by the developer. This can however be done\neasily by binding this value to a view scoped bean, which will automatically remember all its values between postbacks. If\nyou are using a scope with a shorter lifespan (e.g. request scope) then you should expect to have some null values at\npostbacks, since the data “pushed” initially through view parameters into the data model will be lost from the data model at\npostbacks. This happens because at postback, the view parameter does “push” anything into the data model.

\n\n

URL with valid query string (http://.../?nodes=root|node_A|node_B). This query string will successfully pass through conversion and validation and the mindmap will be displayed on screen. This is the expected behavior.

\n\n

This time pressing the Reset Mindmap button works as expected. Remember previously, the issue caused by clicking a node (firing an AJAX select event) and afterwards clicking the Reset Mindmap button ? Well, this issue is now solved. The POSTs via forward mechanism (e.g. pressing Unrelated Minmap button) will skip the invocation of converters/validators and setters attached to view parameters. This is a big win! Stateless mode avoids unnecessary conversions, validations and models updating on postbacks.

\n\n

Supply a label for messages

\n\n

Moreover, pay attention to the error messages label! OmniFaces provides a default value for the label attribute. When the label attribute is omitted, the name attribute will be used as the label. For example, when the label attribute is not set on <o:viewParam/> and a validation error occurs when using the required built-in validator, the following message will be generated:

\n\n

nodes: Validation Error: Value is required.\n

\n\n\n\n\n\n

Supply a default value

\n\n

Note that, starting with OmniFaces 2.2, the ViewParam component also supports the optional default attribute. This attribute allows us to indicate a default value, and OmniFaces will in turn rely on this value in the case where the actual request parameter is null or empty. For example, you may want to initialize the mind map, as below:

\n\n

<f:metadata>             \n <o:viewParam name=\"nodes\" value=\"#{mindmapViewBean.root}\" default=\"root|foo\" \n              required=\"true\" converter=\"nodesConverter\" \n              validator=\"nodesValidator\"/>                \n</f:metadata>\n

\n\n\n\n

Now, if you don’t supply a query string (e.g. http://localhost:8080/SuppressViewParamInvocations) the mindmap will look like below (this way you don’t need the required built-in validator):

\n\n\n

\n\n\n

Suppressing invocation of the converter regardless the `null` values

\n\n

OmniFaces doesn’t allow null view parameters to become empty strings nor does it allow null parameters from participating in query string. This is done automatically by the OmniFaces implementation, so you don’t have to configure anything. OmniFaces analyzes each\nview parameter value and takes care of preventing any such occurrence and it does this by not calling the attached converters. By default, when you are using the includeViewParams, the null view parameters with attached converters are still null when the query string is prepared. For example, if we use <f:viewParam/>, remove validators from our view parameter, omit the nodes request parameter and click on the Reset Mindmap button, you will see this:

\n\n

http://localhost:8080/SuppressViewParamInvocations/faces/index.xhtml?nodes=

\n\n

Notice that nodes was attached with an empty string value. If we switch to <o:viewParam/> then we will obtain the expected result:

\n\n

http://localhost:8080/SuppressViewParamInvocations/faces/index.xhtml

\n\n

Support bean validation and triggering validate events on `null` value

\n\n

The standard UIViewParameter implementation uses in JSF 2.0-2.2 an internal “is required” check when the submitted value is null, hereby completely bypassing the standard UIInput validation, including any bean validation annotations and even the PreValidateEvent and PostValidateEvent events. For example, in Mojarra, the UIViewParameter implementation is adjusted to deal with null values in presence of the built-in required validator. Well, UIInput assumes that a null value means don’t check, but UIViewParameter doesn’t accept null values and the built-in required validator:

\n\n

// Mojarra 2.2.9, UIViewParameter source code\n...\nif (getSubmittedValue() == null && myIsRequired()) {\n     String requiredMessageStr = getRequiredMessage();\n     FacesMessage message;\n     if (null != requiredMessageStr) {\n         message = new FacesMessage(FacesMessage.SEVERITY_ERROR,\n                                 requiredMessageStr,\n                                 requiredMessageStr);\n     } else {\n        message = MessageFactory.getMessage(context, REQUIRED_MESSAGE_ID,\n                          MessageFactory.getLabel(context, this));\n     }\n     context.addMessage(getClientId(context), message);\n     setValid(false);\n     context.validationFailed();\n     context.renderResponse();\n } else {\n     super.processValidators(context);\n }\n...\n

\n\n\n\n

The myIsRequired() method is a private method that checks the well-known isRequired() and another private method, named isRequiredViaNestedRequiredValidator() - its name is self explanatory:

\n\n

// Mojarra 2.2.9, UIViewParameter source code\nprivate boolean myIsRequired() {\n return super.isRequired() || isRequiredViaNestedRequiredValidator();\n}\n

\n\n\n\n

The workaround was added in OmniFaces 2.0. In JSF 2.3, this has been fixed and effectuated when javax.faces.INTERPRET_EMPTY_STRING_SUBMITTED_VALUES_AS_NULL context param is set to true.

\n\n

The complete application is named, SuppressViewParamInvocations.

\n\n

Well, I hope you enjoyed this chapter and learned a bunch of interesting stuff. Not only are view parameters used to initialize PrimeFaces components but coupled with, OmniFaces’ stateless view parameters, you can create bookmarkable URLs that provide initial state of components.

\n\n

Chapter 5: Referencing, rendering and moving PrimeFaces components

\n\n

In the first part of this chapter, we will discuss referencing components. Programmatically speaking, JSF comes with a powerful API that allows us to access and reference the component tree. In addition, OmniFaces provides a comprehensive API for dealing with the component tree (e.g. check the Components utilities). Besides the OmniFaces Showcase, you also may try the examples accessible via the following ZEEF page. On the other hand, as a JSF page author, you may need to reference components in page. For these tasks, we don’t have many approaches. Basically we can use the binding attribute and for current component, #{component}. Furthermore, we will introduce the OmniFaces approach for referencing components in the page.

\n\n

In the second part of this chapter, we will discuss about rendering components. By default, JSF renders all components (transforms the component tree in HTML markup). We can control this process by switching the rendered flag attribute from true to false. All JSF components support this attribute and by default is set to true. When is false, the corresponding component (and its children) will not be rendered, which means that it will not appear in the client side DOM. In this part, you will see another approach for controlling the rendering process.

\n\n

In the last part of this chapter, we will discuss about moving components, facets and behaviors at runtime to a target component in various ways. This allows for simple programmatic composition of components using a declarative page author centric approach.

\n\n

Access a component by using a reference to it

\n\n

As a JSF page author, you may need to access a component by using a reference to it. Essentially, this means you want to refer a component from another component as shown in the figure below:

\n\n\n

\n\n\n

In code lines, we have also added the surnameId:

\n\n

<h:form>\n <p:selectBooleanCheckbox id=\"nameId\" \n                          onchange=\"submit()\" label=\"name\"/> Name\n <p:selectBooleanCheckbox id=\"surnameId\" \n                          onchange=\"submit()\" label=\"surname\"/> Surname\n</h:form>\n\n<h:form>\n <p:inputText rendered=\"...\" placeholder=\"...\"/>\n <p:inputText rendered=\"...\" placeholder=\"...\"/>\n</h:form>\n

\n\n\n\n

As you can see in the above figure, the most important part which is the “reference” itself (\"...\") is missing. Well, there are several approaches to accomplish this task (e.g. using the binding attribute, write a lambda function based on findComponent() method, use #{component} for referencing current component, etc), but none of these methods is dedicated to this goal.

\n\n

Starting with version 2.0, OmniFaces comes with a utility component named ResolveComponent. The ResolveComponent is exposed to JSF page authors as <o:resolveComponent/>, and is capable of creating a reference to a component indicated by ID. Moreover, the reference is stored by default in the “facelet scope” but it can be alternatively stored in the request scope (this option can be set via the optional attribute; scope). The name attribute is required and it represents the name under which the referenced component will be made available to EL. The for attribute is also required and it represents the ID of the referenced component. So, we can re-write the above code as shown below:

\n\n

Storing reference in the “facelet scope”:

\n\n

 <h:form>\n  <p:selectBooleanCheckbox id=\"nameId\" \n                           onchange=\"submit()\" label=\"name\"/> Name\n  <p:selectBooleanCheckbox id=\"surnameId\" \n                           onchange=\"submit()\" label=\"surname\"/> Surname\n </h:form>\n\n <o:resolveComponent name=\"nameRef\" for=\"nameId\" />\n <o:resolveComponent name=\"surnameRef\" for=\"surnameId\" />\n\n <h:form>\n  <p:inputText rendered=\"#{nameRef.value}\" placeholder=\"#{nameRef.label}\"/>\n  <p:inputText rendered=\"#{surnameRef.value}\" placeholder=\"#{surnameRef.label}\"/>\n </h:form>\n

\n\n\n\n

Storing reference in the request scope (use the optional attribute named scope):

\n\n

<h:form>\n <p:selectBooleanCheckbox id=\"nameId\" \n                          onchange=\"submit()\" label=\"name\"/> Name\n <p:selectBooleanCheckbox id=\"surnameId\" \n                          onchange=\"submit()\" label=\"surname\"/> Surname\n</h:form>\n\t\n<o:resolveComponent scope=\"request\" name=\"nameRef\" for=\"nameId\" />\n<o:resolveComponent scope=\"request\" name=\"surnameRef\" for=\"surnameId\" />\n\t\n<h:form>\n <p:inputText rendered=\"#{nameRef.value}\" placeholder=\"#{nameRef.label}\"/>\n <p:inputText rendered=\"#{surnameRef.value}\" placeholder=\"#{surnameRef.label}\"/>\n</h:form>\n

\n\n\n\n

Whenever you need to “link” two (or more) components by a reference, you can use the OmniFaces ResolveComponent. The complete application is named, ResolveComponent.

\n\n

Controlling the rendering of components

\n\n

Letʹs suppose that we want to pick just a few components (even just one component) to be rendered, while the rest of them should not be rendered. Since they are all rendered by default, we need to “populate” the page with several rendered=\"false\" (or <c:if>). This becomes pretty annoying, if the page has many components. In such a case, it would be much simpler to say which one(s) should be rendered, instead of saying which ones shouldnʹt be rendered. But how about rendering only a row in a table? Or in some specific cases, render only the parent component and omit any children? Or load a component in another place on the page? What do we do in order to create simple mashups from various JSF based views, or scripts that need to obtain markup for specific components on an initial (non‐faces) request? Well, these kind of issues are solved by utilizing OmniFaces via the ComponentIdParam component.

\n\n

Let’s have an example. First, we write a simple page as shown below:

\n\n

My favorite player:<br/>\n<p:graphicImage id=\"myPlayerId\" library=\"default\" \n                name=\"images/#{playerBean.favorite}.png\"/>\n<h:form id=\"myFormId\">            \n <p:panelGrid id=\"panelId\"> \n  <h:panelGroup id=\"div1Id\" layout=\"block\">\n   Player Name: \n   <h:outputText id=\"myPlayerNameId\" \n    value=\"#{playerBean.players[playerBean.favorite-1].player}\" />\n  </h:panelGroup>\n  <h:panelGroup id=\"div2Id\" layout=\"block\">\n   Favorite Player Rank: \n   <p:inputText id=\"myPlayerRankId\" value=\"#{playerBean.favorite}\"/>\n   <p:commandButton id=\"myButtonId\" value=\"See\" ajax=\"false\"/>\n  </h:panelGroup>                                                              \n </p:panelGrid>\n</h:form>\n<hr/>\nTop 5 players:\n<h:form id=\"tableFormId\">\n <p:dataTable id=\"playersTableId\" value=\"#{playerBean.players}\" \n              var=\"t\" style=\"width:650px;\">\n  <p:column>\n   <f:facet name=\"header\">Ranking</f:facet>\n   <h:outputText id=\"rankingId\" value=\"#{t.ranking}\"/>\n  </p:column>\n  <p:column>\n   <f:facet name=\"header\">Name</f:facet>\n   <h:panelGroup id=\"playerDivId\" layout=\"block\" \n                 style=\"height:20px; width:200px;background-color:lightgray;\">\n    <h:outputText id=\"playerId\" value=\"#{t.player}\"/>\n   </h:panelGroup>\n  </p:column>\n  <p:column>\n   <f:facet name=\"header\">Age</f:facet>\n   <h:outputText id=\"ageId\" value=\"#{t.age}\"/>\n  </p:column>\n  <p:column>\n   <f:facet name=\"header\">Birthplace</f:facet>\n   <h:outputText id=\"birthplaceId\" value=\"#{t.birthplace}\"/>\n  </p:column>                \n </p:dataTable>\n</h:form>\n

\n\n\n\n

This code produces the HTML markup from the figure below (we have decorated the image with components IDs and client IDs):

\n\n\n

\n\n\n

Now, imagine that you want to render a subset of these components by indicating the corresponding IDs or client IDs. For components like the table or the form, we can use the rendered=\"false\", but what about rendering only a row in the table? As we have said earlier, OmniFaces comes with a dedicated component for such tasks. The ComponentIdParam is accessible to page authors via the <o:componentIdParam/> tag. There are several attributes for shaping the behavior of this component. First, we have two ValueExpressions (evaluated to Strings), componentIdName and clientIdName:

\n\n

The componentIdName value indicates the name of the request parameters (<f:param/>), while the values of these parameters represent the component IDs of the components that should be rendered. On initial request, the components whose component IDs are not present in the values of these request parameters will not be rendered.
The clientIdName is the same as componentIdName, only that we are talking about client IDs instead of component IDs. As you will see in the next examples, this approach allows us to have more control over the rendered components (e.g. render only a row of a table).
A third attribute, named renderChildren, can accompany the above two. This is a flag attribute (default true) that indicates whether children of the components identified by clientIdName or componentIdName are rendered in addition to the component itself.

\n\n

Well, let’s define two <o:componentIdParam/>:

\n\n

<f:metadata>\n <o:componentIdParam componentIdName=\"component\" clientIdName=\"client\" />\n <o:componentIdParam componentIdName=\"component_wc\" \n                     clientIdName=\"client_wc\" renderChildren=\"false\" />\n</f:metadata>\n

\n\n\n\n

Further, letʹs see some examples of using the <o:componentIdParam/> with renderChildren and component IDs:

\n\n

Rendering table with children example:

\n\n\n

\n\n\n

Rendering table without children example:

\n\n\n

\n\n\n

Render only the image (myPlayerId):

\n\n

<p:link target=\"_blank\">                    \n <f:param name=\"component\" value=\"myPlayerId\"/>        \n Click Me!  \n</p:link>\n

\n\n\n\n

Render only the first form (myFormId):

\n\n

<p:link target=\"_blank\">\n <f:param name=\"component\" value=\"myFormId\"/>\n Click Me!        \n</p:link>\n

\n\n\n\n

Render only the player name and the second form (myPlayerNameId, tableFormId):

\n\n

<p:link target=\"_blank\">\n <f:param name=\"component\" value=\"myPlayerNameId\"/>        \n <f:param name=\"component\" value=\"tableFormId\"/>\n Click Me!                                \n</p:link>\n

\n\n\n\n

Render only the player rank input and button (myPlayerRankId, myButtonId):

\n\n

<p:link target=\"_blank\">\n <f:param name=\"component\" value=\"myPlayerRankId\"/>        \n <f:param name=\"component\" value=\"myButtonId\"/>       \n <f:param name=\"client\" value=\"tableFormId:playersTableId:0:playerDivId\"/>     \n Click Me!                      \n</p:link>\n

\n\n\n\n

Render only the players table (playersTableId) ‐ sketched in the figure above:

\n\n

<p:link target=\"_blank\">\n <f:param name=\"component\" value=\"playersTableId\"/>                            \n Click Me!                      \n</p:link>\n

\n\n\n\n

Render only the players table without children (playersTableId) ‐ sketched in the figure above:

\n\n

<p:link target=\"_blank\">\n <f:param name=\"component_wc\" value=\"playersTableId\"/>\n Click Me!                      \n</p:link>\n

\n\n\n\n

Further, letʹs see three examples using the clientIdName (first two examples are sketched in the figure below):

\n\n\n

\n\n\n

Render the divs that contains the players names only for the first two players in the table. The client IDs of the players divs are:\ntableFormId:playersTableId:0:playerDivId and tableFormId:playersTableId:1:playerDivId:

\n\n

<p:link target=\"_blank\">\n <f:param name=\"client\" value=\"tableFormId:playersTableId:0:playerDivId\"/>\n <f:param name=\"client\" value=\"tableFormId:playersTableId:1:playerDivId\"/>\n Click Me!                        \n</p:link>\n

\n\n\n\n

Render without children the divs that contain the players names for the first two players in the table. The client IDs of the players divs are: tableFormId:playersTableId:0:playerDivId and tableFormId:playersTableId:1:playerDivId:

\n\n

<p:link target=\"_blank\">\n <f:param name=\"client_wc\" value=\"tableFormId:playersTableId:0:playerDivId\"/>\n <f:param name=\"client_wc\" value=\"tableFormId:playersTableId:1:playerDivId\"/>\n Click Me!                   \n</p:link>\n

\n\n\n\n

Render the first player (tableFormId:playersTableId:0:rankingId, ...:playerId, ...:ageId, ...:birthplaceId):

\n\n

<p:link target=\"_blank\">\n <f:param name=\"client_wc\" value=\"tableFormId:playersTableId:0:rankingId\"/>\n <f:param name=\"client_wc\" value=\"tableFormId:playersTableId:0:playerId\"/>\n <f:param name=\"client_wc\" value=\"tableFormId:playersTableId:0:ageId\"/>\n <f:param name=\"client_wc\" value=\"tableFormId:playersTableId:0:birthplaceId\"/>\n Click Me!                       \n</p:link>\n

\n\n\n\n

The complete application is named, PFAndComponentIdParamFormAndTable.

\n\n

Here is another example. First, we render a PrimeFaces Carousel:

\n\n

<p:carousel id=\"carouselId\" value=\"#{playerBean.players}\" \n            headerText=\"ATP\" var=\"t\" \n            itemStyle=\"text-align:center\" responsive=\"true\">\n <p:panelGrid id=\"panelgridId\" columns=\"2\" style=\"width:100%;margin:10px 0px\" \n              columnClasses=\"label,value\" layout=\"grid\" \n              styleClass=\"ui-panelgrid-blank\">\n  <f:facet name=\"header\">\n   <p:graphicImage id=\"playerImageId\" library=\"default\" \n                   name=\"images/#{t.ranking}.png\"\n                   width=\"50\" height=\"70\"/> \n  </f:facet>\n\n  <h:outputText id=\"rankingId\" value=\"Ranking:\" />\n  <h:outputText id=\"rankingValueId\" value=\"#{t.ranking}\" />\n\n  <h:outputText id=\"nameId\" value=\"Name:\" />\n  <h:outputText id=\"nameValueId\" value=\"#{t.player}\" />\n\n  <h:outputText id=\"ageId\" value=\"Age:\" />\n  <h:outputText id=\"ageValueId\" value=\"#{t.age}\"/>\n\n  <h:outputText id=\"birthplaceId\" value=\"Birthplace:\" />\n  <h:outputText id=\"birthplaceValueId\" value=\"$#{t.birthplace}\" />\n </p:panelGrid>           \n</p:carousel>\n

\n\n\n\n\n

\n\n\n

Furthermore, we define two <o:componentIdParam/>:

\n\n

<f:metadata>\n <o:componentIdParam componentIdName=\"component\" clientIdName=\"client\" />\n <o:componentIdParam componentIdName=\"component_wc\" \n                     clientIdName=\"client_wc\" renderChildren=\"false\" />\n</f:metadata>\n

\n\n\n\n

Now, let’s have some use cases.

\n\n

Render only the first player’s image (carouselId:0:playerImageId):

\n\n

<p:link>                    \n <f:param name=\"client\" value=\"carouselId:0:playerImageId\"/>        \n Click Me!\n</p:link>\n

\n\n\n\n

Render only the first player’s rank and name (carouselId:0:rankingId, carouselId:0:rankingValueId):

\n\n

<p:link target=\"_blank\">                    \n <f:param name=\"client\" value=\"carouselId:0:rankingId\"/>   \n <f:param name=\"client\" value=\"carouselId:0:rankingValueId\"/>        \n Click Me! \n</p:link>\n

\n\n\n\n

Render the first and the last players (carouselId:0:panelgridId, carouselId:4:panelgridId):

\n\n

<p:link target=\"_blank\">                    \n <f:param name=\"client\" value=\"carouselId:0:panelgridId\"/>        \n <f:param name=\"client\" value=\"carouselId:4:panelgridId\"/>        \n Click Me!\n</p:link>\n

\n\n\n\n

The complete application is named, PFAndComponentIdParamMore.

\n\n\n\n\n\n

By default, JSF/PrimeFaces doesnʹt provide any built‐in artifact dedicated to moving components in the component tree from one place to another. Programmatically speaking, we can combine several methods to achieve such tasks at runtime (e.g. in the proper places, we can use findComponent() with getChildren() and java.util.List methods for manipulating the list items). But, this is not always “comfortable” from a page author’s\nperspective, and there is no component or attribute that can be used declaratively to influence the runtime in such manner. Nevertheless, moving\ncomponents through component tree is not a day by day task; but as you will see, OmniFaces facilitates this by allowing a JSF page author to shape the component tree in a declarative manner. Of course, there are some limitations; but we can actually instruct JSF to move a component before, after, as first/last child of another component.

\n\n

The OmniFaces component, MoveComponent is accessible to page authors via the <o:moveComponent/> tag. We can use this component to move components, facets and behaviors at runtime to a target component in various ways.

\n\n

The <o:moveComponent/> has two important attributes. First, we have the required for attribute, which allows us to indicate the ID of the target component for which the component moving will be done. Second, we have the optional destination attribute, which indicates the destination relative to the target component where the source component(s) are moved to. The values of this attribute can be:

\n\n

\nBEFORE ‐ Component will be moved right before target component (as a sibling with an index thatʹs 1 position lower).
\nADD_FIRST ‐ Component is added as the first child of the target component, any other children will have their index increased by 1.
\nADD_LAST ‐ Component is added as the last child of the target component, any other children will stay in their original location.
\nFACET ‐ Component will be moved to the facet section of the target component under the name denoted by “facet”.
\nBEHAVIOR ‐ A Behavior will be moved to the behavior section of the target component.
\nAFTER ‐ Component is moved right after the target component, i.e. as a sibling with an index thatʹs 1 position higher.

\n\n

Beside the for and destination, <o:moveComponent/> supports three more attributes as follows:

\n\n

When the destination is set to FACET, the name of the facet in the target component to which the components should be moved, must be indicated via the facet attribute.
When the destination is set to BEHAVIOR, the comma separated list of events that the target component is “supposed” to support can be indicated via the behaviorEvents attribute.
When the destination is set to BEHAVIOR, the name of the default event that the target component is “supposed” to have can be indicated via the behaviorDefaultEvent attribute.

\n\n

In order to have an example, let’s focus on PrimeFaces DataTable component. The PrimeFaces data table component is very hard to modify when it comes to the built-in filter/search capabilities. Required components with fixed IDs (globalFilter) and the fact that filtering is applied in the render stage are among the things that make this surprisingly difficult in practice. With the help of the <o:moveComponent/> the required modification actions can be packed up in a Facelets tag file for reuse.

\n\n

First, let’s have a simple data table with searching and filtering capabilities:

\n\n

<h:form id=\"myForm\">\n <p:dataTable id=\"myTable\" value=\"#{playerBean.players}\" var=\"player\" \n              filteredValue=\"#{playerBean.filteredPlayers}\" \n              widgetVar=\"myTableVar\" style=\"width: 650px;\">\n  <p:column filterBy=\"#{player.ranking}\" filterMatchMode=\"contains\">  \n   #{player.ranking}\n  </p:column>\n\n  <p:column filterBy=\"#{player.player}\" filterMatchMode=\"contains\">  \n   #{player.player}\n  </p:column>\n\n  <p:column filterBy=\"#{player.age}\" filterMatchMode=\"contains\"> \n   #{player.age}\n  </p:column>\n               \n  <p:column filterBy=\"#{player.birthplace}\" filterMatchMode=\"contains\"> \n   #{player.birthplace}\n  </p:column>\n </p:dataTable>\n</h:form> \n

\n\n\n\n

Further we have the custom tag (<demo:globalSearch/>) that represents a global search:

\n\n

<demo:globalSearch forx=\"myTable\"/>\n

\n\n\n\n

The following image shows an example:

\n\n

No search:

\n\n\n

\n\n\n

Search, b:

\n\n\n

\n\n\n

The global search (globalSearch.xhtml) is obtained from three instances of <o:moveComponent/>, like below:

\n\n

1.First, the data table is made available in the globalSearch.xhtml page via the <o:resolveComponent/>. Now, the data table is available via tableComponent variable:

\n\n

<o:resolveComponent name=\"tableComponent\" for=\"#{forx}\" />\n

\n\n\n\n

2.Furthermore, the search input is created via <p:inputText/>:

\n\n

<p:inputText id=\"search\" \n             onkeyup=\"$(document.getElementById('#{tableComponent.clientId}:\n                      globalFilter')).val(this.value);\n                      PF('#{tableComponent.widgetVar}').filter();\" \n             placeholder=\"Search\" />\n<h:outputText value=\"&amp;nbsp;\" escape=\"false\"/> \n<h:panelGroup id=\"resultCountPlaceholder\" binding=\"#{resultCountPlaceholder}\" />\n

\n\n\n\n

3.Moving a script to reside after the table

\n\n

The first MoveComponent instance has a JavaScript surrounded by a named panel group as its children. These components are moved in the tree to sit right after the table component. This script takes the number of elements that appear in the so-called filtered collection and updates another panel group with that number. The script needs to be placed AFTER the table component, because the number we need is only available when the table is actually rendered, so it’s only available to components (and EL expressions within those) that are rendered after the table is rendered. This somewhat defeats the purpose of phases in JSF (an important reason for which is to prevent just this location’s dependency), but with the <o:moveComponent/> we can hide this somewhat nasty detail for the tag user:

\n\n

<o:moveComponent for=\"#{forx}\" destination=\"AFTER\">\n <h:panelGroup id=\"resultCount\" binding=\"#{resultCount}\" >\n <!-- Mojarra has issues with dynamically changing UIInstructions -->\n  <h:outputText value=\"&lt;script type='text/javascript'&gt;\" escape=\"false\" />\n  <h:panelGroup rendered=\"#{not empty tableComponent.filteredValue}\">\n   <h:outputText value=\"document.getElementById('#{resultCountPlaceholder.\n   clientId}').innerHTML = 'Showing #{tableComponent.filteredValue.size()}\n   of #{of:evalAttribute(tableComponent, 'value').size()}';\" \n                 escape=\"false\" />\n   </h:panelGroup>\n   <h:panelGroup rendered=\"#{empty tableComponent.filteredValue or \n    (tableComponent.filteredValue.size() eq \n    of:evalAttribute(tableComponent, 'value').size())}\">\n    <!-- MyFaces is not able to re-render text and expressions directly put \n    on a Facelet, so wrap in output text as well -->\n    <h:outputText value=\"document.getElementById('#{resultCountPlaceholder.\n    clientId}').innerHTML = '';\" escape=\"false\"/>\n   </h:panelGroup>\n  <h:outputText value=\"&lt;/script&gt;\" escape=\"false\" />\n </h:panelGroup>\n</o:moveComponent>\n

\n\n\n\n

4.Moving an AJAX event listener into the table

\n\n

The second MoveComponent instance has an AJAX event listener as its child. The event listener makes sure the JavaScript that we defined above is updated after each filtering operation. An AJAX event listener is not a component but a behavior. It therefore needs some extra handling (among others to fool it into believing that it’s temporarily a child of the MoveComponent which does not have the events a behavior can be checking for) It’s moved to the special behavior section components have:

\n\n

<o:moveComponent for=\"#{forx}\" destination=\"BEHAVIOR\">\n <p:ajax event=\"filter\" update=\":#{resultCount.clientId}\" />\n</o:moveComponent>\n

\n\n\n\n

5.Moving a component into the facet section of the table

\n\n

The third MoveComponent instance has a placeholder component with the fixed ID globalFilter as its child. This component is used by PrimeFaces to read the input used by the filtering operation. This placeholder component is needed for this example, since we wanted to have the real input component just above the table, not inside the table. The standard PrimeFaces approach with the facet tightly couples the location of the input component, which we here thus decouples. The real input component updates the placecholder using its onkeyup attribute:

\n\n

<o:moveComponent for=\"#{forx}\" destination=\"FACET\" facet=\"header\">\n <h:inputHidden id=\"globalFilter\" />\n</o:moveComponent>\n

\n\n\n\n

The complete application is named, PFMoveComponent.

\n\n\n\n

Chapter 6: Working with media content

In this chapter, we will discuss including media content in JSF pages (e.g. images, videos, documents, etc). We start by loading and displaying images via native JSF (e.g. <h:graphicImage/>), PrimeFaces (e.g. <p:graphicImage/>) and OmniFaces (e.g. <o:graphicImage/>). Furthermore, we will deal with other kinds of media files, like video and documents. From there on, we will introduce PrimeFaces Media component and the well known OmniFaces BalusC FileServlet. Here we will talk about loading media files that reside outside the web application.

\n\n

Typically, we store and load images from the /resource folder, but this is not always useful. For example, the images might be “served” as data URI, byte arrays (byte[]) or InputStreams by different kinds of services (e.g. web sockets, web services, Servlets, etc). Moreover, the image formats vary from PNG, JPEG to BMP, SVG, etc. As you will further see, there is no “universal” component capable of loading images independent of all these aspects.

\n\n

We finish this chapter with OmniFaces approach for checking if the current request is a PrimeFaces dynamic resource request.

\n\n

Working with images

In native JSF, we can load images via <h:graphicImage/> tag. Basically, this tag is useful when images are stored in /resources folder and we point to them via name and/or library. We can also point to context-relative URL to retrieve the resource associated with this component via value and url attributes. In addition, images will take advantage of the native JSF caching mechanism for resources (more details about caching in JSF are available here). When images are provided as InputStream or byte[] we need more than native JSF support. For example, we may need the PrimeFaces <p:graphicImage/> tag, which is capable of wrapping an InputStream (or a byte[] converted to InputStream) into a DefaultStreamedContent object (this class is specific to the PrimeFaces API). The PrimeFaces component also supports context-relative URLs via value and url attributes. Moreover, PrimeFaces provides a dedicated attribute for controlling images caching; mainly, this is a flag attribute (cache) that defaults to true (enables/disables browsers from caching the image). Or, if you want to avoid the byte[] to InputStream conversion and/or the PrimeFaces API (e.g. DefaultStreamedContent), then you can try the OmniFaces <o:graphicImage/>. This component was especially designed with support for referencing an InputStream or byte[] property in the value attribute (optionally as a data URI). In addition it supports name and library attributes. The GraphicImage component can be used to display SVG images (including SVG view modes via the fragment attribute). Other supported formats are: JPEG, PNG, GIF, ICO, SVG, BMP and TIFF. If OmniFaces cannot auto-detect content header or if the image is rendered as a regular image source, then the content type (obtained via, Faces.getMimeType(String)) will default to image without any sub-type. However, for newer images or older browsers, you can explicitly specify the image type via the type attribute which must represent a valid file extension. You can add unrecognized ones as <mime-mapping/> in web.xml:

\n\n

<mime-mapping>\n <extension>svg</extension>\n <mime-type>image/svg+xml</mime-type>\n</mime-mapping>\n

\n\n\n\n

OmniFaces provides cache control via a dedicated attribute named lastModified. You can supply the “last modified” property (e.g. via image entity) which will be used in the ETag and Last-Modified headers and in If-Modified-Since checks, hereby improving browser caching. The lastModified attribute supports both Date and Long as timestamp in milliseconds. As restrictions, you need to know that, InputStream or byte[] not rendered as data URI must point to a stateless @ApplicationScoped bean (both JSF and CDI scopes are supported). The property will namely be evaluated at the moment the browser requests the image content based on the URL as specified in HTML <img src>, which is usually a different request than the one which rendered the JSF page. Also, just like <h:graphicImage/>, the value attribute is ignored when the name attribute is specified (for JSF resources). And, the value attribute of <o:graphicImage/> does not support URLs anymore. For that, just keep using native JSF <h:graphicImage/>, PrimeFaces <p:graphicImage/> or even plain HTML <img/>.

\n\n

So let’s have a quick overview:

\n\n

Native JSF (<h:graphicImage/>)

\n\n

supports name and library\n
supports relative-context URL via value and url\n
provides JSF default caching mechanism for resources (nothing dedicated to images)
doesn’t support binary data (e.g. byte[] or InputStream)
doesn’t support data URI
doesn’t support SVG and SVG view modes

\n\n

PrimeFaces (<p:graphicImage/>)

\n\n

supports name and library\n
supports relative-context URL via value and url\n
supports enabling/disabling caching images in browser via cache flag attribute
supports binary data (e.g. InputStream) wrapped via specific API, DefaultStreamedContent\n
doesn’t support data URI
doesn’t support SVG and SVG view modes

\n\n

OmniFaces (<o:graphicImage/>)

\n\n

supports name and library\n
supports control for caching images in browser via lastModified attribute
supports binary data directly (e.g. byte[] and InputStream)
supports data URI
supports SVG and SVG view modes
doesn’t support relative-context URL via value and url\n

\n\n

Loading images from `/resources` folder

The images used in the examples are stored in /resources folder under the structure from figure below:

\n\n\n

\n\n\n

Now, let’s see several examples for loading these images into a JSF application:

\n\n

An image provided from /resources (without library) - can be displayed just by using the name attribute. This is supported in native JSF, in PrimeFaces and OmniFaces:

\n\n

<p|o|h:graphicImage name=\"default/images/img_dog.png\"/>\n

\n\n\n\n

An image provided from /resources (with library) - can be displayed using the library and name attributes. This is supported in native JSF, in PrimeFaces and OmniFaces:

\n\n

<p|o|h:graphicImage library=\"default\" name=\"images/img_tom.png\"/>\n

\n\n\n\n

A random image provided from /resources (with library). This is supported in native JSF, in PrimeFaces and OmniFaces:

\n\n

<p|o|h:graphicImage library=\"default\" \n                    name=\"images/img_#{imageIdsBean.id()}.png\" />\n

\n\n\n\n

A list of images provided from /resources. This is supported in native JSF, in PrimeFaces and OmniFaces:

\n\n

<ui:repeat value=\"#{imageIdsBean.ids}\" var=\"id\">\n <p|o|h:graphicImage library=\"default\" name=\"images/img_#{id}.png\" />\n</ui:repeat>\n

\n\n\n\n

An image provided from /resources as data URI. This is supported only in OmniFaces via dataURI=\"true\" flag attribute:

\n\n

<o:graphicImage library=\"default\" name=\"images/img_tom.png\" dataURI=\"true\"/>\n

\n\n\n\n

An image provided from /resources with browser cache control. This is supported by PrimeFaces and OmniFaces via dedicated attributes and by native JSF via native caching mechanism (can be altered as here). PrimeFaces supports cache control via cache flag attribute (default true), while \nOmniFaces supports cache control via lastModified attribute (below we are using the server’s startup time provided by the OmniFaces Startup managed bean):

\n\n

<p:graphicImage library=\"default\" name=\"images/img_tom.png\" cache=\"false\"/>\n<o:graphicImage library=\"default\" name=\"images/img_tom.png\" \n                                  lastModified=\"#{startup.time}\"/>\n

\n\n\n\n

A SVG image provided from /resources. This is supported in native JSF, in PrimeFaces and OmniFaces:

\n\n

<p|o|h:graphicImage library=\"default\" name=\"svgs/sample.svg\"/>\n

\n\n\n\n

A SVG image portion provided from /resources. This is supported only in OmniFaces via fragment attribute:

\n\n

<o:graphicImage library=\"default\" name=\"svgs/sample.svg\" \n                fragment=\"svgView(viewBox(0,50,200,200))\"/>\n

\n\n\n\n

A SVG image provided from /resources as data URI. This is supported only in OmniFaces via dataURI=\"true\":

\n\n

<o:graphicImage library=\"default\" name=\"svgs/sample.svg\" dataURI=\"true\"/>\n

\n\n\n\n

The complete application is named, PFOFLoadingImagesResources.

\n\n

Loading images provided as byte array, `byte[]`, or `InputStream`\n

\n\n

Generally speaking, an image provided as a byte[] is supported directly by OmniFaces and indirectly (convert byte[] into InputStream and wrap it in DefaultStreamedContent ) by PrimeFaces. An image provided as an InputStream is also supported directly by OmniFaces and indirectly (wrap the InputStream in DefaultStreamedContent) by PrimeFaces.

\n\n

An image provided as a byte[]/InputStream via a managed bean from a Servlet (this can be any other service, e.g. a web service). This is supported directly by OmniFaces:

\n\n

<o:graphicImage value=\"#{binaryImageBean.imageAsByteArrayFromServlet()}\"/>\n<o:graphicImage value=\"#{binaryImageBean.imageAsInputStreamFromServlet()}\"/>\n

\n\n\n\n

If the Servlet has a context-relative URL, in PrimeFaces and native JSF, then we can use the url/value attributes:

\n\n

<p|h:graphicImage url=\"/ByteServlet\"/>\n

\n\n\n\n

A random image provided as a byte[]/InputStream via a managed bean from a Servlet (this can be any other service, e.g. a database). This is supported directly by OmniFaces:

\n\n

<o:graphicImage value=\"#{binaryImageBean.\n                         imageAsByteArrayFromServletRnd(imageIdsBean.id())}\" />\n<o:graphicImage value=\"#{binaryImageBean.\n                         imageAsInputStreamFromServletRnd(imageIdsBean.id())}\" />\n

\n\n\n\n

If the Servlet has a context-relative URL, in PrimeFaces and native JSF, then we can use the url/value attributes:

\n\n

<p|h:graphicImage url=\"/ByteServlet?id=tom\"/>\n

\n\n\n\n

A list of images provided as byte[]/InputStream via a managed bean from a Servlet. (this can be any other service). It is supported directly by OmniFaces:

\n\n

<ui:repeat value=\"#{imageIdsBean.ids}\" var=\"id\">\n <o:graphicImage value=\"#{binaryImageBean.\n                          imageAsByteArrayFromServletRnd(id)}\" />\n</ui:repeat>\n<ui:repeat value=\"#{imageIdsBean.ids}\" var=\"id\">\n <o:graphicImage value=\"#{binaryImageBean.\n                          imageAsInputStreamFromServletRnd(id)}\" />\n</ui:repeat>\n

\n\n\n\n

If the Servlet has a context-relative URL, in PrimeFaces and native JSF, then we can use the url/value attributes:

\n\n

<ui:repeat value=\"#{imageIdsBean.ids}\" var=\"id\">\n <p|h:graphicImage url=\"/ByteServlet?id=#{id}\" />\n</ui:repeat>\n

\n\n\n\n

An image provided as a byte[]/InputStream via a managed bean from a Servlet using data URI. This is supported only in OmniFaces via dataURI flag attribute:

\n\n

<o:graphicImage value=\"#{binaryImageBean.imageAsByteArrayFromServlet()}\" \n                dataURI=\"true\"/>\n<o:graphicImage value=\"#{binaryImageBean.imageAsInputStreamFromServlet()}\" \n                dataURI=\"true\"/>\n

\n\n\n\n

Cache control for an image provided as byte[]/InputStream via a managed bean from a Servlet. This is supported directly by OmniFaces via lastModified attribute:

\n\n

<o:graphicImage value=\"#{binaryImageBean.imageAsByteArrayFromServlet()}\" \n                lastModified=\"#{imageIdsBean.timestamp}\"/>\n<o:graphicImage value=\"#{binaryImageBean.imageAsInputStreamFromServlet()}\" \n                lastModified=\"#{imageIdsBean.timestamp}\"/>\n

\n\n\n\n

If the Servlet has a context-relative URL, in PrimeFaces and native JSF, then we can use the url/value attributes. Furthermore, only in PrimeFaces, we can use the cache flag attribute (default true). Native JSF will use native caching mechanism.

\n\n

<p:graphicImage url=\"/ByteServlet\" cache=\"false\"/>\n

\n\n\n\n

Aside from the above examples sited in the complete applications (PFOFLoadingImagesByteArray for byte[] and PFOFLoadingImagesInputStream for InputStream), you will see use cases for images provided as byte[]/InputStream via a managed bean from a folder (we used the /resources folder to store the provided images, but it can be any other folder).

\n\n\n\n

Loading external media content

\n\n

Basically, in this section we will focus on loading media files that reside outside the web application. For example, if you have an image stored on the server outside the web application (e.g. D:\\media\\cartoon.png) then you cannot simply load this image via <p:graphicImage/> as below:

\n\n

<p:graphicImage url=\"D:\\\\media\\\\cartoon.png\"/>\n

\n\n\n\n

In addition, if we have a video, a PDF document, etc in the same D:\\media\\ we cannot simply use the PrimeFaces Media component, as below:

\n\n

<p:media value=\"D:\\\\media\\\\movie.mp4\" width=\"400\">                        \n <f:param name=\"autoplay\" value=\"false\" />     \n</p:media>\n

\n\n\n\n

In order to obtain the desired behavior we need to provide a server-side artifact capable of serving media content from outside the web application. This artifact should provide several features such as:

\n\n

fast NIO stuff instead of legacy RandomAccessFile;
properly dealing with ETag, If-None-Match and If-Modified-Since caching requests;
properly dealing with Range and If-Range ranging requests (RFC7233), which is required by most media players and by web browsers
properly streaming audio/video
a proper resume of a paused download
download accelerators to enable requests to smaller parts simultaneously

\n\n

You have to admit that such an artifact requires some knowledge and work. Fortunately we have the BalusC FileServlet. If you have never heard of the BalusC FileServlet then it is time to find out! Starting with OmniFaces 2.2, the FileServlet was slightly refactored rewritten and modernized to support the features listed above.

\n\n

This servlet is ideal for large files such as media files placed outside the web application and you can’t use the default servlet.

\n\n

You can easily exploit FileServlet by extending this class and overriding the getFile(HttpServletRequest) method to return the desired file. Below you can see a simple implementation:

\n\n

@WebServlet(\"/media/*\")\npublic class MediaFileServlet extends FileServlet {\n   \n private File folder;\n\n @Override\n public void init() throws ServletException {\n  folder = new File(\"D:\\\\media\\\\\");\n }\n\n @Override\n protected File getFile(HttpServletRequest request) \n                            throws IllegalArgumentException {\n       \n  String pathInfo = request.getPathInfo();\n       \n  if (pathInfo == null || pathInfo.isEmpty() || \"/\".equals(pathInfo)) {\n      throw new IllegalArgumentException();\n  }\n\n  return new File(folder, pathInfo);\n }\n}\n

\n\n\n\n

If you want to trigger a HTTP 400 \"Bad Request\" error, simply throw IllegalArgumentException. If you want to trigger a HTTP 404 \"Not Found\" error, simply return null, or a non-existent file. Moreover, you can shape this Servlet behavior by overriding the following methods:

\n\n

\nlong getExpireTime(HttpServletRequest, File) - By default, the resource may be cached by the client before it expires for 30 days (in seconds). Through this method you can alter this value. Pass the involved request and file and return the desired number of seconds.
\nString getContentType(HttpServletRequest request, File file) - The default implementation delegates File#getName() to ServletContext#getMimeType(String) with a fallback default value of application/octet-stream. If you want to alter this behavior, pass the involved request and file and return the desired content type (e.g. for PNG, add return \"image/png\";).
\nboolean isAttachment(HttpServletRequest request, String contentType) - By default, it returns true if the content type does not start with text or image, and the Accept request header is either null or does not match the given content type. If you want to alter this behavior pass the involved request and content type and return the desired value. For example, some browsers tend to download a video instead of playing it (e.g. Google Chrome). In order to prevent this, you can override this method to return false (this will cause FileServlet to add in response headers the Content-Disposition as inline instead of attachment:

\n\n

@Override\nprotected boolean isAttachment(HttpServletRequest request, String contentType) {\n return false;\n}\n

\n\n\n\n

Example of loading external images/videos/PDF

\n\n

Let’s suppose that we have several images/videos and PDF documents in a folder named media under D: disk. So the path for an image named, cartoon.png will be D:\\media\\cartoon.png. We want to load these resources in a web application via pure HTML and JSF tags. Our application uses the /faces/* prefix mapping for faces servlet.

\n\n

Example of loading images

\n\n

Load the image, D:\\media\\cartoon.png (notice that <o:graphicImage/> cannot be used!):

\n\n

HTML:

\n\n

<img src=\"#{request.contextPath}/faces/media/cartoon.png\"/>\n

\n\n\n\n

NativeJSF:

\n\n

<h:graphicImage url=\"faces/media/cartoon.png\"/>\n<h:graphicImage value=\"faces/media/cartoon.png\"/>\n

\n\n\n\n

PrimeFaces:

\n\n

<p:graphicImage url=\"faces/media/cartoon.png\"/>\n<p:graphicImage value=\"faces/media/cartoon.png\"/>\n

\n\n\n\n

The complete application is named BalusCFileServletImagesExample.

\n\n

Example of loading videos

\n\n

Load the video, D:\\media\\movie.mp4:

\n\n

HTML:

\n\n

<video width=\"400\" controls=\"controls\">\n <source src=\"#{request.contextPath}/faces/media/movie.mp4\" type=\"video/mp4\"/>\n <source src=\"#{request.contextPath}/faces/media/movie.ogg\" type=\"video/ogg\"/>\n Your browser does not support HTML5 video.\n</video>\n

\n\n\n\n

PrimeFaces:

\n\n

<p:media value=\"faces/media/movie.mp4\" width=\"400\">                        \n <f:param name=\"autoplay\" value=\"false\" />    \n</p:media>\n

\n\n\n\n

The complete application is named BalusCFileServletVideosExample.

\n\n

Example of loading PDF

\n\n

Load the video, D:\\media\\sample.pdf:

\n\n

HTML:

\n\n

<object width=\"400\" height=\"500\" type=\"application/pdf\"\n        data=\"#{request.contextPath}/faces/media/sample.pdf\">\n <p>Insert your error message here, if the PDF cannot be displayed.</p>\n</object>\n

\n\n\n\n

PrimeFaces:

\n\n

<p:media value=\"faces/media/sample.pdf\" width=\"400\" height=\"500\" />\n

\n\n\n\n

The complete application is named BalusCFileServletPDFExample.

\n\n

Check if the current request is a PrimeFaces dynamic resource request

\n\n

For example, PrimeFaces generates dynamic resource requests when we try to load images from a StreamedContent via <p:graphicImage/>. \nSuch a request may look like in the figure below (you can obtain this image by running the PFLoadingInputStreamImage application under Mozilla Firefox with Firebug extension activated):

\n\n\n

\n\n\n

These request parameters are specific to PrimeFaces and are extracted from a URL like this:

\n\n

http://localhost:8080/PFLoadingInputStreamImage/faces/javax.faces.resource/\ndynamiccontent.properties?ln=primefaces&v=5.3&pfdrid=r1L3mNOT6k3TlqCfC7jLDuk\nDhwJ8o6plkjq%2BF53gi4o%3D&pfdrt=sc&pfdrid_c=true\n

\n\n\n\n

Furthermore, OmniFaces has used these parameters to implement a utility method capable to programmatically detect if the current request is a PrimeFaces dynamic resource request. This utility method returns a boolean value and is named, isPrimeFacesDynamicResourceRequest(). This method can be found in Hacks class, and can easily be used as below:

\n\n

boolean is = Hacks.isPrimeFacesDynamicResourceRequest\n                     (FacesContext.getCurrentInstance());\nif(is){\n   // is\n} else {\n   //is not\n}\n

\n\n\n\n

If you write a custom resource handler, it will be useful to distinguish such cases.

\n\n

Chapter 7: Including Servlets/JSP output in JSF page

\n\n

There is no need to introduce the Servlet/JSP terms, so we will directly discuss the main topic of this chapter, which consists of including the output from a Servlet/JSP in a JSF page (PrimeFaces component). There are at least three important aspects here:

\n\n

Including the Servlet/JSP output “directly” in the page.
Including the Servlet/JSP output in the page via a managed bean.
Including the Servlet/JSP output in the page via a custom component (or other custom artifact).

\n\n

Basically, these three approaches have the same effect in the JSF page (for the end user) but their implementations are quite different. In order to add the output “directly”, you can write the JSF page using JSP syntax, and include the Servlets via <jsp:include page=\"servlet_path\" />. In order to keep the JSF page in Facelets style, you can try to find a workaround based on JavaScript, as an auto-submit form or use a managed bean to interact with the Servlet and serve its output in page.

\n\n

Including a Servlet output in a PrimeFaces component

\n\n

But if you are thinking of a custom component capable of including the Servlet/JSP output in a JSF page (PrimeFaces component) then you have to take into account the OmniFaces ResourceInclude component. This component can be used to “catch” the output from a Servlet/JSP resource and render it via the JSF default response writer. This component is available to the JSF page authors via the <o:resourceInclude/> tag. It has a single attribute, named path. Obviously, the value of this attribute represents the Servlet/JSP resource path and it is required. For example, let’s consider the following simple Servlet (DataServlet):

\n\n

@WebServlet(\"/DataServlet\")\npublic class DataServlet extends HttpServlet {\n\nprotected void processRequest(HttpServletRequest request, \n                              HttpServletResponse response)\n                              throws ServletException, IOException {\n\n // Set the response message's MIME type\n response.setContentType(\"text/html;charset=UTF-8\");\n\n // Allocate a output writer to write the response message\n PrintWriter out = response.getWriter();\n\n // Write the response message\n out.write(\"<p><strong>Tags</strong>:<code>Transformers: 1, RIA: 3, AJAX: 2, \n            jQuery: 5, NextGen: 4, JSF 2.0: 2, FCB: 5, Mobile: 3, Themes: 4, \n            Rocks: 1</code></p>\");       \n }\n\n @Override\n protected void doGet(HttpServletRequest request, HttpServletResponse response)\n                throws ServletException, IOException {\n  processRequest(request, response);\n }\n\n @Override\n protected void doPost(HttpServletRequest request, HttpServletResponse response)\n           throws ServletException, IOException {\n  processRequest(request, response);\n } \n}\n

\n\n\n\n

Now, we can easily include this Servlet output in a PrimeFaces component (e.g. in an OutputPanel):

\n\n

<p:outputPanel>\n <o:resourceInclude path=\"/DataServlet\"/>\n</p:outputPanel>\n

\n\n\n\n

The output reveals the result from figure below:

\n\n\n

\n\n\n

The complete application is named, IncludeServletOutputInPage.

\n\n

Decorating the Servlet output

\n\n

Sometimes the Servlet output cannot be used directly. For example, let’s check out the below Servlet which produces a JSON like string:

\n\n

@WebServlet(\"/DataServlet\")\npublic class DataServlet extends HttpServlet {\n\nprotected void processRequest(HttpServletRequest request, \n                              HttpServletResponse response)\n                              throws ServletException, IOException {\n\n // Set the response message's MIME type\n response.setContentType(\"text/plain\");\n response.setCharacterEncoding(\"utf-8\");\n  \n // Allocate a output writer to write the response message\n PrintWriter out = response.getWriter();\n\n // Write the response\n out.print(\"{\\\"Tags\\\":[\\\"Transformers\\\",\\\"1\\\",\\\"RIA\\\",\\\"3\\\",\\\"AJAX\\\",\\\"2\\\",\n          \\\"jQuery\\\",\\\"5\\\",\\\"NextGen\\\",\\\"4\\\",\\\"JSF 2.0\\\",\\\"2\\\",\\\"FCB\\\",\\\"5\\\",\n          \\\"Mobile\\\",\\\"3\\\",\\\"Themes\\\",\\\"4\\\",\\\"Rocks\\\",\\\"1\\\"]}\");\n }\n\n @Override\n protected void doGet(HttpServletRequest request, HttpServletResponse response)\n                throws ServletException, IOException {\n  processRequest(request, response);\n }\n\n @Override\n protected void doPost(HttpServletRequest request, HttpServletResponse response)\n                throws ServletException, IOException {\n  processRequest(request, response);\n }\n}\n

\n\n\n\n

Now, if we include the output of this Servlet, exactly as we have done in the previous section, we will obtain something like the figure below:

\n\n\n

\n\n\n

This is working as expected, but we may need to alter/decorate this JSON string to use it for creating different kinds of models (or any other stuff). For example, we may want to transform this JSON string into a PrimeFaces LineChartModel (for creating a line chart) or a TagCloudModel (for creating a collection of tags with different strengths).

\n\n

A nice trick (inspired by Arjan Tijms) will consist of using another OmniFaces component named, OutputFormat. This component extends the standard <h:outputFormat/> with support for capturing the output and exposing it to the request scope through the variable name as specified by the var attribute. For example, we can capture the DataServlet output and expose it via <o:outputFormat/> as below:

\n\n

<o:outputFormat var=\"_data\">\n <o:resourceInclude path=\"/DataServlet\"/>\n</o:outputFormat>\n

\n\n\n\n

This time the DataServlet output is not displayed on the screen. This output was stored in the request scope and it is available via _data anywhere in page. This means that we can pass this output to an action method which decorates it accordingly. For example, we can pass it to an action method capable of creating a PrimeFaces LineChartModel:

\n\n

<p:chart type=\"line\" model=\"#{dataBean.createCategoryModels(_data)}\" \n         style=\"height:400px; width:700px;\"/>    \n

\n\n\n\n\n

\n\n\n

Or, we can pass it to an action method capable of producing a PrimeFaces TagCloudModel:

\n\n

<p:tagCloud model=\"#{dataBean.createTagModels(_data)}\"/>\n

\n\n\n\n\n

\n\n\n

Of course, you can still display _data without decorations (e.g. in an OutputPanel):

\n\n

<p:outputPanel>\n #{_data}\n</p:outputPanel>\n

\n\n\n\n

The complete application is named, DecorateDataFromIncludedServlet.

\n\n\n\n\n\n\n\n

Chapter 8: Working with forms

\n\n

Working with request parameters, view parameters and forms can be a real challenge for novices. Certain limitations are not very clear and usually they end up in total confusion that gives birth to bad practices and roundabout code. Some quick highlights of JSF forms in respect to request/view parameters are listed below:

\n\n

At initial request, the query string (the URL part after “?”) is parsed and the request parameters from the query string are stored in the request parameters map.
At postbacks, these request parameters donʹt arrive in the request parameters map anymore since the query string, by default, does not participate in postbacks.
View parameters can be a workaround to avoid losing the request parameter values that come via query strings (GET requests).
For this, view parameters are initialized via query string using the <f:viewParam/> tag nested in the <f:metadata/> tag and using the same parameter names.
A view parameter name matches a request parameter name from the query string, and this tells JSF that the view parameter value should be equal to that of the request parameter (this is the initialization of the view parameter).
Further, the value of the view parameter can be converted, validated and passed in a managed bean property. Moreover, it is stored in state, which makes it available over postbacks and since view parameters are stateful – they need to be initialized only once.
Nevertheless, do not conclude that view parameters can be initialized only via the query string.
In fact, the main goal of view parameters is to provide support for creating bookmarkable URLs.
View parameters can be included in the query string via the includeViewParams=\"true\" attribute in <p:link/> and <p:button/> and via the includeViewParams=true request parameter in any URL.
Forms are the “stars” of JSF. They “shine” in JSF applications and everything “orbits” around them. Basically, they encapsulate POST requests meant to “transport” data from the client side to the server side and expect a response.
These POST requests can use forward or redirect mechanisms.
The parameters submitted via a POST request (user inputs/form parameters) are available programmatically via getRequestParameterMap(), but most of the time we are referring to the managed beans properties that wrap these parameterʹs values. Moreover, this map may contain some extra request parameters that donʹt fit the managed bean properties.
Think of request parameters map as a temporary storage for the goodies (parameters) that HTTP brought during the current request. HTTP is stateless, so JSF needs to transfer the request content into managed beans and store/update managed beans instances in their scopes (e.g. request, session, application scope).
The values of the parameters that donʹt fit the managed beans properties (“automatically” or programmatically) will be lost when the request parameter map is emptied (e.g. at each request).

\n\n

Introducing OmniFaces `Form` component

\n\n

OmniFaces provides a component named Form (exposed in page via the <o:form/> tag). This is an extension of JSF UIForm and provides additional attributes for attaching the request parameters, view parameters or the entire original request URI to the action\nURL. In order to use <o:form/> simply add the OmniFaces namespace and replace the h from <h:form/> with o prefix.

\n\n

Preserving query string over postbacks

\n\n

JSF doesnʹt provide any support for preserving the query string over postbacks. But, the OmniFaces Form supports an attribute named includeRequestParams. This is a flag attribute indicating if the request parameters (all GET parameters) will be added in the action URL that will be rendered on the form. This will override the includeViewParams presented later. In order to see an example, let’s suppose that we have the following page that contains a link with three request parameters (index.xhtml):

\n\n

<h:body>  \n <p:link value=\"Ping Me!\" outcome=\"ping.xhtml\">\n  <f:param name=\"phone\" value=\"0732845714\"/>\n  <f:param name=\"payment\" value=\"MASTERCARD\"/>\n  <f:param name=\"reversecharge\" value=\"YES\"/>\n </p:link>\n</h:body>\n

\n\n\n\n

When we press the Ping Me! link, we will fire a GET request that will load the ping.xhtml page:

\n\n

http://.../ping.xhtml?phone=0732845714&payment=MASTERCARD&reversecharge=YES\n

\n\n\n\n

The ping.xhtml page is pretty simple and intuitive:

\n\n

<p:panelGrid>\n Ping #{param.phone} for #{dataBean.name} #{dataBean.surname}!\n Payment: #{param.payment}\n Reverse Charge: #{param.reversecharge}\n\n <o:form id=\"pingFormId\" includeRequestParams=\"true\">\n  <p:outputLabel for=\"nameId\" value=\"Name:\"/>\n  <p:inputText id=\"nameId\" value=\"#{dataBean.name}\" />\n  <p:outputLabel for=\"surnameId\" value=\"Surname:\"/>\n  <p:inputText id=\"surnameId\" value=\"#{dataBean.surname}\" />\n\n  <p:commandButton id=\"buttonPingId\" value=\"Ping!\" ajax=\"false\"/>\n </o:form>\n</p:panelGrid>\n

\n\n\n\n

Notice the presence of <o:form/>. Each time you press the Ping! command button, you can see that the query string (?phone=0732845714&payment=MASTERCARD&reversecharge=YES) is preserved in the URL. By default, the JSF <h:form/> will loose the query string at first postback! This is not always desirable (see below the effect of a postback with <o:form/> and with <h:form/>):

\n\n\n

\n\n\n

The complete application is named, FormWithIncludeRequestParameters.

\n\n

Preserving view parameters over postbacks

\n\n

JSF doesnʹt provide any support for preserving view parameters over postbacks via the forward mechanism (only for the redirect mechanism).\nBut, the OmniFaces Form supports an attribute named includeViewParams. This is a flag attribute indicating if the view parameters should be added to the action URL that will be rendered on the form. This is similar to how, the attribute of the same name can be used on the <p:link/> and <p:button/> components. In order to see an example, let’s suppose that we have the same index.xhtml page listed in the previous section. When we press the Ping Me! link, we fire a GET request that will load the ping.xhtml page: http://.../ping.xhtml?phone=0732845714&payment=MASTERCARD&reversecharge=YES. Only this time, we modify the ping.xhtml to support two view parameters, as below:

\n\n

<f:metadata>            \n <f:viewParam name=\"phone\" value=\"#{dataBean.phone}\"/>\n <f:viewParam name=\"prefix\" value=\"005\"/>            \n</f:metadata>    \n<h:body>       \n <p:panelGrid>\n  Ping #{param.phone} for #{dataBean.name} #{dataBean.surname}!\n  Payment: #{param.payment}\n  Reverse Charge: #{param.reversecharge}\n            \n  <o:form id=\"pingFormId\" includeViewParams=\"true\">\n   <p:outputLabel for=\"nameId\" value=\"Name:\"/>\n   <p:inputText id=\"nameId\" value=\"#{dataBean.name}\" />\n   <p:outputLabel for=\"surnameId\" value=\"Surname:\"/>\n   <p:inputText id=\"surnameId\" value=\"#{dataBean.surname}\" />\n\n   <p:commandButton id=\"buttonPingId\" value=\"Ping!\" ajax=\"false\"/>\n  </o:form>\n </p:panelGrid>\n</h:body>\n

\n\n\n\n

Notice the presence of <o:form/> again. Each time you press the Ping! command button, you see the view parameters visible as request parameters in the query string (?phone=0732845714&prefix=005). So, the view parameters are preserved in the query string of the current request URL (postback). The request parameters that are not view parameters will be lost at first postback (e.g. payment and reversecharge).

\n\n

By default, the JSF <h:form/> will lose the view parameters from the query string at first postback!

\n\n

The complete application is named, FormWithIncludeViewParameters.

\n\n\n\n

Quick look at `useRequestURI` attribute

\n\n

The OmniFaces Form also supports an attribute named, useRequestURI. When this is set to true the entire original\nrequest URI, including the URL (GET) parameters will be used. This will override the includeViewParams and includeRequestParams. This is particularly helpful when using URL rewriting with, for example, a custom rewrite filter or FacesViews. A good example is zeef.com, all subject pages are forwarded to /index.xhtml with the subject and curator name as special parameters, where the bean and template pick up from further. Using the default <h:form/>, it would still generate /index.xhtml as the action URL instead of the current request URI, which is particularly troublesome in non‐AJAX forms. The useRequestURI=\"true\" is used all over the place in zeef.com (via a <z:form/> template).

\n\n

Ignoring validation failures in `<o:form/>`\n

\n\n

When we are using <o:form/>, we can also attach a tag handler that allows us to tell JSF to ignore validation failures when executing an UICommand action (e.g. <p:commandButton/>, <p:commandLink/>). This tag handler is named IgnoreValidationFailed and must be placed inside of an UICommand component (e.g. nested in <p:commandButton/>, <p:commandLink/>) via <o:ignoreValidationFailed/> tag. The parent of this UICommand must be <o:form/>; do not try to use it with <h:form/>!

\n\n

The data model values will be updated only for components which have actually passed the validation. Also the validation messages will still be displayed. This tag handler practically suppresses the effect of the FacesContext#validationFailed() and the FacesContext#renderResponse() methods.

\n\n

Below you can see a test case (you can have a non-AJAX request and also use custom validators):

\n\n

<o:form id=\"formId\">                     \n <h:panelGrid id=\"gridId\" columns=\"1\" cellpadding=\"2\">              \n\n  <p:outputLabel for=\"nameId\" value=\"Name:\" />\n  <p:inputText id=\"nameId\" value=\"#{userBean.name}\" required=\"true\" />  \n  <p:message for=\"nameId\"/>\n\n  <p:outputLabel for=\"emailId\" value=\"E-mail:\" />\n  <p:inputText id=\"emailId\" value=\"#{userBean.email}\" required=\"true\" /> \n  <p:message for=\"emailId\"/>\n\n  <p:outputLabel for=\"phoneId\" value=\"Phone:\" />\n  <p:inputText id=\"phoneId\" value=\"#{userBean.phone}\" required=\"true\" />         \n  <p:message for=\"phoneId\"/>\n\n  Name: #{userBean.name} | E-mail: #{userBean.email} | Phone: #{userBean.phone}\n </h:panelGrid>\n\n <p:commandButton id=\"submitButtonId\" value=\"Register\" update=\"gridId\">      \n  <o:ignoreValidationFailed />\n </p:commandButton>\n</o:form>\n

\n\n\n\n

Notice in the picture below that the name and e-mail were successfully passed into the data model even if the phone field caused a validation error. The validation error message is displayed, but the validation phase was successfully “passed” even if the validation failed:

\n\n\n

\n\n\n

The complete application is named, PFWithIgnoreValidationFailed.

\n\n\n\n

Chapter 9: Import constants, interfaces, enums and public static methods

\n\n

There is a common practice for declaring constants using the public static final declaration:

\n\n

public class SpinnerBean {\n\n public static final int MIN = 10;\n public static final int MAX = 100;\n\n public static final int[] MINMAXARRAY = {MIN, MAX};\n \n public static final Set<Integer> MINMAXSET = Utils.unmodifiableSet(MIN, MAX);\n}\n

\n\n\n\n

Also, Java interfaces and enums are very useful in applications (they are part of the Java language “bricks”):

\n\n

public interface ATP {\n public String website = \"http://www.atpworldtour.com/\";\n}\n\npublic enum PlayerEnum {\n\n R_NADAL, R_FEDERER, D_FERER;\n\n public Integer getRank() {\n  switch (name()) {\n   case \"R_NADAL\":\n         return 1;\n   case \"R_FEDERER\":\n         return 2;\n   case \"D_FERER\":\n         return 3;\n   default:\n         return 0;\n  }\n }\n}\n

\n\n\n\n

Now, when we write helper methods (public static methods with a non void return type), we usually group them in final classes as below:

\n\n

public final class PlayerHelper implements Serializable {\n\n private static final long serialVersionUID = 1L;\n\n public static boolean isPlayerAvailable(int rank) {\n  // look for player, or at least do something else\n  Random rnd = new Random();\n  if (rnd.nextInt(10) < 5) {\n      return false;\n  }\n      return true;\n  }\n}\n

\n\n\n\n

Now, let’s suppose that we have these artifacts in a JSF application, as a JSF page author we need to use them in page via EL, as below:

\n\n

// use constants\n#{SpinnerBean.MIN}\n#{SpinnerBean.MAX}\n\n// use interfaces and enums\n#{ATP.website}\n#{PlayerEnum.R_NADAL}\n\n// use public static non void methods\n#{PlayerHelper:isPlayerAvailable(1)}\n

\n\n\n\n

There is no elegant way to say that the above usages will simply not work! Of course, we can wrap the constants and enums in bean properties/methods and the helper methods in custom Facelets taglib functions, but this is not our purpose.

\n\n

Import constants/interfaces via PrimeFaces and OmniFaces

\n\n

In order to import constants, we can use the PrimeFaces approach. Actually, we are talking about PrimeFaces Extensions. As you probably know, PrimeFaces Extensions are built on top of PrimeFaces and consists of a lightweight open source component library for Java Server Faces 2.0. In order to use it, you need to add the specific dependency (or JAR) in your project. One of the utilities provided by PrimeFaces Extensions is dedicated for exposing constants in EL expressions. The tag is named <pe:importConstants/> and it supports two important attributes. The constants can be accessed via the name of the class (default setting) indicated via the required className attribute, or via a custom name indicated via the optional var attribute. For example, we can expose in EL the constants from SpinnerBean class as below:

\n\n

// expose class constants in EL\n<pe:importConstants className=\"beans.SpinnerBean\" />\n<pe:importConstants className=\"beans.SpinnerBean\" var=\"MINMAX_PF\" />\n\n// usage examples\n<p:spinner min=\"#{SpinnerBean.MIN}\" max=\"#{SpinnerBean.MAX}\" />\n<p:spinner min=\"#{MINMAX_PF.MIN}\" max=\"#{MINMAX_PF.MAX}\" />\t\n\n<p:spinner min=\"#{SpinnerBean.MINMAXARRAY[0]}\" \n           max=\"#{SpinnerBean.MINMAXARRAY[1]}\" />\n<p:spinner min=\"#{MINMAX_PF.MINMAXARRAY[0]}\" \n           max=\"#{MINMAX_PF.MINMAXARRAY[1]}\" />\t\n\n<p:spinner min=\"#{SpinnerBean.MINMAXSET.toArray()[1]}\" \n           max=\"#{SpinnerBean.MINMAXSET.toArray()[0]}\" />\n<p:spinner min=\"#{MINMAX_PF.MINMAXSET.toArray()[1]}\" \n           max=\"#{MINMAX_PF.MINMAXSET.toArray()[0]}\" />\t\n

\n\n\n\n

For an interface we have something like this:

\n\n

// expose interface constants in EL\n<pe:importConstants className=\"beans.ATP\" />\n<pe:importConstants className=\"beans.ATP\" var=\"atp\" />\n\n// usage examples\n<h:outputLink id=\"atppfId\" value=\"#{atp.website}\">ATP WEBSITE</h:outputLink>\n<p:tooltip for=\"atppfId\" value=\"#{atp.website}\" />\n<p:tooltip for=\"atppfId\" value=\"#{ATP.website}\" />\n

\n\n\n\n

On the other hand, OmniFaces comes with a tag handler named, <o:importConstants/> that is capable of mapping all constant field values of a given fully qualified name of type in the request scope. The constants can be accessed via EL; once we import them as below (the type attribute is required and its value represents the fully qualified name of the class/interface/enum to import and the constant field values for). The <o:importConstants/> also supports the var attribute. You can use it to indicate an alias (the name of the request attribute which exposes the mapping of the constants in the request scope):

\n\n

// expose class constants in EL\n<o:importConstants type=\"beans.SpinnerBean\" />\n<o:importConstants type=\"beans.SpinnerBean\" var=\"MINMAX_OF\" />\n\n// usage examples\n<p:spinner min=\"#{SpinnerBean.MIN}\" max=\"#{SpinnerBean.MAX}\" />\n<p:spinner min=\"#{MINMAX_OF.MIN}\" max=\"#{MINMAX_OF.MAX}\" />\t\n\n<p:spinner min=\"#{SpinnerBean.MINMAXARRAY[0]}\" \n           max=\"#{SpinnerBean.MINMAXARRAY[1]}\" />\t\n<p:spinner min=\"#{MINMAX_OF.MINMAXARRAY[0]}\" \n           max=\"#{MINMAX_OF.MINMAXARRAY[1]}\" />\t\n\n<p:spinner min=\"#{SpinnerBean.MINMAXSET.toArray()[1]}\" \n           max=\"#{SpinnerBean.MINMAXSET.toArray()[0]}\" />\n<p:spinner min=\"#{MINMAX_OF.MINMAXSET.toArray()[1]}\" \n           max=\"#{MINMAX_OF.MINMAXSET.toArray()[0]}\" />\t\n

\n\n\n\n

For an interface we have something like this:

\n\n

// expose interface constants in EL\n<o:importConstants type=\"beans.ATP\" />\n<o:importConstants type=\"beans.ATP\" var=\"atp\" />\n\n// usage examples\n<h:outputLink id=\"atppfId\" value=\"#{atp.website}\">ATP WEBSITE</h:outputLink>\n<p:tooltip for=\"atppfId\" value=\"#{atp.website}\" />\n<p:tooltip for=\"atppfId\" value=\"#{ATP.website}\" />\n

\n\n\n\n\n\n\n\n

The complete application is named, PFOFImportConstants.

\n\n

Import enums via PrimeFaces and OmniFaces

\n\n

Further let’s focus on importing the PlayerEnum enum. Again, let’s start with PrimeFaces Extensions approach. This time we will focus on the tag named <pe:importEnum/> and its two important supporting attributes. The enums can be accessed via the name of the class (default setting) indicated via the required type attribute, or via a custom name indicated via the optional var attribute. It is also possible to get all enum values of the class with the ALL_VALUES suffix or a custom prefix via the allSuffix attribute. For example, we can expose in EL the PlayerEnum like below:

\n\n

// expose enum in EL\n<pe:importEnum type=\"beans.PlayerEnum\" allSuffix=\"ALL_ENUM_VALUES\" />        \n<pe:importEnum type=\"beans.PlayerEnum\" var=\"enumpf\" \n                                       allSuffix=\"ALL_ENUM_VALUES\" />\n\n// Loop enum values:\n<ui:repeat value=\"#{enumpf | PlayerEnum.ALL_ENUM_VALUES}\" var=\"t\">\n #{t}\n</ui:repeat>        \n\n// Providing enum values as dropdown items and test R_NADAL item:\n<h:form>\n <p:selectOneMenu value=\"#{playerBean.selectedPlayerEnum}\">        \n  <f:selectItems value=\"#{enumpf | PlayerEnum.ALL_ENUM_VALUES}\" />\n  <p:ajax update=\"@form\" />\n </p:selectOneMenu>\n #{playerBean.selectedPlayerEnum}\n [#{playerBean.selectedPlayerEnum == enumpf | PlayerEnum.R_NADAL}]\n</h:form>\n\n// Providing enum values as dropdown items by var and test R_NADAL item:\n<h:form>\n <p:selectOneMenu value=\"#{playerBean.selectedPlayerEnum}\">        \n  <f:selectItems value=\"#{enumpf | PlayerEnum.ALL_ENUM_VALUES}\" var=\"t\" \n                 itemLabel=\"#{t.rank}\" itemValue=\"#{t}\" />\n  <p:ajax update=\"@form\" />\n </p:selectOneMenu>\n #{playerBean.selectedPlayerEnum}\n [#{playerBean.selectedPlayerEnum == enumpf | PlayerEnum.R_NADAL}]\n</h:form>\n

\n\n\n\n

Now, from OmniFaces’ perspective, things are very simple. Basically, we can import enums exactly as we have imported constants, via <o:importConstants/> tag handler. So, let’s see the above examples via OmniFaces now:

\n\n

// expose enum in EL\n<o:importConstants type=\"beans.PlayerEnum\" />\n<o:importConstants type=\"beans.PlayerEnum\" var=\"enumof\" />\n\n// Loop enum values:\n<ui:repeat value=\"#{enumof | PlayerEnum.values()}\" var=\"t\">\n #{t}\n</ui:repeat>        \n\n// Providing enum values as dropdown items and test R_NADAL item:\n<h:form>\n <p:selectOneMenu value=\"#{playerBean.selectedPlayerEnum}\">        \n  <f:selectItems value=\"#{enumof | PlayerEnum}\" />\n  <p:ajax update=\"@form\" />\n </p:selectOneMenu>\n #{playerBean.selectedPlayerEnum}\n [#{playerBean.selectedPlayerEnum == enumof | PlayerEnum.R_NADAL}]\n</h:form> \n\n// Providing enum values as dropdown items by var and test R_NADAL item:\n<h:form>\n <p:selectOneMenu value=\"#{playerBean.selectedPlayerEnum}\">        \n  <f:selectItems value=\"#{enumof | PlayerEnum.values()}\" \n                 var=\"t\" itemLabel=\"#{t.rank}\" itemValue=\"#{t}\" />\n  <p:ajax update=\"@form\" />\n </p:selectOneMenu>\n #{playerBean.selectedPlayerEnum}\n [#{playerBean.selectedPlayerEnum == enumof | PlayerEnum.R_NADAL}]\n</h:form>\n

\n\n\n\n

The complete application is named, PFOFImportEnums.

\n\n

Import public static methods with OmniFaces

\n\n

First of all you have to know that PrimeFaces Extensions doesn’t support this feature. In order to expose public static methods with a non void return type via EL, we can use the OmniFaces tag handler <o:importFunctions/>. This allows access to all functions of the given fully qualified name of a type in the Facelet scope using the usual EL functions syntax without the need to register them in *.taglib.xml file. We can use it exactly as <o:importConstants/>, by indicating in the required type attribute the fully qualified name of the class to import the public static non void methods for:

\n\n

<o:importFunctions type=\"beans.PlayerHelper\"/>\n<o:importFunctions type=\"beans.PlayerHelper\" var=\"funcof\"/>\n\nIs rank 1 in ATP available to play with me?\n<h:outputLink id=\"playerId\" value=\"#\">\n <h:outputText value=\"Rafael Nadal\" />\n</h:outputLink>\n<p:tooltip for=\"playerId\" value=\"Available: \n           #{funcof | PlayerHelper:isPlayerAvailable(1)}\" />\n

\n\n\n\n

The complete application is named, PFOFImportFunctions.

\n\n

Do not forget to check out the OmniFaces Showcase. There you can read a brief dissertation on multiple functions with exactly the same method name and some design notes.

\n\n

Chapter 10: Let’s convert data with PrimeFaces and OmniFaces

\n\n

In this chapter, we will explore the facilities provided by PrimeFaces and OmniFaces for converting data. We start with a section about how to use Java enums in UISelectMany components, and continue with how to work with <f:selectitems/> conversion of the submitted strings to their values, how to convert selection components which work directly via a List, how to work with a converter in an iterating component (e.g. <p:dataTable/>) and how to pass through conversion only the modified values. Moreover, we will discuss converters dependency injection and introduce a bunch of built-in PrimeFaces converters and OmniFaces converter functions.

\n\n

Using Java enums in `UISelectMany` components

\n\n

In this chapter we will discuss using Java enums in PrimeFaces UISelectMany components like <p:selectManyCheckbox/>, <p:multiSelectListbox/>,\n<p:selectManyButton/>, etc.Using an enum in UISelectMany components is not a usual day to day task, but it may be useful to have some basic knowledge about it. For example, letʹs say that you have an enum named, PlayerEnum, and you want to use it in an <p:selectManyCheckbox/>. If you bind the <p:selectManyCheckbox/> value to an array of PlayerEnum (PlayerEnum[]) then everything will work as expected, but if you bind it to a List of PlayerEnum (List<PlayerEnum>) then you may have some problems. Mainly, JSF/EL is not aware of the parameterized type of the List and will default to String. So, at some moment, it is very possible to try to operate over a String believing that it is actually a PlayerEnum, which will lead to ClassCastException. If you cannot simply rely on PlayerEnum[], then you must find a workaround to this, and you will most probably find out about JSF built‐in EnumConverter.

\n\n

The EnumConverter can help you in such cases if you are willing to extend it and to specify the enum type during runtime. This will solve the problem, but if you have a “bunch” of enums then you need to write a new converter for each of them. Well, this is definitely not a good approach, and the idea of developing a generic converter should be the next plan. OmniFaces - has already resolved this, and the result is named GenericEnumConverter. This is a generic custom and it is available by converter ID, omnifaces.GenericEnumConverter. Just specify it in the converter attribute of the multi‐selection component holding <f:selectItems/>. So, we have an enum named, PlayerEnum and we use it in a <p:selectManyCheckbox/>, as below:

\n\n

public enum PlayerEnum {\n\n FIRST, SECOND, THIRD;\n\n public Integer getRank() {\n  switch (name()) {\n   case \"FIRST\":\n    return 1;\n   case \"SECOND\":\n    return 2;\n   case \"THIRD\":\n    return 3;\n   default:\n    return 0;\n  }\n }\n}\n

\n\n\n\n

In order to use an enum, we first need to import it in to our page. This can be accomplish via OmniFaces <o:importConstants/> or via PrimeFaces Extensions, <pe:importEnum/>. More details about this topic are available in chapter Import constants, interfaces, enums and public static methods. So, you have to choose between:

\n\n

// OmniFaces\n<o:importConstants type=\"beans.PlayerEnum\" />\n\n// PrimeFaces Extensions\n<pe:importEnum type=\"beans.PlayerEnum\" \n               var=\"enumpf\" allSuffix=\"ALL_ENUM_VALUES\" /> \n

\n\n\n\n

Based on what you choose, you accordingly need to adjust the <f:selectItems/> value:

\n\n

<h:form>\n <p:selectManyCheckbox value=\"#{playerBean.players}\" \n                       converter=\"omnifaces.GenericEnumConverter\">\n  <!-- for PrimeFaces Extensions usage -->\n  <f:selectItems value=\"#{enumpf.ALL_ENUM_VALUES}\" />\n  <!-- for OmniFaces usage -->\n  <f:selectItems value=\"#{PlayerEnum}\" />\n  <p:ajax update=\"selectedPlayers\" />\n </p:selectManyCheckbox>           \n <p>\n  Selected:\n  <p:panel id=\"selectedPlayers\" style=\"width: 400px;\">\n   <ui:repeat value=\"#{playerBean.players}\" var=\"item\" varStatus=\"loop\">\n    #{item} (#{item['class'].simpleName})#{loop.last ? '' : ','}\n   </ui:repeat>\n  </p:panel>\n </p>           \n</h:form>   \n

\n\n\n\n

As you can see in the below figure the selected items are of type PlayerEnum as expected:

\n\n\n

\n\n\n

If you remove the omnifaces.GenericEnumConverter converter then you will see that items are considered of type String:

\n\n\n

\n\n\n

The complete application is named, GenericEnumConverter.

\n\n

The `<f:selectitems/>` and the conversion of the submitted strings to their values

\n\n

Usually, the <f:selectItems/> (or UISelectItems) is used in conjunction with the selection components (UISelectMany or UISelectOne), like <p:selectOneMenu/>, <p:selectManyListbox/>, <p:selectOneRadio/>, etc., to “populate” them with the list of selectable items (SelectItem instances). Typically, the value attribute of the <f:selectItems/> points to an array, a Collection or a map that “feeds” the selectable items with values (objects), which can directly, be instances of SelectItem or any other Java object (e.g. complex Java model objects (entities)), that will be encapsulated by JSF in SelectItem instances. In order to render each selectable item, JSF uses a string representation of the selectable item value (e.g. it may invoke the toString() method of the value (object)). Ideally, at postback, the selected/submitted strings should automatically be converted to the corresponding values.

\n\n

While the rendering process of the selectable items works smoothly, the conversion of the submitted strings to their corresponding values can be accomplished only if we indicate a custom converter which may need to do the job based on possibly expensive service/DAO operations. This problem is resolved by OmniFaces, which provides a general custom converter capable of automatically converting the submitted strings to corresponding values based on the toString() implementation of those values. Moreover, OmniFaces provides an alternative to this approach, which will convert based, on the position of the submitted string (index) in the list of values (each value has an associated index, which is actually its position in the list). Both of them will be\npresented in this section. First we need the base object (value), which can be the one listed below (Player):

\n\n

public class Player implements Serializable {\n\n private static final long serialVersionUID = 1L;\n\n private Long id;\n private String name;\n private String residence;\n private int age;\n\n public Player(Long id, String name, String residence, int age) {\n  this.id = id;\n  this.name = name;\n  this.residence = residence;\n  this.age = age;\n }\n\n // getters and setters\n\n @Override\n public int hashCode() {\n  // ...\n }\n\n @Override\n public boolean equals(Object obj) {\n  // ...\n }\n\n @Override\n public String toString() {\n  return id + \",\" + name + \",\" + residence + \",\" + age;\n }\n}\n

\n\n\n\n

Further, a managed bean contains a List<Player> (the Player instances from this List will “feed” the selectable items with values that the user will see as readable strings, as labels):

\n\n

@Named\n@ViewScoped\npublic class PlayerBean implements Serializable {\n\n private static final long serialVersionUID = 1L;\n\n private Player selected;\n // you can also use List<SelectItem> or SelectItem[]\n private List<Player> topfive;\n\n @PostConstruct\n public void init() {\n  topfive = new ArrayList<>();\n  topfive.add(new Player(1L, \"NOVAK DJOKOVIC\", \"Monte-Carlo\", 27));\n  topfive.add(new Player(2L, \"ROGER FEDERER\", \"Bottmingen\", 33));\n  topfive.add(new Player(3L, \"ANDY MURRAY\", \"London\", 27));\n  topfive.add(new Player(4L, \"MILOS RAONIC\", \"Monte Carlo\", 24));\n  topfive.add(new Player(5L, \"TOMAS BERDYCH\", \"Monte Carlo\", 29));\n }\n\n // getters and setters\n}\n

\n\n\n\n

Finally, we expose to the user the List<Player> via a selection component (e.g. <p:selectOneMenu/>):

\n\n

<h:form>\n <p:messages id=\"msgs\"/>\n <p:panelGrid columns=\"3\">\n  <p:outputLabel for=\"atpId\" value=\"Players: \" />\n  <p:selectOneMenu id=\"atpId\" value=\"#{playerBean.selected}\">\n   <f:selectItem itemLabel=\"Choose player\" noSelectionOption=\"true\" />\n   <f:selectItems value=\"#{playerBean.topfive}\" var=\"t\"\n                  itemLabel=\"#{t.name},#{t.age}\" itemValue=\"#{t}\" />\n  </p:selectOneMenu>            \n  <p:commandButton value=\"Select\" update=\"msgs :selectedId\"/>\n </p:panelGrid>\n</h:form>\nSelected: <h:outputText id=\"selectedId\" \n                        value=\"#{playerBean.selected.name},\n                               #{playerBean.selected.age}\"/>\n

\n\n\n\n

This will be rendered as expected but, if we select and submit a Player string representation, then an error will occur. This is a conversion error indicating that JSF cannot automatically convert the submitted string into the selected Player:

\n\n\n

\n\n\n

In order to fix this problem, we can write a custom converter. But, this means that for another type of entity (e.g. Coach) we will need another converter and so on. A more convenient approach consists of using the generic OmniFaces SelectItemsConverter. This converter is capable of automatically converting the submitted strings into the corresponding values (objects) based on the toString() implementation of these values (objects). As OmniFaces reveals, this converter can be used for different forms of the defining data to which SelectItems can bind, like List<ObjectInstances>, List<SelectItem>, SelectItem[], etc.

\n\n

In order to use it, you have to keep in mind the following steps:

\n\n

This converter is available by converter ID omnifaces.SelectItemsConverter. Just specify it in the converter attribute of the selection component holding <f:selectItems/>.
Make sure you provide a good toString() implementation.
Moreover provide a good implementation for hashCode() and equals() methods.

\n\n\n\n

We already have the Player entity witch has toString(), hashCode() and equals(), so all we need to do is to add the SelectItemsConverter in page:

\n\n

<h:form>\n ...\n <p:selectOneMenu id=\"atpId\" value=\"#{playerBean.selected}\" \n                  converter=\"omnifaces.SelectItemsConverter\">\n  <f:selectItem itemLabel=\"Choose player\" noSelectionOption=\"true\" />\n  <f:selectItems value=\"#{playerBean.topfive}\" var=\"t\" \n                 itemLabel=\"#{t.name},#{t.age}\" itemValue=\"#{t}\" />\n </p:selectOneMenu>            \n ...\n</h:form>\n

\n\n\n\n

Now, instead of an error we will get something like in figure below:

\n\n\n

\n\n\n

The complete application is named, SelectItemsConvertertoString.

\n\n

If you cannot provide an implementation of the toString() method (or you just donʹt need/want one), then extend the SelectItemsConverter and\noverride only the getAsString() method wherein the desired implementation is provided (you do not need to override the getAsObject() method). For example:

\n\n

@FacesConverter(\"mySelectItemsConverter\")\npublic class FooItemsConverter extends SelectItemsConverter {\n @Override\n public String getAsString(FacesContext context, \n                                        UIComponent component, Object value){\n  Long id = (value instanceof FooEntity) ? ((FooEntity) value).getId() : null;\n  return (id != null) ? String.valueOf(id) : null;\n }\n}\n

\n\n\n\n

Of course the above snippet of code is just a skeleton that should be adjusted accordingly. For example, we can provide the below implementation in our case:

\n\n

@FacesConverter(\"playerSelectItemsConverter\")\npublic class PlayerSelectItemsConverter extends SelectItemsConverter {\n\n @Override\n public String getAsString(FacesContext context, \n                                        UIComponent component, Object value) {\n  if (value instanceof Player) {\n      Long id = ((Player) value).getId();\n      if (id != null) {\n          String name = ((Player) value).getName();\n          String residence = ((Player) value).getResidence();\n          int age = ((Player) value).getAge();\n          return id + \",\" + name + \",\" + residence + \",\" + age;\n      }\n  }\n  return null;\n }\n}\n

\n\n\n\n

Furthermore, we need to add in page the playerSelectItemsConverter:

\n\n

<h:form>\n ...\n <p:selectOneMenu id=\"atpId\" value=\"#{playerBean.selected}\" \n                  converter=\"playerSelectItemsConverter\">\n  <f:selectItem itemLabel=\"Choose player\" noSelectionOption=\"true\" />\n  <f:selectItems value=\"#{playerBean.topfive}\" var=\"t\" \n                 itemLabel=\"#{t.name},#{t.age}\" itemValue=\"#{t}\" />\n </p:selectOneMenu>            \n ...\n</h:form>\n

\n\n\n\n

The result will be the same as in the figure above and the complete application is named, SelectItemsConverterByExtension.

\n\n

An alternative to `SelectItemsConverter`\n

\n\n

An alternative to SelectItemsConverter is to switch to SelectItemsIndexConverter, which will convert based on the selected index (position) in the list of values instead of the Object#toString(). This can be used under the following circumstances:

\n\n

This converter is available via the converter ID, omnifaces.SelectItemsIndexConverter. Just specify it in the converter attribute of the\nselection component holding <f:selectItems/>.
There is no need to rely on Object#toString() method of the object.
No need to extend the SelectItemsConverter when the Object#toString() method of the object cannot be used.
There is no need to expose the objectʹs unique key in its Object#toString().

\n\n\n\n

So, we can quickly adjust our case as below:

\n\n

<h:form>\n ...\n <p:selectOneMenu id=\"atpId\" value=\"#{playerBean.selected}\" \n                  converter=\"omnifaces.SelectItemsIndexConverter\">\n  <f:selectItem itemLabel=\"Choose player\" noSelectionOption=\"true\" />\n  <f:selectItems value=\"#{playerBean.topfive}\" var=\"t\" \n                 itemLabel=\"#{t.name},#{t.age}\" itemValue=\"#{t}\" />\n </p:selectOneMenu>            \n ...\n</h:form>\n

\n\n\n\n

The complete application is named, OFSelectItemsIndexConverter.

\n\n

Converting selection components which work directly via a `List`\n

\n\n

The SelectItemsConverter/SelectItemsIndexConverter presented earlier in this chapter are useful in conjunction with selection components which use SelectItems as the source for their selectable items. But, there are also selection components which work directly via a List of entities, like the PrimeFaces, <p:pickList/> and <p:autoComplete/>. For these kind of selection components, OmniFaces especially provides ListConverter and ListIndexConverter. Both of them can be used via <o:converter/> with converter ID omnifaces.ListConverter, respectively, omnifaces.ListIndexConverter.

\n\n

Let’s see how things work, but before do that let’s point out the fact that the ListConverter automatically converts based on the Object#toString() of the selected item (so ensure that you provide a good implementation of toString()), while the ListIndexConverter converts based on the position (index) of the selected item in the list instead of the Object#toString() of the selected item. In both cases it is recommended to provide a good implementation for hashCode() and equals(). Remember from the above section that this is a JSF requirement and it is not specific to ListConverter/ListIndexConverter.

\n\n

So, first we need the base object (value), which can be the one listed below (Player):

\n\n

public class Player implements Serializable {\n\n private static final long serialVersionUID = 1L;\n\n private int rank;\n private String name;\n\n public Player(int rank, String name) {\n  this.rank = rank;\n  this.name = name;\n }        \n\n // getters and setters\n\t\n @Override\n public int hashCode() {\n  // ...\n }\n\t\n @Override\n public boolean equals(Object obj) {\n  // ...\n }\n\t\n @Override\n public String toString() {\n  return \"Player{\" + \"rank=\" + rank + \", name=\" + name + '}';\n }        \n}\n

\n\n\n\n

Further, a managed bean contains a List<Player> (the Player instances from this List will “feed” the selectable items with values that the user will see as readable strings, as labels):

\n\n

@Named\n@ViewScoped\npublic class PlayerBean implements Serializable {\n\n private static final long serialVersionUID = 1L;\n\n private List<Player> players;\n private DualListModel<Player> model;\n\n @PostConstruct\n public void init() {\n  players = asList(\n   new Player(8, \"Tomas Berdych\"),\n   new Player(20, \"Jurgen Melzer\"),\n   ...\n  );\n\n  model = new DualListModel<>(\n          new ArrayList<>(players),\n          new ArrayList<Player>()\n  );\n }\n\n public List<Player> getPlayers() {\n  return players;\n }\n\n public DualListModel<Player> getModel() {\n  return model;\n }\n\n public void setModel(DualListModel<Player> model) {\n  this.model = model;\n }        \n}\n

\n\n\n\n

Finally, we expose to the user the List<Player> via a selection component that uses List (e.g. <p:pickList/>):

\n\n

<h:form>\n <p:messages id=\"msgs\"/>\n <p:pickList id=\"playersList\" value=\"#{playerBean.model}\" var=\"t\" \n             itemLabel=\"#{t.rank}.#{t.name}\" itemValue=\"#{t}\">                \n </p:pickList>\n <p:commandButton value=\"Submit\" \n                  update=\"msgs :selectedPlayersId\" style=\"margin-top:5px\" />\n</h:form>\n<p:panel id=\"selectedPlayersId\" style=\"width: 435px; margin-top: 5px;\">\n <strong>Selected players:</strong><br/>\n <ui:repeat value=\"#{playerBean.model.target}\" var=\"item\">\n  <h:outputText value=\"#{item.rank}.#{item.name}\" style=\"margin-right:5px\" />\n  <br/>\n </ui:repeat>\n</p:panel>\n

\n\n\n\n

This will be rendered as expected, but, if we select and submit a Player string representation, then an error will occur. In this case, the error will be Caused by: javax.el.PropertyNotFoundException: The class 'java.lang.String' does not have the property 'rank'. This reveals the fact that the submitted string is still a string … which is not desirable!

\n\n

In order to fix this problem, we can write a custom converter. But, this means that for another type of entity (e.g. Coach) we will need another converter and so on. An easy approach consists of using the OmniFaces ListConverter via <o:converter/> as below:

\n\n

...\n<p:pickList id=\"playersList\" value=\"#{playerBean.model}\" var=\"t\" \n            itemLabel=\"#{t.rank}.#{t.name}\" itemValue=\"#{t}\">\n <o:converter converterId=\"omnifaces.ListConverter\" \n              list=\"#{playerBean.players}\" />\n</p:pickList>\n...\n

\n\n\n\n

Or, if you don’t want/need to provide a good implementation to toString() method then you can rely on the ListIndexConverter as below:

\n\n

...\n<p:pickList id=\"playersList\" value=\"#{playerBean.model}\" var=\"t\" \n            itemLabel=\"#{t.rank}.#{t.name}\" itemValue=\"#{t}\">\n <o:converter converterId=\"omnifaces.ListIndexConverter\" \n              list=\"#{playerBean.players}\" />\n</p:pickList>\n...\n

\n\n\n\n

In both cases, a possible result will look like in the figure below:

\n\n\n

\n\n\n

The complete applications are named OFListConveter, respectively OFListIndexConverter.

\n\n

Working with a converter in an iterating component (e.g. `<p:dataTable/>`)

\n\n

Since <f:convertXxx>/<f:converter> are tag handlers, they are evaluated during construction/restoration of the component tree (in the Restore View phase). This means that the attributes of tag handlers are evaluated during view build time. On the other hand, UIComponents are executed during view render time (in the Render Response phase). This means that the attributes of UIComponents are evaluated during view render time. So, JSF converters and UIComponents do run at the same time, and their attributes are not evaluated at the same time, at least not the ones we want to discuss in this section (e.g. the id and binding attributes of UIComponents are evaluated during view build time, but are not relevant here).

\n\n

But, letʹs suppose that we are using a JSF converter inside an iterating component (e.g. <p:pickList/>, <p:dataTable/>, <h:dataTable/>, <ui:repeat/>). You may expect that, on every iteration, the converter is re‐evaluated and its attributes are getting new values, specific to the iteration step. For example, if the converter is used in a data table, you may expect that the converterʹs attributes are set every time a data table row is rendered. But, if you read carefully the above subsection, you will notice that this is not true. The expected behavior should be based on the fact that JSF will create only one converter instance per UIComponent (in the Restore View phase), and it will not re‐create or reset the converterʹs attributes each time the row is rendered. So, if we are using deferred value expressions for converterʹs attributes values, we will obtain undesirable behaviors or even exceptions.The solution consists of an artifact that will provide render time evaluation of converters attributes. So, instead of an\nevaluation on a per view build time basis, we want an evaluation on every access, like the UIComponents and bean properties. Another issue, specific to converters, implies the case when multiple <f:converter/> are used for the same input, because the converterMessage attribute of the parent input component applies to all converters. Even if each converter has certain tasks, they will produce the same error message.

\n\n

Furthermore, letʹs see an example that uses a converter in an iterating component. The aim is to apply a different currency symbol for the same amount each iteration; and for this we have used the built‐in <f:convertNumber /> converter with a ValueExpression for the currencySymbol attribute:

\n\n

@Named\n@RequestScoped\npublic class CurrencyBean implements Serializable {\n\n private static final long serialVersionUID = 1L;\n    \n private int amount;\n private List<String> currencies;\n\n @PostConstruct\n public void init() {\n  currencies = new ArrayList<>();\n\n  currencies.add(\"$\");\n  currencies.add(\"£\");\n  currencies.add(\"€\");\n        \n  amount=3000;\n }\n\n public List<String> getCurrencies() {\n  return currencies;\n }   \n\n public int getAmount() {\n  return amount;\n }        \n}\n

\n\n\n\n

Now, let’s apply the <f:convertNumber/> as below:

\n\n

<p:dataTable value=\"#{currencyBean.currencies}\" var=\"t\" style=\"width:80px;\">\n <p:column headerText=\"Value\">\n  <h:outputText value=\"#{currencyBean.amount}\">\n   <f:convertNumber type=\"currency\" currencySymbol=\"#{t}\" />\n  </h:outputText>\n </p:column>\n</p:dataTable>\n

\n\n\n\n

This will not work as expected because the <f:convertNumber/> will not be evaluated per iteration basis. Now, letʹs see the OmniFaces approach for solving these problems/issues. In order to support deferred value expressions in all attributes of converters, OmniFaces has extended the built‐in <f:converter/> with a tag handler that can be evaluated on a per‐iteration basis inside an iterating component. The <o:converter/> extends <f:converter/> with support for deferred value expressions in all attributes of converters. In order to use it, simply follow these steps:

\n\n

Replace your converter with <o:converter>.
Use the converterId attribute to indicate the CONVERTER_ID (e.g. javax.faces.DateTime, javax.faces.Number, javax.faces.Float,\njavax.faces.Enum, etc). For standard converters, you can find the CONVERTER_ID in the official documentation.
Place deferred value expressions in the desired attributes.

\n\n

<p:dataTable value=\"#{currencyBean.currencies}\" var=\"t\" style=\"width:80px;\">\n <p:column headerText=\"Value\">\n  <h:outputText value=\"#{currencyBean.amount}\">\n   <o:converter converterId=\"javax.faces.Number\" \n                type=\"currency\" currencySymbol=\"#{t}\" />\n  </h:outputText>\n </p:column>\n</p:dataTable>\n

\n\n\n\n\n

\n\n\n

The complete application is named, OFConverter.

\n\n

Passing through conversion only the modified values

\n\n

Before validating, if the EditableValueHolder has also attached a custom converter, then the getAsObject() method is invoked right before validating. Actually, the value returned by getAsObject() is the one that gets validated. The problem is that JSF will execute this step on each request without checking if the submitted value is really changed (as you will see in the next chapter, this is also true for validation). So, how do we pass only the modified values through conversion?

\n\n

Well, OmniFaces provides a custom converter that can be used as a template over regular JSF custom converters. Its name is ValueChangeConverter, and in order to understand its use, letʹs assume we have the following JSF custom converter skeleton:

\n\n

public class FooConverter implements Converter {\n @Override\n public Object getAsObject(FacesContext context, \n                                        UIComponent component, String value){\n  // ...\n }\n\n @Override\n public String getAsString(FacesContext context, \n                                        UIComponent component, Object value){\n  // ...\n }\n}\n

\n\n\n\n

Next, we will replace the implements Converter with extends ValueChangeConverter and rename the method from getAsObject() to getAsChangedObject().The getAsString() method of your converter remains unchanged:

\n\n

public class FooConverter extends ValueChangeConverter {\n @Override \n public Object getAsChangedObject(FacesContext context, \n                                  UIComponent component, String submittedValue) {\n  // ...\n }\n\n @Override \n public String getAsString(FacesContext context, \n                           UIComponent component, Object value){\n  // ...\n }\n}\n

\n\n\n\n

Done! Now, in the getAsChangedObject() method rewrite the exact same code that you have written in the getAsObject() method. The difference consists of the fact that the getAsChangedObject() method will be invoked by OmniFaces only when the submitted value is not equal to the model value passed through getAsString() method. In your page, attach your converter, FooConverter, to any EditableValueHolder component.

\n\n

Let’s have an example based on a simple <p:inputText/>. The user provides a player name and submits the form multiple times:

\n\n

<h:form>\n <p:messages id=\"msgs\"/>\n <p:panelGrid columns=\"3\">\n  <p:outputLabel for=\"nameId\" value=\"Player Name:\"/>\n  <p:inputText id=\"nameId\" value=\"#{playerBean.name}\" \n                           converter=\"playerConverter\"/>\n  <p:commandButton value=\"Send\" action=\"#{playerBean.nameAction()}\" \n                                update=\"@form\"/>           \n </p:panelGrid>\n</h:form>\n

\n\n\n\n

The PlayerConverter simply converts the submitted name in upper case (via getAsChangedObject()), and the model value in lower case (via getAsString()). This converter was written in respect to the OmniFaces instructions, so it looks like below:

\n\n

@FacesConverter(\"playerConverter\")\npublic class PlayerConverter extends ValueChangeConverter {\n\n @Override\n public Object getAsChangedObject(FacesContext fc, \n                                  UIComponent uic, String string) {\n        \n  // using OmniFaces shortcut\n  Messages.addGlobalInfo(\"Current value must be converted ...\");\n        \n  return string.toUpperCase();\n }\n\n @Override\n public String getAsString(FacesContext context, \n                           UIComponent component, Object value) {\n  return String.valueOf(value).toLowerCase();\n }\n}\n

\n\n\n\n

The converted value will reach the data model represented here by the PlayerBean class:

\n\n

@Named\n@SessionScoped\npublic class PlayerBean implements Serializable {\n\n private static final long serialVersionUID = 1L;\n    \n private String name;\n\n // getter and setter\n\n public void nameAction() {     \n  // or using OmniFaces shortcut\n  Messages.addGlobalInfo(\"Submitted value was successfully saved in bean ...\");\n }\n}\n

\n\n\n\n

Notice that we have signaled the moment when the flow passes through getAsChangedObject() via the faces message; Current value must be converted .... Moreover, when the flow reaches the PlayerBean#nameAction(), we will signal it via the faces message; Submitted value was successfully saved in bean .... Now, let’s see what happens in our case. We run the application and we type Rafael Nadal as the player name. After we submit the form for the first time, we see something like in the figure below:

\n\n\n

\n\n\n

The faces messages shows us that the submitted value has passed through the converter and reached the model. Now, submit the form again with the same value (don’t modify the name, keep it in lowercase) - and check the result:

\n\n\n

\n\n\n

It is obvious that this time the submitted value (rafael nadal) is equal to the model’s value passed through getAsString() method so the conversion (getAsChangedObject()) is skipped. This happens each time until we submit a different value. So, we practically skip the conversion of unmodified values.

\n\n\n\n

The complete application is named, ValueChangeConverter.

\n\n

Discussing converters dependency injection

\n\n

JSF 2.0 provides very modest support for injection in JSF artifacts. In JSF 2.1 very few JSF artifacts were injection targets. Starting with JSF 2.2, injection is possible in many more artifacts (check Mastering JavaServer Faces 2.2), but as the specification says, converters, validators and behaviors are still not injection targets. It seems that this will be available from JSF 2.3. Until JSF 2.3 comes out, there are a few tricks to obtain converters eligible for injection. First approach, is to present the converter as a managed bean as in the below skeleton:

\n\n

// Until JSF 2.3 - custom converter eligible for @Inject\n\n@Named(value=\"fooConverter\")\n@RequestScoped\npublic class FooConverter implements Converter {\n\n @Inject\n // artifact\n\n @Override\n public Object getAsObject(FacesContext context,\n                           UIComponent component, String value) {\n  ...\n  // use the injected artifact\n  ...\n }\n\n @Override\n public String getAsString(FacesContext context,\n                           UIComponent component, Object value) {\n  ...\n  // use the injected artifact\n  ...\n }\t\t \n}\n

\n\n\n\n

Usage example:

\n\n

<p:inputText value=\"#{bean_property}\" converter=\"#{fooConverter}\" />\n

\n\n\n\n\n\n

Another approach consists of relying on OmniFaces support. This approach brings @Inject and @EJB into custom converters (@FacesConverter) as it has been there forever. There is nothing to configure, no additional annotations, no need to modify your exiting converters. By simply using OmniFaces you get the bonus of having your custom converters eligible for injection. For example, the below code represents a typical JSF custom converter. Since OmniFaces is around, this custom converter supports @Inject and @EJB:

\n\n

@FacesConverter(\"fooConverter\")\npublic class FooConverter implements Converter {\n\n @EJB\n private FooEJB fooejb;\n\n @Inject\n private fooCDI foocdi;\n\n @Override\n public Object getAsObject(FacesContext context,\n                           UIComponent component, String value) {\n  ...\n  // work here with fooejb and foocdi\n  ...\n }\n\n @Override\n public String getAsString(FacesContext context,\n                           UIComponent component, Object value) {\n  ...\n  // work here with fooejb and foocdi\n  ...\n }\t\t \t \n}  \n

\n\n\n\n

Nevertheless, if you are using JSF 2.3 then you don’t need the above two approaches or any other workaround because JSF 2.3 comes with this feature out of the box. In order to test this facility you need to:

\n\n

specify a new attribute called managed on the corresponding annotations;
add in the WEB-INF folder the faces-config.xml with the JSF 2.3 XSD;

\n\n

So, in JSF 2.3 we have:

\n\n

@FacesConverter(value = \"fooConverter\", managed = true)\npublic class FooConverter implements Converter {\n\n @Inject\n // artifact\n\n @Override\n public Object getAsObject(FacesContext context,\n                           UIComponent component, String value) {\n  ...\n  // use the injected artifact\n  ...\n }\n\n @Override\n public String getAsString(FacesContext context,\n                           UIComponent component, Object value) {\n  ...\n  // use the injected artifact\n  ...\n }\t\t\n}  \n

\n\n\n\n

Further details are available here.

\n\n

Do you want more built-in converters?

\n\n

While PrimeFaces comes with JsonConverter, LocaleConverter and ConvertTimelineEvents via PrimeFaces Extensions, OmniFaces provides a collection of EL functions for data conversion. Here we have functions for:

\n\n

\nConvert a Set<E> to a List<E>\n
\nConvert a Map<K, V> to a List<Map.Entry<K, V>>\n
\nConvert a Iterable<E> to a List<E>\n
\nConvert an Iterable<E> to a DataModel<E>\n
\nJoin all elements of an array into a single string, separated by the a separator
\nJoin all elements of a collection into a single string, separated by the given separator
\nJoin all elements of the given map into a single string, separated by the given key-value pair separator and entry separator
\nSplit the given array into an array of subarrays of the given fragment size
\nSplit the given list into a list of sublists of the given fragment size
\nEncode given object as JSON
\nPrint the stack trace of the given exception

\n\n

These artifacts can be exploited together in many scenarios. For example, let’s suppose that we have the following Player entity:

\n\n

public class Player implements Serializable {\n\n private static final long serialVersionUID = 1L;\n\n private Long id;\n private String name;\n private String residence;\n private int age;\n\n public Player(Long id, String name, String residence, int age) {\n  this.id = id;\n  this.name = name;\n  this.residence = residence;\n  this.age = age;\n }\n ...\n // getters and setters\n ...\n}\n

\n\n\n\n

Furthermore, we have a simple managed bean that contains a List of players, as below:

\n\n

@Named\n@ViewScoped\npublic class PlayerBean implements Serializable {\n\n private static final long serialVersionUID = 1L;\n\n private Player selected;\n private List<Player> topfive;\n\n @PostConstruct\n public void init() {\n  topfive = new ArrayList<>();\n  topfive.add(new Player(1L, \"NOVAK DJOKOVIC\", \"Monte-Carlo\", 27));\n  ...\n }\t\n ...\n // getters and setters\n ...\n}\n

\n\n\n\n

Now, we want to display our list as JSON strings in a selection component. For this, we cannot use the PrimeFaces <pe:convertJson/> because this tag needs a parent of type ValueHolder. In order to obtain the JSON representation of each item from the list we can use the OmniFaces, of:toJson() function as below (this has the advantage that can be used in attributes like itemLabel):

\n\n

<p:selectOneListbox value=\"#{playerBean.selected}\" style=\"width: 450px;\">\n <f:selectItems value=\"#{playerBean.topfive}\" var=\"t\" \n                itemLabel=\"#{of:toJson(t)}\" itemValue=\"#{t}\"/>\n</p:selectOneListbox>\n

\n\n\n\n

The problem is that if we submit a selected player then we will get an error of type Conversion Error setting value 'beans.Player@409037b' for 'null Converter'. You should be familiar with this kind of error from The <f:selectitems/> and the conversion of the submitted strings to their values section above. The solution can be the generic OmniFaces omnifaces.SelectItemsConverter:

\n\n

<p:selectOneListbox value=\"#{playerBean.selected}\" style=\"width: 450px;\" \n                    converter=\"omnifaces.SelectItemsConverter\">                \n <f:selectItems value=\"#{playerBean.topfive}\" var=\"t\" \n                itemLabel=\"#{of:toJson(t)}\" itemValue=\"#{t}\"/>                \n</p:selectOneListbox> \n

\n\n\n\n

Or, the dedicated PrimeFaces Extensions <pe:convertJson/> converter:

\n\n

<p:selectOneListbox value=\"#{playerBean.selected}\" style=\"width: 450px;\">\n <f:selectItems value=\"#{playerBean.topfive}\" var=\"t\" \n                itemLabel=\"#{of:toJson(t)}\" itemValue=\"#{t}\"/>\n <pe:convertJson />  \n</p:selectOneListbox> \n

\n\n\n\n\n\n

The result will look like in the figure below:

\n\n\n

\n\n\n

The complete application is named, PFOFJsonConversion.

\n\n

Chapter 11: Let’s validate data with PrimeFaces and OmniFaces

\n\n

In this chapter we will explore the facilities provided by PrimeFaces and OmniFaces for validating data. We start with a section on customizing Bean Validation error messages, continue on with PrimeFaces validation features (including client-side validation) and we end it with OmniFaces powerful set of validators, including cross-field and class level validators. Moreover, we will also cover injection in validators and converters.

\n\n

Display the label of the component where a constraint violation originated from

\n\n

Starting with the Java EE 6 platform a new server‐side validation model is available. It is known as JavaBeans Validation (or ‘Bean Validation’ for short), and it consists of a set of constraints applicable via annotations at field, method or class level of a JavaBeans\ncomponent (e.g. managed bean). The validation API is in the javax.validation package and the constraints are grouped under the javax.validation.constraints package (e.g. @NotNull, @Min, @Max, @Size, etc). We can use multiple constraints on a single JavaBeans component object and any validation failures will be displayed by the <p:messages/> tag.

\n\n

The default messages for built‐in constraints (Bean Validation also supports user defined constraints) can be found in a resource bundle named ValidationMessages. Commonly, this is a properties file named, ValidationMessages.properties and resides in the default package of the application (class-path root). Locale variants of this are added by appending an underscore and the locale prefix to the base name of the file (e.g. ValidationMessages_de.properties). These messages can be customized, and localized as you wish.

\n\n

As you know, JSF comes with its own validation error messages which can be customized pretty easily using several techniques specific to JSF. Bean Validation is also a very flexible API that comes with its own techniques for customizing error messages. It is important to know these techniques, especially when you want to obtain error messages that cannot be produced by the default Bean Validation implementation. For example, if a component causes a validation failure, then the label associated with this component can appear only in the front or behind the error message. This is possible thanks to the bundle key, javax.faces.validator.BeanValidator.MESSAGE (exemplified in the next subsection). But, how about placing the label anywhere in the message body? Well, this is a job for OmniFaces because by default, Bean Validation cannot do this!

\n\n

We can start from a simple form that contains two fields, name and surname. Both of these will be validated using Bean Validation annotations ‐ the messages will be displayed via <p:messages/> and <p:growl/>:

\n\n

<h:form>\n <p:messages/>\n <p:growl/>\n <p:panelGrid columns=\"2\">\n  <p:outputLabel for=\"name\" value=\"First Name\"/>\n  <p:inputText id=\"name\" label=\"name\" value=\"#{dataBean.name}\" />\n\n  <p:outputLabel for=\"surname\" value=\"Last Name\" />\n  <p:inputText id=\"surname\" label=\"surname\" value=\"#{dataBean.surname}\" />\n\n  <p:commandButton value=\"Register\" update=\"@form\"/>                    \n </p:panelGrid>            \n <h:outputText value=\"Thank you !\" rendered=\"#{facesContext.postback \n                                    and not facesContext.validationFailed}\" />\n</h:form>  \n

\n\n\n\n

The DataBean uses the Bean Validation constraints for restricting the size of the name and surname to between 2 and 25 characters. For this, we simply annotate the name and surname fields with @Size constraint:

\n\n

@Named\n@RequestScoped\npublic class DataBean {\n\n @Size(min = 2, max = 25)\n private String name;\n\n @Size(min = 2, max = 25)\n private String surname;\n\n // getters and setters\n ...\n}\n

\n\n\n\n

Now, if the validation fails, you will see these two messages (these are default messages, and you cannot say which belongs to name and which to surname):

\n\n\n

\n\n\n

We can fix this by adding the label of the component that causes the validation constraint violation. Configure a message bundle that contains the key javax.faces.validator.BeanValidator.MESSAGE:

\n\n

javax.faces.validator.BeanValidator.MESSAGE={1}: {0}\n

\n\n\n\n

Notice that this is a parameterized message with two placeholders. The placeholder {0} represents the error message (e.g. size must be between 2 and 25) as created by the Bean Validation runtime, while {1} refers to the label of the component that caused the\nvalidation constraint violation. So, we can drop to any of these two placeholders, or combine them to place the label in front of behind the message. Below, shows them placed behind the message:

\n\n

javax.faces.validator.BeanValidator.MESSAGE={0}; {1}\n

\n\n\n\n

Now, the messages will look like below:

\n\n

size must be between 2 and 25; name\nsize must be between 2 and 25; surname\n

\n\n\n\n

But, how about shaping a message into a more human readable shape, as below:

\n\n

The size of name must be between 2 and 25 characters\n

\n\n\n\n

Well, this is not easy to obtain, because even if we override the default Bean Validation messages file (ValidationMessages.properties) we still cannot simply “slip” the component label in there. Something like below will not work (in\nValidationMessages.properties, override the javax.validation.constraints.Size.message):

\n\n

javax.validation.constraints.Size.message = \nThe size of {my label placeholder} must be between {min} and {max} characters\n

\n\n\n\n

In order to accomplish this task we can use the OmniFaces the JsfLabelMessageInterpolator custom message interpolator. There are two steps that must be accomplished to use it:

\n\n

1.Create a /META-INF/validation.xml file in WAR with the following content:

\n\n

<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<validation-config xmlns=\"http://jboss.org/xml/ns/javax/validation/configuration\"\n                   xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n                   xsi:schemaLocation=\"http://jboss.org/xml/ns/javax/validation/\n                       configuration validation-configuration-1.0.xsd\">\n\n <message-interpolator>\n  org.omnifaces.validator.JsfLabelMessageInterpolator\n </message-interpolator>\n</validation-config>\n

\n\n\n\n

For Java EE 7, it is possible that you would need to update the version from below:

\n\n

<validation-config xmlns=\"http://jboss.org/xml/ns/javax/validation/configuration\"\n                   xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n                   xsi:schemaLocation=\"http://jboss.org/xml/ns/javax/validation/\n                       configuration validation-configuration-1.1.xsd\" \n                       version=\"1.1\">\n <message-interpolator>\n  org.omnifaces.validator.JsfLabelMessageInterpolator\n </message-interpolator>\n</validation-config>\n

\n\n\n\n

2.In the class-path root (the default package of the application), add the ValidationMessage.properties file, and override the desired messages. Use the OmniFaces, {jsf.label}, placeholder for indicating the place(s) in message where you expect to see the label. In the below example, the {jsf.label} placeholder will be replaced by text, name or surname ‐ the two labels from our form:

\n\n

javax.validation.constraints.Size.message = The size of {jsf.label} must be\nbetween {min} and {max} characters\n

\n\n\n\n

This will produce the messages from the figure below:

\n\n\n

\n\n\n\n\n\n\n

<context-param>\n <param-name> \n  javax.faces.INTERPRET_EMPTY_STRING_SUBMITTED_VALUES_AS_NULL \n </param-name>\n <param-value>true/false</param-value>\n</context-param>\n

\n\n\n\n

The complete application is named, OFLabelMessageInterpolator.

\n\n

Customize the PrimeFaces client-side bean validation error messages

\n\n

As you probably know, PrimeFaces supports Bean Validation. Actually, PrimeFaces comes with a client side validation framework integrated with Bean Validation Specification. Basically, PrimeFaces obtains via a set of classes (located in org.primefaces.validate.bean) the server side validation constraints for each type of supported validators. These constrains will be used in a JavaScript file named beanvalidation.js to perform the validation on client side and generate the corresponding messages.

\n\n

For example, let’s suppose that we have our bean that uses @size. PrimeFaces extracts the constraints for @Size via org.primefaces.validate.bean.SizeClientValidationConstraint, like below:

\n\n

package org.primefaces.validate.bean;\n\nimport java.util.HashMap;\nimport java.util.Map;\nimport javax.validation.constraints.Size;\nimport javax.validation.metadata.ConstraintDescriptor;\nimport org.primefaces.util.HTML;\n\npublic class SizeClientValidationConstraint \n             implements ClientValidationConstraint {\n\n private static final String MESSAGE_METADATA = \"data-p-size-msg\";\n private static final String MESSAGE_ID = \n                \"{javax.validation.constraints.Size.message}\";\n\n public Map<String, Object> getMetadata(ConstraintDescriptor \n                                         constraintDescriptor) {\n       \n  Map<String, Object> metadata = new HashMap<String, Object>();\n  Map attrs = constraintDescriptor.getAttributes();\n  Object message = attrs.get(\"message\");\n\n  metadata.put(HTML.VALIDATION_METADATA.MIN_LENGTH, attrs.get(\"min\"));\n  metadata.put(HTML.VALIDATION_METADATA.MAX_LENGTH, attrs.get(\"max\"));\n\n  if (!message.equals(MESSAGE_ID)) {\n      metadata.put(MESSAGE_METADATA, message);\n  }\n\n  return metadata;\n }\n\n public String getValidatorId() {\n  return Size.class.getSimpleName();\n }\n}\n

\n\n\n\n

Now, the extracted constrains are used in beanvalidation.js, as below:

\n\n

if (window.PrimeFaces) {\n    ...\n    PrimeFaces.locales.en_US.messages[\"javax.validation.constraints.\n                       Size.message\"] = \"size must be between {0} and {1}\";\n\n    PrimeFaces.validator.Size = {\n    MESSAGE_ID: \"javax.validation.constraints.Size.message\",\n      validate: function(d, f) {\n       if (f !== null) {\n           var e = d.val().length,\n           c = d.data(\"p-minlength\"),\n           a = d.data(\"p-maxlength\"),\n           b = PrimeFaces.util.ValidationContext;\n\n           if (e < c || e > a) {\n               throw b.getMessageBV(d, this.MESSAGE_ID, \n                                    d.data(\"p-size-msg\"), c, a)\n           }\n       }\n      }\n    };\n    ...  \n};\n

\n\n\n\n

So this will produce the default Bean Validation error message. Now, let’s suppose that we want to change this message and involve more information in it. For example, let’s suppose that we want to provide in the error message the label of the invalid component exactly as the OmniFaces JsfLabelMessageInterpolator does.

\n\n

In order to accomplish this task we have several approaches. One of these approaches consists of overriding the SizeClientValidationConstraint for extracting the validated input label and overriding the client-side implementation to take this label into account.

\n\n

So, first we will write a new SizeClientValidationConstraint like below:

\n\n

import static org.omnifaces.util.Components.getCurrentComponent;\nimport static org.omnifaces.util.Components.getLabel;\n...\n\npublic class SizeClientValidationConstraint \n             implements ClientValidationConstraint {\n\n private static final String MESSAGE_METADATA = \"data-p-size-msg\";\n private static final String MESSAGE_ID = \n                      \"{javax.validation.constraints.Size.message}\";\n\n public Map<String, Object> getMetadata(ConstraintDescriptor \n                                        constraintDescriptor) {\n       \n  Map<String, Object> metadata = new HashMap<String, Object>();\n  Map attrs = constraintDescriptor.getAttributes();\n  Object message = attrs.get(\"message\");\n\n  metadata.put(HTML.VALIDATION_METADATA.MIN_LENGTH, attrs.get(\"min\"));\n  metadata.put(HTML.VALIDATION_METADATA.MAX_LENGTH, attrs.get(\"max\"));\n  metadata.put(HTML.VALIDATION_METADATA.LABEL, getLabel(getCurrentComponent()));\n\n  if (!message.equals(MESSAGE_ID)) {\n      metadata.put(MESSAGE_METADATA, message);\n  }\n\n  return metadata;\n }\n\n public String getValidatorId() {\n  return Size.class.getSimpleName();\n }\n}\n

\n\n\n\n

Thanks to OmniFaces utilities, we can obtain the label of the current validated input component via Components#getCurrentComponent() and Components#getLabel(). This save us from writing a good chunk of code! Further, we simply add the label in the metadata under HTML.VALIDATION_METADATA.LABEL.

\n\n

Now, on client-side, we adjust the JavaScript code to use this label in error validation messages for @Size:

\n\n

<script type=\"text/javascript\">\n //<![CDATA[\n PrimeFaces.locales.en_US.messages[\"javax.validation.constraints.Size.message\"] =\n  \"The size of {0} must be between {1} and {2} characters\";\n PrimeFaces.validator.Size = {\n  MESSAGE_ID: \"javax.validation.constraints.Size.message\",\n  validate: function (d, f) {\n  if (f !== null) {\n      var e = d.val().length,\n          c = d.data(\"p-minlength\"),\n          a = d.data(\"p-maxlength\"),\n          l = d.data(\"p-label\");\n          b = PrimeFaces.util.ValidationContext;\n\n          if (e < c || e > a) {\n              throw b.getMessageBV(d, this.MESSAGE_ID, \n                                   d.data(\"p-size-msg\"), l, c, a)\n          }\n   }\n  }\n };\n //]]>  \n</script>\n

\n\n\n\n

Done! The complete application is named, PFAlterClientValidationMsg.

\n\n

“Force” the user to tick a checkbox

\n\n

The PrimeFaces <p:selectBooleanCheckbox/> tag is an elegant approach for dealing with tasks that can be resolved via a boolean value (e.g. check if the user has accepted the terms and conditions, ask the user if he wants to be kept logged in for a period of time, ask the user if his password should be remembered, etc). In such cases, when the user doesnʹt tick the checkbox, we need to render an error/warning message to inform him that is mandatory to tick that checkbox. For example, if the user must tick the checkbox signaling that he consents to the terms and conditions, then we need a validation layer before the business logic. Obviously, if we ask the user to inform us about remembering his password, we can deal with it without the validation layer, by supposing that an unticked checkbox ergo, “donʹt remember my password”. Furthermore, we are interested in the case when we need to “force” the user to tick the checkbox.

\n\n

Now, we add the built‐in required=\"true\" attribute to the <p:selectBooleanCheckbox/>. We need this attribute for ensuring that the user will tick the terms and conditions checkbox. As we said, if the user doesnʹt tick the checkbox then we will return an error message of type You must accept terms and conditions!. The problem is that this will not work as expected! The error message never appears because the built‐in required validator will not cause a validation failure, no matter if the checkbox was ticked or not. So, in case of <p:selectBooleanCheckbox/>, the presence of the required validator is pointless.

\n\n

The below snippet of code should follow a simple scenario: if the checkbox (termsId) is unticked, then the message, You must accept terms and conditions! should appear. Until the user ticks this checkbox, JSF should stop processing the current request in the Process Validations phase.

\n\n

<h:form>                        \n <p:panelGrid columns=\"3\">\n  <p:outputLabel for=\"termsId\" value=\"Tick terms and conditions:\" />\n  <p:selectBooleanCheckbox id=\"termsId\" required=\"true\"\n     requiredMessage=\"You must accept terms and conditions!\"/>\n  <p:commandButton value=\"Submit\" update=\"@form\"/>                \n </p:panelGrid>            \n <p:message for=\"termsId\" />\n <h:outputText value=\"Thank you !\" \n               rendered=\"#{facesContext.postback \n                           and not facesContext.validationFailed}\" />\n</h:form>\n

\n\n\n\n

Unfortunately, the required validator has no effect. Check the below figure (notice that the checkbox is not ticked):

\n\n\n

\n\n\n

OmniFaces comes with a custom validator especially for filling up this JSF gap named, RequiredCheckboxValidator. This validator is available via, omnifaces.RequiredCheckboxValidator ID, and it can be used as any JSF built‐in validator, via <f:validator/> tag or validator attribute. Both of the below examples are correct:

\n\n

// using \"validator\" atribute\n<p:selectBooleanCheckbox id=\"termsId\" required=\"true\"\n                         validator=\"omnifaces.RequiredCheckboxValidator\"\n                         requiredMessage=\"You must accept terms & conditions!\"/>\n\n// using \"<f:validator/>\" tag\n<p:selectBooleanCheckbox id=\"termsId\" required=\"true\"\n                         requiredMessage=\"You must accept terms & conditions!\">\n <f:validator validatorId=\"omnifaces.RequiredCheckboxValidator\" />\n</p:selectBooleanCheckbox>   \n

\n\n\n\n

Now, the result will look like in the figure below:

\n\n\n

\n\n\n\n\n

javax.faces.component.UIInput.REQUIRED = \n {0}: Sorry, you have to tick terms and conditions!\n

\n\n\n\n\n\n

The complete application is named, PFOFSelectBooleanCheckbox.

\n\n

Passing through validation only the modified values

\n\n

In a nutshell, JSF custom validation is a straightforward process that validates submitted EditableValueHolders along with their attached custom validators, when an EditableValueHolder value violates the applied validation constraints, throws a ValidatorException. This exception encapsulates an error message signaling to the user that the validation has failed (the error messages are typically rendered via <p:message/>/<p:messages/>). By default, this process is applied in the Process Validations phase, which is executed for each postback.

\n\n

Sometimes, custom validation implies more than checking if a value is a valid e‐mail, phone number, respect a regular expression, etc. For example, you may need to validate the submitted data against a database, which is usually a time consuming task that should take place as fast as possible and with a minimum impact on communication with the database.

\n\n

Imagine that we submit a bulk of data that is successfully validated against a database, and is stored in managed beans (e.g. in view scope). Further, via another postback, we submit the same bulk of data, but this time with\nseveral values modified (not all), and the validation takes place again.

\n\n

Now, you might think that only those modified values will pass through validation, since you already know that the rest of values are valid (they successfully passed through validation on the previous request). Well, this is not true, because JSF doesnʹt distinguish between modified and unmodified values; it simply validates all of them again (both requests will spend the same time in the Process Validations phase, and they will ʺhitʺ the database equally!). If the unmodified values are quite many and/or the validation process is pretty difficult, then this phase will take longer than necessary.

\n\n

Let’s see the below simple example. First, we have an input that has attached a custom validator:

\n\n

<h:form id=\"myFormId\">            \n Name: \n <p:inputText id=\"nameId\" value=\"#{myBean.name}\" validator=\"myValidator\"/>\n <p:commandButton value=\"Send\" action=\"#{myBean.nameAction()}\" update=\":msgs\"/>\n</h:form>\n<p:messages id=\"msgs\"/>\n

\n\n\n\n

The custom validator simply simulates some validation failures and report them via a faces message:

\n\n

@FacesValidator(\"myValidator\")\npublic class MyValidator implements Validator {\n\n @Override\n public void validate(FacesContext context, UIComponent component, \n                           Object value) throws ValidatorException {\n\n  // simulate validation failure\n  Random random = new Random();\n  if (random.nextInt(10) < 5) {\n      // use OmniFaces shortcut\n      throw new ValidatorException(Messages.\n       createError(\"The validation has randomly failed. Submit again ...\"));\n  }\n }\n}\n

\n\n\n\n

Furthermore, MyBean reports the success of storing the submitted (and validated) value:

\n\n

@Named\n@SessionScoped\npublic class MyBean implements Serializable {\n\n private static final long serialVersionUID = 1L;\n\n private String name;\n\n // getter/setter\n\n public void nameAction() {               \n  // use OmniFaces shortcut\n  Messages.addGlobalInfo(\"Submitted value was successfully saved in bean ...\");\n }\n}\n

\n\n\n\n

In the figure below, you can see that the same value passes through validator at each submit. Since we randomly force the validation failure, you will see the error message from time to time, depending on the random flag value:

\n\n\n

\n\n\n

Especially for fixing this issue, OmniFaces provides a custom validator named, ValueChangeValidator. In order to use it, let’s suppose that we have the following generic custom validator:

\n\n

public class MyValidator implements Validator {\n @Override \n public void validate(FacesContext context, UIComponent component,\n                           Object value) throws ValidatorException {\n // ... \n }\n}  \n

\n\n\n\n

Next, we will replace the implements Validator with extends ValueChangeValidator, and rename the method from validate() to validateChangedObject():

\n\n

public class MyValidator extends ValueChangeValidator {\n @Override \n public void validateChangedObject(FacesContext fc, UIComponent uic,\n                                 Object o) throws ValidatorException {\n  // ...\n }\n}\n

\n\n\n\n

Now, in the validateChangedObject() method we write exactly the same code that you have written in the validate() method. The difference consists of the fact that the validateChangedObject() method will be invoked by OmniFaces only when the submitted value is not equal to the model value of the validated component. In the page, attach your validator, MyValidator, to any EditableValueHolder component:

\n\n

@FacesValidator(\"myValidator\")\npublic class MyValidator extends ValueChangeValidator {\n\n @Override\n public void validateChangedObject(FacesContext fc, \n                   UIComponent uic, Object o) throws ValidatorException {\n        \n  // use the OmniFaces shortcut\n  Messages.addGlobalInfo(\"Current value is not equal with the submitted value, \n                                                    so validation neeeded ...\");\n\n  // simulate validation failure\n  Random random = new Random();\n  if (random.nextInt(10) < 5) {\n         \n      // use the OmniFaces shortcut\n      throw new ValidatorException(Messages.\n       createError(\"The validation has randomly failed. Submit again ...\"));\n  }\n }\n}\n

\n\n\n\n

In the figure below, you notice that the validation takes place only when the submitted value is not equal to the model value:

\n\n\n

\n\n\n\n\n

The complete application is named, ValueChangeValidator.

\n\n

Validating unique column in `UIData`\n

\n\n

It is common practice to have a <h:form/> that contains a <p:dataTable/> for displaying a set of tabular data as a combination of plain text and UIInputs (for data that can be altered (e.g. edited) by the user). Furthermore, an UICommand is responsible for submitting the data table containing the user’s modifications and updating the model. Most probably, the data provided by the user must be validated, and in such cases we can attach built-in/custom validators using the validator attribute or the <f:validator/> tag to the corresponding UIInputs. In order to see the error messages next to the rows that contain invalid data, a column is especially reserved for displaying error messages via <p:message/> tag. At each postback, the data table is submitted and all UIInputs will be validated (one by one will pass through the indicated validator(s)) and the error messages (if any) will appear in the reserved column. I think that this is a common scenario that every JSF developer has implemented in his projects.

\n\n

But, in our scenario, each submitted UIInput is validated independently (individually) of the rest of submitted UIInputs, which is not always the desired behavior. For example, if the user edits a list of names, ZIP codes, e‐mails, etc, then a validation constraint must ensure that the list contains only unique values. This means that each submitted UIInput must be validated with respect to the rest of the submitted UIInputs, and signal to the user when a duplicate value is found. This is a typical case of cross-field validation. In this section, you will see how OmniFaces validates if the given UIInput component in an UIData component has a unique value throughout all rows, also those not visible by pagination.

\n\n

In the code lines, our scenario may look like below:

\n\n

<h:form id=\"form\">            \n <p:panel style=\"text-align: center;\">\n  <p:dataTable id=\"custom\" value=\"#{barcelonaSquadBean.players}\" var=\"t\">\n   <p:column>                   \n    <p:inputText id=\"playerNameId\" value=\"#{t.name}\" required=\"true\"/>\n   </p:column>                            \n   <p:column>\n    <p:message for=\"playerNameId\"/>\n   </p:column>\n  </p:dataTable>    \n </p:panel>\n\n <p:panel style=\"text-align: center; margin-top: 10px;\">\n  <p:commandButton actionListener=\"#{barcelonaSquadBean.someAction()}\" \n                   update=\"@form\" value=\"Subscribe Team\"/>\n  <p:messages id=\"msgs\"/>\n </p:panel>\n</h:form>\n

\n\n\n\n

This snippet of code will work in conjunction with BarcelonaSquadBean to return the result from the image below (for brevity, we cropped the image but basically there are 11 different player names):

\n\n\n

\n\n\n

Now, let’s duplicate a player name. For example, let’s type Abidal in place of Pique and let’s submit the modified team. The result will be like in the figure below:

\n\n\n

\n\n\n

The issue consist off the fact that we have the same player name at positions three and five, Abidal. Obviously, we cannot have the same player twice, but as you can see the received message is an INFO that confirms that the team was successfully updated.

\n\n

OmniFaces comes with a custom validator especially for filling up this JSF gap. This validator is named ValidateUniqueColumn and is exposed to page authors via <o:validateUniqueColumn/> tag. The main characteristics of this validator are:

\n\n

It validates if the given UIInput component in an UIData component has a unique value throughout all rows.
It includes in the validation the data that is not visible in case of using pagination, as long as it is in the data model.
It works directly on the data model (e.g. when lazy loading is used, the data model contains a subset of data; only this subset counts on validation).
It signals only the first invalid row on which the value is actually changed.
A faces message will be added on the client ID of the input component in this invalid row.
Its default message is of type (the {0} placeholder represents the label of the input component, while the {1} placeholder represents the 1‐based row index of the data model):

\n\n

{0}: Please fill out a unique value for the entire column. \nDuplicate found in row {1}\n

\n\n\n\n

If you need to include a custom message then just use the message attribute:

\n\n

<o:validateUniqueColumn message=\"custom message here\" />\n

\n\n\n\n

So, we can use <o:validateUniqueColumn/> in our case like below:

\n\n

<p:dataTable id=\"custom\" value=\"#{barcelonaSquadBean.players}\" var=\"t\">\n <p:column>                   \n  <p:inputText id=\"playerNameId\" value=\"#{t.name}\" required=\"true\">            \n   <o:validateUniqueColumn message=\"Duplicate player not allowed!\"/>\n  </p:inputText>                     \n </p:column>                            \n <p:column>\n  <p:message for=\"playerNameId\"/>\n </p:column>\n</p:dataTable>\n

\n\n\n\n

This time we cannot submit the team with duplicate players. Check figure below:

\n\n\n

\n\n\n

The complete application is named, ValueUniqueColumnTable.

\n\n

As we just said, the <o:validateUniqueColumn/> validates if the given UIInput component in an UIData component has a unique value throughout all rows. This means that we can use it for any other PrimeFaces component based on UIData. For example, we can also use it for <p:ring/>. We have adjusted the example above to use a <p:ring/> instead of <p:dataTable/>:

\n\n

<p:panel>\n <p:ring id=\"custom\" value=\"#{barcelonaSquadBean.players}\" var=\"t\">\n  <p:outputPanel style=\"text-align: center; height:90%;\" layout=\"block\">\n   <p:inputText value=\"#{t.name}\" required=\"true\" \n                style=\"width: 90%; height: inherit;\">            \n    <o:validateUniqueColumn message=\"Duplicate player not allowed!\"/>\n   </p:inputText>                     \n  </p:outputPanel>                            \n </p:ring>    \n</p:panel>\n

\n\n\n\n

Checkout the image from figure below:

\n\n\n

\n\n\n

The complete application is named, ValueUniqueColumnRing.

\n\n

Validation control and cross-field validation (class level validation)

\n\n

Starting with Java EE 6, the JavaBeans Validation (or shortly, Bean Validation, or JSR 303), represents a new validation model based on adding validation constrains as annotations attached to a field, method or class level of a JavaBeans component. For example, in a JSF bean, you just place the desired annotations (e.g. @Size, @NotNull, @Pattern, etc.) on a field level (by default, JSF cannot validate the class or method level constraints). At the end, you will obtain a centralized place for bean validation constraints that works with no further adjustments.

\n\n

Server-side validation control per-`UICommand` or `UIInput`\n

\n\n

The <f:validateBean/> tag is optional, and its main goal is to provide a “fine tune” validation. Mainly, this tag provides validation control on a per‐form or a per‐request basis. It allows groups (subsets) of constraints to be indicated via the validationGroups attribute as a comma‐separated list of fully‐qualified class names, and allows per‐input disabling of validation via a disabled flag attribute. Do not fall into the trap of using <f:validateBean/> without attributes, because it is simply useless. Use it only when you need to modify the default values of its attributes.

\n\n

You have to be aware that, from a JSF perspective, there are several limitations to using Bean Validation. One of them involves the fact that JSF cannot validate class or method level constraints (so called, cross‐field validation), only field constrains. Another one consists of the fact the <f:validateBean/> allows validation control on per‐form or a per‐request basis, not on a per‐UICommand or UIInput. In order to achieve more control, you have to be open to writing boilerplate code, and to shape custom solutions that works only on specific scenarios. Except the part that has to do with validating the method level constrains, the rest of the problems listed here are solved by OmniFaces, ValidateBean (<o:validateBean/>).

\n\n

Letʹs suppose that we have a simple form that contains two input fields representing the name and e‐mail of a website member or admin. Next to these inputs, we have two buttons, one with label Contact Member and another one with label Contact Admin. When the user clicks on the first button, he will “contact” the specified website member, and when he clicks on the second button, he will “contact” the specified website admin.

\n\n

<h:form>   \n <p:panelGrid columns=\"2\">\n  <p:outputLabel for=\"nameId\" value=\"Name\"/>\n  <p:inputText id=\"nameId\" value=\"#{contactBean.name}\"/>                \n  \n  <p:outputLabel for=\"emailId\" value=\"E-mail\"/>\n  <p:inputText id=\"emailId\" value=\"#{contactBean.email}\"/>                      \n  \n  <p:commandButton value=\"Contact Member\" action=\"contact_member\" ajax=\"false\"/>\n  <p:commandButton value=\"Contact Admin\" action=\"contact_admin\" ajax=\"false\"/>\n </p:panelGrid>        \n <p:messages/>\n</h:form> \n

\n\n\n\n

For a website member/admin, the name input should not violate any of the constraints defined in a group named, MemberContactValidationGroup. Moreover, for a website member/admin the email input should not violate any of the constrains defined in a group AdminContactValidationGroup. Even more noteworthy, we have a constraint over email in the default group (applicable to members and admins).

\n\n

Next, we should attach these constraints to the name and email inputs, but, we need to obtain the following functionality:

\n\n

If the user clicks on the Contact Member button, then the validation should take into account only constraints from the default group and from the MemberContactValidationGroup, and ignore the constraints from the AdminContactValidationGroup.
If the user clicks on the Contact Admin admin button, then the validation should take into account only constraints from the default group and from the AdminContactValidationGroup, and ignore the constraints from the MemberContactValidationGroup.

\n\n

First, in order to accomplish this we need to annotate the ContactBean properly. So, here it is:

\n\n

@Named\n@RequestScoped\npublic class ContactBean implements Serializable {\n\n private static final long serialVersionUID = 1L;\n @Size.List({\n  @Size(min = 3, max = 20, \n        message=\"(member)# please enter a valid name (between 3-20 characters)\", \n        groups=beans.MemberContactValidationGroup.class),\n  @Size(min = 6, max = 10, \n        message=\"(admin)# please enter a valid name (between 6-10 characters)\", \n        groups=beans.AdminContactValidationGroup.class)\n  })\n  @Pattern(regexp = \"(admin)[a-zA-Z0-9]*\", \n           message=\"(admin)# please enter a valid name (start with admin)\", \n           groups=beans.AdminContactValidationGroup.class)\n  private String name;\n\n  @Size(min = 1, message = \"Please enter the e-mail !\")\n  @Pattern.List({\n   @Pattern(regexp = \"[a-zA-Z0-9]+@[a-zA-Z0-9]+\\\\.[a-zA-Z0-9]+\", \n            message = \"(member)# please enter a valid formated e-mail\", \n            groups = beans.MemberContactValidationGroup.class),\n   @Pattern(regexp = \"(admin)+@[a-zA-Z0-9]+\\\\.[a-zA-Z0-9]+\", \n            message = \"(admin)# please enter a valid e-mail (start with admin@)\",\n            groups = beans.AdminContactValidationGroup.class)\n   })\n   private String email;\n\n // getters and setters\n}\n

\n\n\n\n

Furthermore, we need OmniFaces help. The features brought by OmniFaces via <o:validateBean/> tag are exactly what we need to solve our use case. While the standard <f:validateBean/> only allows validation control on a per‐form or a per‐request basis, the <o:validateBean/> allows us to control bean validation on a per‐UICommand or UIInput component basis.

\n\n

For example, we can obtain the claimed functionality via <o:validateBean/>, like below:

\n\n

<h:form>   \n <p:panelGrid columns=\"2\">\n  <p:outputLabel for=\"nameId\" value=\"Name\"/>\n  <p:inputText id=\"nameId\" value=\"#{contactBean.name}\"/>                \n  \n  <p:outputLabel for=\"emailId\" value=\"E-mail\"/>\n  <p:inputText id=\"emailId\" value=\"#{contactBean.email}\"/>                      \n  \n  <p:commandButton value=\"Contact Member\" action=\"contact_member\" ajax=\"false\">\n   <o:validateBean validationGroups=\"javax.validation.groups.Default, \n                                     beans.MemberContactValidationGroup\"/>\n  </p:commandButton>\n  <p:commandButton value=\"Contact Admin\" action=\"contact_admin\" ajax=\"false\">\n   <o:validateBean validationGroups=\"javax.validation.groups.Default, \n                                     beans.AdminContactValidationGroup\"/>\n  </p:commandButton>           \n </p:panelGrid>        \n <p:messages/>\n</h:form> \n

\n\n\n\n

In the below screenshots you can see two tests. In the first test the Contact Member will not cause any error messages, while the Contact Admin will cause error messages specific to AdminContactValidationGroup:

\n\n\n

\n\n\n\n

\n\n\n

In the second test, both buttons will cause error messages specific to the corresponding group:

\n\n\n

\n\n\n\n

\n\n\n

The complete application is named OFValidateBeanUICommand.

\n\n\n\n

Server-side cross-field validation (class level validation)

\n\n

Furthermore, letʹs suppose that the provided email should always start with the provided name (respect the condition: getEmail().startsWith(getName()). This is basically a cross‐field constraint that can be applied via a class level constraint. But, JSF doesnʹt support this kind of constraints. We can name \nthe annotation specific to this constraint @ValidContact and assign it to ContactBean as below:

\n\n

@Named\n@RequestScoped\n@ValidContact(groups = ContactGroup.class)\npublic class ContactBean implements Serializable {\n ...\n}\n

\n\n\n\n

The <f:validateBean/> does not provide anything related to bean validation, so we can “jump” directly to <o:validateBean/>. Right from the start, you should know that <o:validateBean/> supports an attribute named method, which indicates if this is a copy bean validation (default) or an actual bean validation:

\n\n

\nCopy bean validation ‐ When the method attribute is not present, this is the default validation method (method=\"validateCopy\"). Basically, the idea is to make a copy of the object to validate at the end of the Process Validations phase, set the values retrieved from the input components on it, and perform class level validation on the copy. If the validation is a success, then the original bean is updated and a potential action method is invoked, otherwise “jump” directly to Render Response phase ‐ does not update the model if validation errors occur. Of course, making a copy can be considered a drawback to this approach.
\nActual bean validation ‐ This method must be explicitly set via method=\"validateActual\". In this case, the validation happens at the end of the Update Model Values, so the original bean is first updated with the values retrieved from the input components, afterwards validated. The main drawback here consists of the fact that we may pollute the model with invalid values, so the bean developer must perform a “manual” check. A potential action method will be invoked independently on the validation result, because the flow continues with the Invoke Application phase.

\n\n

In case of using copy bean validation, OmniFaces tries a suite of strategies for determining the copy mechanism. By default, OmniFaces comes with an interface (Copier) that is to be implement by classes that know how to copy an object, and provides four implementations (strategies) of it:

\n\n

\nCloneCopier ‐ This is an implementation of Copier capable of dealing with beans that implements Cloneable interface and provides cloning support.
\nSerializationCopier ‐ This is an implementation of Copier capable of dealing with beans that implement the Serializable interface and support serialization according to the rules of that interface.
\nCopyCtorCopier ‐ This is an implementation of Copier capable of dealing with beans that have an additional constructor (next to the default constructor) taking a single argument of its own type that initializes itself with the values of that passed in type.
\nNewInstanceCopier ‐ This is an implementation of Copier capable of dealing with beans that have a public no arguments (default) constructor. Every official JavaBean satisfies this requirement. Note that in this case no copy is made of the original bean, but just a new instance is created.

\n\n

Besides these four implementations (strategies), OmniFaces comes with another one named, MultiStrategyCopier, which basically defines the order of applying the above copy strategies: CloneCopier, SerializationCopier, CopyCtorCopier, NewInstanceCopier. When one of these strategies obtains the desired copy, the process stops. If you already know the strategy that should be used (or, you have your own Copier strategy (e.g. a partial object copy strategy), then you can explicitly specify it via copier attribute (e.g. copier=\"org.omnifaces.util.copier.CopyCtorCopier\").

\n\n

Now, letʹs focus on our cross‐field validation: (getEmail().startsWith(getName()). In order to obtain a class level constraint based on this condition, we need to follow several steps.First, wrap this constrains in a custom Bean Validation validator (e.g. ContactValidator):

\n\n

@Override\npublic boolean isValid(ContactBean value, ConstraintValidatorContext context) {\n return value.getEmail().startsWith(value.getName());\n}\n

\n\n\n\n

Second, define a proper annotation for it (e.g. ValidContact, used as @ValidContact). Furthermore, annotate the desired bean (optionally, add it in a group(s)):

\n\n

@Named\n@RequestScoped\n@ValidContact(groups = ContactGroup.class)\npublic class ContactBean implements Serializable {\n ... \n private String name; \n private String email;\n ...\n // getters/setters\n}\n

\n\n\n\n

Finally, use the <o:validateBean/> to indicate the bean to be validated via the value attribute (javax.el.ValueExpression that must evaluate to java.lang.Object), and the corresponding groups (this is optional). Additionally, you can specify the actual bean validation, via the method attribute, and a Copier, via the copier attribute:

\n\n

<h:form>\n ...\n <o:validateBean value=\"#{contactBean}\" validationGroups=\"beans.ContactGroup\" />\n</h:form>\n

\n\n\n\n

In the figure below, you can see an example when the cross-field validation fails:

\n\n\n

\n\n\n

The complete application is named, OFValidateBeanCrossField.

\n\n\n\n

PrimeFaces cross-field client side validation

\n\n

PrimeFaces comes with an out-of-the-box example of cross-field validation for the Password component. Basically, for the input password you need to use the match attribute and point to the ID of the confirmation input password. Further, PrimeFaces will ensure that the validation will succeed only if the two passwords are the same. But, this is an “isolated” case, because we cannot do this for other cases (e.g. like getEmail().startsWith(getName()).

\n\n

On the other hand, PrimeFaces comes with a very useful support for client side validation based on JSF validation API and Bean Validation. Further we will focus on Bean Validation, and say that this can be successfully used as long as we don’t need cross-field validation or class level validation. This means that the validation constraints placed on the class level will not be recognized by PrimeFaces client side validation.

\n\n

But, for accomplishing this task, we will slightly adapt the PrimeFaces custom client side validation. First, we create ValidContact annotation:

\n\n

@Documented\n@Constraint(validatedBy = {ContactValidator.class})\n@ClientConstraint(resolvedBy=ValidContactClientConstraint.class)\n@Target({ANNOTATION_TYPE, METHOD, FIELD})\n@Retention(RUNTIME)\npublic @interface ValidContact {\n\n String message() default \"Invalid contact !\";\n\n Class<?>[] groups() default {};\n\n Class<? extends Payload>[] payload() default {};\n}\n

\n\n\n\n

Further, in our bean we annotate the proper fields (name and email) with this annotation - we need to do this to indicate the fields that enter in cross-field validation; so, annotate each such field:

\n\n

@Named\n@RequestScoped\npublic class ContactBean implements Serializable {\n\n private static final long serialVersionUID = 1L;\n   \n @ValidContact(message = \"The name should be used in e-mail as name@domain.com!\")\n private String name;\n   \n @ValidContact(message = \"The e-mail should be of type name@domain.com!\")\n private String email;\n\n // getters and setters\n\n public void someAction() {\n  // OmniFaces approach\n  Messages.addGlobalInfo(\"Thank you for your contacts!\");\n }\n}\n

\n\n\n\n

Now, we write the validator. Here, we need to also keep the name until the validator gets the e-mail. For this, we can use the faces context attributes, as below:

\n\n

public class ContactValidator \n             implements ConstraintValidator<ValidContact, String> {\n\n @Override\n public void initialize(ValidContact constraintAnnotation) {\n  // NOOP\n }\n\n @Override\n public boolean isValid(String value, ConstraintValidatorContext context) {\n  if (Faces.getContextAttribute(\"NAME_VALUE\") == null) {\n      Faces.setContextAttribute(\"NAME_VALUE\", value);\n  } else {\n      return value.startsWith(String.valueOf(\n             Faces.getContextAttribute(\"NAME_VALUE\")));\n  }\n  return true;\n }\n}\n

\n\n\n\n

Now, we have to accomplish the client-side validation. Again, notice that we store the name into an array (you can add more fields here) and wait for the e-mail:

\n\n

<script type=\"text/javascript\">\n var data = [];\n PrimeFaces.validator['ValidContact'] = {\n  MESSAGE_ID: 'org.primefaces.examples.validate.contact.message',\n  validate: function (element, value) {\n   if (data.length == 0) {\n       data.push(value);\n   } else {\n       if (!value.startsWith(data[0])) {\n           var msgStr = element.data('p-contact-msg'),\n           msg = msgStr ? {summary: msgStr, detail: msgStr} :\n            vc.getMessage(this.MESSAGE_ID);\n           throw msg;\n       }\n   }\n  }\n };\n</script>\n

\n\n\n\n

Finally, we ensure the presence of ClientValidationConstraint implementation:

\n\n

public class ValidContactClientConstraint implements ClientValidationConstraint {\n\n public static final String MESSAGE_METADATA = \"data-p-contact-msg\";\n\n public Map<String, Object> getMetadata(ConstraintDescriptor \n                                        constraintDescriptor) {\n  Map<String, Object> metadata = new HashMap<String, Object>();\n  Map attrs = constraintDescriptor.getAttributes();\n  Object message = attrs.get(\"message\");\n\n  if (message != null) {\n      metadata.put(MESSAGE_METADATA, message);\n  }\n\n  return metadata;\n }\n\n public String getValidatorId() {\n  return ValidContact.class.getSimpleName();\n }\n}\n

\n\n\n\n

Here it is a valid case:

\n\n\n

\n\n\n

And an invalid case:

\n\n\n

\n\n\n

The complete application is named, PFValidateBeanCrossField.

\n\n

Multiple field validators

\n\n

By its construction and usage, the JSF validation model is not applicable for cross‐field validation. You already saw the mighty OmniFaces ValidateBean, so is time to check a list with more cross‐field validators that are not available in JSF:

\n\n

\n<o:validateAll/> validates if ALL of the given UIInput components have been filled out.
\n<o:validateAllOrNone/> validates if at least ALL of the given UIInput components have been filled out or that NONE of the given UIInput components have been filled out.
\n<o:validateEqual/> validates if ALL of the given UIInput components have the same value.
\n<o:validateOne/> validates if ONLY ONE of the given UIInput components have been filled out.
\n<o:validateOneOrMore/> validates if at least ONE of the given UIInput components has been filled out.
\n<o:validateOneOrNone/> validates if ONLY ONE of the given UIInput components has been filled out or that NONE of the given UIInput components have been filled out.
\n<o:validateOrder/> validates if the values of the given UIInput respects a specified order.
\n<o:validateUnique/> validates if ALL of the given UIInput components have a unique value.
\n<o:validateMultiple/> validate multiple fields by either a custom validator method.

\n\n

In order to use this bunch of validators you need to know several general usage rules. Each of these validators must be placed in the same form with the inputs that they validate. You must choose the right place in the form depending on your needs and with respect to the fact that the components will be validated in the order as they appear in the form. Most probably, you will place them at the beginning (before the components to validate) or at the end (after the components to validate) of the form, which means that you have two distinct cases: if you place them at the beginning then they will be executed before any of the component’s own validators. If this validator fails, then the component’s own validators will not be fired; if they are placed at the end, then it will be executed after any of the component’s own validators. If any of them fails, then these validators will not be executed. Obviously, placing the validator somewhere between components is not a good practice and may lead to weird behaviors.

\n\n

All these validators require an attribute named components. The value of this attribute is a string of client IDs separated by space referencing the UIInputs that need to be validated. You will shortly see it at work, but before that let’s say that, by default, in an invalidating case, all of the referenced components will be marked invalid and a faces message will be added on the client ID of this validator component. The default message can be changed by the optional message attribute. Any {0} placeholder in the message will be substituted with a comma separated string of labels of the referenced input components. You can also change the default message in the message bundle file as identified by <message-bundle/> in faces-config.xml. The messages keys are:

\n\n

// ValidateAll\norg.omnifaces.component.validator.ValidateAll=\n    {0}: Please fill out all of those fields\n\n// ValidateAllOrNone\norg.omnifaces.component.validator.ValidateAllOrNone=\n    {0}: Please fill out all or none of those fields\n\n// ValidateEqual\norg.omnifaces.component.validator.ValidateEqual=\n    {0}: Please fill out the same value for all of those fields\n\n// ValidateMultiple\norg.omnifaces.component.validator.ValidateMultiple=\n    {0}: Invalid value\n\n// ValidateOne\norg.omnifaces.component.validator.ValidateOne=\n    {0}: Please fill out only one of those fields\n\n// ValidateOneOrMore\norg.omnifaces.component.validator.ValidateOneOrMore=\n    {0}: Please fill out at least one of those fields\n\n// ValidateOneOrNone\norg.omnifaces.component.validator.ValidateOneOrNone=\n    {0}: Please fill out only one or none of those fields\n\n// ValidateOrder\norg.omnifaces.component.validator.ValidateOrder=\n    {0}: Please fill out the values of all those fields in order\n\n// ValidateUnique\norg.omnifaces.component.validator.ValidateUnique=\n    {0}: Please fill out a unique value for all of those fields\n

\n\n\n\n

We also have the following optional attributes:

\n\n

We can use invalidateAll=\"false\" to only mark those components which are actually invalid as invalid. In case of for example “input all” or “input all or none” validation, that would only be the fields which are left empty.
The faces message can also be shown for all of the referenced components using showMessageFor=\"@all\".
The faces message can also be shown for only the invalidated components using showMessageFor=\"@invalid\".
The faces message can also be shown for specific components referenced by a space separated collection of their client IDs in showMessageFor attribute.
The showMessageFor attribute defaults to @this. The validator can be disabled by the disabled attribute. It accepts a request based EL expression.

\n\n

Validating if ALL `UIInput`s have been filled out

\n\n

The ValidateAll validates if ALL of the given UIInput components have been filled out. For example, the below form will be valid only if you fill each input:

\n\n

<h:form>            \n <p:messages/>\n <p:panelGrid columns=\"2\">\n  <p:outputLabel for=\"nameId\" value=\"Name:\"/>\n  <p:inputText id=\"nameId\" value=\"#{playerBean.name}\"/>\n\n  <p:outputLabel for=\"surnameId\" value=\"Surname:\"/>\n  <p:inputText id=\"surnameId\" value=\"#{playerBean.surname}\"/>\n\n  <p:outputLabel for=\"emailId\" value=\"E-mail:\"/>\n  <p:inputText id=\"emailId\" value=\"#{playerBean.email}\"/>\n\n  <p:outputLabel for=\"addressId\" value=\"Address:\"/>\n  <p:inputTextarea id=\"addressId\" value=\"#{playerBean.address}\"/>\n\n  <p:outputLabel for=\"handId\" value=\"Hand:\"/>\n  <p:selectOneRadio id=\"handId\" value=\"#{playerBean.hand}\">\n   <f:selectItem itemLabel=\"Left\" itemValue=\"Left\" />\n   <f:selectItem itemLabel=\"Right\" itemValue=\"Right\" />            \n  </p:selectOneRadio>\n\n  <p:commandButton value=\"Submit\" update=\"@form\"/>\n </p:panelGrid>\n\n <o:validateAll id=\"all\" \n                components=\"nameId surnameId emailId addressId handId\" />\n</h:form>\n

\n\n\n\n\n

\n\n\n

The complete application is named, ValidateAllInputs_1.

\n\n

Or, if you want to display a custom error message next to each component via <p:message/>, then you need to use the message and showMessageFor=\"@all\" attributes:

\n\n

<h:form>                        \n <p:panelGrid columns=\"3\">\n  <p:outputLabel for=\"nameId\" value=\"Name:\"/>\n  <p:inputText id=\"nameId\" value=\"#{playerBean.name}\"/>\n  <p:message for=\"nameId\"/>\n\n  <p:outputLabel for=\"surnameId\" value=\"Surname:\"/>\n  <p:inputText id=\"surnameId\" value=\"#{playerBean.surname}\"/>\n  <p:message for=\"surnameId\"/>\n\n  <p:outputLabel for=\"emailId\" value=\"E-mail:\"/>\n  <p:inputText id=\"emailId\" value=\"#{playerBean.email}\"/>\n  <p:message for=\"emailId\"/>\n\n  <p:outputLabel for=\"addressId\" value=\"Address:\"/>\n  <p:inputTextarea id=\"addressId\" value=\"#{playerBean.address}\"/>\n  <p:message for=\"addressId\"/>\n\n  <p:outputLabel for=\"handId\" value=\"Hand:\"/>\n  <p:selectOneRadio id=\"handId\" value=\"#{playerBean.hand}\">\n   <f:selectItem itemLabel=\"Left\" itemValue=\"Left\" />\n   <f:selectItem itemLabel=\"Right\" itemValue=\"Right\" />            \n  </p:selectOneRadio>\n  <p:message for=\"handId\"/>\n\n  <p:commandButton value=\"Submit\" update=\"@form\"/>\n </p:panelGrid>\n\n <o:validateAll id=\"all\" components=\"nameId surnameId emailId addressId handId\" \n                message=\"Please fill out all fields\" showMessageFor=\"@all\" />\n</h:form> \n

\n\n\n\n\n

\n\n\n

The complete application is named, ValidateAllInputs_2.

\n\n\n\n\n

\n\n\n

Validating if at least ALL or that NONE of `UIInput`s components have been filled out

\n\n

The ValidateAllOrNone validates if at least ALL of the given UIInput components have been filled out or that NONE of the given UIInput components have been filled out. For example, the below form will be valid only if you fill all inputs or none of them:

\n\n

// the form content is the same as in the previous section\n<h:form>                        \n ...\n <o:validateAllOrNone id=\"allornone\" \n                      components=\"nameId surnameId emailId addressId handId\" />\n</h:form>\n

\n\n\n\n\n

\n\n\n

The complete application is named, ValidateAllOrNone_1.

\n\n

You can also invalidate only the empty fields and show message message only on invalid fields as below:

\n\n

<h:form>                        \n ...\n <o:validateAllOrNone id=\"allornone\" \n                      components=\"nameId surnameId emailId addressId handId\" \n                      invalidateAll=\"false\" showMessageFor=\"@invalid\"\n                      message=\"Please fill up all fields or none\"/>\n</h:form>\n

\n\n\n\n\n

\n\n\n

The complete application is named, ValidateAllOrNone_2.

\n\n

Validating if ALL of the given `UIInput` components have the same value

\n\n

The <o:validateEqual/> validates if ALL of the given UIInput components have the same value. PrimeFaces has such a behavior for the <p:password/> component for allowing the user to confirm the provided password. The OmniFaces approach is more general, and ideally it works for any number of inputs and all kinds of inputs. For example, we can ensure that the user enters/selects the same player name in the below form like this:

\n\n

<h:form> \n <p:messages/>\n <p:panelGrid columns=\"2\">\n  <p:outputLabel for=\"name1Id\" value=\"Name:\"/>\n  <p:inputText id=\"name1Id\" value=\"#{playerBean.name1}\"/>\n\n  <p:outputLabel for=\"name2Id\" value=\"Confirm name:\"/>\n  <p:inputText id=\"name2Id\" value=\"#{playerBean.name2}\"/>\n\n  <p:outputLabel for=\"name3Id\" value=\"Name:\"/>\n  <p:selectOneRadio id=\"name3Id\" value=\"#{playerBean.name3}\">\n   <f:selectItem itemLabel=\"Roger Federer\" itemValue=\"Roger Federer\" />\n   <f:selectItem itemLabel=\"Rafael Nadal\" itemValue=\"Rafael Nadal\" />            \n  </p:selectOneRadio>                                         \n\n  <p:commandButton value=\"Submit\" update=\"@form\"/>\n </p:panelGrid>\n\n <o:validateEqual id=\"allequal\" components=\"name1Id name2Id name3Id\" />\n</h:form>\n

\n\n\n\n\n

\n\n\n

By selecting the Rafael Nadal radio button you will successfully validate the form.

\n\n

The complete application is named, ValidateEqual.

\n\n

Validating if ONLY ONE of the given `UIInput` components has been filled out

\n\n

The <o:validateOne/> validates if ONLY ONE of the given UIInput components has been filled out. For example, let’s suppose that you want to collect player’s Facebook, Twitter or Instagram id:

\n\n

<h:form> \n <p:messages/>\n <p:panelGrid columns=\"2\">\n  <p:outputLabel for=\"twitterId\" value=\"Twitter:\"/>\n  <p:inputText id=\"twitterId\" value=\"#{playerBean.twitter}\"/>\n\n  <p:outputLabel for=\"facebookId\" value=\"Facebook:\"/>\n  <p:inputText id=\"facebookId\" value=\"#{playerBean.facebook}\"/>\n\n  <p:outputLabel for=\"instagramId\" value=\"Instagram:\"/>\n  <p:inputText id=\"instagramId\" value=\"#{playerBean.instagram}\"/>\n\n  <p:commandButton value=\"Submit\" update=\"@form\"/>\n </p:panelGrid>\n\n <o:validateOne id=\"one\" components=\"twitterId facebookId instagramId\" />\n</h:form>\n

\n\n\n\n\n

\n\n\n

By typing a single id (Facebook, Twitter or Instagram) you will successfully validate the form.

\n\n

The complete application is named, ValidateOne.

\n\n

Validating if ONLY ONE or NONE of the given `UIInput` components has been filled out

\n\n

The <o:validateOneOrNone/> validates if ONLY ONE of the given UIInput components has been filled out or that NONE of the given UIInput components has been filled out. If in the previous section we require only one of the Facebook, Twitter or Instagram id, now let’s require one or accept none:

\n\n

<h:form> \n ...\t\n <o:validateOneOrNone id=\"oneornone\" \n                      components=\"twitterId facebookId instagramId\" />\n</h:form>\n

\n\n\n\n\n

\n\n\n

By typing a single id (Facebook, Twitter or Instagram) or none you will successfully validate the form.

\n\n

The complete application is named, ValidateOneOrNone.

\n\n

Validating if ALL of the given `UIInput` components have a unique value

\n\n

The <o:validateUnique/> validates if ALL of the given UIInput components have a unique value. Again, we can use the Facebook, Twitter or Instagram example from above. This time we “force” the user to provide at least two ids and to be, as it should, unique values.

\n\n

<h:form> \n ...\t\n <o:validateUnique id=\"unique\" components=\"twitterId facebookId instagramId\" />\n</h:form>\n

\n\n\n\n\n

\n\n\n

Since Facebook and Instagram are both empty spaces they are practically considered the same. In order to obtain a valid form, the user must also at least provide Facebook’s or Instagram’s id which should be different by than Twitter’s id.

\n\n

The complete application is named, ValidateUnique.

\n\n

Validating if at least ONE of the given `UIInput` components has been filled out

\n\n

The <o:validateOneOrMore/> validates if at least ONE of the given UIInput components has been filled out. For example, below we allow the user to provide some ratings; he/she must provide at least one rating:

\n\n

<h:form> \n <p:messages/>\n Rating Rafael Nadal favorite shots:\n <p:panelGrid columns=\"2\">\n  <p:outputLabel for=\"serveId\" value=\"Serve:\"/>\n  <p:rating id=\"serveId\" value=\"#{playerBean.serve}\" />\n\n  <p:outputLabel for=\"forehandId\" value=\"Forehand:\"/>\n  <p:rating id=\"forehandId\" value=\"#{playerBean.forehand}\"/>\n\n  <p:outputLabel for=\"backhandId\" value=\"Backhand:\"/>\n  <p:rating id=\"backhandId\" value=\"#{playerBean.backhand}\"/>\n\n  <p:commandButton value=\"Submit\" update=\"@form\"/>\n </p:panelGrid>\n\n <o:validateOneOrMore id=\"oneormore\" \n                      components=\"serveId forehandId backhandId\" />\n</h:form>\n

\n\n\n\n\n

\n\n\n

By providing at least one rating you will successfully validate the form.

\n\n

The complete application is named, ValidateOneOrMore.

\n\n

Validating if the given `UIInput` components are specified in a certain order

\n\n

The <o:validateOrder/> validates if the values of the given UIInput components, as specified in the components’s attribute, are in the order specified by the type attribute which accepts the following values:

\n\n

\nlt (defaults): from least to greatest, without duplicates.
\nlte: from least to greatest, allowing duplicates (equal values next to each other).
\ngt: from greatest to least, without duplicates.
\ngte: from greatest to least, allowing duplicates (equal values next to each other).

\n\n

For example, let’s suppose that we submit the career prize money of a tennis player for 2014, 2015 and 2016. Obviously, the three inserted values must be entered after the lte rule. Below we have shaped this scenario via three PrimeFaces Sliders and ValidateOrder:

\n\n

<h:form> \n <p:messages/>\n <p:panelGrid columns=\"3\">                \n  <p:panelGrid columns=\"1\" style=\"margin-bottom: 10px\">\n   <h3 style=\"margin-top: 0\">Rafa career prize money until 2014:</h3>\n   <h:outputText id=\"output2014\" value=\"#{playerBean.prizemoney2014}\">\n    <f:convertNumber currencySymbol=\"$\" type=\"currency\" />\n   </h:outputText>\n   <p:inputText id=\"value2014\" value=\"#{playerBean.prizemoney2014}\"/>\n   <p:slider for=\"value2014\" display=\"output2014\" minValue=\"10000\" \n             maxValue=\"100000000\" style=\"width: 200px\"/>                \n  </p:panelGrid>   \n\n  <p:panelGrid columns=\"1\" style=\"margin-bottom: 10px\">\n   <h3 style=\"margin-top: 0\">Rafa career prize money until 2015:</h3>\n   <h:outputText id=\"output2015\" value=\"#{playerBean.prizemoney2015}\">          \\\n          \n    <f:convertNumber currencySymbol=\"$\" type=\"currency\" />\n   </h:outputText>\n   <p:inputText id=\"value2015\" value=\"#{playerBean.prizemoney2015}\"/>\n   <p:slider for=\"value2015\" display=\"output2015\" minValue=\"10000\" \n             maxValue=\"100000000\" style=\"width: 200px\"/>                \n  </p:panelGrid>\n\n  <p:panelGrid columns=\"1\" style=\"margin-bottom: 10px\">\n   <h3 style=\"margin-top: 0\">Rafa career prize money until 2016:</h3>\n   <h:outputText id=\"output2016\" value=\"#{playerBean.prizemoney2016}\">\n    <f:convertNumber currencySymbol=\"$\" type=\"currency\" />\n   </h:outputText>\n   <p:inputText id=\"value2016\" value=\"#{playerBean.prizemoney2016}\"/>\n   <p:slider for=\"value2016\" display=\"output2016\" minValue=\"10000\" \n             maxValue=\"100000000\" style=\"width: 200px\"/>                \n  </p:panelGrid>           \n </p:panelGrid>\n            \n <o:validateOrder id=\"order\" type=\"lte\" \n                  components=\"value2014 value2015 value2016\" \n                  message=\"Please provide the prize money in order.\" />\n           \n <p:commandButton value=\"Submit\" update=\"@form\"/>\n</h:form>\n

\n\n\n\n\n

\n\n\n

Since the career prize money in 2015 is smaller than in 2016 the validation failed.

\n\n

The complete application is named, ValidateOrderSlider.

\n\n

Let’s have another scenario! Let’s suppose that we need to schedule the matches that will play in a day. We practically have three matches per day and we need to submit the time of each match will begin at in ascending order:

\n\n

<h:form> \n <p:messages/>\n <p:panelGrid columns=\"3\">\n  <h3 style=\"margin-top: 0\">First match of the day starts at:</h3>\n  <p:outputLabel for=\"firstMatchId\" value=\"Time:\" />\n  <p:calendar id=\"firstMatchId\" value=\"#{playerBean.firstMatch}\" \n              pattern=\"HH:mm\" timeOnly=\"true\"  />\n                \n  <h3 style=\"margin-top: 0\">Second match of the day starts at:</h3>\n  <p:outputLabel for=\"secondMatchId\" value=\"Time:\" />\n  <p:calendar id=\"secondMatchId\" value=\"#{playerBean.secondMatch}\" \n              pattern=\"HH:mm\" timeOnly=\"true\"  />\n                \n  <h3 style=\"margin-top: 0\">Third match of the day starts at:</h3>\n  <p:outputLabel for=\"thirdMatchId\" value=\"Time:\" />\n   <p:calendar id=\"thirdMatchId\" value=\"#{playerBean.thirdMatch}\" \n               pattern=\"HH:mm\" timeOnly=\"true\"  />\n  </p:panelGrid>\n  <o:validateOrder id=\"order\" type=\"lt\" \n                   components=\"firstMatchId secondMatchId thirdMatchId\" \n                   message=\"Please fill out the times of the matches in order\"/>\n\n <p:commandButton value=\"Submit\" update=\"@form\"/>\n</h:form>\n

\n\n\n\n\n

\n\n\n

The second match of the day cannot start after the third match of the day, so validation fails.

\n\n

The complete application is named, ValidateOrderTime.

\n\n

This validator has the additional requirement that the to-be-validated values must implement Comparable. This validator throws an IllegalArgumentException when one or more of the values do not implement.

\n\n\n\n

Let’s suppose that we have a simple UI for setting matches of type player 1 vs player 2. We impose a rule conforming to the player 2 must have a higher rank than player 1. A player is represented by the Player class (wraps the player rank and name), which means that the <o:validateOrder/> will not know how to compare two Players and how to check the specified order. In order to “help” this validator, we need to implement the Comparable interface and provide the desired comparison rule to the compareTo() method - the validator will use rule:

\n\n

public class Player implements Serializable, Comparable<Player> {\n\n private static final long serialVersionUID = 1L;\n\n private int rank;\n private String name;\n\n public Player(int rank, String name) {\n  this.rank = rank;\n  this.name = name;\n }        \n\n // getters and setters\n\n @Override\n public int compareTo(Player p) {\n  int rank = p.getRank();\n  return this.rank - rank;\n }\n\n @Override\n public String toString() {\n  return \"Player{\" + \"rank=\" + rank + \", name=\" + name + '}';\n }        \n}\n

\n\n\n\n\n\n

<h:form> \n <p:messages/>\n Next match: #{playerBean.selectedOne.name} vs. #{playerBean.selectedTwo.name}\n <p:panelGrid columns=\"2\">\n  <p:panelGrid columns=\"2\">\n   <p:outputLabel for=\"selectFirstId\" value=\"Choose first player\" />\n   <p:selectOneMenu id=\"selectFirstId\" value=\"#{playerBean.selectedOne}\" \n                    converter=\"omnifaces.SelectItemsConverter\">\n    <f:selectItem itemLabel=\"Select first player for this game\" itemValue=\"\" />\n    <f:selectItems value=\"#{playerBean.players}\" var=\"t\" \n                   itemLabel=\"#{t.rank}.#{t.name}\" itemValue=\"#{t}\" />\n   </p:selectOneMenu>\n  </p:panelGrid>\n\n  <p:panelGrid columns=\"2\">\n   <p:outputLabel for=\"selectSecondId\" \n                  value=\"Choose second player (choose a better rank)\" />\n   <p:selectOneMenu id=\"selectSecondId\" value=\"#{playerBean.selectedTwo}\" \n                    converter=\"omnifaces.SelectItemsConverter\">\n    <f:selectItem itemLabel=\"Select second player for this game\" itemValue=\"\" />\n    <f:selectItems value=\"#{playerBean.players}\" var=\"t\" \n                    itemLabel=\"#{t.rank}.#{t.name}\" itemValue=\"#{t}\" />\n   </p:selectOneMenu>\n  </p:panelGrid>\n </p:panelGrid>\n            \n <o:validateOrder components=\"selectFirstId selectSecondId\" type=\"gt\" \n    message=\"Second player must have a better rank than the first\"/>\n           \n <p:commandButton value=\"Submit\" update=\"@form\"/>\n</h:form>\n

\n\n\n\n\n

\n\n\n

The second player rank is 23. Since this is bigger than 20 the validation has failed.

\n\n

The complete application is named, ValidateOrderComparable.

\n\n

Validating multiple fields by a custom validator method or by a managed bean instance which implements the MultiFieldValidator interface

\n\n

The <o:validateMultiple/> allows the developer to validate multiple fields by either a custom validator method or, by a managed bean instance which implements the MultiFieldValidator interface. In the first approach, the method that performs the validation must respect the following signature:

\n\n

public class FooBean {\n // ...\n public boolean fooMethod(FacesContext context, \n                          List<UIInput> components, List<Object> values) {\n  // ...\n }\n // ...\n}\n

\n\n\n\n

And, it is referenced from <o:validateMultiple/> like below:

\n\n

<o:validateMultiple ... validator=\"#{fooBean.fooMethod}\" />\n

\n\n\n\n

In the second approach, we implement the MultiFieldValidator interface and override the validateValues() method:

\n\n

@Override\npublic class FooBean implements MultiFieldValidator {\n // ...\n public boolean validateValues(FacesContext context, \n                               List<UIInput> components, List<Object> values) {\n  // ...\n }\n // ...\n}\n

\n\n\n\n

And, it is referenced from <o:validateMultiple/> like below:

\n\n

<o:validateMultiple ... validator=\"#{fooBean}\" />\n

\n\n\n\n

Let’s have an examples that uses the second approach. For this let’s suppose that we have a PrimeFaces PickList and a SelectManyCheckbox. Both components will be populated with the same data and our validation constraint imposes that the selected data from the PickList should contain the data checked in the SelectManyCheckbox. Before we add the validation constrains, let’s have some preparations. So, let’s say that the used data are instances of the Player class listed below:

\n\n

public class Player implements Serializable {\n\n private static final long serialVersionUID = 1L;\n\n private int rank;\n private String name;\n\n public Player(int rank, String name) {\n  this.rank = rank;\n  this.name = name;\n }        \n\n // getters and setters\n\n // This method is needed for using the OmniFaces ListConverter \n // and SelectItemsConverter. Both need  that our entity has a \n // good toString() implementation\n @Override\n public String toString() {\n  return \"Player{\" + \"rank=\" + rank + \", name=\" + name + '}';\n }        \n}\n

\n\n\n\n

Furthermore, let’s create a few Players and let’s prepare the data accordingly to PickList and SelectManyCheckbox requirements:

\n\n

@Named\n@ViewScoped\npublic class PlayerBean implements Serializable {\n\n private static final long serialVersionUID = 1L;\n\n private List<Player> players;\n private List<Player> selectedviaCheckbox;\n private DualListModel<Player> model;\n\n @PostConstruct\n public void init() {\n  selectedviaCheckbox = new ArrayList<>();\n  players = asList(\n   new Player(8, \"Tomas Berdych\"),\n   new Player(20, \"Jurgen Melzer\"),\n   ...\n  );\n\n  model = new DualListModel<>(\n              new ArrayList<>(players),\n              new ArrayList<Player>()\n  );\n }\n\n // getters and setters     \n    \n // some dummy action\n public void playersAction(){\n  Messages.addGlobalInfo(\"The selected players are valid\");\n } \n} \n

\n\n\n\n

Next, we can expose this data to the user (notice that we have used the omnifaces.ListConverter for PickList and omnifaces.SelectItemsConverter for SelectManyCheckbox - these converters have been detailed in Chapter 10):

\n\n

<h:form>\n <p:messages id=\"msgs\"/>\n <p:pickList id=\"playersList\" value=\"#{playerBean.model}\" var=\"t\" \n             itemLabel=\"#{t.rank}.#{t.name}\" itemValue=\"#{t}\">\n  <o:converter converterId=\"omnifaces.ListConverter\" \n               list=\"#{playerBean.players}\" />\n </p:pickList>\n\n <p:selectManyCheckbox id=\"playersCheckbox\" \n                       value=\"#{playerBean.selectedviaCheckbox}\"\n                       converter=\"omnifaces.SelectItemsConverter\"\n                       layout=\"responsive\" \n                       style=\"width: 435px; margin-top: 5px;\" \n                       columns=\"3\">\n  <f:selectItems value=\"#{playerBean.players}\" var=\"t\" \n                 itemLabel=\"#{t.rank}.#{t.name}\" itemValue=\"#{t}\" />\n </p:selectManyCheckbox>\n\n <p:commandButton value=\"Submit\" action=\"#{playerBean.playersAction()}\" \n                  update=\"msgs\" style=\"margin-top:5px\" />                       \n</h:form>\n

\n\n\n\n

At this moment any combination of selections will be valid, as you can see in the figure below:

\n\n\n

\n\n\n

It is time for ValidateMultiple to enter in the scene! As we said earlier, we will implement the MultiFieldValidator interface and override the validateValues() method. This method receives a list of UIInputs representing the input components that enter in validation and a list of Objects representing the local values of these components (these are the values that should be validated). Now, we need to provide the code specific to our validation constraint. We can accomplish this in multiple ways, but notice that our list of components contains two instances: one instance of org.primefaces.component.picklist.PickList and one instance of org.primefaces.component.selectmanycheckbox.SelectManyCheckbox; moreover, the list of values should contain an instance of org.primefaces.model.DualListModel and an instance of List):

\n\n

@Named\n@ApplicationScoped\npublic class ValidatePlayers implements MultiFieldValidator {\n\n @Override\n public boolean validateValues(FacesContext fc, \n                               List<UIInput> components, List<Object> values) {\n\n  List<Player> fromModel;\n\n  if (values.get(0) instanceof DualListModel) {\n      fromModel = ((DualListModel) values.get(0)).getTarget();\n      return fromModel.containsAll((List) values.get(1));\n  } else {\n      fromModel = ((DualListModel) values.get(1)).getTarget();\n      return fromModel.containsAll((List) values.get(0));\n  }\n }\n} \n

\n\n\n\n

Finally, we need to use <o:validateMultiple/> in the page. This is pretty straightforward:

\n\n

<h:form>\n ...\n <o:validateMultiple id=\"validateMultiple\" \n                     components=\"playersList playersCheckbox\" \n                     validator=\"#{validatePlayers}\"\n                     message=\"The selected players via checkboxes must be \n                              contained by the selected player list.\" />\n</h:form>\n

\n\n\n\n

This time the selection from the above picture is not valid. Checkout the figure below:

\n\n\n

\n\n\n

But, if in the PickList, we also select the Pablo Cuevas and Jeremy Chardy players then the submission will become valid:

\n\n\n

\n\n\n

The complete application is named ValidateMultiple.

\n\n

Working with a validator in an iterating component (e.g. `<p:dataTable/>`)

\n\n

Since <f:validateXxx>/<f:validator> are tag handlers, they are evaluated during construction/restoration of the component tree (in the Restore View phase). This means that the attributes of tag handlers are evaluated during view build time. On the other hand, UIComponents are executed during view render time (in the Render Response phase). This means that the attributes of UIComponents are evaluated during the view render time. So, JSF validators and UIComponents donʹt run at the same time, and their attributes are not evaluated at the same time, at least not the ones we want to discuss in this section (e.g. the id and binding attributes of UIComponents are evaluated during the view build time, but are not relevant here).

\n\n

But, letʹs suppose that we are using a JSF validator inside an iterating component (e.g. <p:pickList/>, <p:dataTable/>, <h:dataTable/>, <ui:repeat/>). You may expect that, at every iteration, the validator is re‐evaluated and that its attributes are getting new values, specific to the iteration step. For example, if the validator is used in a data table, you may expect that the validatorʹs attributes are set every time a data table row is rendered. But, if you read carefully the above subsection, you realize that this is not true. The expected behavior should be based on the fact that JSF will only create one validator instance per UIComponent (in the Restore View phase), and will not re‐create or reset the validatorʹs attributes each time the row is rendered. So, if we are using deferred value expressions for validatorʹs attributes values, we obtain undesirable behaviors or even exceptions.The solution consists of an artifact that will provide render time evaluation of validators attributes. So, instead of an\nevaluation on a per view build time basis, we want an evaluation on every access, like the UIComponents and bean properties. Another issue, specific to validators, implies the case when multiple <f:validator/> are used for the same input, because the validatorMessage attribute of the parent input component applies to all validators. Even if each validator has certain tasks, they will produce the same error message.

\n\n

Furthermore, letʹs see an example that uses a validator in an iterating component. The aim is to apply a different pattern for each input (at each iteration), and for this we have used the built‐in <f:validateRegex/> validator with a ValueExpression for the pattern attribute:

\n\n

public class Player implements Serializable {\n    \n private static final long serialVersionUID = 1L;\n \n private String pattern;\n private String field;\n private String label;\n    \n public Player(String pattern, String field, String label) {\n  this.pattern = pattern;\n  this.field = field;\n  this.label = label;\n } \n ...       \n // getters and setters\n ...\n}\n\n@Named\n@SessionScoped\npublic class PlayerBean implements Serializable {\n\n private static final long serialVersionUID = 1L;\n\n private List<Player> players;\n\n @PostConstruct\n public void init() {\n  players = Arrays.asList(\n   new Player(\"([^.@]+)(\\\\.[^.@]+)*@([^.@]+\\\\.)+([^.@]+)\", \n                                                     \"mike@gmail.com\", \"E-mail\"),\n   new Player(\"^\\\\+(?:[0-9] ?){6,14}[0-9]$\", \"+1 1234567890123\", \"Phone Number\"),\n   new Player(\"^[0-9]{5}(?:-[0-9]{4})?$\", \"12345-4423\", \"Zip Code\"),\n   new Player(\"^[a-zA-Z\\\\\\\\s]+\", \"MikeTorn\", \"Full Name\"));\n }\n\n public List<Player> getPlayers() {\n  return players;\n }\n}\n

\n\n\n\n

Now, let’s apply the <f:validateRegex/> as below:

\n\n

<h:form>\n <p:dataTable value=\"#{playerBean.players}\" var=\"player\">                \n  <p:column headerText=\"Player\">    \n   <p:outputLabel value=\"#{player.label}\" for=\"inputId\"/>\n  </p:column>\n  <p:column headerText=\"Details\">\n   <p:inputText id=\"inputId\" value=\"#{player.field}\">\n    <f:validateRegex pattern=\"#{person.pattern}\"/>\n   </p:inputText>\n  </p:column>\n  <p:column>\n   <p:message for=\"inputId\" />\n  </p:column>\n </p:dataTable>\n <p:commandButton value=\"Submit\" update=\"@form\"/>      \n <h:outputText value=\"Thanks!\" rendered=\"#{facesContext.postback and not \n                                           facesContext.validationFailed}\" />\n</h:form>\n

\n\n\n\n

Now, we intentionally provide an invalid pattern (e.g. for the zip code). This will cause the result in the figure below (obviously this is not the expected result):

\n\n\n

\n\n\n

Now, letʹs see the OmniFaces approach for solving these problems/issues. In order to support deferred value expressions in all of the validators attributes, OmniFaces extended the built‐in <f:validator/> with a tag handler that can be evaluated on a per‐iteration basis inside an iterating component. The <o:validator/> extends <f:validator/> with support for the deferred value expressions in all off tha validators attributes of validators. In order to use it, simply follow these steps:

\n\n

Replace your validator with <o:validator/>.
Use the validatorId attribute to indicate the VALIDATOR_ID (e.g. javax.faces.LongRange, javax.faces.RegularExpression, javax.faces.DoubleRange, etc). For standard validators, you can find the VALIDATOR_ID in the official documentation.
Place deferred value expressions in the desired attributes.

\n\n

For example, in our case replace <f:validateRegex/> with <o:validator/> like below:

\n\n

...\n<p:column headerText=\"Details\">\n <p:inputText id=\"inputId\" value=\"#{player.field}\">\n  <o:validator validatorId=\"javax.faces.RegularExpression\" \n               pattern=\"#{player.pattern}\"/>\n </p:inputText>\n</p:column>\n...\n

\n\n\n\n\n

\n\n\n

Or, if there are several invalid fields we will obtain something like in the figure below:

\n\n\n

\n\n\n

The complete application is named, ValidatorIteratingComponent.

\n\n

Discussing validators dependency injection

\n\n

JSF 2.0 provides a very modest support for injection in JSF artifacts. In JSF 2.1 very few JSF artifacts were injection targets. Starting with JSF 2.2, injection is possible in many more artifacts (check Mastering JavaServer Faces 2.2), but as the specification says, converters, validators and behaviors are still not injection targets. It seems that this will be available from JSF 2.3. Until JSF 2.3, there were a few tricks to obtain validators eligible for injection. First approach, was to provide the validator as a managed bean as in the below skeleton:

\n\n

// Until JSF 2.3 - custom validator eligible for @Inject\n\n@Named(value=\"fooValidator\")\n@RequestScoped\npublic class FooValidator implements Validator {\n\n @Inject\n // artifact\n\n @Override\n public void validate(FacesContext context, \n        UIComponent component, Object value) throws ValidatorException {\n  ...                                                               \n  // use the injected artifact\n  ...\n }\n}\n

\n\n\n\n

Usage example:

\n\n

<p:inputText value=\"#{bean_property}\" validator=\"#{fooValidator.validate}\" />\n

\n\n\n\n\n\n

Another approach consists of relying on OmniFaces support. This approach brings @Inject and @EJB into custom validators (@FacesValidator) as if it were there forever. There is nothing to configure, no additional annotations, no need to modify your exiting validators. Simply by using OmniFaces you get the bonus of having your custom validators eligible for injection. For example, the below code represents a typical JSF custom validator. Since OmniFaces is around, this custom validator supports @Inject and @EJB:

\n\n

@FacesValidator(\"fooValidator\")\npublic class FooValidator implements Validator {\n\n @EJB\n private FooEJB fooejb;\n\n @Inject\n private fooCDI foocdi;\n\n @Override\n public void validate(FacesContext context, \n        UIComponent component, Object value) throws ValidatorException {\n  ...\n  // work here with fooejb and foocdi\n  ...\n }\n}  \n

\n\n\n\n

\n\n

specify a new attribute called managed on the corresponding annotations;
add in the WEB-INF folder the faces-config.xml with the JSF 2.3 XSD;

\n\n

So, in JSF 2.3 we have:

\n\n

@FacesValidator(value = \"fooValidator\", managed = true)\npublic class FooValidator implements Validator {\n\n @Inject\n // artifact\n\n @Override\n public void validate(FacesContext fc, \n             UIComponent uic, Object o) throws ValidatorException {\n  ...\n  // use the injected artifact\n  ...\n }\n}  \n

\n\n\n\n

Further details are available here.

\n\n

Entirely skip validation

\n\n

OmniFaces 2.3 comes with a new tag handler named SkipValidators. As its name suggest, this tag handler allows us to entirely skip validation when executing an UICommand or ClientBehaviorHolder action. Simply place the <o:skipValidators/> tag inside a UICommand or ClientBehaviorHolder component. For example, in the below code, the button labeled Hard Submit will take validation into account, while the button labeled Soft Submit will entirely skip validation and the submitted data end up in the data model:

\n\n

<h:form>\n <p:messages/>\n <p:panelGrid columns=\"2\">\n  <p:outputLabel for=\"nameId\" value=\"Name:\"/>\n  <p:inputText id=\"nameId\" value=\"#{dataBean.name}\" required=\"true\"/>\n  <p:outputLabel for=\"emailId\" value=\"E-mail:\"/>\n  <p:inputText id=\"emailId\" value=\"#{dataBean.email}\" \n               required=\"true\" validator=\"emailValidator\"/>\n  <p:commandButton value=\"Hard Submit\" update=\"@form\"/>\n  <p:commandButton value=\"Soft Submit\" update=\"@form\">\n   <o:skipValidators />\n  </p:commandButton>\n </p:panelGrid>\n Name: #{dataBean.name} | E-mail: #{dataBean.email}\n</h:form>\n

\n\n\n\n

In the figure below you can see the effect produced by the two buttons (figure from the right takes advantage of <o:skipValidators />):

\n\n\n

\n\n\n\n\n

This can be useful in different scenarios including debugging, testing, dynamically adding/removing items from a form, etc. You can temporarily disable the validation for large forms and perform different checks with respect to data model. Instead of removing validators one by one, you simply add this tag handler.

\n\n

The complete application is named EntirelySkipValidation.

\n\n

Handling view parameters validation failure

\n\n

As a quick reminder, view parameters extend UIInput and they support built‐in/custom converters and validators. These artifacts can be attached via <f:converter/>/<f:validator/>, <f:convertXxx/>/ <f:validateXxx/> and converter, validator attributes.

\n\n

In this section, we think of solving the following tasks:

\n\n

Handle a view parameter validation failure with either a redirect or an HTTP error status.
Optionally add a flash message to redirect or an HTTP error message to HTTP error status.
Place the validation failure handling “locally”, per view parameter, or “globally” in <f:metadata/>, as a validation failure handling for all view parameters.

\n\n

So, letʹs see an example meant to highlight this problem/issue. Letʹs suppose that the following <f:metadata/> section (you can also use the built‐in validator, required=\"true\"):

\n\n

<f:metadata>\n <f:viewParam id=\"nameId\" name=\"name\" \n              validatorMessage=\"The name is not valid!\">\n  <f:validateRegex pattern=\"^[a-zA-Z\\\\\\\\s]+\"/> \n </f:viewParam>\n <f:viewParam id=\"ageId\" name=\"age\" \n              validatorMessage=\"The age is not valid!\">\n  <f:validateRegex pattern=\"^(\\d?[1-9]|[1-9]0)$\"/>\n </f:viewParam>\n</f:metadata>\n

\n\n\n\n

Validating the `<f:metadata/>` view parameters

\n\n

If the validation failed (FacesContext#isValidationFailed() returns true) we need to verify the validation status for all view parameters (check UIInput#isValid() for each view parameter) until we find the first invalid one (if any). When we found an invalid view parameter (UIInput#isValid() return false) we send a HTTP error status with a custom message (ExternalContext#responseSendError()). We can accomplish this via lambda expressions and JSF API, like below:

\n\n

<h:body>     \n #{facesContext.validationFailed ? \n   (vdl = facesContext.application.viewHandler.\n          getViewDeclarationLanguage(facesContext, view.viewId);\n    viewMetadata = vdl.getViewMetadata(facesContext, view.viewId);\n    allViewParams = viewMetadata.getViewParameters(view);\n    allViewParams.size() gt 0 ? \n     (allViewParams.stream().forEach((t) -> (t.valid ? \n       '' : (facesContext.externalContext.responseCommitted ? \n       '' : facesContext.externalContext.\n            responseSendError(400, \"One of your view parameters is invalid !\");\n            facesContext.responseComplete())))):''):''}                        \n\n <h:outputText value=\"Everything works perfect!\"/>\n\n</h:body>\n

\n\n\n\n\n\n

Validating each view parameter

\n\n

As you can see, we have two view parameters. Letʹs suppose that we want to perform a redirect, if the first view parameter (nameId) validation fails, and to send a HTTP error status, if the second view parameter (ageId) validation fails. We can easily adjust the above approach to obtain a general solution, but we can also use a particular approach and do something like this:

\n\n

<h:body>     \n #{facesContext.validationFailed ? \n   (facesContext.viewRoot.findComponent('nameId').valid ?\n     '' : facesContext.externalContext.\n           redirect('https://leanpub.com/PrimeFaces-OmniFaces-Powers-Combined');\n          facesContext.viewRoot.findComponent('ageId').valid ? \n     '' : facesContext.externalContext.\n           responseSendError(400, 'Please, provide a valid age !');\n    facesContext.responseComplete()):''}     \n\n <h:outputText value=\"Everything works perfect!\"/>\n</h:body>\n

\n\n\n\n

Introducing the OmniFaces `viewParamValidationFailed`\n

\n\n

Now, letʹs see the OmniFaces approach for solving these problems/issues. OmniFaces comes with a tag handler named, ViewParamValidationFailed. This tag handler can be used in page via <o:viewParamValidationFailed/> tag and allows us to handle a view parameter validation failure with either a redirect or an HTTP error status, optionally with respectively a flash message or HTTP error message. It can be applied to <f:param/>, <o:param/> and <f:metadata/>, and it supports three optional attributes as follows:

\n\n

\nsendRedirect ‐ Indicates the URL to send redirect to on validation failure. This attribute is required when the sendError attribute is not present, and it relies on the Faces#redirect() utility method.
\nsendError ‐ Indicates the HTTP status code. Donʹt use this attribute and sendRedirect in the same time. This attribute relies on the Faces#responseSendError() utility method.
\nmessage ‐ Indicates a custom message to send along with the redirect or error. By default, the validation error message will be used.

\n\n

Use `viewParamValidationFailed` for validating the `<f:metadata/>` view parameters

\n\n

In this case, we need to attach the <o:viewParamValidationFailed/> to <f:metadata/>. So, we have:

\n\n

<h:head>\n <f:metadata>\n  <f:viewParam id=\"nameId\" name=\"name\" required=\"true\"\n                   validatorMessage=\"The name is not valid!\">\n   <f:validateRegex pattern=\"^[a-zA-Z\\\\\\\\s]+\"/>\n  </f:viewParam>\n  <f:viewParam id=\"ageId\" name=\"age\" required=\"true\"\n               validatorMessage=\"The age is not valid!\">\n   <f:validateRegex pattern=\"^(\\d?[1-9]|[1-9]0)$\"/>\n  </f:viewParam>\n  <o:viewParamValidationFailed sendError=\"400\" \n     message=\"One of your view parameters is invalid !\" />\n </f:metadata>\n</h:head>\n<h:body>    \n <h:outputText value=\"Everything works perfect!\"/>\n</h:body>\n

\n\n\n\n

Now, let’s suppose that we run the code from the following URLs:

\n\n

a valid name and surname: http://.../?name=rafaelnadal&age=29\n

\n\n\n

\n\n\n

an invalid age (or/and name): http://.../?name=rafaelnadal&age=29d\n

\n\n\n

\n\n\n

The complete application is named VPVFAndMetadata.

\n\n

Use `viewParamValidationFailed` for validating each view parameter

\n\n

In this case, we need to attach the <o:viewParamValidationFailed/> to each view parameter. So, we have:

\n\n

<h:head>\n <f:metadata>\n  <f:viewParam id=\"nameId\" name=\"name\" \n               validatorMessage=\"The name is not valid!\">\n   <f:validateRegex pattern=\"^[a-zA-Z\\\\\\\\s]+\"/> \n   <o:viewParamValidationFailed sendRedirect=\n    \"https://leanpub.com/PrimeFaces-OmniFaces-Powers-Combined\" />\n  </f:viewParam>           \n  <f:viewParam id=\"ageId\" name=\"age\" validatorMessage=\"The age is not valid!\">\n   <f:validateRegex pattern=\"^(\\d?[1-9]|[1-9]0)$\"/>                              \n   <o:viewParamValidationFailed sendError=\"400\" \n                                message=\"Please, provide a valid age !\" />\n  </f:viewParam>            \n </f:metadata>\n</h:head>\n<h:body>    \n <h:outputText value=\"Everything works perfect!\"/>\n</h:body>\n

\n\n\n\n

Now, let’s suppose that we run the code from the following URLs:

\n\n

a valid name and surname: http://.../?name=rafaelnadal&age=29\n

\n\n\n

\n\n\n

an invalid age: http://.../?name=rafaelnadal&age=29d\n

\n\n\n

\n\n\n

an invalid name (and/or age): http://.../?name=29rafaelnadal&age=29\n

\n\n\n

\n\n\n

The complete application is named VPVFEachParam.

\n\n

That’s more

\n\n

You can customize HTTP error pages via <error-page/> entries in web.xml. Otherwise the server‐default one will be displayed instead. If we skip the message attribute, then OmniFaces will use the default error messages (e.g. in the above use cases, the messages indicated via validatorMessage attribute). If we attach <o:viewParamValidationFailed/> “locally” to view parameters and “globally” to <f:metadata/> also, then the “global” <o:viewParamValidationFailed/> will be evaluated only if none of the “local” <o:viewParamValidationFailed/> has already handled the validation error.

\n\n

Do not forget to check out the OmniFaces Showcase. There, you can read more details (e.g. design notes) and test more examples.

\n\n

Chapter 12: Boost `<f:event/>` and `<f:viewAction/>`\n

\n\n

In this chapter, we will discuss about two tags that are usually used together (not mandatory): <f:event/> and <f:viewAction/>. First, you will see how OmniFaces adds two more events to <f:event/>, afterwards you will see how if attribute of <f:viewAction/> can evaluate a condition based on converterd/validated data instead of state data.

\n\n

The `<f:event/>` and `preInvokeAction`/`postInvokeAction` event types

\n\n

If you are not familiar with <f:event/> tag handler then you should know that its main goal is to allow page authors to install ComponentSystemEventListener instances on a component in a page. The required type attribute represents the name of the event for which to install a listener and it can be one of: preRenderComponent, preRenderView, postAddToView, preValidate, postValidate or the fully qualified class name of any java class that extends javax.faces.event.ComponentSystemEvent. Commonly, <f:event/> is used for calling actions in GET/POST requests via preRenderView, as below:

\n\n

<f:event type=\"preRenderView\" listener=\"fooBean.fooInit\"/> \n

\n\n\n\n

But, in some specific cases, the preRenderView event might be too late, while the postValidate might be to earlier or useless. For example, we may need to perform initialization only if validation was successfully passed. Unfortunately, preRenderView event will cause the initialization to take place even when validation failed.

\n\n

For a better understanding let’s have a simple example. Basically, we will use <f:viewParam/> to bring in the current view an e-mail address via a context parameter. This address will go through a custom validator, and if it is valid, it will be used to initialize a message of type Welcome, foo-email!. A typical approach will look like this:

\n\n

// index.xhtml\n<p:link outcome=\"subscribe?email=leoprivacy@yahoo.com\" value=\"Click Me!\"/>\n

\n\n\n\n

// subscribe.xhtml\n<f:metadata>\n <f:viewParam name=\"email\" value=\"#{emailBean.email}\" \n              validator=\"emailValidator\" />\n <f:event type=\"preRenderView\" listener=\"#{emailBean.preRender}\" />\n</f:metadata>   \n

\n\n\n\n

@FacesValidator(value = \"emailValidator\")\npublic class EmailValidator implements Validator {\n         \n @Override\n public void validate(FacesContext context, UIComponent component, \n                           Object value) throws ValidatorException {\n        \n  String email = value.toString();\n        \n  if (!isValidEmail(email)) {\n      FacesMessage message = Messages.\n       createError(\"The provided address is not a valid e-mail.\");            \n      throw new ValidatorException(message);\n  }\n }\n ...\n}\n

\n\n\n\n

@Named\n@RequestScoped\npublic class EmailBean implements Serializable {\n\n private String email;\n\n public String getEmail() {\n  return email;\n }\n\n public void setEmail(String email) {\n  this.email = email;\n }\n\n public void preRender() {     \n  Messages.addGlobalInfo(\"Welcome, \" + email);\n }\n}\n

\n\n\n\n

So, the first stop will happen in the EmailValidator. If the e-mail is valid then the process will advance in the Update Model Values phase, otherwise it will queue an error faces message and will advance in the Render Response phase. Independent of this action, the preRenderView will instruct JSF to invoke the preRender() method, which queues another faces messages based on the passed e-mail. This means that when the e-mail is valid, we will something like in figure below:

\n\n\n

\n\n\n

And, when the e-mail is invalid (e.g. leoprivacyyahoo.com) we will see something like in figure below:

\n\n\n

\n\n\n

Well, is obvious that this is not the expected or desired result. A quick approach consists in having a check inside preRender() method of type if (!Faces.isValidationFailed()) ... (see OmniFaces shortcut Faces#isValidationFailed()). This will fix the issue, but it means that preRender() method is still invoked! Basically, the same effect will take place in case of postValidate event.

\n\n

Since we are using OmniFaces, there is no need for this workaround. Once OmniFaces is added in the project, we have access out-of-the-box to the preInvokeAction/postInvokeAction event types. Basically, the InvokeActionEventListener will add support for new <f:event/> types preInvokeAction and postInvokeAction. Those events are published before, respectively after, the Invoke Application phase. So, these events can be attached to <f:event/>, and in our case we can use the preInvokeAction as below:

\n\n

// subscribe.xhtml\n<f:metadata>\n <f:viewParam name=\"email\" value=\"#{emailBean.email}\" \n              validator=\"emailValidator\" />\n <f:event type=\"preInvokeAction\" listener=\"#{emailBean.preInvoke}\" />\n</f:metadata>\n

\n\n\n\n

// EmailBean\npublic void preInvoke() {\n Messages.addGlobalInfo(\"Welcome, \" + email);\n}\n

\n\n\n\n

This time, when the validation fails, the flow will go in Render Response phase, which means that it “jumps” over the Invoke Application phase and the preInvoke() method will not be invoked. So, for an invalid e-mail we will see something like in figure below:

\n\n\n

\n\n\n

In case that you want to invoke a listener at the end of Invoke Applicaation phase too, then simply add a new <f:event/> as below:

\n\n

<f:metadata>\n ...\n <f:event type=\"preInvokeAction\" listener=\"#{fooBean.fooPreInvoke}\" />\n <f:event type=\"postInvokeAction\" listener=\"#{fooBean.fooPostInvoke}\" />\n</f:metadata>\n

\n\n\n\n

The complete application is named, ViewParamAndPrePostIA.

\n\n

Furthermore, let’s suppose that we want to invoke multiple action listeners in an UIComponent. You have to know that the OmniFaces InvokeActionEventListener is supported on any UIComponent (e.g. UIViewRoot, UIForm, UIInput, UICommand, etc). Practically, you can invoke multiple action listeners on a single UIInput and UICommand component on an easy manner. For example, let’s suppose that when we click on an UICommand (e.g. <h:commandButton/>) we want to submit a form and obtain the following sequence of messages: a) Welcome, foo-email! - message produced by a method invoked during before Invoke Application phase (preInvoke()), b) Your foo-email was successfully registered! - message produced by an action method (registerEmail()), and c) Bye, foo-email! - message produced by a method during after Invoke Application phase (postInvoke()).

\n\n

In order to accomplish this task, we can write the following form - notice how we have attached the desired listeners to the UICommand:

\n\n

<h:form>          \n <p:growl id=\"msgs\"/>\n <p:outputLabel for=\"emailId\" value=\"E-mail:\"/>\n <p:inputText id=\"emailId\" value=\"#{emailBean.email}\" \n              validator=\"emailValidator\"/>\n <p:commandButton value=\"Subscribe\" \n                  action=\"#{emailBean.registerEmail()}\" \n                  update=\"msgs\">      \n  <f:event type=\"preInvokeAction\" listener=\"#{emailBean.preInvoke}\" />\n  <f:event type=\"postInvokeAction\" listener=\"#{emailBean.postInvoke}\" />\n </p:commandButton>\n</h:form> \n

\n\n\n\n

The relevant part from EmailBean is:

\n\n

public void preInvoke() {\n Messages.addGlobalInfo(\"Welcome, \" + email);\n}\n\npublic void registerEmail() {\n Messages.addGlobalInfo(\"Your \" + email + \" was successfully registered!\");\n}\n\npublic void postInvoke() {\n Messages.addGlobalInfo(\"Bye, \" + email);\n}\n

\n\n\n\n

If the provided e-mail is not valid, then you will see the error messages produces by the e-mail validator. Otherwise, you will see the sequence of messages from the below figure:

\n\n\n

\n\n\n

The complete application is named, UICommandAndPrePostIA.

\n\n

Or, you may want to invoke multiple action listeners on a single UIInput when the keyup event occur. For example:

\n\n

<h:form>          \n <p:growl id=\"msgs\"/>\n <p:outputLabel for=\"emailId\" value=\"E-mail:\"/>\n <p:inputText id=\"emailId\" value=\"#{emailBean.email}\" validator=\"emailValidator\">\n  <p:ajax event=\"keyup\" listener=\"#{emailBean.registerEmail()}\" update=\"msgs\" />\n  <f:event type=\"preInvokeAction\" listener=\"#{emailBean.preInvoke}\" />\n  <f:event type=\"postInvokeAction\" listener=\"#{emailBean.postInvoke}\" />\n </p:inputText>                     \n</h:form>\n

\n\n\n\n

The complete application is named, InputAndPrePostIA.

\n\n

Boost `<f:viewAction/>` via `<o:viewAction/>`\n

\n\n

Starting with JSF 2.2, we can deal with calling actions on GET/POST requests by using the new generic view action feature (well-known in Seam 2 and 3). This new feature is materialized in the <f:viewAction/> tag, which is declared as a child of the metadata facet, <f:metadata/>. This allows the view action to be part of the JSF life cycle for faces/non-faces requests. The main attribute is named action, and its value is a MethodExpression. The expression must evaluate to a public method that takes no parameters, and returns void or an outcome.

\n\n

<f:metadata>\n ...\n <f:viewAction action=\"#{fooBean.fooAction()}\"/>\n ...\n</f:metadata>\n

\n\n\n\n

We can also place an outcome directly in action:

\n\n

<f:metadata>\n ...\n <f:viewAction action=\"foopage\"/>\n ...\n</f:metadata>\n

\n\n\n\n

The problem identified and fixed by OmniFaces is related to the if attribute of the <f:viewAction/> tag. Practically, via this attribute we can decide when the specified action (indicated via the action attribute) should be executed or not.

\n\n

<f:metadata>\n ...\n <f:viewAction if=\"#{foo_condition}\" action=\"#{fooBean.fooAction()}\"/>\n ...\n</f:metadata>\n

\n\n\n\n

The value of the if attribute is evaluated in the Apply Request Values phase, which means that this value wasn’t converted, validated and, obviously, set in the model yet (if there is a converter/validator specified and/or a proper model). Conversion and validation will take place in the Process Validation phase and the model will be updated in the Update Model Values phase; both of these phases are after the Apply Request Values phase. Let’s suppose that the if value is evaluated to true against a non-null data check, and a custom converter will convert the checked data to null without causing any exception. This means that the pointed action (method) will be invoked (by default, in Invoke Application phase), but the data in the model is actually null (JSF doesn’t check this again before calling the action(method)). This is at least a “strange” behavior, because we may think that the checked data is not null and try to use it for further tasks. Moreover, the invoked action (method) may causes unexpected behaviors.

\n\n

Let’s begin with an example. Check out the below code (do not conclude that <f:viewAction/> cannot be used without <f:viewParam/>):

\n\n

// index.xhtml - starting page\n<p:link outcome=\"ping?numberParam=0721-9348334\">Ping 0721-9348334</p:link>\n<p:link outcome=\"ping?numberParam=0743-9348334\">Ping 0743-9348334</p:link>\n\n// ping.xhtml\n<f:metadata>\n <f:viewParam name=\"numberParam\" value=\"#{pingBean.number}\" \n              converter=\"phoneNumberConverter\"/>        \n <f:viewAction if=\"#{pingBean.number ne null}\"\n               action=\"#{pingBean.ping()}\"/>\n</f:metadata>\n

\n\n\n\n

// custom converter\n@FacesConverter(value = \"phoneNumberConverter\")\npublic class PhoneNumberConverter implements Converter {\n  \n @Override\n public Object getAsObject(FacesContext context, \n             UIComponent component, String value) {\n  if (value.startsWith(\"0721\")) {\n      return \"343-\" + value;\n  }\n  return null;\n }\n\n @Override\n public String getAsString(FacesContext context, \n             UIComponent component, Object value) {\n  return (String) value;\n }\n}\n

\n\n\n\n

// PingBean.java\n@Named\n@RequestScoped\npublic class PingBean {\n\n private String number;\n private String ping;\n\n public PingBean() {\n  number = \"0000-000000\";\n  ping = \"Nothing to ping!\";\n }\n\n public void ping() {\n  ping = \"Ping number: \" + number + \"!\";\n }\n\n public String getNumber() {\n  return number;\n }\n\n public void setNumber(String number) {\n  this.number = number;\n }\n\n public String getPing() {\n  return ping;\n }\n}\n

\n\n\n\n

The code is very simple to understand - just check it line by line and pay attention to the highlighted parts. Basically, our converter “accepts” only phone numbers starting with 0721 prefix. For those numbers it adds one more local prefix, 343. For numbers that start with other prefixes (e.g. 0743) our converter returns null (!it doesn’t throw an exception).

\n\n

Test 1: If you press on the first link, Ping 0721-9348334, you will see the expected result of calling the ping() method:

\n\n

Ping number: 343-0721-9348334!

\n\n

Test 2: If you press on the second link, Ping 0743-9348334, you will see an un-expected result (you may be surprised by the fact that ping() was invoked, and you don’t see anything on the screen to ping!). This is happening because the if doesn’t evaluate the value returned by the PhoneNumberConverter, which is null (!the converter was not even called). The flow is in the Apply Request Values phase and it evaluates the #{pingBean.number} against the state, which doesn’t confirm the null value!

\n\n

Ping number: null!

\n\n

A simple approach to solve this issue is to add an explicit null check condition in the ping(), like this:

\n\n

public void ping() {\n if (number != null) {\n     ping = \"Ping number: \" + number + \"!\";\n }\n}\n

\n\n\n\n

This will solve the issue, but it has at least two drawbacks: the ping() method is still invoked and this works only for this specific case.

\n\n

It is time to see how OmniFaces solves this issue! The OmniFaces solution is named ViewAction and it is focused on postponing the moment of if value evaluation. The OmniFaces implementation practically, postpones the if evaluation until the Invoke Application phase. Since the if attribute’s value will be evaluated during the Invoke Application phase instead of the Apply Request Values phase, the evaluated value is converted/validated (if this is required) and set in the model (if there is the need). In order to use the OmniFaces implementation just replace the f with o, and add OmniFaces namespace, http://omnifaces.org/ui, as below:

\n\n

<f:metadata>\n <f:viewParam name=\"numberParam\" \n              value=\"#{pingBean.number}\" \n              converter=\"phoneNumberConverter\"/>        \n <o:viewAction if=\"#{pingBean.number ne null}\" action=\"#{pingBean.ping()}\"/>\n</f:metadata>\n

\n\n\n\n

Test 1: If you press on the first link, Ping 0721-9348334, you will see the expected result of calling the ping() method:

\n\n

Ping number: 343-0721-9348334!

\n\n

Test 2: If you press on the second link, Ping 0743-9348334, you will see the expected result also:

\n\n

Nothing to ping!

\n\n\n\n

The complete application is named, OFViewAction.

\n\n

Chapter 13: Caching aspects in PrimeFaces and OmniFaces

\n\n

In this chapter, we will discuss caching from JSF’s perspective. We start with a brief overview of JSF’s client-side caching mechanism. Furthermore, we will talk about server-side caching using PrimeFaces and OmniFaces. You will see how to cache HTML markup and EL expressions.

\n\n

JSF cient-side caching aspects

\n\n

Web cache (or caching) is one of the mechanisms used for tuning web sites performance. It is especially focused on increasing the speed of feeding the browser with HTML code, images, etc. This decreases bandwidth usage, server load, and perceived lag. The idea behind basic caching consists of temporarily storing copies of data (pages, documents, images) and, at subsequent requests, serve this data from this location instead of hitting the application business logic that initially provided the data. Some significant cases consist of static data that comes from a database, large images, data used by multiple users, keyword searching, auto-completion, etc.

\n\n

Speaking from JSF angle of view, caching is handled by the resource handler (ResourceHandler). By using the JSF tags, like <h:outputStylesheet/> instead of <link/>, <h:outputScript/> instead of <script/> and <h:graphicImage/> instead of <img/>, you allow ResourceHandler to use its default caching mechanism (e.g. images will be cached from 1 week - 604800 seconds). Now, it is important to notice that we are speaking about the browser cache, not the server-side cache. The default caching period can be altered via context parameters. For example, in Mojarra implementation this can be accomplished like below:

\n\n

<context-param>\n <param-name>com.sun.faces.defaultResourceMaxAge</param-name>\n <param-value>time in seconds</param-value>\n</context-param>\n

\n\n\n\n

Another context parameter specific to Mojarra, named com.sun.faces.resourceUpdateCheckPeriod (default 5 minutes), allows us to indicate the frequency of checking for changes in web application artifacts that contain resources. If a change is detected, the cache will be cleared and rebuilt. If the value of this option is -1, the cache will never be cleared and new resources will not be picked up.

\n\n

On the other hand, MyFaces implementation supports several cache zones as follows:

\n\n

Expression Language (EL) Cache

\n\n

From version 2.0.8, MyFaces implementation allows a cache mechanism for EL expressions. This can be configured using the below context parameter:

\n\n

<context-param>\n <param-name>org.apache.myfaces.CACHE_EL_EXPRESSIONS</param-name>\n <param-value>one of the below value</param-value>\n</context-param>\n

\n\n\n\n

The supported values are (the below snippet is copied from MyFaces official documentation):

\n\n

\nalways: Only does not cache when expressions are inside user tags or the expression contains a variable resolved using VariableMapper\n
\nallowCset: Like always, but does not allow cache when <ui:param/> is used on the current template context
\nstrict: Like allowCset, but does not allow cache when <c:set/> with var and value properties, it is only used on the current page context
\nnoCache: All expression is created each time the view is built

\n\n

Resources Cache

\n\n

From version 2.0.2, MyFaces provides org.apache.myfaces.RESOURCE_HANDLER_CACHE_ENABLED, which enables or disables the cache used to “remember” if a resource handled by the default ResourceHandler exists or not (default true), and org.apache.myfaces.RESOURCE_HANDLER_CACHE_SIZE, which controls the size of the cache used to check if a resource exists or not (default 500).

\n\n

View Handling Cache

\n\n

From version 2.0.2, MyFaces enables/disables cache via org.apache.myfaces.CHECKED_VIEWID_CACHE_ENABLED context parameter flag (default true), and set the size of this cache via the context parameter org.apache.myfaces.CHECKED_VIEWID_CACHE_SIZE (default 500). This cache is used to “remember” if a view exists or not and reduce the impact of successive calls to ExternalContext#getResource() method.\nIn addition, from version 2.0.13, MyFaces enable or disable a cache used to “remember” the generated facelets unique ids and reduce the impact over memory usage via org.apache.myfaces.VIEW_UNIQUE_IDS_CACHE_ENABLED (default false). MyFaces allows us to configure the size of cache used to store strings generated using SectionUniqueIdCounter for component ids, via the context parameter org.apache.myfaces.COMPONENT_UNIQUE_IDS_CACHE_SIZE(default 100).

\n\n

State Saving (state) Cache

\n\n

From older versions of MyFaces (1.1), we have org.apache.myfaces.SECRET.CACHE context parameter - if set to false, the secret key used for the encryption algorithm is not cached - and, org.apache.myfaces.MAC_SECRET.CACHE - if set to false, the secret key used for MAC algorithm is not cached. Of course, let’s not forget the org.apache.myfaces.CACHE_OLD_VIEWS_IN_SESSION_MODE context parameter. It defines the method of handling old view references (views removed from session), making it possible to store it in a cache; So the state manager first tries to get the view from the session. By default, is off and supports the following values: off, no, hard-soft, soft, soft-weak, weak.

\n\n

Beside these context parameters, browsers provide internal wizards, add-ons, plug-ins etc that can be used to control how the cache is done. HTML meta-tags, like CACHE-CONTROL, PRAGMA NO-CACHE, EXPIRES and LAST-MODIFIED are also useful. The JSF resource handler sets the EXPIRES and LAST-MODIFIED, and usually all we have to set is the CACHE-CONTROL.

\n\n

As a final note, do not forget about the JSF versioning system, which is based on the resources folder and libraries. By respecting JSF conventions, you can instruct JSF to load your latest resources very easily.

\n\n

PrimeFaces and OmniFaces server-side caching aspects

\n\n

But, what about caching a fragment of rendered markup (e.g. HTML markup)? Well, there is no JSF default configuration or context parameter for this. In this chapter, we will see how to cache HTML markup via PrimeFaces and OmniFaces approaches. PrimeFaces and OmniFaces support cache at rendering time. Basically, on the initial request, PrimeFaces and OmniFaces will cache the HTML markup that corresponds to the content delimited by <p:cache/> tag (in PrimeFaces) or by <o:cache/> tag (in OmniFaces). This means that the initial request doesn’t take advantage of caching. Furthermore, it will take longer than usual since at this moment PrimeFaces/OmniFaces caches the corresponding markup. But, at postbacks the cache will serve the cached HTML instead of rendering it again via specific renderers. This reduces the time for loading pages at postbacks.

\n\n

Caching HTML markup via PrimeFaces and EHCache

\n\n

PrimeFaces supports two different providers of cache implementation; EHCache and Hazelcast. First, we take a look at the EHCache provider.

\n\n

Let’s suppose that we have a static table that lists tennis players from ATP. See figure below (this table is produced via a simple usage of the <p:dataTable/> tag):

\n\n\n

\n\n\n

Rendering a table (<p:dataTable/>) is a time-consuming task, especially if the table contains many rows. So instead of re-rendering this static table, we are better off cache it. In order to accomplish this via PrimeFaces and EHCache, we need to follow these steps:

\n\n

Configure the pom.xml to contain the needed dependencies as below

\n\n

<dependencies>\n <dependency> \n  <groupId>org.primefaces</groupId> \n  <artifactId>primefaces</artifactId> \n  <version>5.3</version> \n </dependency>\n <dependency>\n  <groupId>org.ehcache</groupId>\n  <artifactId>ehcache</artifactId>\n  <version>3.0.0</version>\n </dependency>  \n <dependency>\n  <groupId>net.sf.ehcache</groupId>\n  <artifactId>ehcache</artifactId>\n  <version>2.10.1</version>\n </dependency>\n ...\n</dependencies>\n

\n\n\n\n

Configure the cache provider in web.xml via the primefaces.CACHE_PROVIDER context param

\n\n

<context-param>\n <param-name>primefaces.CACHE_PROVIDER</param-name>\n <param-value>org.primefaces.cache.EHCacheProvider</param-value>\n</context-param>\n

\n\n\n\n

Configure EHCache

\n\n

There are multiple ways to accomplish this. One of these consists of providing the ehcache.xml file in /src/main/resources folder of your application. The content of this file calibrates cache as you want (more details are available here):

\n\n

<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<ehcache xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n xsi:noNamespaceSchemaLocation=\"ehcache.xsd\" updateCheck=\"true\"\n monitoring=\"autodetect\" dynamicConfig=\"true\">\n\n <!-- By default, Ehcache stored the cached files in temp folder. -->\n <!-- <diskStore path=\"java.io.tmpdir\" /> -->\n      \n <!-- Ask Ehcache to store cache in this path -->\n <diskStore path=\"D:\\\\cache\" />\n       \n <!-- Sample cache named myCache\n      This cache contains a maximum in memory of 10000 elements, and will expire\n      an element if it is idle for more than 5 minutes and lives for more than\n      10 minutes. If there are more than 10000 elements it will overflow to the\n      disk cache -->   \n <cache name=\"myCache\"\n        statistics=\"true\"\n        maxEntriesLocalHeap=\"10000\"\n        maxEntriesLocalDisk=\"1000\"\n        eternal=\"false\"\n        diskSpoolBufferSizeMB=\"20\"\n        timeToIdleSeconds=\"300\" timeToLiveSeconds=\"600\"\n        memoryStoreEvictionPolicy=\"LFU\"\n        transactionalMode=\"off\">\n         <persistence strategy=\"localTempSwap\" />\n </cache>\n</ehcache>\n

\n\n\n\n\n\n

Use the <p:cache/> tag to point out the content that should be cached

\n\n

As you can see in the official documentation, this tag supports a bunch of optional attributes. We are especially interested in the region attribute which allows us to point to the cache region that we want to use, which is myCache in our case. Of course, this means that we can use <p:cache/> with different regions. Since, by default, the region defaults to view id (if you want to use it like this simply add a <defaultCache/> region), we need to explicitly set it as below:

\n\n

<p:cache region=\"myCache\">\n <p:dataTable var=\"t\" value=\"#{playersBean.data}\">\n  <p:column headerText=\"Player\">\n   <h:panelGroup id=\"playerId\">#{t.player}</h:panelGroup>\n  </p:column>\n\n  <p:column headerText=\"Age\">\n   <h:panelGroup id=\"ageId\">#{t.age}</h:panelGroup>\n  </p:column>\n\n  <p:column headerText=\"Birthplace\">\n   <h:panelGroup id=\"birthplaceId\">#{t.birthplace}</h:panelGroup>\n  </p:column>\n\n  <p:column headerText=\"Residence\">\n   <h:panelGroup id=\"residenceId\">#{t.residence}</h:panelGroup>\n  </p:column>\n\n  <p:column headerText=\"Height\">\n   <h:panelGroup id=\"heightId\">#{t.height} cm</h:panelGroup>\n  </p:column>\n\n  <p:column headerText=\"Weight\">\n   <h:panelGroup id=\"weightId\">#{t.weight} kg</h:panelGroup>\n  </p:column>\n </p:dataTable>\n</p:cache>\n

\n\n\n\n

Done! If you run the application at this point then everything should work as expected. You will notice that the initial request takes some time to load, while postbacks will work very fast. This is a sign that, on postbacks, the table markup comes from cache.

\n\n

Register MBeans in JConsole via OmniFaces `@Eager`\n

\n\n

But, how can we be sure that this is working? Well, EHCache provides management and monitoring using JMX. A simple approach consists off registering the cache statistics in the JDK platform MBeanServer, which works with the JConsole management agent. The needed code is listed below:

\n\n

CacheManager manager = CacheManager.create();\nMBeanServer mBeanServer = ManagementFactory.getPlatformMBeanServer();\nManagementService.registerMBeans(manager, mBeanServer, true, true, true, true);\n

\n\n\n\n

We can easily slip this code in an application scoped bean that is eagerly loaded via OmniFaces @Eager.

\n\n

@Eager\n@ApplicationScoped\npublic class CacheStatisticsBean {\n\n private static final Logger LOG = \n  Logger.getLogger(CacheStatisticsBean.class.getName());\n private static final String CACHE_MANAGER = \n  \"net.sf.ehcache:type=CacheManager,name=__DEFAULT__\";\n private static final String CACHE = \n  \"net.sf.ehcache:type=Cache,CacheManager=__DEFAULT__,name=myCache\";\n private static final String CACHE_STATISTICS = \n  \"net.sf.ehcache:type=CacheStatistics,CacheManager=__DEFAULT__,name=myCache\";\n private static final String CACHE_CONFIGURATION = \n  \"net.sf.ehcache:type=CacheConfiguration,CacheManager=__DEFAULT__,name=myCache\";\n private static final ArrayList<ObjectName> objectNames = \n                             new ArrayList<ObjectName>() {\n  {\n  try {\n      add(new ObjectName(CACHE_MANAGER));\n      add(new ObjectName(CACHE));\n      add(new ObjectName(CACHE_STATISTICS));\n      add(new ObjectName(CACHE_CONFIGURATION));\n  } catch (MalformedObjectNameException ex) {\n                Logger.getLogger(CacheStatisticsBean.class.getName()).\n                 log(Level.SEVERE, null, ex);\n  }\n }\n };\n\n @PostConstruct\n public void init() {\n  try {\n      LOG.info(\"------------ Configure JConsole MBeans ------------\");\n      MBeanServer mBeanServer = ManagementFactory.getPlatformMBeanServer();\n      LOG.info(\"----------------- Unregister MBeans ---------------\");\n      for (ObjectName name : objectNames) {\n           if (mBeanServer.isRegistered(name)) {\n               mBeanServer.unregisterMBean(name);\n           }\n      }\n\n      LOG.info(\"------------------ Register MBeans ----------------\");\n      CacheManager manager = CacheManager.create();\n      ManagementService.\n       registerMBeans(manager, mBeanServer, true, true, true, true);\n\n      LOG.info(\"------------ ------------------------  ------------\");\n  } catch (NullPointerException | InstanceNotFoundException | \n           MBeanRegistrationException ex) {\n    Logger.getLogger(CacheStatisticsBean.class.getName()).\n           log(Level.SEVERE, null, ex);\n  }\n }\n}\n

\n\n\n\n

Now we can perform a quick test to see if cache is working. For this, we have to run the application on the Payara application server. The steps of the test are:

\n\n

Delete the content of D:\\\\cache folder and ensure that Payara is not running.
Start the application server. For Payara simply, start it via asadmin start-domain form the /bin folder.
Start JConsole. Simply navigate to your Java home and double-click on jconsole.exe in the /bin folder.
Connect to Payara domain as in the figure below:

\n\n\n

\n\n\n

After the connection is successfully accomplished navigate to the MBeans tab. Notice the entry named net.sf.ehcache. This entry was added via the CacheStatisticsBean from above and is what we are looking for.

\n\n\n

\n\n\n

At this moment, there is nothing in the cache. For checking this, simply expose some attributes under CacheStatistics as DiskStoreObjectCount, MemoryStoreObjectCount, CacheHits, etc:

\n\n\n

\n\n\n

Now, deploy and run the application. After the application starts, let’s point out that at this moment we have 1 object stored in memory and on disk; nothing was read from cache yet:

\n\n\n

\n\n\n

Now, refresh the browser a few times or open the application in multiple tabs or even other browsers:

\n\n\n

\n\n\n

Well, now it is obvious that our cache is working fine.

\n\n

Programmatically, you can clean cache content like this:

\n\n

RequestContext.getCurrentInstance().\n getApplicationContext().getCacheProvider().clear();\n

\n\n\n\n

The complete application is named PFAndECache.

\n\n

Caching HTML markup via PrimeFaces and Hazelcast

\n\n

As mentioned earlier, PrimeFaces supports two different providers of cache implementation: EHCache and Hazelcast. Furthermore, we take a look at the Hazelcast provider based on the same scenario described above. So, instead of re-rendering this static table, we are better off caching it. In order to accomplish this via PrimeFaces and Hazelcast, we need to follow these steps:

\n\n

Configure the cache provider in web.xml via the primefaces.CACHE_PROVIDER context param

\n\n

<context-param>\n <param-name>primefaces.CACHE_PROVIDER</param-name>\n <param-value>org.primefaces.cache.HazelcastCacheProvider</param-value>\n</context-param>\n

\n\n\n\n

Use the <p:cache/> tag to point out the content that should be cached

\n\n

As you can see in the official documentation this tag supports a bunch of optional attributes. We are especially interested in the region and key attributes. The region attribute allows us to point to the cache region that we want to use, which is myCache in our case. The key attribute represents a unique id of the cache entry in regions and defaults to client id of the component. We set it as myTable. Of course, this means that we can use <p:cache/> with different regions and keys:

\n\n

<p:cache region=\"myCache\" key=\"myTable\">\n <p:dataTable var=\"t\" value=\"#{playersBean.data}\">\n  <p:column headerText=\"Player\">\n   <h:panelGroup id=\"playerId\">#{t.player}</h:panelGroup>\n  </p:column>\n\n  ... \n\n  <p:column headerText=\"Residence\">\n   <h:panelGroup id=\"residenceId\">#{t.residence}</h:panelGroup>\n  </p:column>\n\n  <p:column headerText=\"Height\">\n   <h:panelGroup id=\"heightId\">#{t.height} cm</h:panelGroup>\n  </p:column>\n\n  <p:column headerText=\"Weight\">\n   <h:panelGroup id=\"weightId\">#{t.weight} kg</h:panelGroup>\n  </p:column>\n </p:dataTable>\n</p:cache>\n

\n\n\n\n

Done! If you run the application at this point then everything should work as expected. You will notice that the initial request takes some time to load, while postbacks work very fast. This is a sign that, on postbacks, the table markup comes from cache. Moreover, you can see that Hazelcast is at work:

\n\n\n

\n\n\n

But, let’s add some code to check the cache content. First, let’s display the cache content in the page:

\n\n

Cache content:\n<hr/>       \n <p>\n  <code>\n   #{playersBean.showCache()}\n  </code>\n </p>\n<hr/>\n

\n\n\n\n

public Object showCache() {\n HazelcastCacheProvider cacheProvider = (HazelcastCacheProvider)\n  RequestContext.getCurrentInstance().getApplicationContext().getCacheProvider();\n return cacheProvider.get(\"myCache\", \"myTable\");\n}\n

\n\n\n\n

We also may want to programmatically remove our entry from cache. For this we can simply use an action method as below:

\n\n

public void clearCache() {\n HazelcastCacheProvider cacheProvider = (HazelcastCacheProvider)\n  RequestContext.getCurrentInstance().getApplicationContext().getCacheProvider();\n cacheProvider.remove(\"myCache\", \"myTable\");\n}\n

\n\n\n\n

On the initial request there is nothing in the cache:

\n\n\n

\n\n\n

On postback (click the Refresh button) the cache content shows the HTML markup corresponding to our data table:

\n\n\n

\n\n\n

Furthermore, if you click the Clear Cache button, the cache entry will be removed.

\n\n

The complete application is named PFAndHazelcast.

\n\n

Caching HTML markup via OmniFaces

\n\n

In this section we will discuss caching HTML markup via OmniFaces Cache component. The OmniFaces cache allows us to control the re‐caching interval individually per fragment, cache value expressions, reset caching programmatically or via an attribute, cache a number of limited elements(items), cache post‐processing code and disable caching for only one request and more. Caching can take place in application scope or in session scope.

\n\n

In this section, you will see several examples that use the OmniFaces Cache component. We will cache tables, forms, panels, etc. You will see how to take advantage of the Cache attributes, depending on the goal of the application and on the content type that will be cached. The Cache component is exposed to page authors via the <o:cache/> tag.

\n\n

The simplest cache can be achieved by using the <o:cache/> without attributes (fixed cache). In this case, its attributes rely on the default values: key (no value), scope (session), time (no value), useBuffer (false), reset (false), disabled (false). Below you can see how to cache a markup for a <p:dataTable/>:

\n\n

<o:cache>\n <p:dataTable var=\"t\" value=\"#{playersBean.data}\">\n  <p:column headerText=\"Player\">\n   <h:panelGroup id=\"playerId\">#{t.player}</h:panelGroup>\n  </p:column>\n  ...\n </p:dataTable>\n</o:cache>\n

\n\n\n\n

Simple caching

\n\n

On initial request, the Cache component will add in cache (represented by a special Map) an entry composed of a generated key (used for identifying this entry) and the rendered markup, as a value. So each cached snippet is an entry in this Map. On postbacks the <p:dataTable/> markup will be supplied from the cache using the corresponding key.

\n\n

The complete application is named OFSimpleCache.

\n\n

When no key is indicated, OmniFaces will generate one of type viewId+\"_\"+clientId. But, you can indicate a custom key via the key attribute, like this:

\n\n

<o:cache key=\"myTable\">\n ...\n</o:cache>\n

\n\n\n\n

Reset caching

\n\n

The reset attribute is a flag that defaults to false. When it is set to true, the corresponding entry is removed from cache and the latest rendered markup is added in the cache under the same key. OmniFaces also supports cached value expressions via <o:cachevalue/>. These will be explained in more detail below, but for now it suffices to say they will be re‐evaluated when next referenced. Below, we remove players from table one by one and we reset the cache each time the size of data is even.

\n\n

<!-- Each time we press this button a player is remove from table -->\n<h:form>\n <p:commandButton value=\"Remove player (#{playersBean.data.size()})\" \n                  action=\"#{playersBean.removePlayer()}\" ajax=\"false\"/>\n</h:form>\n

\n\n\n\n

This time the <o:cache/> is used as below:

\n\n

<o:cache reset=\"#{playersBean.data.size() % 2 eq 0}\">\n <p:dataTable var=\"t\" value=\"#{playersBean.data}\">\n  <p:column headerText=\"Player\">\n   <h:panelGroup id=\"playerId\">#{t.player}</h:panelGroup>\n  </p:column>\n  ...\n </p:dataTable>\n</o:cache>\n

\n\n\n\n

On initial request the table is cached and contains 10 players:

\n\n\n

\n\n\n

If we press the Remove Player once, we can not see any changes reflected in the table content because this content is provided from cache (but, we have 9 players in data now):

\n\n\n

\n\n\n

Furthermore, if we press the Remove Player button one more time then one more player will be removed from the data. Since this time the size of data is 8 (an even number) the cache will be reset and re-cached. This action is not visually reflected by the table content:

\n\n\n

\n\n\n

This test can continue until there are no more players in the data. This is useful when you want to synchronize the cache content with the current content.\nFor example, when a data table reflects a database content, you may want to cache the table content instead of “hitting” the database, again. But when new records are inserted/deleted/updated in the database, you may want to reset the cache and “hit” the database for the new updates, which will be cached again under the same key.

\n\n

The complete application is named OFResetCache.

\n\n

The above example is a reset via component attribute, but you can also reset it programmatically (the second argument of the getCache() method represents the scope of the cache, and, for the default provider (presented later), this can be session or application):

\n\n

public void resetProgrammaticFromSessionScope() {\n CacheFactory.getCache(getContext(), \"session\").remove(\"foo_key\");\n}\n

\n\n\n\n

For a key generated automatically by OmniFaces, you can also use the below approaches (practically build a key exactly as OmniFaces does):

\n\n

FacesContext context = FacesContext.getCurrentInstance();\nCacheFactory.getCache(getContext(), cacheComponent.getScope()).\nremove(\"viewId\" + \"_\" + \"clientId\");\n// or\nremove(context.getViewRoot().getViewId()+ \"_\" + \n cacheComponent.getClientId(context));\n

\n\n\n\n

Or, if you have access to the Cache component itself:

\n\n

org.omnifaces.component.output.cache.Cache cacheComponent;\n...\npublic void resetProgrammaticFromSessionScope() {\n CacheFactory.getCache(getContext(), cacheComponent.getScope()).\n  remove(cacheComponent.getKey());\n}\n

\n\n\n\n

Caching post processing

\n\n

Going further, the Cache component comes with an attribute named useBuffer that defaults to false. This attribute is needed when you want to cache markup that contains a post‐processing part (cache <h:form/> ‐ nothing else does post‐processing; forms write (client) state after view is rendered). This is for advanced users who really understand the implications of caching forms. For now, letʹs say that we need to place our table in a <h:form/> and we donʹt use buffering:

\n\n

<o:cache>\n <h:form>\n  <p:dataTable var=\"t\" value=\"#{playersBean.data}\">\n   <p:column headerText=\"Player\">\n    <h:panelGroup id=\"playerId\">#{t.player}</h:panelGroup>\n   </p:column>\n   ...\n  </p:dataTable>\n  <p:commandButton value=\"Submit\" ajax=\"false\"/>\n </h:form>\n</o:cache>\n

\n\n\n\n

Now the entire form is cached, except the post‐processing part, which in the case of a form is represented by a markup similar to this – it is easy to see that this part is not coming from cache if you compare the value of the javax.faces.ViewState at multiple requests. For example, at initial request you may see something like this:

\n\n

<input type=\"hidden\" name=\"javax.faces.ViewState\" \n       id=\"j_id1:javax.faces.ViewState:0\" \n       value=\"-7261722298707610536:-3405156646486980264\" \n       autocomplete=\"off\" />\n

\n\n\n\n

At postback, instead of the above code, you will see this:

\n\n

~com.sun.faces.saveStateFieldMarker~\n

\n\n\n\n\n\n

<o:cache useBuffer=\"true\">\n <h:form>\n  <p:dataTable var=\"t\" value=\"#{playersBean.data}\">\n   <p:column headerText=\"Player\">\n    <h:panelGroup id=\"playerId\">#{t.player}</h:panelGroup>\n   </p:column>\n   ...\n  </p:dataTable>\n  <p:commandButton value=\"Submit\" ajax=\"false\"/> \n </h:form>\n</o:cache>\n

\n\n\n\n

This time the post-processing part is cached, and you will see the same result at each postback.

\n\n

When this attribute is set to true, OmniFaces needs a special filter that will be capable of buffering the Faces Servlet response. This filter is named org.omnifaces.filter.OnDemandResponseBufferFilter, and you can configure it in web.xml descriptor, like this:

\n\n

Use the org.omnifaces.CACHE_INSTALL_BUFFER_FILTER context parameter:

\n\n

<context-param>\n <param-name>org.omnifaces.CACHE_INSTALL_BUFFER_FILTER</param-name>\n <param-value>true</param-value>\n</context-param>\n

\n\n\n\n

Use the classic style, add <filter/> tag:

\n\n

<filter>\n <filter-name>bufferFilter</filter-name> \n <filter-class>org.omnifaces.filter.OnDemandResponseBufferFilter</filter-class>\n</filter>\n<filter-mapping>\n <filter-name>bufferFilter</filter-name> \n <url-pattern>/faces/*</url-pattern>\n</filter-mapping>\n

\n\n\n\n

In a real case scenario, you may want to use *.xhtml or filter the FacesServlet itself. The *.xhtml is better because it prevents a security issue (source code exposure), while if all views are enabled, filtering on the FacesServlet is better since then the filter doesnʹt have the knowledge off the actual mapping. The power of manually mapping filters is that it can be done for specific pages.

\n\n

The complete application is named OFCacheBuffer.

\n\n

Cache scope

\n\n

For the default cache provider, OmniFaces can store the cache in session or in application. If the scope attribute is not specified, then the cache is stored in session. Below, we have stored the same markup in session and in application ‐ for testing this example, use two different browsers:

\n\n

<o:cache scope=\"session\">\n <p:dataTable var=\"t\" value=\"#{playersBean.data}\">\n  <p:column headerText=\"Player\">\n   <h:panelGroup id=\"playerId\">#{t.player}</h:panelGroup>\n  </p:column>\n  ...\n </p:dataTable>\n</o:cache>\n\n<o:cache scope=\"application\">\n <p:dataTable var=\"t\" value=\"#{playersBean.data}\">\n  <p:column headerText=\"Player\">\n   <h:panelGroup id=\"playerId\">#{t.player}</h:panelGroup>\n  </p:column>\n  ...\n </p:dataTable>\n</o:cache>\n

\n\n\n\n

The complete application is named OFCacheScope.

\n\n

Disabling cache

\n\n

The OmniFaces cache can be disabled per request by using the disabled attribute (default false). If the cache is disabled then the cache children will be directly rendered without influencing the cached data. When cache is enabled again, you will see the content that was cached before disabling it. The content rendered between disabled=\"true\" and disabled=\"false\" doesnʹt interact with cache. For example, we can control the disable of caching by using a simple button and a ValueExpression as below:

\n\n

<h:form>\n <p:commandButton value=\"Remove player\" \n                 action=\"#{playersBean.removePlayer()}\" ajax=\"false\"/>\n <!-- cache enable/disable switch -->\n <p:commandButton value=\"Enabled/Disable Cache (status: \n                         #{playersBean.disabled ? \n                        'disabled' : 'enabled'})\"\n                  action=\"#{playersBean.cacheOnOff()}\" ajax=\"false\"/>\n</h:form>\n\n<o:cache disabled=\"#{playersBean.disabled}\">\n <p:dataTable var=\"t\" value=\"#{playersBean.data}\">\n  <p:column headerText=\"Player\">\n   <h:panelGroup id=\"playerId\">#{t.player}</h:panelGroup>\n  </p:column>\n  ...\n </p:dataTable>\n</o:cache>\n

\n\n\n\n

The complete application is named OFCacheDisabled.

\n\n

Control the cache size

\n\n

By default, the OmniFaces cache doesnʹt have a pre‐defined limit, but if you want to control the size of this cache then you can set it in the web.xml a maximum capacity via the org.omnifaces.CACHE_SETTING_SESSION_MAX_CAPACITY context parameter. The value of this parameters indicates the maximum number of elements (items) that can be stored in the cache. You can think of an element (item) as a single <o:cache/>. So, if you define a maximum size of 3, then you can use three <o:cache/> tags. The fourth <o:cache/> will cause the OmniFaces to remove one element and add this one instead of it. The one that will be removed is calculated using the LRU (Least Recently Used) algorithm.

\n\n

<context-param>\n <param-name>org.omnifaces.CACHE_SETTING_SESSION_MAX_CAPACITY</param-name> \n <param-value>3</param-value>\n</context-param>\n

\n\n\n\n

Caching a fragment of render markup for a limited period of time

\n\n

OmniFaces allows us to use cache for a fixed period of time specified in seconds (known as TTL ‐ Time To Live. This can be done at the element level, using the time attribute (allows individual times) or globally, in the web.xml, via the context parameters: org.omnifaces.CACHE_SETTING_SESSION_TTL and org.omnifaces.CACHE_SETTING_APPLICATION_TTL. The time attribute will override these context parameters. Notice that, when the time has elapsed, the default cache implementation will NOT automatically refresh the cache. New content will only be inserted into the cache following a page request. Without a request, even if time has elapsed, the viewed content (and the cached content) remains the same. Moreover, note that this component does not support a cache loader and locking mechanism ‐ the locking is mostly a feature of the cache provider, and the default provider indeed does not support locking. A Cache loader would be difficult, since it means you need to have a way of rendering markup outside a JSF request. For the moment, this means that after content times out, several simultaneous page requests may render the same content. Furthermore, itʹs\nundetermined which of those will end up being cached.

\n\n

Plug in a cache provider

\n\n

In order to provide a more powerful cache implementation, OmniFaces allows you to plug‐in a cache provider in web.xml as below:

\n\n

<context-param>\n <param-name>org.omnifaces.CACHE_PROVIDER</param-name> \n <param-value>com.example.MyProvider</param-value>\n</context-param>\n

\n\n\n\n\n\n

Caching EL

\n\n

OmniFaces provides a special TagHandler for caching EL. It is exposed via <o:cacheValue/> tag, and it is important to know that:

\n\n

The direct parent of this component MUST be Cache or a potential subclass of the associated UIComponent. Itʹs an error to have any other kind of parent.
If the parent Cache component clears its cache (e.g. because of time to live expiration), the value cached by this value expression will be automatically cleared as well.

\n\n

In order to use <o:cacheValue/> you have to indicate two required attributes:

\n\n

\nname ‐ Indicates the name under which the value expression will be made available to EL, scoped to the Facelet in which this tag occurs.
\nvalue ‐ Indicates the value expression for which its value will be cached on demand and made available as a new value expression.

\n\n

Remember our table of players? Well, letʹs adjust it a little:

\n\n

<h:form>\n Selected player: #{playersBean.selectedPlayer}\n <o:cache>\t  \n  <p:dataTable value=\"#{playersBean.data}\" var=\"t\">\n   <p:column headerText=\"Player (with fixed cache)\">\n    #{t}\n   </p:column>\n   <p:column>\n    <p:commandButton value=\"Select\" \n                     action=\"#{playersBean.selectPlayer(t)}\" update=\"@form\" />\n   </p:column>\n  </p:dataTable>\n </o:cache>\n</h:form>\n

\n\n\n\n

Now, you may think that everything will work smoothly: the table content is cached and by pressing a button labeled Select, a player will be selected and you will see the selected player displayed above the table. This is only apparently correct, because as the OmniFaces Showcase explains, JSF doesnʹt send the actual row data alone, but merely a row number. Because the backing bean is request scoped and the expression #{playersBean.data} is freshly evaluated after each postback, you will see the new selection each time. You can visually achieve this by shuffling the players list on each request. When you do that, you will see this “strange” behavior (notice that the selected player doesn’t match the player listed in the table):

\n\n\n

\n\n\n

We did multiple selections until the above screenshot was taken. The Cache Content doesnʹt change (even if we shuffle the collection that feeds the table, its markup comes from cache), the Cache EL Content is null (since we didnʹt use <o:cacheValue/>) and the current selection (indicated by the red arrow) doesnʹt match the selected player! Obviously, this is not correct. Now let’s adjust the code to cache the #{playersBean.data} expression:

\n\n

<h:form>\n Selected player: #{playersBean.selectedPlayer}\n <o:cacheValue name=\"data\" value=\"#{playersBean.data}\"/>\n  <p:dataTable value=\"#{data}\" var=\"t\" style=\"width:350px;\">\n   <p:column headerText=\"Player (with fixed cache)\">\n    #{t}\n   </p:column>\n   <p:column>\n    <p:commandButton value=\"Select\" \n                     action=\"#{playersBean.selectPlayer(t)}\" update=\"@form\" />\n   </p:column>\n  </p:dataTable>\n </o:cache>\n</h:form>\n

\n\n\n\n

This time things go as we expected:

\n\n\n

\n\n\n

The complete application is named OFCachingEL. As a bonus, in this application, you will also see a test that reveals how <o:cacheValue/> acts if we disable the <o:cache/>.You should notice that, in this case, we can cache the expression instead of the table and not in addition of the table. To see the cache content and cache EL content for a specific key (and name), you can use these two methods:

\n\n

public String getCacheContent(String key) {\n String cacheContent = CacheFactory.getCache(getContext(),\n                       \"session/application\").get(key);\n return cacheContent == null ? \"null\" : cacheContent;\n}\n\npublic String getCacheELContent(String key, String name) {\n Object cacheELContent = CacheFactory.getCache(getContext(),\n                         \"session/application\").getAttribute(key, name);\n return cacheELContent == null ? \"null\" : cacheELContent.toString();\n}\n

\n\n\n\n

The `<o:cache/>` resume

\n\n

Cache component is exposed to JSF page authors via <o:cache/> tag.
Cache encapsulates a server-side caching mechanism for the markup produced by the Render Response phase.
Cache takes action in Render Response phase.
The cached markup is stored under a key generated by OmniFaces or indicated via the optional key attribute of <o:cache/>.
Caching can be disabled per request via the optional disabled flag attribute of <o:cache/>.
A cached entry can be re-cached via reset flag attribute of the <o:cache/>.
By default, cached data is stored in session scope (application scope is also supported).

\n\n

Add a header with given a name and value to the HTTP response

\n\n

The OmniFaces addResponseHeader() method adds a header with a given name and value to the HTTP response. For example, you can add cache specific headers like below:

\n\n

import org.omnifaces.util.Faces;\n...\n// set 'Content-Type' response header\nFaces.addResponseHeader(\"Content-Type\", \"text/html; charset=UTF-8\");\n// set 'Cache-Control' response header\nFaces.addResponseHeader(\"Cache-Control\", \"no-cache, no-store\");\n

\n\n\n\n\n

\n\n\n

Facelets default non-hot reload in production

\n\n

JSF has the ability to cache Facelets. In order to update the cache, JSF performs periodic checks of Facelets views changes. In the development stage, you may need to perform this check much often than in production. For this, you can set the javax.faces.FACELETS_REFRESH_PERIOD context parameter as shown in the following example (the value represents the number of seconds between two consecutive checks).

\n\n

// 5 SECONDS TIMEOUT\n\n<context-param>\n <param-name>javax.faces.FACELETS_REFRESH_PERIOD</param-name>\n <param-value>5</param-value>\n</context-param>\n

\n\n\n\n

There are two special values:

\n\n

-1 means no refresh (cache indefinitely)

\n\n

0 means no caching at all (always hot reload)

\n\n

Starting with JSF 2.3, when the project stage is Production (default) the Facelets refresh period is -1 (no refresh).

\n\n

Chapter 14: Handling exceptions

\n\n

In this chapter, we will discuss handling exceptions (especially AJAX exceptions) in JSF applications via PrimeFaces and OmniFaces solutions. In addition, we will discuss OmniFaces approach of adding every exception as a global FATAL faces message.

\n\n

Handling AJAX exceptions

\n\n

Exception handling is an important aspect of any application that needs to work in the production field. As you probably know the exceptions that occur in JSF applications during AJAX requests are not treated as exceptions that occur during non‐AJAX requests. By default, most of them are invisible to the client. Since the user doesnʹt receive feedback about AJAX request success, he/she may get confused, restart the application, or resend the request, etc.

\n\n

Working with OmniFaces exception handler

\n\n

For example, let’s suppose the below managed bean which acts as an exceptions, gets triggered via several action methods:

\n\n

@Named\n@RequestScoped\npublic class ExceptionBean {\n\n public void throwNullPointerException() {\n  throw new NullPointerException(\"A NullPointerException!\");\n }\n\n public void throwWrappedIllegalStateException() {\n  Throwable t = new IllegalStateException(\"A wrapped IllegalStateException!\");\n  throw new FacesException(t);\n }\n\n public void throwMyCoolException() throws MyCoolException {\n  throw new MyCoolException(\"A NullPointerException!\");\n }\n}\n\npublic class MyCoolException extends Exception {\n\n private static final long serialVersionUID = 1997753363232807009L;\n\n public MyCoolException() {\n  // NOPE\n }    \n \n MyCoolException(String msg) {\n  super(msg);\n }\n}\n

\n\n\n\n

Furthermore, we add a command button per action method. Each of these buttons will fire an AJAX request:

\n\n

<h:form>             \n <p:commandButton value=\"Throw NullPointerException\" \n                  action=\"#{exceptionBean.throwNullPointerException()}\"/>\n <p:commandButton value=\"Throw Wrapped IllegalStateException\" \n                  action=\"#{exceptionBean.throwWrappedIllegalStateException()}\"/>\n <p:commandButton value=\"Throw MyCoolException\" \n                  action=\"#{exceptionBean.throwMyCoolException()}\"/>\n</h:form> \n

\n\n\n\n

Let’s suppose that we run this application and we press the button Throw NullPointerException:

\n\n\n

\n\n\n

Well, if we check the server log then we will see a java.lang.NullPointerException reported, but on the client side (in the browser) nothing happens. Nevertheless, if we use a browser debugging tool such as Firebug we find this exception in the partial response as in the figure below:

\n\n\n

\n\n\n

It would be nice to be informed about this exception in a more suggestive way. So, let’s see how we can deal with this issue via OmniFaces and PrimeFaces. From a JSF lifecycle’s perspective, we need to handle different kinds of exceptions in different phases of the application. Starting with JSF 2, we have a generic API that allows us to write a global exception handler. This is very helpful, especially when we need to signal the “silent” exceptions that are not reported to the user or otherwise are reported in a very discreet manner. In order to write a global exception handler, we need to do the following:

\n\n

Extend the ExceptionHandlerFactory, which is a factory object that is capable of creating and returning a new ExceptionHandler instance, and override the getExceptionHandler() method.
Extend the ExceptionHandlerWrapper, which is a simple implementation of ExceptionHandler, and override the handle() method.
Configure the custom exception handler in faces-config.xml.

\n\n

Based on these steps, OmniFaces has implemented an ExceptionHandler named FullAjaxExceptionHandler and PrimeFaces has another one named PrimeExceptionHandler.

\n\n

The OmniFaces exception handler allows developers to handle exceptions that occur during AJAX requests via error pages configured in web.xml (or web-fragment.xml). In order to exploit the FullAjaxExceptionHandler, we need to explicitly configure the FullAjaxExceptionHandlerFactory in the faces-config.xml. This is not implicitly configured, so we need to do it like this:

\n\n

<factory>\n <exception-handler-factory>\n   org.omnifaces.exceptionhandler.FullAjaxExceptionHandlerFactory\n </exception-handler-factory>\n</factory>\n

\n\n\n\n\n\n

If we run the application again and press the Throw NullPointerException button, Firebug will reveal the following exception (this also happens for the other two buttons also):

\n\n\n

\n\n\n

This exception is fired by OmniFaces and signals that we didn’t configure an error page for this exception. So, after we configure the FullAjaxExceptionHandler, we need to add the error pages in the web.xml (or web-fragment.xml) via <error-page/> tag. These configurations should fit the exceptions that we want to report. For example, in our case, we may want to have an error page for the java.lang.NullPointerException exception and another page for the wrapped IllegalStateException exception. We can easily configure these pages in the web.xml like this:

\n\n

<error-page>\n <exception-type>java.lang.NullPointerException</exception-type>\n <location>/WEB-INF/errors/NullPointerException.xhtml</location>\n</error-page>\n<error-page>\n <exception-type>java.lang.IllegalStateException</exception-type>\n <location>/WEB-INF/errors/IllegalStateException.xhtml</location>\n</error-page> \n

\n\n\n\n

Now, if we press the Throw NullPointerException button, we obtain something like in the figure below (this is the code of the /WEB-INF/errors/NullPointerException.xhtml page):

\n\n\n

\n\n\n

But, most of the time we cannot anticipate all the exceptions that may occur. This is why it is a good practice to provide at least a fall back error page whenever thereʹs no match to any of the declared specific exceptions. When we have error pages for specific exception types, then we’d better use the 500 status code as a fallback error page:

\n\n

<error-page>\n <error-code>500</error-code>\n <location>/WEB-INF/errors/500.xhtml</location>\n</error-page>\n

\n\n\n\n

In order to see this at work, we can press the Throw MyCoolException button (notice that for this exception type we did not intentionally set an entry in the web.xml file). This will reveal the /WEB-INF/errors/500.xhtml which looks like the below (fall back error page):

\n\n\n

\n\n\n\n\n\n

\n\n\n\n\n\n\n

Done! The complete application is named OFHandleAjaxException.

\n\n

Displaying details of exceptions

\n\n

Typically, the error page contains more than a simple message as we did above. For example, we may want to see some details about the thrown exception such as the HTTP error status code, the error type, the user IP and so on. Well, in the case of FullAjaxExceptionHandler the details are available in the request scope and they are the standard Servlet error request attributes like in any error page response. So, we have the following details available:

\n\n

date/time when the exception occurred, #{of:formatDate(now, 'yyyy-MM-dd HH:mm:ss')};
user agent, #{header['user-agent']};
user IP, #{request.remoteAddr};
request URI, #{requestScope['javax.servlet.error.request_uri']};
Ajax request, #{facesContext.partialViewContext.ajaxRequest ? 'Yes' : 'No';
status code, #{requestScope['javax.servlet.error.status_code']};
exception type, #{requestScope['javax.servlet.error.exception_type']};
exception message, #{requestScope['javax.servlet.error.message']};
stack trace, #{of:printStackTrace(requestScope['javax.servlet.error.exception'])};

\n\n\n\n

Most probably, you will want to present the above information in a list or styled with some CSS as in the figure below:

\n\n\n

\n\n\n

As you can see, we can use this information to write custom error pages per exception or to use a single fall back styled error page.

\n\n

<error-page>\n <error-code>500</error-code>\n <location>/WEB-INF/errors/500.xhtml</location>\n</error-page> \n

\n\n\n\n

The complete application is named, OFAjaxExceptionDetails.

\n\n

Unwrapping the AJAX exceptions

\n\n

Earlier, in the OFHandleAjaxException application we triggered an exception of type IllegalStateException wrapped in a FacesException. Even if the \nIllegalStateException is wrapped the application reports it correctly as in the figure below:

\n\n\n

\n\n\n

Well, we obtain this behavior because, by default, the FacesException and ELException are unwrapped. But, let’s suppose that we trigger the same IllegalStateException wrapped in an SQLException:

\n\n

@Named\n@RequestScoped\npublic class ExceptionBean {\n\n public void throwWrappedIllegalStateException() throws SQLException {\n  Throwable t = new IllegalStateException(\"A wrapped IllegalStateException!\");\n  throw new SQLException(t);\n } \n}\n

\n\n\n\n

And, in the web.xml we have the following error page set:

\n\n

<error-page>\n <exception-type>java.lang.IllegalStateException</exception-type>\n <location>/WEB-INF/errors/IllegalStateException.xhtml</location>\n</error-page>\n

\n\n\n\n

Since the SQLException is not unwrapped by default, the above scenario will not work as expected. Actually, no error will be reported! In order to fix this issue we have at least three possibilities:

\n\n

Modify the exception type in the web.xml to correspond to the java.sql.SQLException:

\n\n

<error-page>\n <exception-type>java.sql.SQLException</exception-type>\n <location>/WEB-INF/errors/IllegalStateException.xhtml</location>\n</error-page>\n

\n\n\n\n

This case will lead to the following report:

\n\n\n

\n\n\n

Keep the exception type that corresponds to the IllegalStateException and supply the context parameter org.omnifaces.EXCEPTION_TYPES_TO_UNWRAP to specify additional exception types to unwrap:

\n\n

 <context-param>\n  <param-name>org.omnifaces.EXCEPTION_TYPES_TO_UNWRAP</param-name>\n  <param-value>java.sql.SQLException</param-value>\n </context-param>\n

\n\n\n\n

This case will lead to the following report:

\n\n\n

\n\n\n\n\n

Use a fall back error page whenever thereʹs no match to any of the declared specific exceptions:

\n\n

<error-page>\n <error-code>500</error-code>\n <location>/WEB-INF/errors/500.xhtml</location>\n</error-page>\n

\n\n\n\n

The complete application is named OFUnwrapAjaxException.

\n\n

Customizing `FullAjaxExceptionHandler`\n

\n\n

In order to obtain more control over the behavior of FullAjaxExceptionHandler, the OmniFaces team allows us to override the following methods (their names are very suggestive, but you can also check the documentation):

\n\n

Now, when we decide to override any of these methods, we need to follow the next steps:

\n\n

extend the FullAjaxExceptionHandler;
override the desired methods;
create a custom ExceptionHandlerFactory;
register the custom ExceptionHandlerFactory in faces-config.xml;

\n\n\n\n

Ok, as a proof of concept we have followed the above code and we have obtained a skeleton that you can further use for a real implementation. First, we extend the FullAjaxExceptionHandler as below:

\n\n

public class MyAjaxExceptionHandler extends FullAjaxExceptionHandler {\n\n private static final Logger LOG = \n  Logger.getLogger(MyAjaxExceptionHandler.class.getName());\n\n public MyAjaxExceptionHandler(ExceptionHandler wrapped) {\n  super(wrapped);\n }    \n\n @Override\n protected Throwable findExceptionRootCause(FacesContext context, \n                                             Throwable exception) {\n  LOG.info(\"MyAjaxExceptionHandler#findExceptionRootCause()\");\n  return super.findExceptionRootCause(context, exception);\n }\n    \n @Override\n protected boolean shouldHandleExceptionRootCause(FacesContext context, \n                                                   Throwable exception) {\n  LOG.info(\"MyAjaxExceptionHandler#shouldHandleExceptionRootCause()\");\n  return super.shouldHandleExceptionRootCause(context, exception);\n }\n\n @Override\n protected String findErrorPageLocation(FacesContext context, \n                                         Throwable exception) {\n  LOG.info(\"MyAjaxExceptionHandler#findErrorPageLocation()\");\n  return super.findErrorPageLocation(context, exception);\n }\n\n @Override\n protected void logException(FacesContext context, Throwable exception,\n                 String location, String message, Object... parameters) {\n  LOG.info(\"MyAjaxExceptionHandler#logException()\");\n  super.logException(context, exception, location, message, parameters);\n }\n\n @Override\n protected void logException(FacesContext context, Throwable exception,\n                             String location, LogReason reason) {\n  LOG.info(\"MyAjaxExceptionHandler#logException()\");\n  super.logException(context, exception, location, reason);\n }\n}\n

\n\n\n\n

Furthermore, we create a custom ExceptionHandlerFactory as follows:

\n\n

public class MyExceptionHandlerFactory extends ExceptionHandlerFactory {\n\n private ExceptionHandlerFactory exceptionHandlerFactory;\n\n public MyExceptionHandlerFactory(){        \n }\n    \n public MyExceptionHandlerFactory(ExceptionHandlerFactory \n                                  exceptionHandlerFactory) {\n  this.exceptionHandlerFactory = exceptionHandlerFactory;\n }\n\n @Override\n public ExceptionHandler getExceptionHandler() {\n  ExceptionHandler handler = new MyAjaxExceptionHandler(exceptionHandlerFactory.\n                                                         getExceptionHandler());\n\n  return handler;\n }\n}\n

\n\n\n\n

Finally, we register the MyExceptionHandlerFactory in the faces-config.xml:

\n\n

<factory>\n <exception-handler-factory>\n  exceptionhandler.MyExceptionHandlerFactory\n </exception-handler-factory>\n</factory>\n

\n\n\n\n

In order to test it, we just trigger a NullPointerException exception. In the server log we obtain the output from the below figure:

\n\n\n

\n\n\n

The complete application is named OFCustomAjaxExceptionHandler.

\n\n

Working with PrimeFaces exception handler

\n\n

Furthermore, let’s talk about the PrimeFaces exception handler. This is named PrimeExceptionHandler and it is available in org.primefaces.application.exceptionhandler package. The PrimeFaces exception handler can be used for AJAX and non-AJAX requests, but let’s see a suite of examples that only treats the AJAX exceptions (for non-AJAX things are pretty much the same).

\n\n

The first thing to accomplish consists of configuring/activating the exception handler in faces-config.xml as below (basically, the PrimeFaces exception handler is “served” by a dedicated factory named PrimeExceptionHandlerFactory):

\n\n

<factory>\n <exception-handler-factory>\n  org.primefaces.application.exceptionhandler.PrimeExceptionHandlerFactory\n </exception-handler-factory>\n</factory>\n

\n\n\n\n

Furthermore, in the web.xml (or web-fragment.xml) file of our application, we configure the following error pages (notice the 500.xhtml page which is our fall back error page; exactly like in the case of OmniFaces, this page is shown when thereʹs no match to any of the declared specific exceptions):

\n\n

<error-page>\n <exception-type>java.lang.NullPointerException</exception-type>\n <location>/faces/pages/errors/NullPointerException.xhtml</location>\n</error-page>\n<error-page>\n <exception-type>java.lang.IllegalStateException</exception-type>\n <location>/faces/pages/errors/IllegalStateException.xhtml</location>\n</error-page>\n<error-page>\n <error-code>500</error-code>\n <location>/faces/pages/errors/500.xhtml</location>\n</error-page> \n

\n\n\n\n

In order to create a scenario, we will use a simple bean capable of throwing several exceptions:

\n\n

Named\n@RequestScoped\npublic class ExceptionBean {\n\n public void throwNullPointerException() {\n  throw new NullPointerException(\"A NullPointerException!\");\n }\n\n public void throwWrappedIllegalStateException() {\n  Throwable t = new IllegalStateException(\"A wrapped IllegalStateException!\");\n  throw new FacesException(t);\n }\n\n public void throwMyCoolException() throws MyCoolException {\n  throw new MyCoolException(\"A MyCoolException!\");\n }\n} \n

\n\n\n\n

And, we trigger these exceptions via three command buttons:

\n\n

<h:form>             \n <p:commandButton ajax=\"false\" value=\"Throw NullPointerException\" \n                  action=\"#{exceptionBean.throwNullPointerException()}\"/>\n <p:commandButton value=\"Throw Wrapped IllegalStateException\" \n                  action=\"#{exceptionBean.throwWrappedIllegalStateException()}\"/>\n <p:commandButton value=\"Throw MyCoolException\" \n                  action=\"#{exceptionBean.throwMyCoolException()}\"/>\n</h:form>\n

\n\n\n\n

That’s all! We just finished our example, and if we arbitrarily choose to press a button then the application will return the error page that corresponds to the thrown exception.

\n\n\n\n\n

\n\n\n\n\n\n\n

The complete application is named PFAjaxExceptionDeclarative.

\n\n

Displaying details of exceptions

\n\n

In order to display details about an exception, we need to add one more configuration in our faces-config.xml. Basically, PrimeFaces provides access to several details about the exception via a custom EL resolver, named PrimeExceptionHandlerELResolver. This is available in org.primefaces. application.exceptionhandler. This can be configured next to the PrimeExceptionHandlerFactory as follows:

\n\n

<application>\n <el-resolver>\n  org.primefaces.application.exceptionhandler.PrimeExceptionHandlerELResolver\n </el-resolver>\n</application>\n

\n\n\n\n

Once we’ve done this configuration, we can use the EL name pfExceptionHandler to render the following details of an exception:

\n\n

exception, #{pfExceptionHandler.exception};
type of the exception, #{pfExceptionHandler.type};
exception message, #{pfExceptionHandler.message}’
an array of java.lang.StackTraceElement instances, #{pfExceptionHandler.stackTrace};
stack trace as presentable string, #{pfExceptionHandler.formattedStackTrace};
timestamp as date, #{pfExceptionHandler.timestamp};
timestamp as presentable string, #{pfExceptionHandler.formattedTimestamp};

\n\n

Most probably, you will want to present the above information in a list or styled with some CSS as in the figure below:

\n\n\n

\n\n\n

As you can see, we can use this information to write custom error pages per exception or to use a single fall back styled error page.

\n\n

<error-page>\n <error-code>500</error-code>\n <location>/faces/pages/errors/500.xhtml</location>\n</error-page> \n

\n\n\n\n

The complete application is named, PFAjaxExceptionDetails.

\n\n

Unwrapping the AJAX exceptions

\n\n

Earlier, in the PFAjaxExceptionDeclarative application we triggered an exception of type IllegalStateException wrapped in a FacesException, even if the IllegalStateException is wrapped the application still reports it correctly. Well, we obtain this behavior because, by default, the FacesException and ELException are unwrapped by the PrimeFaces exception handler. But, let’s suppose that we trigger the same IllegalStateException wrapped in an SQLException:

\n\n

@Named\n@RequestScoped\npublic class ExceptionBean {\n\n public void throwWrappedIllegalStateExceptionInSQLException() \n                                          throws SQLException {\n  Throwable t = new IllegalStateException(\"An IllegalStateException \n                                              wrapped in SQLException\");\n  throw new SQLException(t);\n }\n\n public void throwWrappedIllegalStateExceptionInFacesException() {\n  Throwable t = new IllegalStateException(\"An IllegalStateException \n                                              wrapped in FacesException\");\n  throw new FacesException(t);\n }\n\n public void throwWrappedIllegalStateExceptionInELException() {\n  Throwable t = new IllegalStateException(\"An IllegalStateException \n                                              wrapped in ELException\");\n  throw new ELException(t);\n }\n}\n

\n\n\n\n

Since the SQLException is not unwrapped by default, the above scenario will not work as expected. Actually, no error will be reported! In order to fix this issue we have at least two possibilities:

\n\n

Modify the exception type in web.xml to correspond to the java.sql.SQLException:

\n\n

<error-page>\n <exception-type>java.sql.SQLException</exception-type>\n <location>/faces/pages/errors/IllegalStateException.xhtml</location>\n</error-page>\n

\n\n\n\n

This case will lead to the following report:

\n\n\n

\n\n\n

Use a fall back error page whenever thereʹs no match with any of the declared specific exceptions:

\n\n

<error-page>\n <error-code>500</error-code>\n <location>/faces/pages/errors/500.xhtml</location>\n</error-page>\n

\n\n\n\n

The complete application is named, PFUnwrapAjaxException.

\n\n

Well, the problem is that none of these two approaches solves the issue. Basically, they are more like workarounds because we didn’t unwrap really the exception. In order to unwrap the exception we should try to override the PrimeExceptionHandler#getRootCause() which currently looks like this; as you can see only exceptions of type FacesException and ELException are unwrapped:

\n\n

 @Override\n public Throwable getRootCause(Throwable throwable) {\n  while ((ELException.class.isInstance(throwable) || \n          FacesException.class.isInstance(throwable)) \n          && throwable.getCause() != null) {\n           throwable = throwable.getCause();\n  }\n\n  return throwable;\n}   \n

\n\n\n\n

So, we can extend the PrimeExceptionHandler and provide the code necessary to unwrap the exception in getRootCause() method. At this point, OmniFaces can help us via its Exceptions#unwrap() utility method. This method unwraps the nested causes of given exception as long as until it is not an instance of the given type and then return it.

\n\n

For example, let’s suppose that we want to adjust our ExceptionBean bean to throw the following wrapped exceptions:

\n\n

@Named\n@RequestScoped\npublic class ExceptionBean {\n      \n // IllegalStateException wrapped in SQLException\n public void throwWrappedIllegalStateExceptionInSQLException() \n                                           throws SQLException {\n  Throwable t = new IllegalStateException(\"An IllegalStateException\n                                              wrapped in a SQLException\");\n  throw new SQLException(t);\n }\n\n // IllegalStateException wrapped in SQLException \n // wrapped further in RuntimeException\n public void throwWrappedIllegalStateExceptionInRuntimeException() {\n  Throwable t = new IllegalStateException(\"An IllegalStateException \n            wrapped in a SQLException wrapped further in a RuntimeException\");\n  throw new RuntimeException(new SQLException(t));\n }\n\n // FileNotFoundException wrapped in IOException\n public void throwFileNotFoundExceptioninIOException() throws IOException {\n  Throwable t = new FileNotFoundException(\"An FileNotFoundException \n                                         wrapped in a IOException\");\n  throw new IOException(t);\n }  \n}\n

\n\n\n\n

This means that in the web.xml we will have the following error pages and we expect it to work properly:

\n\n

<error-page>\n <exception-type>java.lang.IllegalStateException</exception-type>\n <location>/faces/pages/errors/IllegalStateException.xhtml</location>\n</error-page>      \n<error-page>\n <exception-type>java.io.FileNotFoundException</exception-type>\n <location>/faces/pages/errors/FileNotFoundException.xhtml</location>\n</error-page>  \n

\n\n\n\n

So, first we want to unwrap an IllegalStateException wrapped in a SQLException, second an IllegalStateException wrapped in a SQLException and wrapped again in a RuntimeException, and finally a FileNotFoundException wrapped in a IOException. This means that we can override the getRootCause() like below:

\n\n

@Override\npublic Throwable getRootCause(Throwable e) {\n Throwable realRootCause = Exceptions.unwrap(e,\n           javax.faces.FacesException.class,\n           RuntimeException.class,                \n           java.io.IOException.class,\n           java.sql.SQLException.class);\n return realRootCause;\n}    \n

\n\n\n\n

Of course, depending on your (exceptions) cases, you have to adjust this method accordingly.

\n\n

Now, we just need to extend the PrimeExceptionHandler, loop over the unhandled exceptions, and replace each exception with its unwrapped version. We can accomplish this in the PrimeExceptionHandler#handle() method as below:

\n\n

public class MyAjaxExceptionHandler extends PrimeExceptionHandler {\n\n private static final Logger LOG = Logger.\n  getLogger(MyAjaxExceptionHandler.class.getName());\n\n public MyAjaxExceptionHandler(ExceptionHandler wrapped) {\n  super(wrapped);\n }\n\n @Override\n public void handle() throws FacesException {\n\n  FacesContext fc = FacesContext.getCurrentInstance();\n\n  Iterable<ExceptionQueuedEvent> exceptionQueuedEvents =\n                      getUnhandledExceptionQueuedEvents();\n  if (exceptionQueuedEvents != null && \n      exceptionQueuedEvents.iterator() != null) {\n      Iterator<ExceptionQueuedEvent> unhandledExceptionQueuedEvents = \n                        getUnhandledExceptionQueuedEvents().iterator();\n\n      if (unhandledExceptionQueuedEvents.hasNext()) {\n\n          ExceptionQueuedEventContext eventContext = \n           unhandledExceptionQueuedEvents.next().getContext();\n          Throwable throwable = eventContext.getException();\n\n          LOG.info(\"----------------------------------------\");\n          LOG.log(Level.INFO, \"Unwrapping:{0}\", throwable);\n          Throwable rootCause = getRootCause(throwable);\n          LOG.log(Level.INFO, \"Root cause:{0}\", rootCause);\n          LOG.info(\"----------------------------------------\");\n\n          unhandledExceptionQueuedEvents.remove();\n          fc.getApplication().publishEvent(fc, ExceptionQueuedEvent.class,\n             new ExceptionQueuedEventContext(fc, rootCause, \n              eventContext.getComponent(), eventContext.getPhaseId()));\t\n      }\n  }\n\n  super.handle();\n  }\n   \n @Override\n public Throwable getRootCause(Throwable e) {\n  Throwable realRootCause = Exceptions.unwrap(e,\n            javax.faces.FacesException.class,\n            RuntimeException.class,                \n            java.io.IOException.class,\n            java.sql.SQLException.class);\n  return realRootCause;\n }        \n} \n

\n\n\n\n

Well, just two more steps and we are done! At this point, the application will not consider MyAjaxExceptionHandler and will still use the default PrimeExceptionHandler. This is happening because we have configured in faces-config.xml the PrimeExceptionHandlerFactory which is responsible of “serving” instances of PrimeExceptionHandler. In order to set MyAjaxExceptionHandler as the default we need to write a custom ExceptionHandlerFactory as fallows:

\n\n

public class MyExceptionHandlerFactory extends ExceptionHandlerFactory {\n\n private ExceptionHandlerFactory exceptionHandlerFactory;\n\n public MyExceptionHandlerFactory(){        \n }\n    \n public MyExceptionHandlerFactory(ExceptionHandlerFactory \n                                  exceptionHandlerFactory) {\n  this.exceptionHandlerFactory = exceptionHandlerFactory;\n }\n\n @Override\n public ExceptionHandler getExceptionHandler() {\n  ExceptionHandler handler = new MyAjaxExceptionHandler(exceptionHandlerFactory.\n                                                          getExceptionHandler());\n\n  return handler;\n }\n}\n

\n\n\n\n

And, finally, we need to configure this exception handler factory in faces-config.xml in place of PrimeExceptionHandlerFactory:

\n\n

<factory>\n <exception-handler-factory>\n  exceptionhandler.MyExceptionHandlerFactory\n </exception-handler-factory>\n</factory>\n

\n\n\n\n

Done! Now if we run the application and we arbitrarily press one of the three available buttons,

\n\n\n

\n\n\n

we will obtain something like in the figure below (for the FileNotFoundException wrapped in a IOException):

\n\n\n

\n\n\n

Or, if we consult the server log we will see something like in the figure below:

\n\n\n

\n\n\n

If we suppose the case of an IllegalStateException wrapped in a SQLException wrapped further in a RuntimeException then the server log will reveal something like in the figure below:

\n\n\n

\n\n\n

In order to better understand what we have done check out the below image:

\n\n\n

\n\n\n

The complete application is named PFOFUnwrapAjaxException.

\n\n

Showing the exceptions in a dialog on the same page

\n\n

One of the greatest feature provided by PrimeFaces for dealing with exceptions that occurs during AJAX requests consists of the possibility to treat the exceptions in the same page. We can execute callbacks on the client side and update other components on the same page. This is possible via the <p:ajaxExceptionHandler/> tag. For example, let’s suppose that we prepared the following dialog with details about the exceptions:

\n\n

<p:dialog id=\"exceptionDialog\" \n          header=\"Exception '#{pfExceptionHandler.type}' occured!\"\n          widgetVar=\"exceptionDialog\" height=\"500px\" width=\"600px\">\n Message: #{pfExceptionHandler.message} <br/>\n StackTrace: <h:outputText value=\"#{pfExceptionHandler.formattedStackTrace}\"\n                           escape=\"false\" />           \n</p:dialog>\n

\n\n\n\n

Now, our ExceptionBean was adjusted to trigger the following exceptions via three action methods:

\n\n

@Named\n@RequestScoped\npublic class ExceptionBean {\n\n public void throwNullPointerException() {\n  throw new NullPointerException(\"A NullPointerException!\");\n }\n\n public void throwWrappedIllegalStateException() {\n  Throwable t = new IllegalStateException(\"A wrapped IllegalStateException!\");\n  throw new FacesException(t);\n }\n\n public void throwMyCoolException() throws MyCoolException {\n  throw new MyCoolException(\"A MyCoolException!\");\n }\n}\n

\n\n\n\n

The idea is pretty simple … we trigger one of these exceptions and we want the corresponding details to appear in our dialog on the same page. Obviously, this means that we cannot use the separate error pages, and we must rely on the missing pieces form this puzzle, on the <p:ajaxExceptionHandler/> tag. We define a <p:ajaxExceptionHandler/> for each of these exceptions, as follows:

\n\n

<!-- for the NullPointerException -->\n<p:ajaxExceptionHandler type=\"java.lang.NullPointerException\"\n                        update=\"exceptionDialog\"\n                        onexception=\"PF('exceptionDialog').show();\" />\n        \n<!-- for the IllegalStateException -->\n<p:ajaxExceptionHandler type=\"java.lang.IllegalStateException\"\n                        update=\"exceptionDialog\"\n                        onexception=\"PF('exceptionDialog').show();\" />\n        \n<!-- for the MyCoolException -->\n<p:ajaxExceptionHandler type=\"beans.MyCoolException\"\n                        update=\"exceptionDialog\"\n                        onexception=\"PF('exceptionDialog').show();\" />\n

\n\n\n\n

Now, if we run the application and we fire an exception (e.g. NullPointerException) we will obtain something like in the figure below:

\n\n\n

\n\n\n

The complete application is named PFAjaxExceptionClientCallback.

\n\n

Showing the exceptions in a dialog on the same page using PrimeFaces and unwrapping the exceptions using OmniFaces

\n\n

The section title is pretty suggestive. Basically, PrimeFaces can treat AJAX exceptions in the same page via <p:ajaxExceptionHandler/> without using separate error pages while OmniFaces cannot do that. On the other hand, OmniFaces can unwrap exceptions via org.omnifaces.EXCEPTION_TYPES_TO_UNWRAP context parameter while PrimeFaces cannot unwrap other exceptions apart of FacesException and ELException. So, we can easily combine the above application, PFAjaxExceptionClientCallback, with the PFOFUnwrapAjaxException application presented earlier in the Unwrapping the AJAX exceptions section and obtain an application that shows the exceptions in a dialog on the same page using PrimeFaces and unwraps the exceptions using OmniFaces. This application is available with this book and it is named OFUnwrapPFDisplayAjaxException.

\n\n

Handling non-AJAX exceptions

\n\n

Now, speaking of non-AJAX exceptions thing are pretty straightforward. While OmniFaces doesn’t treat non-AJAX exceptions, PrimeFaces does very well and pretty similar to AJAX exceptions. That’s all folks!

\n\n

PrimeFaces vs OmniFaces exception handlers

\n\n

In the figure below we have synthesized the three main differences between PrimeFaces and OmniFaces exception handlers:

\n\n\n

\n\n\n

Report exceptions as global FATAL faces messages

\n\n

OmniFaces provides one more exception handler named FacesMessageExceptionHandler. This exception handler is capable of adding every exception as a global FATAL faces message. In order to use it, you just need to configure the factory that “serves” FacesMessageExceptionHandler instances in the web.xml as below:

\n\n

<factory>\n <exception-handler-factory>\n  org.omnifaces.exceptionhandler.FacesMessageExceptionHandlerFactory\n </exception-handler-factory>\n</factory> \n

\n\n\n\n

Furthermore, in the page we must ensure the presence of a component capable of displaying messages, such as <p:growl/> or <p:messages/>.

\n\n

If we want to customize the FATAL error messages then we extend the FacesMessageExceptionHandler and override the createFatalMessage() method. For example, let’s suppose that we have the following bean that triggers some exceptions:

\n\n

@Named\n@RequestScoped\npublic class ExceptionBean {\n\n public void throwNullPointerException() {\n  throw new NullPointerException(\"A NullPointerException!\");\n }\n\n public void throwWrappedIllegalStateException() {\n  Throwable t = new IllegalStateException(\"A wrapped IllegalStateException!\");\n  throw new FacesException(t);\n }\n\n public void throwMyCoolException() throws MyCoolException {\n  throw new MyCoolException(\"A MyCoolException!\");\n }\n}\n

\n\n\n\n

And, for any of these exceptions (and others) we want to return the FATAL error message, Oooops! We have some issues in our application .... For this, we can write the following custom error handler:

\n\n

public class MyFacesMessageExceptionHandler\n       extends FacesMessageExceptionHandler {\n\n public MyFacesMessageExceptionHandler(ExceptionHandler wrapped) {\n  super(wrapped);\n }\n\n @Override\n protected String createFatalMessage(Throwable exception) {\n  return \"Oooops! We have some issues in our application ...\";\n }\n}\n

\n\n\n\n

And we replace the OmniFaces factory with the following one:

\n\n

public class MyExceptionHandlerFactory extends ExceptionHandlerFactory {\n\n private ExceptionHandlerFactory exceptionHandlerFactory;\n\n public MyExceptionHandlerFactory(){        \n }\n    \n public MyExceptionHandlerFactory(ExceptionHandlerFactory \n                                 exceptionHandlerFactory) {\n  this.exceptionHandlerFactory = exceptionHandlerFactory;\n }\n\n @Override\n public ExceptionHandler getExceptionHandler() {\n  ExceptionHandler handler = new MyFacesMessageExceptionHandler(\n                  exceptionHandlerFactory.getExceptionHandler());\n\n  return handler;\n }\n}\n

\n\n\n\n

Now, a JSF page can provide three buttons for testing this use case:

\n\n

<h:form>    \n <p:messages/>\n <p:growl/>\n <p:commandButton value=\"Throw NullPointerException\" \n                 action=\"#{exceptionBean.throwNullPointerException()}\" \n                 update=\"@form\" />\n <p:commandButton value=\"Throw Wrapped IllegalStateException\" \n                  action=\"#{exceptionBean.throwWrappedIllegalStateException()}\" \n                  update=\"@form\" />\n <p:commandButton value=\"Throw MyCoolException\" \n                  action=\"#{exceptionBean.throwMyCoolException()}\" \n                  update=\"@form\" />\n</h:form>\n

\n\n\n\n

No matter which button we click on the result will always be the one from the figures below:

\n\n\n

\n\n\n\n

\n\n\n

The complete application is named OFExceptionFATALMessage.

\n\n

Chapter 15: Final word

\n\n

In this book you saw 100+ applications of combining the ultimate UI framework for Java EE and the most comprehensive JSF utility library. Asside from the topics discussed in this book, you may also be interested in exploring more features as:

\n\n

PrimeFaces and OmniFaces web sockets support;
PrimeFaces and OmniFaces multiple file upload;
OmniFaces CDI artifacts as ContextParam, Cookie, Eager, etc;
PrimeFaces and OmniFaces tree components;
OmniFaces ExtensionlessURLs;
OmniFaces utilities

\n\n

… and so on … and on …and on

\n\n

The end!

\n\n\n

\n\n","tocStructure",[384,385,386,387,388,389,390,391,392,393,394,395,396,397,398,399,400,401,402,403,404,405,406,407,408,409,410,411,412,413,414,415,416,417,418,419,420,421,422,423,424,425,426,427,428,429,430,431,432,433,434,435,436,437,438,439,440,441,442,443,444,445,446,447,448,449,450,451,452,453,454,455,456,457,458,459,460,461,462,463,464,465,466,467],{"_75":76,"_43":77,"_70":-5,"_78":79,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":76,"_43":85,"_70":-5,"_78":86,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":76,"_43":89,"_70":-5,"_78":90,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":76,"_43":93,"_70":-5,"_78":94,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":98,"_70":-5,"_78":99,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":103,"_70":-5,"_78":104,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":106,"_70":-5,"_78":107,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":76,"_43":109,"_70":-5,"_78":110,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":113,"_70":-5,"_78":114,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":116,"_70":-5,"_78":117,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":119,"_70":-5,"_78":120,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":122,"_70":-5,"_78":123,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":76,"_43":125,"_70":-5,"_78":126,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":129,"_70":-5,"_78":130,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":132,"_70":-5,"_78":133,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":135,"_70":-5,"_78":136,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":138,"_70":-5,"_78":139,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":141,"_70":-5,"_78":142,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":144,"_70":-5,"_78":145,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":76,"_43":147,"_70":-5,"_78":148,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":151,"_70":-5,"_78":152,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":154,"_70":-5,"_78":155,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":157,"_70":-5,"_78":158,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":160,"_70":-5,"_78":161,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":163,"_70":-5,"_78":164,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":76,"_43":166,"_70":-5,"_78":167,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":170,"_70":-5,"_78":171,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":173,"_70":-5,"_78":174,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":176,"_70":-5,"_78":177,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":76,"_43":179,"_70":-5,"_78":180,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":183,"_70":-5,"_78":184,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":186,"_70":-5,"_78":187,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":189,"_70":-5,"_78":190,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":76,"_43":192,"_70":-5,"_78":193,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":196,"_70":-5,"_78":197,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":199,"_70":-5,"_78":200,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":76,"_43":202,"_70":-5,"_78":203,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":206,"_70":-5,"_78":207,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":209,"_70":-5,"_78":210,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":212,"_70":-5,"_78":213,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":215,"_70":-5,"_78":216,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":218,"_70":-5,"_78":219,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":76,"_43":221,"_70":-5,"_78":222,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":225,"_70":-5,"_78":226,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":228,"_70":-5,"_78":229,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":231,"_70":-5,"_78":232,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":76,"_43":234,"_70":-5,"_78":235,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":238,"_70":-5,"_78":239,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":241,"_70":-5,"_78":242,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":244,"_70":-5,"_78":245,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":247,"_70":-5,"_78":248,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":250,"_70":-5,"_78":251,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":253,"_70":-5,"_78":254,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":256,"_70":-5,"_78":257,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":76,"_43":259,"_70":-5,"_78":260,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":263,"_70":-5,"_78":264,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":266,"_70":-5,"_78":267,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":269,"_70":-5,"_78":270,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":272,"_70":-5,"_78":273,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":275,"_70":-5,"_78":276,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":278,"_70":-5,"_78":279,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":281,"_70":-5,"_78":282,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":284,"_70":-5,"_78":285,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":287,"_70":-5,"_78":288,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":290,"_70":-5,"_78":291,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":293,"_70":-5,"_78":294,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":76,"_43":296,"_70":-5,"_78":297,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":300,"_70":-5,"_78":301,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":303,"_70":-5,"_78":304,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":76,"_43":306,"_70":-5,"_78":307,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":310,"_70":-5,"_78":311,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":313,"_70":-5,"_78":314,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":316,"_70":-5,"_78":317,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":319,"_70":-5,"_78":320,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":322,"_70":-5,"_78":323,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":325,"_70":-5,"_78":326,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":328,"_70":-5,"_78":329,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":331,"_70":-5,"_78":332,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":76,"_43":334,"_70":-5,"_78":335,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":338,"_70":-5,"_78":339,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":341,"_70":-5,"_78":342,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":344,"_70":-5,"_78":345,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":97,"_43":347,"_70":-5,"_78":348,"_71":80,"_100":-5,"_101":-5,"_83":-5},{"_75":76,"_43":350,"_70":-5,"_78":351,"_71":80,"_100":-5,"_101":-5,"_83":-5},"publicChapterContent","nextChapter","sections",[],"routes/_store+/_layout","routes/_store+/_readers+/_layout","actionData","errors"]

Introduction

Table of Contents

Author

Contributor

Introduction

Chapter 1: Working with faces messages

Faces messages with multiple client IDs in the for attribute

Show a single custom global message

Highlight invalid inputs via custom CSS

Alter CSS directly

Use OmniFaces Highlight component

Chapter 2: Working with links and request parameters

Use <p:link/> and <o:param/> to pass objects into generated link

Use <p:commandButton/Link/> and <o:param/> to pass objects into managed beans

Create complex labels

Using <h:outputFormat/> output as input parameter

Chapter 3: Working with JavaScript/CSS resources

Executing a JavaScript snippet after each AJAX/non-AJAX request

Executing a JavaScript snippet after each AJAX request

Executing a JavaScript snippet after each non-AJAX request

Using the OmniFaces OnloadScript component

Fire AJAX requests from plain JavaScript functions

Fire AJAX requests from plain JS functions without arguments

Fire AJAX requests from plain JS functions with arguments

Fire AJAX requests from plain JS functions on page load (autorun)

Some differences between PrimeFaces and OmniFaces approaches

The RemoteCommand supports a bunch of attributes not available in CommandScript\n

The CommandScript supports nested <f:param/> and <o:param/>\n

The CommandScript supports <f:setPropertyActionListener/>\n

Combining PrimeFaces resources in a single resource

Configuring CombinedResourceHandler\n

Combining PrimeFaces resources

Combining PrimeFaces themes

Providing external (CDN) URLs instead of the default local URLs for JSF resources

Wildcard configuration

EL expessions in the CDN URL

Real case - delegate PrimeFaces jQuery to CDN

JSF resource lookup issues

Defer loading and parsing of JavaScript resources

Defer loading and parsing of JavaScript resources via PrimeFaces

Defer loading and parsing of JavaScript resources via OmniFaces

Defer loading and parsing of PrimeFaces resources via OmniFaces

Using CombinedResourceHandler with <o:deferredScript/>\n

Using CDNResourceHandler with <o:deferredScript/>\n

Reference relative URLs to images in CSS files without #{resource}\n

Chapter 4: Initializing PrimeFaces components via view parameters

Suppressing the invocation of the setter/converter/validator at each postback

Supply a label for messages

Supply a default value

Suppressing invocation of the converter regardless the null values

Support bean validation and triggering validate events on null value

Chapter 5: Referencing, rendering and moving PrimeFaces components

Access a component by using a reference to it

Controlling the rendering of components

Moving components, facets and behaviors at runtime to a target component

Chapter 6: Working with media content

Working with images

Loading images from /resources folder

Loading images provided as byte array, byte[], or InputStream\n

Loading external media content

Example of loading external images/videos/PDF

Example of loading images

Example of loading videos

Example of loading PDF

Check if the current request is a PrimeFaces dynamic resource request

Chapter 7: Including Servlets/JSP output in JSF page

Including a Servlet output in a PrimeFaces component

Decorating the Servlet output

Chapter 8: Working with forms

Introducing OmniFaces Form component

Preserving query string over postbacks

Preserving view parameters over postbacks

Quick look at useRequestURI attribute

Ignoring validation failures in <o:form/>\n

Chapter 9: Import constants, interfaces, enums and public static methods

Import constants/interfaces via PrimeFaces and OmniFaces

Import enums via PrimeFaces and OmniFaces

Import public static methods with OmniFaces

Chapter 10: Let’s convert data with PrimeFaces and OmniFaces

Using Java enums in UISelectMany components

Faces messages with multiple client IDs in the `for` attribute

Use OmniFaces `Highlight` component

Use `<p:link/>` and `<o:param/>` to pass objects into generated link

Use `<p:commandButton/Link/>` and `<o:param/>` to pass objects into managed beans

Using `<h:outputFormat/>` output as input parameter

The `RemoteCommand` supports a bunch of attributes not available in `CommandScript`\n

The `CommandScript` supports nested `<f:param/>` and `<o:param/>`\n

The `CommandScript` supports `<f:setPropertyActionListener/>`\n

Configuring `CombinedResourceHandler`\n

Using `CombinedResourceHandler` with `<o:deferredScript/>`\n

Using `CDNResourceHandler` with `<o:deferredScript/>`\n

Reference relative URLs to images in CSS files without `#{resource}`\n

Suppressing invocation of the converter regardless the `null` values

Support bean validation and triggering validate events on `null` value

Loading images from `/resources` folder

Loading images provided as byte array, `byte[]`, or `InputStream`\n

Introducing OmniFaces `Form` component

Quick look at `useRequestURI` attribute

Ignoring validation failures in `<o:form/>`\n

Using Java enums in `UISelectMany` components

The `<f:selectitems/>` and the conversion of the submitted strings to their values

An alternative to `SelectItemsConverter`\n

Converting selection components which work directly via a `List`\n

Working with a converter in an iterating component (e.g. `<p:dataTable/>`)