Help

Ilya Shaikovsky is the Exadel products engineer working on the RichFaces project since Exadel began Ajax4jsf. He’s responsible for requirements gathering, specification development, JSF related products analysis and supporting RichFaces and JSF related technologies and products for business applications. Prior to this he worked on the Exadel Studio Pro product which better known as JBoss Tools now.

Co-author of the second edition of Practical RichFaces book with Max Katz.

Reviewer of the Practical RichFaces book by Max Katz.

Co-author of DZone Jboss RichFaces 3 refcard.

Co-author of DZone Jboss RichFaces 4 refcard.

Projects: RichFaces

Location: Minsk
Occupation: Products engineer
Archive

After some waiting time and much promising announcements I can proudly tell that the Practical RichFaces book is published! It’s very happy moment for Max Katz and I because a lot of effort was made to make it happen. We’ve done our best to make it as much useful for JSF developers as possible, and now we believe that it doesn’t matter if you’re a novice in JSF world or skilled developer with rich expertise in various development areas – everyone should find useful parts inside.

The book completely dedicated to development with latest RichFaces 4 release and that means that it's all based on new JavaServer Faces 2. Let me briefly describe what is waiting our readers inside.

Book Content Overview

We start with describing new and most important pieces of JSF 2. It should be useful for future understanding of how the component works, and how the RichFaces extends standard JSF. We will tell not only about brand new features but also highlight most important general points for those who just starting to learn JSF 2. Good understanding of where are the core features and where the extension points should greatly help the developers with further development and troubleshooting of any kind.

Then we continue with RichFaces. Two chapters are dedicated to RichFaces core framework features and tags (a4j:). That knowledge should become a baseline for any developer who is planning to work with RichFaces 4. Because any rich component starting from simplest ones and up to most complex built according to the same basic rules and follows the same approaches that we will describe there. It's simple just to play with JSF creating pages using simple drag and drop operations in your favorite IDE. But only good knowledge of basics will make your future application really extendable and efficient. That was our main point during writing that chapter.

After the core features we will spend most of the time describing various component groups in rich: RichFaces components library. Every component section, in every group provides set of ready-to-use examples starting from very basic (using component on simple page) and to really interesting ones (like custom model for data and tree components, using server and client side components API and customization options and so on). We paid significant attention to making examples as useful as possible by making them as real-life as possible. Most of the complex samples were done according to common Web use-cases, interesting requests from RichFaces community or good questions sent to us directly. So you may think about those chapters as about a good combination of cookbook and reference guide.

A few chapters in the end will describe utility components and functions which are also included in the rich: library. We will tell (also with numerous examples) about new RichFaces validation facilities like client and object validation, components providing drag and drop functionality, and about functions and other utility tags available in RichFaces.

Penultimate chapter will describe redesigned Skins feature of RichFaces 4. Being simplified and optimized Skins become even more powerful than before allowing you add styling to the whole application in a very short time and then perform detailed customization of any depth without using any proprietary formats but relying to standard CSS enhanced with EL support.

Finally, the last chapter will show you the RichFaces Components Development Kit (CDK). Also being fully redesigned in RichFaces 4, it become really easy to use tool which allows you to create JSF 2 components of any complexity in a very short time doing most of routine work for you. This chapter demonstrates how to build a complete example of custom component written from scratch and implemented with all the RichFaces capabilities including skinning.

Full table of content and other information are available at Apress page.
All sources available at Github.

Acknowledgements

After finishing that work on the book and also looking backward to my working experience in RichFaces development I would like to extend a few special thanks to the guys without whom it would not be possible. It’s Alexander Smirnov, Nick Belaevski and Pavel Yaschenko. There were many other great developers working on that project for sure, but these three people were always the core team and great mentors and supporters for anybody who had most complex challenges in JSF world. It’s their ideas implemented now in RichFaces 4 and incorporated in JSF 2. Besides I would like to extend special thanks to Jay Balunas who helped me a lot in establishing myself as a good (as I hope :) ) JBoss community member.

It was (and will be) always easy to move forward together with you guys. So, thank you all!

So, the book is now here, and we are looking forward for your feedback! Hope it will help to make a bunch of good starts for many Java developers.


[Get updates of my blogs in twitter]

[My jroller.com blog]

There is an important feature in RichFaces 4 that get documented at wiki recently and today I want to point you to that article. That article is related to Programmatic control of partial processing in RichFaces 4.

If you working with RichFaces 3.3.x and looking for the same info - do not ignore that page. It's written as comparison of 3.3.x and 4.x functionality so you will see RichFaces 3.3.x methods also!

Questions which are adressed in that article (for both RichFaces 3.3.x and 4.x) listed below. Again all the answers related to programmatical access to PartialViewContext and not just working at component/attributes level.

  • How to add component to set of execute'd ones.
  • How to add component to set of render'ed ones.
  • How to check if current request is Ajax request.
  • How to limit Ajax updates to just set of render'ed components excluding automatically rendered ones.
  • How to append JavaScript event handlers from server side
  • ...more

