We’ll start by creating a project from the knappsackjee6-servlet-basic archetype. This gives us all the features of Java EE 6 without too much code to get in the way. We’ll start by creating a backing bean that is request scoped and looking at how that is used and what effect request scope has.

import java.io.Serializable;

import javax.enterprise.context.RequestScoped;
import javax.inject.Named;

@Named("bean")
@RequestScoped
public class BackingBean implements Serializable {

	private Long value = new Long(0);

	public Long getValue() {
		return value;
	}

	public void setValue(Long value) {
		this.value = value;
	}

        public String getMessage() {
            return "The value is : "+value;
        }
}

Simple enough, now lets add a page called listEdit.xhtmlthat lets us enter the value, post the value back and see what the message is.

<?xml version="1.0" encoding="UTF-8"?>
<ui:composition xmlns="http://www.w3.org/1999/xhtml"
	xmlns:ui="http://java.sun.com/jsf/facelets"
	xmlns:f="http://java.sun.com/jsf/core"
	xmlns:h="http://java.sun.com/jsf/html"
	template="/WEB-INF/templates/template.xhtml">
	<ui:define name="content">
		<h:form id="form">
            Value : <h:inputText value="#{bean.value}" />
			<h:commandButton value="Submit Value" action="submit" />
			<br />
			<br />
            Message : #{bean.message}
   </h:form>

	</ui:define>
</ui:composition>

Edit home.xhtml to include a link to this page :

<a href="listEdit.jsf">Start New List</a>

Open up the home page and click the link to go to the listEdit page. If we enter a value in the input box and click the submit button, predictably, our message says that the value is whatever we entered.

What is happening here is that when the form is posted back, the value in the input box is sent back to the bean.value attribute. When the page is rendered back to the user and the message is rendered, it is rendered using this value that we passed back to the server. We pass the state of the attribute from the server to the client, and then back to the server, and we can do that all day long using just the request scope without any problems. This is a stateless page and doesn’t require any state to be held on the server.

Let’s add something a bit more stateful to the page such as a list of values that we have added previously. In our backing bean, add the following field and getter method and a method to add the value.

private List<Long> values = new ArrayList<Long>();
..
..
..
public List<Long> getValues() {
	return values;
}

public void addToList() {
	values.add(value);
}

Now we will add the list of values to our page to be displayed.

<ui:define name="content">
	<h:form id="form">
		Value : <h:inputText value="#{bean.value}" />
		<h:commandButton value="Submit Value" action="#{bean.addToList}" />
		<br />
		<br />
		Message : #{bean.message}
		<h2>Added Values</h2>
		<ui:repeat var="v_value" value="#{bean.values}">
			#{v_value}<br />
		</ui:repeat>
	</h:form>
</ui:define>

If we refresh our page, enter a number and click submit, you will see that the number appears at the bottom of the page where it should. When we click the submit button on the form the value is assigned to the value attribute. When the addToList method is called, the value attribute is added to the list. When the page is rendered, the latest value is used to generate the message and for the list of items we return the list containing one item, the new value.

So far so good. Let’s enter a new number and add it to the list. When we click the button the second time, the only number in the list of numbers is the one we just entered. The first value is gone! The problem is that the second time we posted the value the bean was re-constructed from scratch and had no idea whatsoever about the first value we added to the list. There was nothing on the form to tell the bean about the first number even though we displayed it on the page. The backing bean keeps forgetting our list of numbers from one request to the next, or in other words, our application is missing some state.