So look through the article and let RichFaces team know about your experience of using all that stuff. And share your thoughts about anything still missing at User Forum.


[Get updates of my blogs in twitter]

[My jroller.com blog]

Overview

I believe that this probably one of the most expected articles to come. It will touch the RichFaces iteration component in-depth, covering advanced models which we are using under the hood. Actually real enterprise application using huge data sets, applies paging with lazy data loading, uses sorting, filtering, selection and the other features which makes then application really rich and interactive. So in most cases you could not rely on simple lists or maps with data wrapped using default models. And in order to achieve the best RichFaces tables experience with a good performance and scalability you need to understand the base principles of our models.

Models sample

At first I would like to introduce new sample available on our live demo – Arrangeable Model Sample. It works using Hibernate Entity Manager and all the paging/sorting/filtering operations really performed at DB level instead of performing in wrapped model.

In that article I will guide you through the base points which you should look in that sample in order to get main ideas and be able to work on your own models.

Why do we need the models

Let's start from a good question – why RichFaces introduces custom models having JSF javax.faces.model.DataModel contract already. And the reason is pretty simple. In difference with JSF 2 implementation which is supposed just to provide basic stuff RichFaces introduces new rich components and adds new features on top of them. Here is just overview:

  • Trees components family. With support of swing-based data models and RichFaces custom data models. With additional providers which allows to create data model declaratively from any custom non-hierarchical model. With selection feature plugged and available using different modes (Ajax, client, server)
  • Tables components family. RichFaces unifies sorting/filtering/paging features among two rich tables. It adds the ability of master-detail layouts creation in rich:dataTable with the built-in feature of collapse/expand details subtables. It adds Ajax lazy loading of the data on vertical scroll and selection with rich:extendedDataTable. And so on..

Of course all that stuff requires good model base. And in order to standardize the API between different components providing unified contract to the RichFaces developers we designed our models.

ExtendedDataModel Overview

From the beginning let me introduce our models principles and then later we will see how them are implemented in the showcase demo.

ExtendedDataModel

is a base model abstract class which provides the contract for all the other models particular implementations. Let’s see closer to that class:

public abstract class ExtendedDataModel<E> extends DataModel<E> {

    public abstract void setRowKey(Object key);

    public abstract Object getRowKey();

    public abstract void walk(FacesContext context, DataVisitor visitor, Range range, Object argument);

}

Well, we seeing new entity introduced there. And it’s rowKey. Let’s see the goal of that entity. Working with complex data structures (like trees) and using advanced UI component features like filtering/sorting/paging/selection in tables we need to have a simple way to identify the object in the model. And just rowIndex’es doesn’t play nice enough as requires additional complex look-up mechanisms (to identify db object according to index in wrapped model) to do that. And with the rowKey you could just use the same id which you are using at db level.

Besides you see walk() method introduced there. RichFaces iteration components uses visitor pattern while working with model. So that method should perform model iteration and call the visitor passed as a parameter in order to handle every object in the model.

ExtendedDataModel implementations

  • SequenceDataModel – default implementation of the ExtendedDataModel for the tables. Used when filtering and sorting not used by the component.
  • ArrangeableModel – implementation of the ExtendedDataModel which implements Arrangeable interface additionally which are used to add sorting and filtering support.
  • TreeSequenceKeyModel abstract model and all the models which extends it used by the tree component family. That model is out of scope for that article.

Sample Code

At first I would like to say that will not describe all the code used in the sample. You could easily check it at showcase live or obtain from SVN repository and explore in your favorite IDE. Besides the fact that it will be boring and will make article really huge I also want to say that the goal of that write-up – to guide you in the right direction while reviewing RichFaces data models usage principles.

And overview of that sample functionality:

  • Obtaining the list of Person object s from the db according to given filtering and sorting rules
  • Displaying objects using the rich:dataTable
  • Addition of the controls which control sorting and filtering
  • Addition of the rich:dataScroller which allows breaking the data loading from db to the pages.

Sample Code – Base Person entity

That would be self-explanatory I believe. We just using simple and frequently used classes to define Person object.

@Entity
public class Person {
    
    private String name;
    private String surname;
    private String email;
    @Id
    @GeneratedValue
    private Long id;
//getters and setters
}

Sample Code – Generic Model

Now let’s look closer to the model code.

JPADataModel

–is a generic model which supposed to provide unified approach of working with data for all implementers. It’s parameterized with the class which should be defined to work with particular entity classes in models which will implement it. And besides it passed with the EntityManager in order the implementer classes to be responsible for particular EntityManager lookup.

Also from the beginning you should note abstract getId(T t) method which should be also implemented in the model which implements that abstract model. It should return the id of the particular entity which will be used as rowKey in that model.

Now let’s review two most important methods there. And let’s look to arrange() method from the beginning. It probably too simple to have it listed but any way:

public void arrange(FacesContext context, ArrangeableState state) {
    arrangeableState = state;
}

Just wanted to give some simple explanation of why we perform just simple storing of the passed state in the model property without any further processing. If you will look or already looked to RichFaces sources you will see that default ArrangeableModel implementation of that method performs actual sorting and filtering. But that’s done because our default model works with wrapped model (e.g. simple list or map passed as rich:dataTable value). But in our case we will load the data from db according to current data table page and apply sorting and filtering using db queries also. So we just need to store all the information passed from component in ArrangeableState object for future usage in walk().

Now let’s look to walk() method:

    @Override
    public void walk(FacesContext context, DataVisitor visitor, Range range, Object argument) {
        CriteriaQuery<T> criteriaQuery = createSelectCriteriaQuery();
        TypedQuery<T> query = entityManager.createQuery(criteriaQuery);
        
        SequenceRange sequenceRange = (SequenceRange) range;
        if (sequenceRange.getFirstRow() >= 0 && sequenceRange.getRows() > 0) 
	{
            query.setFirstResult(sequenceRange.getFirstRow());
            query.setMaxResults(sequenceRange.getRows());
        }
        
        List<T> data = query.getResultList();
        for (T t : data) {
            visitor.process(context, getId(t), argument);
        }
    }

The component calls that method a few times during lifecycle and expects it to iterate over the model calling the DataVisitor which will process every object (e.g. encode row for the object at render phase).

Besides visitor, table component passes the Range object there which contains information about from which row the table wants get the data (defined using first attribute or set by rich:dataScroller while switching pages) and the number of rows to fetch (defined using rows attribute). So all we are doing here – just creating query with given sort, filtering and range parameters, loading data from db to the List of entities and finally iterate over that list passing every object to DataVisitor for processing.. You probably will be interested in createSelectCriteriaQuery() method as it performs actual applying of sort and filter parameters. But actually I would like to leave it just to you because JPA queries creation question really out of scope of that article and well explained already at more specific resources.

Besides you may be interested to look into getRowCount() method:

    @Override
    public int getRowCount() {
        CriteriaQuery<Long> criteriaQuery = createCountCriteriaQuery();
        return entityManager.createQuery(
	    criteriaQuery).getSingleResult().intValue();
    }

So there we’re applying sorting and filtering creating the criteria in order to return the rowCount for current component state.

Sample Code – Specific Model Class

The implementation of our generic model placed in PersonBean and defined with the next code:

@ManagedBean
@SessionScoped
public class PersonBean implements Serializable {
    //...
    private static final class PersonDataModel extends JPADataModel<Person> {
        private PersonDataModel(EntityManager entityManager) {
            super(entityManager, Person.class);
        }
        @Override
        protected Object getId(Person t) {
            return t.getId();
        }
    }
    //...
    private EntityManager lookupEntityManager() {
        FacesContext facesContext = FacesContext.getCurrentInstance();
        PersistenceService persistenceService = 
	    facesContext.getApplication().
	    evaluateExpressionGet(facesContext, "#{persistenceService}", 
      PersistenceService.class);
        return persistenceService.getEntityManager();
    }

    public Object getDataModel() {
        return new PersonDataModel(lookupEntityManager());
    }
    //...
}

So actually all we are doing there - performing lookup of entity manager and initiating the particular model implementation with the Person class as entity class and that entity manager.

Sample Code – Page Code

We used two pages there. At first arrangeableModel-sample.xhtml:

<h:form id="form">
    <rich:dataTable keepSaved="true" id="richTable" var="record" 
	value="#{personBean.dataModel}" rows="20">
        <ui:include src="jpaColumn.xhtml">
            <ui:param name="bean" value="#{personBean}" />
        	<ui:param name="property" value="name" />
            </ui:include>
            <ui:include src="jpaColumn.xhtml">
        	<ui:param name="bean" value="#{personBean}" />
        	<ui:param name="property" value="surname" />
            </ui:include>
            <ui:include src="jpaColumn.xhtml">
        	<ui:param name="bean" value="#{personBean}" />
        	<ui:param name="property" value="email" />
            </ui:include>
            <f:facet name="footer">
		<rich:dataScroller id="scroller" />
            </f:facet>
    </rich:dataTable>
</h:form>

Nothing pretty interesting there. We just defining table pointed to our model and including the columns passing properties of the person and the bean to it.

And the second is jpaColumn.xhtml:

<ui:composition>
    <rich:column sortBy="#{property}"
	sortOrder="#{bean.sortOrders[property]}" filterValue="#{bean.filterValues[property]}"
	filterExpression="#{property}">
	<f:facet name="header">
            <h:commandLink action="#{bean.toggleSort}">
            	#{bean.sortOrders[property]}	
            	<a4j:ajax render="richTable" />
            	<f:setPropertyActionListener target="#{bean.sortProperty}" 
		    value="#{property}" />
	     </h:commandLink>
	     <br />
	     <h:inputText value="#{bean.filterValues[property]}">
	         <a4j:ajax render="richTable@body scroller" event="keyup" />
	     </h:inputText>
	</f:facet>
	<h:outputText value="#{record[property]}" />
    </rich:column>