As per part 1, there are a number of ways we can get around this problem. We could save the list to the database each time we post, which is over kill for this simple task. We could push the state down to the client, say using a comma delimited list of existing numbers pushed into a hidden field. When the form is posted, the comma delimited list is sent back to the server where the numbers are unpacked and the list is rebuilt on the server side and the state is restored.
Both of these two methods are doable but what happens when we have more information on the server that we need to keep hold of? Do we have to keep adding add each piece of information to the client state manually, including passing it around from one page to the next for multi-page processes? What if it is a list of entity objects we want to hold on to? Do we just save the Ids on the client and keep re-loading them from the database each time?
These solutions are impractical from the perspective of building a maintainable app quickly. However, note that these solutions are completely possible with JSF and CDI. It just offers better alternatives, but the opportunity to get under the hood and use more lower level solutions in the interests of optimizing the application are always there. This is an important factor since if you have a widely used conversational page that is creating a bottle neck, you can refactor it down to use a more stateless approach.

Since this article is all about conversations, obviously, we are going to solve our problems using the conversation scope. We will change our bean to be @ConversationScoped and @Inject a Conversation instance we’ll be using. We’ll then start the conversation for the page when our bean is constructed. This is an example and typically you don’t start conversations in bean construction but it serves our purpose here.
Tip : Conversations are typically started at specific points on certain initialization methods, starting it on bean construction is bad because you never know when another task might use an instance of that bean

@Named("bean")
@ConversationScoped
public class BackingBean implements Serializable {
	...
	...
	...
	@Inject
	private Conversation conversation;
	...
	...
	@PostConstruct
	public void postConstruct() {
		conversation.begin();
	}

	public Conversation getConversation() {
		return conversation;
	}
	...
	...
}

Reload our page and you can see how you can enter and submit as many numbers as you want to the page and the list state is managed.

Conversations are just a natural extension of the existing scopes in current web applications. They also become very natural to use. Let’s add another page that lets us review our list of numbers before ‘confirming’ them. Add the following new button at the bottom of our page :

	<h:commandButton action="review" value="Review Numbers"/>

Because the action attribute is set to review we will create a new page called review.xhtml that will display the numbers. Our first concern obviously is ‘where does it get the list of numbers from?’, well the answer is, from the same place it got the numbers from last time, using the expression #{bean.values}.

review.xhtml

<?xml version="1.0" encoding="UTF-8"?>
<ui:composition xmlns="http://www.w3.org/1999/xhtml"
	xmlns:ui="http://java.sun.com/jsf/facelets"
	xmlns:f="http://java.sun.com/jsf/core"
	xmlns:h="http://java.sun.com/jsf/html"
	template="/WEB-INF/templates/template.xhtml">
	<ui:define name="content">
		<h:form id="form">
			<h1>Please Confirm The Values : </h1>
			<h2>Added Values</h2>
			<ui:repeat var="v_value" value="#{bean.values}">
			#{v_value}<br />
			</ui:repeat>
			<h:commandButton action="#{bean.confirm}" value="Confirm"/>
		</h:form>
	</ui:define>
</ui:composition>

The way to think about this is to imagine what happens when the page is rendered. JSF will look for the value beans.values which the CDI implementation can provide. Since this page is being rendered in an active conversation, CDI will look in the active conversation ‘bucket’ for a bean called bean. Since we are coming from the page that adds the numbers, this bean will already exist in the conversation and so the same instance is returned. Should we render this page without an active conversation, by typing in the URL manually, the page will render, but this time, the instance of beans.xml will not already exist and so CDI will create a new instance of it that doesn’t contain any items.
Tip : There are ways to prevent pages rendering without an active conversation which can also help with duplicate form submissions

Getting back to the page, we just want to add our confirm method to our backing bean. This method ends the conversation and redirects to the home page which is going back to the number entry page.

public void confirm() {
	conversation.end();
	try {
		FacesContext.getCurrentInstance().getExternalContext().redirect("home.jsf?faces-redirect=true");
	} catch (IOException e) {
		e.printStackTrace();
	}
}

Add the following at the top of either the review or list edit page to see the conversation Id you are currently in :

Conversation : #{bean.conversation.id}

If you run the application, you can add numbers and when you click review, you get a list of all the numbers you just entered on a separate page.