</ui:composition>

That’s actually more interesting for us. Most important what you should note there that we passing just Person properties names as sortBy and filterExpression values. Usually you used EL binding to iteration object property and boolean expression in case you using our default models. But that’s not the case for us. As we implementing our model with in-db sorting and filtering – all we need to know just properties names and we will apply the rules in queries like you could see in the model.

Exercises

That sample is still not ideal for sure. Most important you could easily see that there is absolutely no caching. Every time when walk() or getRowCount() called it queries the db with the request for data. You should add it on your own because there is actually no unified recipe for all the situations. Somebody could need just to read the data from db once when filtering sorting or page changes and be sure that it never changes more between requests. In some cases you should consider that data could be inserted/deleted/edited concurrently by different users so the List obtained in walk() method could be changed even between different walk calls and so on. So it’s up to you to define the rules for that. The same applied to rowCount. It’s highly important to cache it also as possible because it’s called also multiple time during request (by both table and data scroller)

Besides you might want to add Weld/Seam in order to be able to tie beans, entities and services in more graceful way.

The result

Even considering all you could open the demo that blog article would be boring without at least single screenshot of the result we achieved. So here is the table after we performed sorting by surname and filtered by emails to obtain only persons with emails in .com domain:

More information

As usually please refer to RichFaces Documentation to get more info from JavaDoc's and references.

Overview

RichFaces Push allows you to perform realtime client side updates triggered via events from the server side. We integrate with the Atmosphere framework which provides various transport mechanisms according to concrete browser support(Comet, HTML5 WebSockets). On the server events are managed by integrating Java Messaging Service (JMS). This provide enterprise level messaging integration all the way to the browser!

In this blog I will describe our irc-client example application that was created to introduce the RichFaces push features. It provides the following functionality:

  • Connect to the freenode.org IRC server
  • Join a channel with choosen nickname
  • Receive all channel messages (nick change, join, part...)
  • Send messages to the channel
  • Observe the list of joined users with real-time updates

In this blog I'm only going to review the important configuration, and source code snippets from the application. The full source code can be checked out from SVN so you can try it for yourself. Instructions for building and deploying the application is in the readme.txt.

Dependencies

To save time with application setup I have created a starter application using richfaces-archetype-simpleapp archetype. Next we need to update application pom.xml to add Atmosphere fremework dependency. For the client side a4j:push uses jquery-atmosphere.js plugin (added implicitly by the component renderer).

NOTE: that particular sample targeted for JBoss 6 Application Server. So we will use JBoss HornetQ available out of the box. Using RichFaces Push under Tomcat or Jetty requires additional JMS dependencies and configuration code. We will work on maven profiles and additional optional classes for that case also in future releases. At the moment the only place to review that configuration is with our developer demo which configured for tomcat using external HornetQ dependencies and configuration class for its initialization.

We need to add the atmosphere-runtime to the pom.xml. This is only needed if you are using the push component.

<dependency>
    <groupId>org.atmosphere</groupId>
    <artifactId>atmosphere-runtime</artifactId>
</dependency>

Also as the demo shown there provides simple IRC client we added one more dependency:

<dependency>
    <groupId>pircbot</groupId>
    <artifactId>pircbot</artifactId>
    <version>1.4.2</version>
</dependency>

PircBot is a simple framework for writing IRC bots.

Configuring JMS

Lets first discuss why we need JMS at all? Why not just use for example push context object? The answer is pretty straightforward. Usage of JMS at the back-end provides excellent integration with EE containers, and advanced messaging services. It also frees you from managing various entities at your business layer. If you are already using JMS for messaging in your application - you will just continue to send the same messages and you just need to to declare a4j:push at views which should listen that topics.

We assume that you're familiar with JMS so will not provide details here. To learn more about it visit JMS documentation.

Now it is time to configure JMS for our example. We will use JBoss 6 AS for application deployment as mentioned in dependencies section. So we'll use JMS server bundled with JBoss AS. We need to create topics which will be used by Push to check for the messages. Let's start JBoss 6 AS and open http://localhost:8080/admin-console. We will use default admin/admin credentials to log-in. Then click the JMS topics in navigation menu and create new JMS topic with the following settings:

Name: chat

JNDI name: /topic/chat All the others: by default.

In the same form we need to add roles for that topic. For that demo application we will create single role with next parameters:

Name: guest

Send: yes

Consume: yes

create subscriber: yes

delete subscriber: yes

create durable subscriber: yes

delete durable subscriber: yes

IMPORTANT: The last two options are critical for push functionality as we using durable subscriptions in order to be able to receive all the events including ones which were sent while the push was not connected to the server. So if they are set to false - push will not be able to register subscribers.

So here is what you should see after JMS setting done:

That's all. Now we are ready with JMS configuration.

NOTE: if you not familiar with JBoss configuration using admin-console visit JBoss AS Administration Console User Guide.

Web Application Configuration

Now let's add application settings required by RichFaces Push. We need an additional filter and a few context-param's to be added. Here is what we used for that demo application:

<context-param>
    <param-name>org.richfaces.push.jms.connectionUsername</param-name>
    <param-value>guest</param-value>
</context-param>
<context-param>
    <param-name>org.richfaces.push.jms.connectionPassword</param-name>
    <param-value>guest</param-value>
</context-param>
<filter>
    <filter-name>PushFilter</filter-name>
    <filter-class>org.richfaces.webapp.PushFilter</filter-class>
    <async-supported>true</async-supported>
</filter>
<filter-mapping>
    <filter-name>PushFilter</filter-name>
    <servlet-name>Faces Servlet</servlet-name>
</filter-mapping>

Let's review those parameters in details. At first we need the PushFilter to be installed and mapped to Faces Servlet. It will handle the push request and serve event using the Atmosphere runtime. And connectionUserName and connectionPassword context parameters are needed in order to defined the credentials used to work with JMS for connecting and subscribing to topics.

Here is the table with all the parameters which could be used in your application:

context-param Name Default value Description
org.richfaces.push.jms.connectionFactory /ConnectionFactory JMS connection factory JNDI name
org.richfaces.push.jms.topicsNamespace /topic used as a root name from which all topics are resolved: i.e. 'chat' topic by default will be looked up via /topics/chat JNDI name.
org.richfaces.push.jms.connectionUsername - Username used for connection and topics creation/listening
org.richfaces.push.jms.connectionPassword - Password used for connection and topics creation/listening

Note: there are also JNDI references to credentials strings available:

  • java:comp/env/org.richfaces.push.jms.connectionUsername
  • java:comp/env/org.richfaces.push.jms.connectionPassword

An alternative to using web.xml definitions is to provide all the parameters using properties file org/richfaces/push.properties.

TopicsContext initialization

Now we need to initialize org.richfaces.application.push.TopicsContext with the JMS topics we will listen for. For this purpose we created a JSF 2 System Event listener which handles PostConstructApplicationEvent:

public class TopicsInitializer implements SystemEventListener {
   public void processEvent(SystemEvent event) throws AbortProcessingException {
       TopicsContext topicsContext = TopicsContext.lookup();
       Topic topic = topicsContext.getOrCreateTopic(new TopicKey("chat"));
       topic.setMessageDataSerializer(DefaultMessageDataSerializer.instance());
       topic.addTopicListener(new SessionTopicListener() {...});
   }
  public boolean isListenerForSource(Object source) {
       return true;
   }
}

and registered it in faces-config:

<application>
    <system-event-listener>
        <system-event-listener-class>org.ircclient.listeners.TopicsInitializer</system-event-listener-class>
        <system-event-class>javax.faces.event.PostConstructApplicationEvent</system-event-class>
    </system-event-listener>
</application>

With this we have created new topic in TopicContext with chat name (the same as we defined configuring the JMS).

Actually MessageDataSerializer and TopicListener creation are optional, so let's briefly describe the main idea of these objects.

  • Messages serializer is used to serialize the message to the expected format for passing to the client. By default built-in serializer will serialize the message data to JavaScript.
  • Session topic listener is used to handle subscriptions (pre and post-processing) and unsubscription events. This could be used for example in order to check user permissions prior to connecting to some topic and perform some additional post-processing after some push component successfully attached to topics. In the sample there are just logging used so the code is omitted there.

Application Code

We are done with settings and push initialization stuff, and it's time to actually explore the example code to see how we manage the IRC connections, and how push is used for page updates according to server-side events.

Logging to IRC

This section is not directly related to Push but describes the code used for connection to IRC. Here is the simple page used:

<rich:panel header="Connect to IRC">
    <h:form>
        <rich:messages style=”color:red”/>
            <h:panelGrid columns="2">
                <h:outputText value="Your nickname:" />
                <h:inputText required="true" id="name" value="#{chatBean.userName}" />
                <h:outputText value="Channel:" />
                <h:outputText value="RichFaces" style="font-weight:bold"/>                        
                <h:outputText value="Server:" />
                <h:outputText value="irc.freenode.org" style="font-weight:bold"/>                
            </h:panelGrid>
        <h:commandButton value="Connect" action="#{chatBean.connect}" />
    </h:form>
</rich:panel>

It's rendered as:

Note that for simplicity purposes the channel and server names are using constants. In the future we plan to extend the sample with ability to open multiple channels and so on..

And here is the ChatBean.java used:

@ManagedBean
@SessionScoped
public class ChatBean extends PircBot implements Serializable {
private static final String SERVER_URL = "irc.freenode.org";
private static final int SERVER_PORT = 6667;
private static final String CHANNEL_PREFIX = "#";
private static final String SUBTOPIC_SEPARATOR = "_";
private static final String DEFAULT_CHANNEL = "richfaces";
private String channelName;
private String message;
public String connect() {
       try {
           this.connect(SERVER_URL, SERVER_PORT);
           this.joinChannel(CHANNEL_PREFIX + DEFAULT_CHANNEL);
           channelName = DEFAULT_CHANNEL;
       } catch (NickAlreadyInUseException e) {
           FacesContext.getCurrentInstance().addMessage(null,
               new FacesMessage(FacesMessage.SEVERITY_ERROR, this.getName() + " nick 
               already in use", this.getName()
               + " nick already in use"));
           return null;
       } catch (IOException e) {
           FacesContext.getCurrentInstance().addMessage(null,
               new FacesMessage(FacesMessage.SEVERITY_ERROR, "Sorry, server unresponsive. 
               Try again later.",
               "Sorry, server unresponsible. Try again later."));
           return null;
       } catch (IrcException e) {
           FacesContext.getCurrentInstance().addMessage(null,
               new FacesMessage(FacesMessage.SEVERITY_ERROR,
                   "Sorry, we encountered IRC services problems. Try again later.",
                   "Sorry, we encountered IRC services problems. Try again later."));
        return null;
       }
       return "chat";
   }
...
}

As you can see our bean extends the PirBot abstract class. So we just using PircBot api in order to get connected to server. And performing redirect to most interesting for us chat.xhtml page.

Client main page

Screenshot below shows you the result we want to achieve on that page:

Here is the complete listing of the chat.xhtml page. We'll review it in details below:

<script>
    function getMessageString(data){
        return data.author + " - " +data.timestamp+ ": " + data.text;
    }
</script>
<rich:panel header="Welcome to #{chatBean.channelName} channel at #{chatBean.serverName}" 
id="chatpanel">
    <rich:panel styleClass="chatOutput" bodyClass="#{chatBean.channelName}Output" />
    <rich:panel styleClass="chatList">
        <rich:list value="#{chatBean.users}" var="user" id="users" type="unordered">
            #{user.nick}
        </rich:list>
    </rich:panel>
    <br clear="all" />
    <hr />
    <h:form>
        <a4j:push address="#{chatBean.listSubtopic}@chat"
            onerror="alert(event.rf.data)">
            <a4j:ajax event="dataavailable" render="users" execute="@none" />
        </a4j:push>
        <a4j:push address="#{chatBean.messagesSubtopic}@chat"
            onerror="alert(event.rf.data)" ondataavailable="jQuery('&lt;div/&gt;').
            prependTo('.#{chatBean.channelName}Output').text(
            getMessageString(event.rf.data))" />
        <h:inputTextarea value="#{chatBean.message}" rows="3" style="width:80%" id="nm" />
        <a4j:commandButton value="Send" action="#{chatBean.send}" render="@none" execute="@form" />
    </h:form>
    <hr />
    <h:form>
        <rich:panel header="Change nickname:">
            <h:inputText valueChangeListener="#{chatBean.changeNick}" id="cn" />
            <a4j:commandButton value="Change" execute="@form" render="@none"/>
        </rich:panel>
        <h:commandButton value="Disconnect" action="#{chatBean.leave}"/>
    </h:form>
</rich:panel>

I will show you two options of performing push updates.

  1. Using ondataavailable JavaScript handler which will grab the data from the JMS event directly on the client.
  2. Using a4j:ajax behavior to trigger an Ajax request which will perform partial update when the push informs us about server event.

So the first panel:

<rich:panel styleClass="chatOutput" bodyClass="#{chatBean.channelName}Output" />

is just a container for the chat text which will be updated via JavaScript.

And the second panel:

<rich:panel styleClass="chatList">
    <rich:list value="#{chatBean.users}" var="user" id="users" type="unordered">
        #{user.nick}
    </rich:list>
</rich:panel>

contains the rich:list component which displays the users connected to the channel. It will be updated via an Ajax request that is triggered when the event about list change is populated at server side.

Client side updates on server-side events using JavaScript

Let's review the first a4j:push component more closely:

<a4j:push address="#{chatBean.messagesSubtopic}@chat" onerror="alert(event.rf.data)"
    ondataavailable="jQuery('&lt;div/&gt;').prependTo('.#{chatBean.channelName}Output').
    text(getMessageString(event.rf.data))" />

It's used to get the messages into the main chat window. Here is the TopicContext declaration and main methods from the ChatBean which are generates events for that push:

import org.richfaces.application.push.TopicKey;
import org.richfaces.application.push.TopicsContext;
...
private transient TopicsContext topicsContext;
public String getMessagesSubtopic() {
   return this.getUserName() + SUBTOPIC_SEPARATOR + channelName;
}
private TopicsContext getTopicsContext() {
if (topicsContext == null) {
topicsContext = TopicsContext.lookup();
}
return topicsContext;
}
@Override
protected void onMessage(String channel, String sender, String login, String hostname, String message) {
   try {
       Message messageObject = new Message(message, sender, DateFormat.getInstance().format(
new Date()));
       getTopicsContext().publish(new TopicKey("chat", getMessagesSubtopic()), messageObject);
   } catch (MessageException e) {
       LOGGER.error(e.getMessage(), e);
   }
}
public void send() {
   this.sendMessage(CHANNEL_PREFIX + channelName, message);
   try {
       Message messageObject = new Message(message, this.getName(), 
DateFormat.getInstance().format(new Date()));
       getTopicsContext().publish(new TopicKey("chat", getMessagesSubtopic()), messageObject);
   } catch (MessageException e) {
       LOGGER.error(e.getMessage(), e);
   }
}