If we were managing state ourselves, we would have to pass something to the review page to let is know what the list of numbers was, either a database row key, or the comma delimited values. Again, the more state you have to pass around the less verbose and maintainable the application becomes. CDI is automatically passing our key (the conversation id) around for us. Under the review button the list edit page, add the following GET link :

<h:link outcome="review" value="Review"/>

If you look at the link URL it is http://localhost:8080/conversationdemo/review.jsf?cid=xxx where xxx is some number. CDI automatically creates a URL that propagates the conversation for us. If we didn’t want to propagate the conversation, we can just add a blank cid parameter and CDI will leave it alone. This can be useful when you want to launch a page without a conversation from a page that is in a conversation. Add the following link :

<h:link value="Start New List" target="_blank">
	<f:param name="cid" />
</h:link>

This lets you start a fresh new list in a separate window (since we didn’t specify an outcome it defaults to the current page). If you create a new list and add some numbers you can see that you can manage separate lists independently without doing anything to handle multiple browser windows.

When you have multiple windows open, set the url of one window to the url of other (i.e. http://localhost:8080/conversationdemo/listEdit.jsf?cid=xxx where xxx is the other conversation ID) when you load this page, you see the list from the other conversation so you can just switch conversations using GET requests by specifying a different conversation id.

Workspace Management

One cool feature of Seam that had a lot of potential was workspace management which lets you see a list of active conversations and select one. We are going to implement a version of that here by providing the user with a set of links that takes us to the active conversation. Create a new bean that is session scoped that will keep a track of our conversation ids.

import java.io.Serializable;
import java.util.ArrayList;
import java.util.List;

import javax.enterprise.context.SessionScoped;
import javax.inject.Named;

@Named
@SessionScoped
public class WorkspaceBean implements Serializable {

	private List<String> conversations = new ArrayList<String>();

	public List<String> getConversations() {
		return conversations;
	}

}

This is just a bean that keeps a list of the conversation Ids currently active. When we start a conversation, we need to add that id to the list and when we end a conversation, we need to remove it from the list.

We will inject this session scoped bean into our backing bean and change the postConstruct and confirm methods in the BackingBean class to add and remove the conversation from the list.

@Inject
private WorkspaceBean workspace;

...
...

@PostConstruct
public void postConstruct() {
	conversation.begin();
	workspace.getConversations().add(conversation.getId());
}

public void confirm() {
	workspace.getConversations().remove(conversation.getId());
	conversation.end();

	try {
		FacesContext ctx = FacesContext.getCurrentInstance();
		ctx.getExternalContext().redirect("home.jsf?faces-redirect=true");
	} catch (IOException e) {
		e.printStackTrace();
	}
}

Now we need some view code to display the list of conversations and provide links to them. Simply add this to the home.xhtml page, and even the listEdit.xhtml or review.xhtml pages if you want :

	<h1>Workspaces</h1>
	<ui:repeat var="v_conv" value="#{workspaceBean.conversations}">
		<h:link outcome="listEdit" value="Goto Conversation #{v_conv}">
			<f:param name="cid" value="#{v_conv}" />
		</h:link>
		<br />
	</ui:repeat>

This just loops through the conversations and creates a link to the listEdit page and passes the conversation Id as a parameter. Because we pass a value for cid CDI will not try to add the current conversation as the cid value.

That’s all you need for a workspace demonstration. You can create new lists and if you jump back to the home page, you will see the available conversations and be able to click the link and jump back into the conversation. When you review the list and confirm it and the conversation ends, when you end up back on the front page, that conversation is longer listed.

This is a fairly powerful mechanism that is built upon the simplicity of CDI Conversations. There is very little work that is required to use conversations, just inject the Conversation instance and call the begin() and end() methods when you need to start and end the conversation. Conversations also have a minimal impact on our code, mainly just an annotation since the getters and settings and other methods don’t change. We can also easily revert back to a stateless request scoped solution should we have to which would cause additional code to be required to read/write the list to the client.
Conversations should be used with care, especially in terms of making sure you have strict demarcation boundaries, and careful consideration should be given to determining what you include in a conversation.

You can download the maven project source code for this demo (Conversation Demo ), just unzip it and enter mvn jetty:run and navigate to http://localhost:8080/conversationdemo/home.jsf.

groupId = org.fluttercode.knappsack
artifactId=jee6-servlet-basic
version=1.0.5

Once you have your project, just run mvn jetty:run in the command line and navigate to http://localhost:8080/jsfbasics/home.jsf. Ok, so now we are up and running, lets look at a JSF page and what it contains.

JSF uses a templating language called facelets. JSF 1 originally used JSP as its view language, but for JSF 2.0 Facelets became the defacto standards and was adopted as the standard view definition languages for JSF 2.0. In our application, we have a template file called WEB-INF/templates/template.xhtml. The template just has a lot of boilerplate view code but there are some ui:insert tags that mark places in the template where we should insert content. For example, the main content is inserted in a facelets area called content

<ui:insert name="content">Main Content</ui:insert>

These are insertion points which are used by pages that base themselves on this template. One of the great features of facelets is that the template defines the content points, while the page itself is used to define the template used and then push the content into the content points. This is much better than having to include page fragments in a JSP page, using a page decorator or using a template to include the content page. Our main page home.xhtml is one such page that uses this template.

home.xhtml

<?xml version="1.0" encoding="UTF-8"?>
<ui:composition xmlns="http://www.w3.org/1999/xhtml"
	xmlns:ui="http://java.sun.com/jsf/facelets"
	xmlns:f="http://java.sun.com/jsf/core"
	xmlns:h="http://java.sun.com/jsf/html"
	template="/WEB-INF/templates/template.xhtml">

	<ui:define name="content">
		<h1><h:outputText value="Hello From JSF" /></h1>
	</ui:define>

</ui:composition>

At the very top, in the composition tag, we tell Facelets that we want to use the file template.xhtml as our template page. Next we have a ui:define tag that defines the content that is to be used in the template. Facelets works by having the page pull the template into the page and pushing its content into the slots provided by the template. This is much better than pulling content into the main page using includes, or specifying a template used everywhere and decorating the content with it. This is the best of both worlds. Each page defines which template page it uses and pushes the content into it.

Our first used component

In here you can see we have used our first JSF component :

<h:outputText value="Hello From JSF" />

This is a standard JSF component that is used to output text. We could have just written the text right in the page, but the goal of this page is to test that the JSF configuration is working and to do that, we need to see if the JSF component is rendered correctly. You can edit the text in the value and obviously it will change the text displayed on the page.

Our first backing bean

Displaying static text isn’t what web frameworks were built for, what we really want is to display something that comes from some java code. To do this, we will create a backing bean which is a java object that is part of the web application that JSF is aware of. To create backing bean, create a new class and call it PageBean.

import javax.enterprise.context.RequestScoped;
import javax.inject.Named;

@Named
@RequestScoped
public class PageBean {

	private String message = "Mighty apps from little java beans grow";

	public String getMessage() {
		return message;
	}

	public void setMessage(String message) {
		this.message = message;
	}
}

The code itself is pretty simple. One field with a default value and getters and setters. However, we have a couple of new annotations at the class level. First is the @Named annotation that tells CDI that this bean has a name that be used to refer to this bean using EL expressions. Since we didn’t supply a name the default name of pageBean is used. The @RequestScope annotation tells CDI that this bean is request scoped so when it is created, it should last till the end of the current request and then be destroyed. This means that the next time we call this page, this bean will be re-created and a fresh version used which again will be destroyed at the end of the request.

Now we are going to change our application to display this message instead.From now on, we will just be showing the code within the ui:define statements:

	<ui:define name="content">
		<h:outputText value="#{pageBean.message}" />
	</ui:define>
</ui:composition>

If we run the application now, you should see the message displayed on the main page:

Now let’s take look at a producer method that can be used to display the date and time the page was rendered. First, open up the template file and look for the footer panel at the bottom and change it to :

<h:panelGroup id="footer" layout="block">This page was rendered at #{currentSysDate}</h:panelGroup>

What is currentSysDate value? Well, we need to go back to our PageBean and define it. We will add a new method that returns a new Date object and we’ll annotate it with @Named and @Produces.

@Produces @Named("currentSysDate")
public Date produceDate() {
	return new Date();
}

The Produces and Named annotation tells CDI that this method can be used to produce a value with the name currentSysDate. When our application is deployed, CDI makes a note that this value comes from this method so when our page is rendered and JSF is looking for the value currentSysDate, CDI calls the method and returns the value obtained from this method.

If we refresh the page we can see that our new timestamp function is on there.

This will come in handy later on when we start using AJAX and want to check that the full page has not updated (the timestamp will stay the same because that portion of the page won’t change). We’ve shown how we can pull data from the server onto the page so let’s take a look at how we send data back to the server.

In our home.xhtml page, we’ll add a text input to edit the message and a button to post it back.

<h:form id="messageForm">
	<h:outputText value="#{pageBean.message}" /><br/>
	<br/>
	New Message : <h:inputText value="#{pageBean.message}"/>
	<h:commandButton action="update" value="Update"/>
</h:form>

First, we added the h:form tags which gives us an HTML form in which to put input controls. Any data entry in a JSF page needs to be enclosed in a JSF form tag in order to be passed back to the server. We defined an input text box that was bound to the same value as the message display and a command button that is used to post the values back. If we refresh the page, enter a new message and click the button our message changes.

However, this is the age of Web 2.0, and just posting back a form and displaying the results isn’t enough, we need to do it with AJAX. AJAX is a mechanism by which the browser makes an asynchronous request to the server and gets a response back. When the response is returned, the browser will call a javascript function that will update part of the page instead of all of it. Sounds complicated, but the nice folks that wrote JSF wrapped all that functionality up in one little tag called f:ajax

What we want to do is make our command button an AJAX button which we can do by placing the f:ajax tag as a child tag of the button. All we need to supply the AJAX tag with is the execute and render attributes. This indicates which parts of the page we want to post back to the server, and which parts we want to re-render when the response comes back. We want to execute the form and re-render the form, so we could use the component id (messageForm) for the attribute values. JSF also provides a couple of shortcuts that we can use. The value @form references the form the button is in so rather than hardcode the form id, the @form value will let us reference the form without doing so by name.

<h:commandButton action="update" value="Update">
	<f:ajax execute="@form" render="@form" />
</h:commandButton>

Notice that now you have an ajax button, the timestamp in the footer doesn’t change when you post the value back.

Performing Actions

So far we have covered displaying information from the server side bean and writing values back, but often we want some user action to execute some code on the server.

Start by adding a Integer attribute on to our PageBean class and two methods, one to increase it, and another to decrease it as well as getters and setters for the value.

	private int value = 0;

	public void increase() {
		value++;
	}

	public void decrease() {
		value--;
	}

In the view, we want to display the value and have a couple of buttons to increase and decrease the value. Add the following view code in home.jsf somewhere between the h:form tags :

<h:panelGroup layout="block" id="spinner">
     <h:commandButton action="#{pageBean.decrease}" value="-" />
     #{pageBean.value}
     <h:commandButton action="#{pageBean.increase}" value="+" />
</h:panelGroup>

Refresh the page and click away, and you’ll notice something is wrong. Press the increase button and the value goes to 1, click it again and it…goes to 1. Click the decrease button and it will always go to -1. The problem is an issue of state. Each time we click the button, we post back to the server, and the server creates a new instance of the pageBean and calls the increase or decrease methods. The problem is that each time we create the bean, the value starts at zero and so is only ever increased to 1 or decreased to -1.
Now you may be wondering that since you are displaying the value on the page, isn’t that enough to post it back to the server, after all, we displayed the message in an input box and it got passed back to the server. The difference is that an input box is known as a JSF value holder, which means it actually holds the value it is bound to on the client and posts it back to the server when the form is posted back. We can see this demonstrated by changing the value text display component to an input text box component:

<h:panelGroup layout="block" id="spinner">
    <h:commandButton action="#{pageBean.decrease}" value="-"/>
    <h:inputText value="#{pageBean.value}"/>
    <h:commandButton action="#{pageBean.increase}" value="+" />
</h:panelGroup>

Now when you click the +/- buttons the value changes beyond -1 and 1. This is because when the page is rendered, the value is stored on the client. When the button is clicked and the form is posted back, the client side value is sent back to the server side attribute and then the increase/decrease method is called with the value that is set. This is fairly common with web forms, and one way of handling state by putting it in client side forms, even as hidden field values.

We can demonstrate this further by manually entering a value into the text input and then clicking a button. Enter 1000 in the input text box and click the increase button. The value should now be 1001.

When we manually enter a value, we are changing the value held on the client in the value holder represented by the input text box. When we click the increase button we are sending that value back to the server. On postback, the server creates an instance of our PageBean class, sets the value attribute to the value in our text box (1000) and then calls the increase method which increases the value to 1001. Once the method has finished, JSF then must render a response which includes taking the value from the pageBean.value attribute and putting it in our text box which is how the text box shows 1001 after clicking the button. At this point, once our request is complete, the page bean is destroyed as it is only request scoped.

Validating the value

If we only want the value to be between 0 and 10, we can add validation annotations onto the value field to enable it to be checked for correctness when we post back the values. In our PageBean class, we’ll add the annotations as follows :

@Min(value=0)
@Max(value=10)
private int value = 0;

We also need some way to display error messages if the user enters an invalid value so we’ll add a h:message tag. The message tag is used to associate a JSF message with a component and display it. We give the input text box a name and add the message for that component :

<h:panelGroup layout="block" id="spinner">
	  <h:commandButton action="#{pageBean.decrease}" value="-"/>
	  <h:inputText value="#{pageBean.value}" id="valueInput"/>
	  <h:commandButton action="#{pageBean.increase}" value="+" />
	  <h:message for="valueInput" styleClass="errorMessage"/>
</h:panelGroup>

Now refresh the page and enter 1000 into the value text input and click the increase button. You should see an error message next to the text editor because the value is above 10. Try entering the value of -1000 and clicking a button.

My Personal Choices

For me personally, nothing does Web Applications better than JSF backed by Java EE 6. A year ago I would have said Seam, but Java EE 6 now carries most of the Seam functionality. Java EE 6 with Seam 3 sprinkled in for good measure will rock. (if you think Java EE 6 sucks for not being whole until it has Seam 3 added, think of it more like adding jQuery to your web pages). I do like Wicket, but for me, it’s one of those that sits in the middle and does a bit of both. It’s like riding a bike to the mailbox (only a little bit of overkill), or to the store (better than walking, but still with limits). However, it is a very viable alternative.

For web site type projects, I would look for a framework that is more client oriented since people will want to start leveraging the advancements with HTML 5 and Javascript. I would probably use Spring MVC or at a stretch, possibly Grails. Primarily because it offers a development structure that is not so dissimilar to using JSF, and can include Spring Web Flow for more statefulness. At the same time it lets you get under the hood more with CSS, HTML and JavaScript if you choose to. It also gives you some more deployment options without taking features away.

Note that these are merely my personal choices and their selection says nothing about the choices made by anyone else any more than choosing to drive a Ford is being critical of someone driving a Honda. Similarly, if you think Fords suck, you should have at least have a good reason for believing so, other than you couldn’t drive one before you learned how to.