onMessage method - just overriden PircBot method and it's invoked when the message comes from the other chat users. And send method is invoked when we are sending a message. This is a standard JSF action of the send button.

As you can see in order to raise an event for a4j:push we just publish it to the TopicContext. publish method accepts two parameters:

  • TopicKey key - adress which consist of topic and subtopic names.
  • Object data - actual data passed to client side event.

Messages subtopic generated by getMessagesSubtopic() method used by a4j:push component on the page and is unique for every user and channel, so only current user will receive the event populated by the object.

The Message object passed as data is pretty simple POJO with three String properties - author, text and timestamp. It's later used on the client in push oncomplete to create formatted string by getMessageString(data) JavaScript method and later add to chat div:

<script>
    function getMessageString(data){
        return data.author + " - " +data.timestamp+ ": " + data.text;
    }
</script>
IMPORTANT: As was mentioned before the other way to publish an event is by just sending it to JMS bus. So you have no need to use our TopicContext in this common case. We've just used this approach for simple example as we have no components other than our simple JSF bean. See Additional Details section for more information about publishing via JMS bus.

Ajax updates on server-side events using a4j:ajax

Now let's review the second approach to perform updates according to events received by a4j:push:

<a4j:push address="#{chatBean.listSubtopic}@chat" onerror="alert(event.rf.data)">
    <a4j:ajax event="dataavailable" render="users" execute="@none" />
</a4j:push>

It's used to update the rich:list which shows the current channel users. Here is the main methods from the ChatBean which are generates events for that push:

public String getListSubtopic() {
   return this.getUserName() + SUBTOPIC_SEPARATOR + channelName + "List";
}
@Override
protected void onUserList(String channel, User[] users) {
   try {
       getTopicsContext().publish(new TopicKey("chat", getListSubtopic()), null);
   } catch (MessageException e) {
       LOGGER.error(e.getMessage(), e);
   }
}
@Override
protected void onJoin(String channel, String sender, String login, String hostname) {
   try {
       getTopicsContext().publish(new TopicKey("chat", getListSubtopic()), null);
       Message messageObject = new Message("joined channel", sender, 
           DateFormat.getInstance().format(new Date()));
       getTopicsContext().publish(new TopicKey("chat", getMessagesSubtopic()), messageObject);
   } catch (MessageException e) {
       LOGGER.error(e.getMessage(), e);
   }
}

We are using the same publishing through TopicContext at server side just defining different subtopic for that a4j:push. And passing null as data because we do not planning to process anything at client side. That's where:

<a4j:ajax event="dataavailable" render="users" execute="@none" />

come in play. When push receives the event an ajax behavior sends a request which just perform rich:list render with new values. Pretty simple isn't it?

Additional Details

There I want to pay your attention to some details not covered within the article.

Single Connection

As you can see in this example we used two a4j:push component on a single page in order to demonstrate two different ways to process push events. It is important to know that this does not mean wo connections are getting opened. All the instances of the push component uses single connection and only the subscribed one gets the event for processing according to it's adress after some event is received. You can verify that by using Firebug for FireFox for example.

Publishing via JMS bus

JMS messages types supported by push are:

  • ObjectMessage
  • TextMessage

Corresponding data from getObject or getText passed to DataSerializer and getting serialized to the client data(to JavaScript using default serializer).

To be Continued...

And finally I want to announce topics which planned to be covered in next Push related articles.

Integration with CDI events

Being a first class citizen in JEE6 ecosystem CDI getting paid much attention during RichFaces development for sure. And support of CDI event system by a4j:push are also topic for upcoming separate blog entry!

And more...

There are a lot of possibilities with this component, too many to describe using just a single article. So follow our blogs or RichFaces twitter for any future examples and documentation updates related to this great component!


[Get updates of my blogs in twitter]

[My jroller.com blog]

24. Feb 2011, 16:41 CET, by Ilya Shaikovsky
Article updated. Mistake with 3.3.x functionality description corrected in Implementation details section

Introduction

As we reviewed in a previous blog with JSF 2 and RichFaces 4 you already have the Bean Validation support all the way to the browser with our client side validation. So you can effectively work with your server side object without any additional view level code related to validation.

This blog is going to review the last (but not least) validation feature which RichFaces 4 adds to JSF 2 . It's called Object Validation and provides a way to validate all your model Object fields considering even ones which were not used in the current view.

Why do you need that? The very first example which came to my mind as it appears frequently on various forums is dependent fields validation.

Password Validation Example

Let's check the password validation example:

<h:form>
	<rich:panel header="Change password" style="width:500px">
		<h:panelGrid columns="3">
			<h:outputText value="Enter new password:" />
			<h:inputSecret value="#{userBean.password}" id="pass"/>
			<rich:message for="pass"/>
			<h:outputText value="Confirm the new password:" />
			<h:inputSecret value="#{userBean.confirm}" id="conf"/>
			<rich:message for="conf"/>
		</h:panelGrid>
		<a4j:commandButton value="Store changes"
			action="#{userBean.storeNewPassword}" />
	</rich:panel>
</h:form>

And the simple managed bean source:

@ManagedBean
@RequestScoped
public class UserBean {

    @Size(min = 5, max = 15, message="Wrong size for password")
    private String password;
    @Size(min = 5, max = 15, message="Wrong size for confirmation")
    private String confirm; 
//...
    public void storeNewPassword(){
        FacesContext.getCurrentInstance().addMessage("", new FacesMessage(FacesMessage.SEVERITY_INFO, "Succesfully changed!", "Succesfully changed!"));
    }

//Getters and setters
}

So we solved half of the problem:

We are seeing the error messages if the password fields do not satisfy the validation rules given. Nothing is checking if passwords are the same though, just that they are independently valid. So what is the easiest way to validate if the fields are equals? We could perform that in action but that is quite late in the JSF lifecycle for validation. We could use some solutions using f:attribute in order to pass dependent field id to the other input and find the component by that id in custom validate method. There are also some other ways which are pretty easy to find across different knowledge-bases'. But most of them are either invoked in an improper phase (like action at INVOKE_APPLICATION) or has possible maintenance problems(f:attribute solution requires us to be patient with id's changes in view as validation depends on them).

RichFaces 4 Object Validation for cross-field validation

This is where RichFaces 4 Object Validation feature come in play! Here is what we propose to use:

<h:form>
	<rich:graphValidator value="#{userBean}" id="gv">
		<rich:panel header="Change password" style="width:500px">
			<rich:messages globalOnly="true"/>
			<rich:messages for="gv"/>
			<h:panelGrid columns="3">
				<h:outputText value="Enter new password:" />
				<h:inputSecret value="#{userBean.password}" id="pass"/>
				<rich:message for="pass"/>
				<h:outputText value="Confirm the new password:" />
				<h:inputSecret value="#{userBean.confirm}" id="conf"/>
				<rich:message for="conf"/>
			</h:panelGrid>
			<a4j:commandButton value="Store changes"
				action="#{userBean.storeNewPassword}" />
		</rich:panel>
	</rich:graphValidator>
</h:form>

And the Bean(Updated with implements Cloneable):

@ManagedBean
@RequestScoped
public class UserBean implements Cloneable{

    @Size(min = 5, max = 15, message="Wrong size for password")
    private String password="";
    @Size(min = 5, max = 15, message="Wrong size for confirmation")
    private String confirm="";

    @AssertTrue(message = "Different passwords entered!")
    public boolean isPasswordsEquals() {
        return password.equals(confirm);
    }

    public void storeNewPassword(){
        FacesContext.getCurrentInstance().addMessage(null, new FacesMessage(FacesMessage.SEVERITY_INFO, "Succesfully changed!", "Succesfully changed!"));
    }

So lets look through the sample details. rich:graphValidator tag should wrap the inputs bound to the object which we are interested in validating. The value attribute should be pointed to that bean name. Then at PROCESS_VALIDATION phase all the object fields will be validated according to constraints added. And in that particular case isPassWordEquals will be validated using AssertTrueValidator. That looks just like we expected!

Different passwords entered(but valid according to size):

Verification successful:

Implementation Details

UPDATED(28.02) section below. Actually 3.3.x used the same way. Was written that it worked at model updates by mistake.

Just one question appears. Those who know the JSF life-cycle will ask immediately about how the bean could be validated before the model updates? Does RichFaces propose to use validation after process updates phase? No. We perform a clone() on your bean instance at validation phase and updating new instance with all the new values submitted(that's why we still need to wrap all the inputs related to rich:graphValidator). We then validate the cloned object firing validation messages if needed. Your model objects remains clean, lifecycle gets interrupted properly after Process Validations phase and messages encoded to client during Render Response.

NOTE: if cloneNotSupportedException thrown from the object – validation will be done at model updates. And that is the only exception to our architecture which really can't be workaround-ed.

Try it out!

Now having JSF 2 Bean Validation support standardized, RichFaces 4 Client Side Validation and Object Validation features we believe you will be able completely concentrate on your business tasks and will not spend time for any additional JSF development in the validation phase. Try our new features in RichFaces 4.0.0.M6 and let us know about any problems or questions appeared. That will help us greatly to provide those features stable and well documented prior to RichFaces 4 Final release!


[Get updates of my blogs in twitter]

[My jroller.com blog]

Showing 1 to 5 of 26 blog entries