Andy Gibson » Apprentice

CDI Conversations part 2

Andy Gibson — Tue, 21 Sep 2010 13:07:43 +0000

This article will look at using the Conversation scope defined in JSR 299 (Java Contexts and Dependency Injection), and released as part of Java EE 6. For now, we’ll stick to non-data driven examples as we explore the ins and outs of the Conversation scope. We’ll finish up by creating a workspace manager so we can list all the active conversations and switch between them.

A Conversation is like a numbered bucket in the session that exists until either the end of the users session, the conversation times out, or the server side code deliberately ends the conversation. The benefits of a conversational scope are many, letting us easily create pages that can be opened in multiple tabs without having to juggle the state on the client without filling the session with data that will last as long as the user session should we forget to remove it.

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.



	
		
            Value : 
			
			

			

            Message : #{bean.message}

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

Start New List

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 values = new ArrayList();
..
..
..
public List getValues() {
	return values;
}

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

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


	
		Value : 
		
		

		

		Message : #{bean.message}
		Added Values
		
			#{v_value}

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 :

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



	
		
			Please Confirm The Values : 
			Added Values
			
			#{v_value}

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 :

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 :

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 conversations = new ArrayList();

	public List 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 :

	Workspaces

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.

JSF Basics

Andy Gibson — Wed, 08 Sep 2010 12:51:19 +0000

This is a brief tutorial that takes a quick look at some of the very basics of JSF, how we define pages and hook them up to server side objects. Rather than cover the fundamentals of starting a new JSF application, I’m going to start from one of the Knappsack archetypes which can provide you with a JEE 6 application ready to roll. In this case, we are going to start with a servlet based example so you can run it using the embedded servlet containers.

To create the new project, we are going to use the following archetype GAV values. You can also read up on creating a new Knappsack application

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

Main Content

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

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 :

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:

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 :

This page was rendered at #{currentSysDate}

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.


	

	

	New Message :

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.

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 :


     
     #{pageBean.value}

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:

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 :

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.

Knappsack Archetypes Part 2

Andy Gibson — Thu, 12 Aug 2010 15:03:07 +0000

In part 1, we looked at the basic structure and configuration of the project that is common in all the archetypes. This time we’ll look at the minimal archetype that contains some more functionality and a number of different classes used to implement that functionality.

The Java EE 6 Minimal Archetype

While there is still only one web page in the project, there are now a few more classes provided. These have been grouped into packages off the main package folder.

Package	Description
`bean`	The `bean` package contains the `EntityManager` producer and also a dao object for fetching and persisting `Person` objects as a stateless EJB (and a local interface).
`model`	Contains the JPA model for ther application which in this case is just one `Person` class
`qualifier`	Contains the qualifier used to specify injection points for the `EntityManager`
`view`	Contains the backing beans for the JSF view. These beans provide server side logic for the JSF pages, usually by invoking functions on the service beans in the `bean` package. The `HelloBean` accepts a user entered name and returns a message. The `PersonBean` has a person entity that can be modified by a JSF page and then persisted to the database. There is also a method to return the list of previously saved people from the database.

Layered code

We have a fairly clear separation of concerns with the different packages. The EJBs in the bean and qualifier packages don’t have any dependency on JSF while the beans in the view package are for JSF support only. Such organization means that you could put the contents of the bean and qualifier packages into a separate jar and re-use them with a different view framework. Technically, because they are also POJOs you could use them in a non-EJB environment.

Producing Entity Managers

The EntityManager is produced in the DataRepositoryProducer bean by returning the persistence context that was injected into the stateless bean by the container. When an entity manager needs to be injected into an injection point, this method is used to produce one. It is marked as @ConversationScoped so it can participate in CDI conversations. The @DataRepository annotation is a qualifier annotation used to mark what kind of entity manager you are producing and therefore can only be injected into injection points with the same annotation. This is useful if there are multiple databases used to distinguish between different entity managers produced.

Service Beans

In the PersonDao we inject the EntityManager that is then used in the other methods to save and fetch objects. In EJB 3.1 the default transaction attribute is Required for EJB methods so we don’t need to specify any transaction handling on the methods.

The PersonDao is injected into the view/PersonBean class so as the view needs to fetch or update data, the dao can be used to provide those functions.

If there was a mechanism that we could use to provide transactions on CDI (non-EJB) beans, then we wouldn’t really need EJBs, but as it is, we do. Nothing is stopping us from later changing the EJBs to CDI Managed beans with sufficient transaction support.

JPA Model

The only model class we use is the Person class that has properties for first name, last name and an integer Id value. On the name fields, we have specified a number of validators as well as the column size using annotations. These validators check that the field is not empty, or null and does not have a length greater than 25 characters.

Now we’ve covered the server side code, let’s take a look at the JSF page that uses these beans in home.xhtml.

JSF Content

The single page in this archetype is split into three different sections that test different parts of the environment.

The first part is producing the hello message from the helloBean class. The class is annotated with @Named("helloBean") which lets us reference this bean from the JSF page. The method getHelloMessage() returns a fixed string which is displayed in the page by using the EL expression #{helloBean.helloMessage}. This tells JSF to get the helloMessage property from the bean called helloBean. The bean name is resolved using an EL expression resolver that looks up the bean name in the beans registered with CDI using the @Named annotation.

If you are using JBoss Developer Tools and have enabled CDI for this application (right click on project, click Configure->Add CDI Support, you can go into the JSF page and ctrl+click on the expression (either the bean name or the property name) and the IDE will go to the point in the code that the expression is defined.

You can interact with the CDI hello bean by entering your name and clicking the submit button which posts your name back to the backing bean and when the page is re-rendered, your name appears in the message below the submit button. Again, the control is bound to the name property of the helloBean bean which is then used to return the correct message to the user when the page is re-rendered.

The final section uses JSF and CDI to edit an instance of a Person object on the CDI backing bean, with JPA persisting the object and Bean Validation providing validation for the JSF page. JPA also returns a list of the people previously saved. The PersonBean class has the @Named annotation which gives it the name personBean and it is marked with a @RequestScoped annotation. The bean has a person instance that is used as the model for the JSF page input boxes. The text boxes are defined for the first and last names and bound to the person entity on the personBean bean. Each input has a h:message JSF tag that reports errors for that input value. This will report errors on the person bean based on the validators we specified on the model. In the JSF page, the Add button calls the savePerson method on the personBean backing bean which uses the person dao implementation to persist the person entity in the backing bean. JSF automatically includes validation specified on the JPA model and will report errors back to the user for invalid input.

Underneath the person data entry, there is a list of names that have already been entered. Just enter a new name and click add to see the new name appear.This is fetched from the backing bean using the dao that is injected into it.

Using the app for yourself

If you want to create a new application from this archetype, you will probably want to delete the following items.

/bean/PersonDao.java
/bean/PersonDaoLocal.java
/model/Person.java
/view/HelloBean.java
/view/PersonBean.java

While you may want to re-use the template, or a modified version of it, you won’t need the content in the home.xhtml file. You can remove the content surrounded by the tags. Alternatively, you can just create a new project using the jee6-basic-archetype which has none of this additional code.

In the next section we’ll start looking at the JPA model and pre-defined data in the sandbox archetype.

Create A New Project With Maven Archetypes

Andy Gibson — Sun, 01 Aug 2010 16:50:12 +0000

Prerequisites

Install Maven

In this tutorial, we will create a new project using the Knappsack Archetypes and compile and deploy it. For this example, we will use the jee6-basic-archetype. Before you begin, you will need to have installed Maven, but you no longer need to manually install the Knappsack Archetypes as they are in the Central Maven Repository now, so you just need to make sure your index is up to date. These instructions will work for any Maven Archetype you have installed and creating new maven projects in general.

Maven archetypes can be thought of as templates that are installed into the Maven environment and can be used to generate new applications from scratch that are pre-configured for certain environments, whether it is Java EE 6, Wicket or Spring. We can create our project using either the command line or an IDE and both Eclipse and Netbeans both have support for Maven. Netbeans has it out of the box while Eclipse requires m2Eclipse to be installed. This tutorial covers all three methods of creating projects from Maven.

New project from the Command Line

Start by opening up a command prompt and navigating to the directory your project will reside in
The easy way to create a project on the command line is to just type
```
mvn archetype:generate
```
We will use the easier version where we don’t have to specify long command lines that include the group and archetype Ids and versions.

You will be greeted with a long list of possible archetypes with a number next to them and a prompt at the bottom to enter the number of the archetype you want to use.

4: local -> jee6-minimal-archetype (Minimal Java EE application with a single page demo of CDI, JSF, JPA and Validation to ...
5: local -> jee6-basic-archetype (Basic Java EE application with just configuration for CDI, JSF, JPA and a sample empty page.)
6: local -> jee6-sandbox-archetype (Sandbox project for Java EE 6 with CDI, JSF, JPA and a sample model and test data to play ....
7: local -> jee6-sandbox-demo-archetype (Complete demo example using CDI, JSF, JPA and validation showcasing a number of ...
8: remote -> docbkx-quickstart-archetype (null)
9: remote -> j2me-simple (Maven 2 Archetype for midlet application using j2me-maven-plugin)
10: remote -> vaadin-archetype-clean (This archetype generates a simple Vaadin application as a Maven project...
...
...
...
...
Choose a number: 65:

Hint : Your locally installed ones should be near the start of the list. The default number (in this case 65) is the quickstart archetype to produce and empty maven project.

Enter the number of the Knappsack archetype you want to use and press enter.

You will then be asked to enter a number of different properties for the project :

Define value for property 'groupId': : com.yourcompany
Define value for property 'artifactId': : yourprojectname
Define value for property 'version': 1.0-SNAPSHOT:
Define value for property 'package': com.yourcompany:
Confirm properties configuration:
groupId: com.yourcompany
artifactId: yourprojectname
version: 1.0-SNAPSHOT
package: com.yourcompany
Y:

Here we assumed the version is the default SNAPSHOT version and that the default package is the same as the groupId value.

Once complete, if you look in the directory you will see a new directory called yourprojectname. Move into this directory and if you have JBOSS_HOME set up you can deploy the project straight away.
```
mvn clean package jboss:hard-deploy
```
Start up JBoss if it isn’t already and go to http://localhost:8080/yourprojectname/home.jsf.
You can now import this project into an IDE such as Eclipse or Netbeans as these IDEs recognize Maven projects

Alternatively, you can use the command line to enter one long command, or as I do, put it in a script or batch file that I can edit in a text editor and run it from there. Here’s an example to get you started which you can copy and paste:

mvn archetype:generate -DarchetypeGroupId=org.fluttercode.knappsack -DarchetypeArtifactId=jee6-sandbox-demo-archetype -DinteractiveMode=false -DarchetypeVersion=1.0.4 -DgroupId=org.application -DartifactId=sandboxdemo -Dpackage=org.application

Creating a project in an IDE

Creating a Maven project in an IDE is much easier, although sometimes not by much. Typically, you choose to create a new project in the IDE and select maven as the type of project you want to create.

Netbeans

Select File->New Project and in the first list, select Maven and on the right hand side, select Maven Project (not Maven Web Application). Click Next.
Here we will pick our archetype to create our application from. In the list, expand the Archetypes from Local Repository item in the list. If you don’t see the archetypes there, you might need to refresh the index in the IDE. Close the new project window to do this.
1. Select Window->Other->Maven Repository Browser to open the repository browser.
2. In the repository browser window, right click on the repository and select Update Index.
Now you should be able to start the new project from scratch and see the missing archetypes.

Once you have selected the archetype, click finish to setup the project properties.
The project properties are the group and archetype Id for the new project as well as the optional default package name.

You will also configure the project location here and click Finish when done.
Once complete, Netbeans will create your project and open it up. To run it, click Run->Run Main Project and it will prompt you for a Java EE 6 server to use. Select one and click ok. Remember that you need to change the datasource name in persistence.xml so it is not looking for the JBoss default datasource name.

Eclipse

First make sure you have m2Eclipse installed and are running Eclipse under a JDK instead of a JRE. For more details see this Installing and configuring Eclipse tutorial.

In Eclipse, click on File->New->Other.. to bring up the dialog for new projects and start typing “maven” in the search box

Select the maven project item from the list and click Next.
This page lets you determine where the project will reside. Leave the defaults, but make sure the “Create simple project” option is unchecked and click Next.
Here we will pick our archetype which in this case is our Knappsack jee6 minimal archetype. Start typing “knappsack” in the list and you will see the list of available Knappsack archetypes. Again, it is possible that the IDE’s index of the local repository is not up to date and needs a refresh. You will need to cancel the project creation window to do this.
1. Select Window->Show View->Other and in the view selection , start typing “Maven” until you see the window “Maven Repositories”. Select this to open up the view.
2. In the Maven Repositories view, expand the Local Repositories item and right click click on the Local Repository (pathname) item and select Rebuild Index. Confirm that you want to rebuild the index and wait a few moments.
3. Restart the project creation and this time you should see the archetypes you are looking for.
Select the archetype you want to create and click Next.
Now we need to enter the project configuration information, what our project is called, give it a group id, version and default package.

Once the above information is entered you can click Finish and Eclipse will work away at creating your project
To run the project, the easiest way is to install a server in Eclipse (see Tutorial on adding servers in Eclipse) and add the new project to the server. Start the server and navigate to your main page to see it in action.

Knappsack Archetypes Part 1

Andy Gibson — Sun, 01 Aug 2010 16:28:53 +0000

This set of articles will document the contents of the Java EE archetypes for Maven. The archetypes come in four flavors, basic,minimal, sandbox and sandbox demo with each one being based on the previous one. In part 1, we’ll give an overview of the archetypes and the structure and configuration used in all of the archetypes.

The Java EE 6 Archetypes

These Maven archetypes will help developers to get up and running with a new Java EE project quickly by creating the project structure that includes pre-defined configuration files. This lets developers create a project, remove parts they don’t need, and tweak those they want to keep. The balance is to provide something useful without burdening developers with a bunch of unwanted code and configuration. The basic and minimal archetypes serve this purpose. The basic archetype contains virtually no content, just configuration and a JSF page to confirm that it is working. The minimal archetype contains just a single page of content that demonstrates that JSF, JPA, CDI and validation are working. There are also two additional archetypes for servlet containers that can be used to run core features of Java EE 6 in a servlet contain such as Tomcat or Jetty.

The sandbox archetype takes things a bit further by adding a simple JPA model pre-populated with data. This gives developers a sandbox to play in with everything configured and data to use so they can test out ideas or play around with different pieces of Java EE. I also plan on using it as the foundation project for tutorials and articles on Java EE 6 that developers can follow along with. It removes the need to create and document creating a project with a data model and example data for each tutorial. With a pre-built tutorial project we can dive right in to the meat of the tutorial without the boilerplate.

The sandbox-demo archetype takes the sandbox application and extends it into a full featured application (albeit a contrived one) that demonstrates a number of features of Java EE 6, and gives developers an idea on how to get started developing applications using the Java EE stack. The demo is by no means perfect, it is mostly the bare minimum required to implement the necessary functionality. Again, it provides a good project to launch tutorials from by showing developers how to fix those little problems in the demo application. The demo also fills a gap in demonstrating to new developers how to work with these different technologies and integrate them.

These articles will cover the different archetypes and explain the functionality and features in each. We’ll start by covering the very basics, which is the creation of the project structure and configuration in the basic archetype which is also shared with all of the archetypes.

The jee6-basic-archetype

The basic archetype is a Maven project that is configured and ready to deploy in a Java EE 6 container. It contains the configuration files necessary to start up the Java EE services such as CDI, JPA and JSF as well as the dependencies in the pom.xml file.

In the root directory of the new project, we have the pom.xml file and a readme.txt which contains a description of the project and notes on how to deploy it.
The src/main/resources/ folder contains resources that the application may need. The META-INF sub folder contains the persistence.xml file which defines the JPA datasource name and sets properties for the JPA provider. If you are deploying to JBoss you are all set to go with the DefaultDS datasource, but for Glassfish, you will need to specify the jdbc/__default datasource instead which is commented out in the file, and remove the DefaultDS definition.

The main web content resides in the src\main\webapp folder which is structured as so :

Web folder structure and content

src/main/webapp			  Top level webapp folder
 |
 |-META-INF
 |    |-context.xml	 	  Configuration file for tomcat
 |
 |-resources			  Resources folder for JSF resources
 |  |-css			  CSS folder for stylesheets
 |     |
 |     |-screen.css	 	  Default stylesheet
 |
 |-WEB-INF			  Standard WEB-INF folder
 |   |-templates	   	  Templates folder for JSF templates
 |   |    |-template.xhtml     	  Default template file
 |   |
 |   |-beans.xml		  Indicates that this archive file has CDI beans
 |   |-faces-config.xml		  Configuration file for JSF
 |   |-web.xml			  web.xml file containing JSF configuration
 |
 |-home.xhtml			  Default home page using the WEB-INF\template\template.xhtml
 |-index.html			  Default file used to redirect to the home.jsf page

The beans.xml,faces-config.xml and the web.xml files have very little in them. The web.xml file provides the definition and mapping for the the faces servlet. The beans.xml is required to signal the container that this archive contains CDI beans and should be processed by the CDI deployer. This file could have other content if you use alternatives, decorators or interceptors.

Servlet Schema Version

The schema version for the web.xml defaults to 2.5 because of problems with Eclipse not recognizing the schema as valid when creating the project. For the most part, everything will work the same, but if it must be version 3.0 or later you can change once the project has been created without any problems.

Pretty much everything in the webapp folder can be used in a new application, and it isn’t that difficult to rename and move elements (templates, page file names etc) to get everything how you want it set up. In general, xml files shouldn’t be moved or renamed, but everything else can be.

If you are starting a new project, your first steps would be to move/rename/edit the template, home.xhtml and screen.css pages to your liking. You would also want to delete the readme.txt file.

The bulk of the content is in the pom.xml file which specifies all the depencies the project uses, most of which have the scope of provided since we anticipate the server providing the dependencies.

All of the archetypes also contain some code for producing an EntityManager in the application using a Stateless EJB implementing a Local interface, and a CDI qualifier to specifying injection points for the entity manager produced.

DataRepository.java – Qualifier for the EntityManager instance.
DataRepositoryProducer.java – Stateless EJB that produces the EntityManager
DataRepositoryProducerLocal.java – Local interface for the stateless EJB

Technically, the Local interface shouldn’t be needed under EJB 3.1 which is part of Java EE 6, however Weld, the reference implementation of CDI has problems with EJBs without a local interface in that it cannot locate them. To see how to use the produced EntityManager, see the next part which covers the minimal archetype that has a small JPA data model.

This about wraps it up for configuration, there is very little added to the core project that you probably won’t need for a JSF/CDI/JPA application making the basic archetype a good choice for a new project where you don’t need the smoke tests to see if everything is setup and working.

Next time we’ll look at the minimal archetype in detail which contains somewhat more code and functionality to test that JSF/CDI/JPA is working as planned.

Accessing and Paginating CSV Files with DataValve

Andy Gibson — Wed, 28 Jul 2010 17:07:30 +0000

Prerequisites

Install Maven
Installing DataValve Into Maven

While DataValve is mostly used with database driven back ends, this tutorial shows you how DataValve can turn a comma delimited file into a paginated list of objects that the user can page through. We will then use this data provider in a console application, a Swing application and a JSF web page using the DataValve data client interfaces.

We will start by writing this tutorial as a console application and then demonstrate how the data provider can be used in other applications, even web applications. We’ll start by creating a new Maven application and then include the dependencies for DataValve. We’ll then create our comma delimited data provider, define a row mapper class for it, and hook it up to our demo data. We’ll then attach it to a dataset so we can easily iterate through the data. We will then take our provider and use it in different clients.

Create a new Maven application in your IDE and add datavalve-dataset as a dependency in your pom.xml file.
```
	
		
			org.fluttercode.datavalve
			datavalve-dataset
			0.9.0.CR2
		
	
```
Create a new class called Person in the package of your choice. I used org.fluttercode.tutorials.datavalve.csvreader We will only be using one package in this demonstration.

The Person class will be our model which will be populated from the comma delimited file.

public class Person {

	private Integer id;
	private String firstName;
	private String middleName;
	private String lastName;
	private Date dob;
	private String email;
	private String address;
	private String city;
	private String zip;

	public Person() {
	}

	public Person(Integer id, String firstName, String lastName,String middleName,
			Date dob, String email, String address,
			String city, String zip) {
		super();
		this.id = id;
		this.firstName = firstName;
		this.middleName = middleName;
		this.lastName = lastName;
		this.email = email;
		this.dob = dob;
		this.address = address;
		this.city = city;
		this.zip = zip;
	}

	public String getName() {
		return firstName + " " + lastName;
	}

	public String getAddressText() {
		return address+ "," + city+","+zip;
	}

	@Override
	public String toString() {
		return String.format("Person [id=%d, name=%s, dob=%s,address=%s, email=%s",
		    id,getName(),dob,getAddressText(),email);
	}

    .... Getters and Setters Omitted ....
}

In order to convert the csv data to an object, we need to create a ColumnarRowMapper instance. This takes a row of data, already converted to an array of string values, builds the model object from it and returns it back to the caller. Create a new class called PersonRowMapper.

public class PersonRowMapper implements ColumnarRowMapper {

    private static SimpleDateFormat converter = new SimpleDateFormat(
			"MM/dd/yyyy");

	public Person mapRow(String[] values) {
		Date dob = null;

		try {
			dob = converter.parse(values[5]);
		} catch (ParseException e) {
		}

		return new Person(DataConverter.getInteger(values[0]), values[1],
				values[2], values[3], dob, values[4], values[6], values[7],
				values[8]);
	}
}

This row mapper implements the ColumnarRowMapper interface and implements the single method to return a built entity object from the array of column values passed in.

The only other element we need is some test data to run it on which you can download from here. Download this file and place it in the package folder with your source code. Depending on your IDE, you may need to refresh the folder in the package explorer so it can pick up the new file in the folder. The example file has 100 rows of data in it.
Create a new class called ProviderFactory which will create our provider and initialize it with the CSV file url.
```
public class ProviderFactory {

	public static CommaDelimitedProvider createProvider() {
		URL url = ProviderFactory.class.getResource("data.csv");
		CommaDelimitedProvider provider;
		provider = new CommaDelimitedProvider(url.getFile());
		provider.setRowMapper(new PersonRowMapper());
		return provider;
	}
}
```
We use a URL to reference the csv file stored in the jar from which we get a File instance that we can pass to our CommaDelimitedProvider. This relies on the data.csv file being in the same location as this class. Alternatively, you can put the file elsewhere and just create a regular File object to it rather than use the URL.

For the console part of this demo, create a Main class and add a main method containing the code get an instance of the provider, and perform a simple iteration through the data.

public class Main {

	public static void main(String[] args) {
		CommaDelimitedProvider provider;

		provider= ProviderFactory.createProvider();

		List results = provider.fetchResults(new DefaultPaginator());
		for (Person p : results) {
			System.out.println(p);
		}
	}
}

In this example we are reading all the results at once in memory and displaying the whole list.

Paginating the results

We can control which results and how many are displayed by using a paginator to control the flow of data. This can be useful if you have a huge file and it would be impractical to read all the results into memory in one go. Datasets have paginators built in and use a reference to a provider to fetch the actual data.

In the main method, instead of using the provider directly, create a dataset and pass it a reference to our data provider.
```
public static void main(String[] args) {
	CommaDelimitedProvider provider;

	provider = ProviderFactory.createProvider();

	CommaDelimitedDataset ds = new CommaDelimitedDataset(provider);
	ds.setMaxRows(10);
	List results = ds.getResultList();
	for (Person p : results) {
		System.out.println(p);
	}
}
```
We have set the maximum number of rows to 10 so the results returned only contains 10 rows of data at most. We can use this mechanism to control the number of results fetched if they are paginated.
The dataset classes implement the Iterable interface which lets us iterate over the entire set of data. By setting the page size, we can control the batch sizes when the data is fetched in while it is being iterated over. This allows us to control the flow of data, either to reduce the in-memory realization of the source data, or to reduce latency in an otherwise slow data source as the application can process one page of data while the provider is loading the next page of data.
```
public static void main(String[] args)  {
	CommaDelimitedProvider provider;
	provider = ProviderFactory.createProvider();

	CommaDelimitedDataset ds = new CommaDelimitedDataset(provider);
	ds.setMaxRows(5);
	for (Person p : ds) {
		System.out.println(p);
	}
}
```

You can see this process in action by extending the comma delimited data provider as an anonymous class and adding logging to the post fetch methods. We do this by modifying the ProviderFactory.createProvider() method :

public static CommaDelimitedProvider createProvider() {
	URL url = Main.class.getResource("data.csv");
	CommaDelimitedProvider provider = new CommaDelimitedProvider(url.getFile()) {
		@Override
		protected List doPostFetchResults(List results,
				Paginator paginator) {
			int end = paginator.getFirstResult()+paginator.getMaxRows();
			System.out.println("Fetching results from "+paginator.getFirstResult()+" to "+end);
			return results;
		}
	};
	provider.setRowMapper(new PersonRowMapper());
	return provider;
}

If you run this now, with the max rows set to 5, in you will see in that log that we iterate through all the records, but we only fetch the results every 5 rows since the max results is set to 5.

Fetching results from 0 to 5
Person [id=6825, name=JUANITA LAMBERT, address=139 MANNING HWY,CLYO,76604, email=mbeasley@everyma1l.biz
Person [id=5740, name=GREG CABRERA, address=736 GENESSEE BLVD,CORDELE,17433, email=cholder@b1zmail.biz
Person [id=8599, name=ALISSA WISE, address=205 ALICE RD,CAMILLA,14855, email=theyweb@eyec0de.net
Person [id=9282, name=SHARON WINTERS, address=955 COHEN PIKE,TYRONE,811, email=jlogan@hotma1l.com
Person [id=2150, name=KRISTY FRANKS, address=1471 ALEXIS PKWY,BALDWIN,85, email=jgates3@somema1l.com
Fetching results from 5 to 10
Person [id=9927, name=JEFF RICE, address=104 DUNDEE PKWY,HOGANSVILLE,3741, email=diedlots@b1zmail.org
Person [id=7972, name=TAMARA BRYANT, address=1382 WOGAN BLVD,CITY OF CALHOUN,43790, email=hotworn@everyma1l.us
Person [id=5824, name=ALISHA YANG, address=716 HOGANS DR,HARDING,58932, email=foundwrong@hotma1l.net
Person [id=3402, name=JASON NGUYEN, address=527 MICHAEL CRES,FORT STEWART,14664, email=haveothers@ma1l2u.com
Person [id=3620, name=LINDSEY CABRERA, address=1420 LAZELERE HTS,FORT STEWART,21650, email=askeddreams@b1zmail.com
Fetching results from 10 to 15
Person [id=3511, name=ANTHONY MATHEWS, address=1325 OKEY LN,THUNDERBOLT,63656, email=cfarrell@everyma1l.co.uk
Person [id=572, name=JARED FORD, address=722 EUCLID RD,FORSYTH,42014, email=ortrying@b1zmail.co.uk
Person [id=9720, name=AUTUMN WILLIAMS, address=260 HILL PARK,NORCROSS,58355, email=roomwhere@hotma1l.net
Person [id=3447, name=MARION BROWN, address=739 MIDDLE PATH,MACON,9944, email=hwagner@b1zmail.co.uk
Person [id=9356, name=HOPE HAYNES, address=1023 COOPERRIDERS CRES,STATENVILLE,34247, email=sacrificeit@eyec0de.com
Fetching results from 15 to 20
Person [id=2259, name=JEANNIE RANDOLPH, address=672 EDISON PATH,CENTERVILLE,48580, email=wornto@eyec0de.net
Person [id=8264, name=RACHAEL CONLEY, address=1223 STEVENS CT,CARROLLTON,40084, email=smokewhite20@eyec0de.net

Creating a Swing Client

DataValve provides an interface for data access that can be used by different clients. Lets look at using our provider with a Swing JTable.

Start by creating a new class that will be the Swing frame that contains the table and the scroll pane.

public class CsvTableFrame extends JFrame {

	private JTable table;
	private JScrollPane pane;

	public CsvTableFrame(CommaDelimitedProvider provider) {
		initControls();
		initModel(provider);
	}

        //here we will create the table model and attach the provider
	private void initModel(CommaDelimitedProvider provider) {
	}

        //construct the gui table and scrollable panel
 	private void initControls() {
		setTitle("CSV Data");
		setSize(400, 400);
		setDefaultCloseOperation(EXIT_ON_CLOSE);
		setVisible(true);

		table = new JTable();
		pane = new JScrollPane(table);
		table.setAutoResizeMode(JTable.AUTO_RESIZE_OFF);
		getContentPane().add(pane);
	}
}

This will setup the display for showing a frame with a scrollable table in it.

Now we need to implement the initModel method which will create a ProviderTableModel and attach the provider passed in. The table model class enables us to present our data to the Swing table in a way it understands. The ProviderTableModel implements a method which supplies column values to the model from the data supplied by the provider. The columns are defined in the latter half of the method and determines the order used to supply data to the table for each column.

        //here we will create the table model and attach the provider
	private void initModel(CommaDelimitedProvider provider) {
		ProviderTableModel model = new ProviderTableModel(
				provider) {

			@Override
			protected Object getColumnValue(Person person, int column) {
				switch (column) {
				case 0:
					return person.getId();
				case 1:
					return person.getName();
				case 2:
					return person.getEmail();
				case 3:
					return person.getAddressText();
				default:
					throw new RuntimeException(
							"Unexpected column for person object " + column);
				}
			}
		};

		//add the columns to the model
		model.addColumn("Id");
		model.addColumn("Name");
		model.addColumn("Email");
		model.addColumn("Address");

		//assign this model to the table
		table.setModel(model);
	}

The last piece we need to change is in the main method where we will create our provider and then pass it into the creation of our Swing frame.
```
public static void main(String[] args) {

	CommaDelimitedProvider provider;

	provider = ProviderFactory.createProvider();

	new CsvTableFrame(provider);

}
```
Creating the CsvTableFrame initializes and shows the Swing window.
If we run this now, we will get a Swing Window which contains a table with our data in it.

The model controls the flow of the data and even includes built-in caching and look-ahead loading so no matter how big your CSV dataset is, there is no long delay while the data is loaded and converted to Java objects. In this case, we pass only the provider to the model and the model is responsible for how much data is fetched in each batch.

If you look in the log as you scroll down the list, you will see that it is loading in the data as you scroll. If you go to the end of the list, and start slowly scrolling back up, you won’t see any more loading messages until you get to the top of the list. This is because the values are cached, but if you have a large dataset, the least recently used items (i.e. those at the top of the table) are removed from the cache and therefore need re-loading when you go back to the start of the list.

Creating a JSF Client

The DataValve API allows us to re-use providers with many different clients which we’ll demonstrate with JSF.

Start by creating a new JSF web application, or use the Knappsack Archetypes for Maven to get started quickly. Use the basic archetype so there is no existing application in there or alternative Person objects to clash with.

Add the datavalve-dataset API and the datavalve-faces dependencies to the project,

		
			org.fluttercode.datavalve
			datavalve-dataset
			0.9.0.CR2
		
		
			org.fluttercode.datavalve
			datavalve-faces
			0.9.0.CR2

For convenience, copy the ProviderFactory.java,Person.java and PersonRowMapper.java classes over to the new project.

Create a new class called that will be our backing bean that will hold the dataset the JSF page will go against.

@Named("csvDataset")
@RequestScoped
public class CsvDatasetBean {

	CommaDelimitedDataset dataset =
	     new CommaDelimitedDataset(ProviderFactory.createProvider());

	public CsvDatasetBean() {
		//initialize the dataset settings
		dataset.setMaxRows(10);
	}

	public CommaDelimitedDataset getDataset() {
		return dataset;
	}
}

Now we have created the backing bean pieces, open home.xhtml to edit it, and replace the hello world text with the following :
```
	
		
			
				ID
				
			

			
				Name
				
			

			
				Email
				
			

		
		
			
		
	
```
This page contains a table that takes the results from #{csvDataset.dataset.resultList} and displays the id, name and email fields. The last item wrapped in a form is the datavalve-faces default paginator which allows to you scroll across the data. This is provided as part of datavalve-faces and the namespace is added at the top of the page. With JSF 2.0 including support for AJAX, you can have AJAX enabled pagination by setting the attributes on the component.

Summary

This tutorial has shown how to consume csv files in a way that is re-usable across different client applications using DataValve. Alternatively, if you change the implementation of ProviderFactory.createProvider to return a different type of provider (i.e. JDBC, ORM, Hibernate) as long is it returns the same kind of Person object, your code will run unchanged in the clients you create. Given the simplicity of the DataValve interfaces, it is not hard to see how easy it is to create providers for other file types whether they be text or binary based.

Introducing DataValve

Andy Gibson — Tue, 27 Jul 2010 14:05:07 +0000

DataValve is a free open source library that facilitates the creation of re-usable view and data access components as well as providing a number of features for pagination, sorting and parameterizing queries. This article defines the problems DataValve aims to solve and how it solves them.

The need for DataValve

Most data driven applications have a need for displaying data that is organized into pages. Whether it is search results or sales reports, dumping a complete set of data results into a web page or a Swing grid is sooner or later going to run into problems as the datasets grow larger.

Visual web frameworks such as Wicket or JSF usually have some components that facilitate pagination and most data access frameworks such as JDBC, Hibernate or JPA have facilities to access results in a paginated manner. Typically however, you need to write your own code to bridge the gap between the view and the data access mechanism. If you write your own glue code you will probably need to re-write it again and again if you want to re-use the back end code with a different view layer or change the data access mechanism.

Applications With DataValve

Exotic Data Sources

There may even be times when you have a sudden request to provide paginated data access to more exotic data sources such as XML, CSV, and binary files, even pulling data from a web service. In such a scenario not only do you have to write most of the pagination yourself, but again, your view layer will need some work to handle the new data access mechanism. This also includes paginated access to in-memory data that is regularly used, but changes rarely and is cached in memory.

Most of you are probably thinking that this isn’t a big problem because you write layered code with an interface that can have different implementations. You are right, logical organization of code can help with all these problems, however, at the end of the day, you still have to write something that integrates with the new datasource in the same way as the old datasource in the implementation.

If you are thinking that you will never need to change your view layer or data providers, there are still some problems you might want to consider that DataValve can help with.

Dynamic Querying

One common feature in data driven applications is to query a set of data using parameters with the ability to exclude query clauses where the parameter is not set. If you are searching for people, why filter by address if the user didn’t enter an address? The solutions to get around this problem involve either building the query at run time and ignoring restrictions with missing parameter values or accommodating the potentially null parameter in the query itself which makes it look ugly and can harm performance.

Ordering data safely

Another problem is the abstraction of the ordering of data, especially with web applications. You don’t want to store the actual SQL columns used for sorting data on the web page in case of SQL injection attacks. The best way is to use a key that maps to how you want the data ordered . You would also have to allow for ascending and descending ordering.

Parameterizing queries

Dynamic queries should be parameterized to allow variables in the query to be set in a safe manner as opposed to changing the query text which can again lead to SQL injection attacks. Typically though most parameters have to be set manually and many times we add new parameters and forget to set them. The process of adding and assigning parameters can require lengthy boilerplate code. DataValve offers vastly improved parameter handling for queries.

How DataValve solves all these problems

DataValve works by using a well defined interface to access and paginate data that comes from a data provider. There are different data providers for each kind of data source (JDBC,ORM,Hibernate,File based) and you can even write your own using an interface with just 2 methods. Because we have a well defined interface to the data, we can create components for the view to connect to that interface. Since we are coupled to the interface only, we can change the implementation and as long as it returns the same kind of entity objects, our view code remains unchanged. The view doesn’t care whether the list of Person entities comes from a database, an XML file, a web service or an in-memory list. When the dataset is connected up to a different view layer, it is coupled to the same interface and accesses the data in the same defined way.

Here’s a quick example of how we create a data provider and paginate the results.

DataProvider provider = new SomeDataProvider();
Paginator paginator = new DefaultPaginator();
paginator.setMaxRows(10);
pagiantor.setFirstResult(15);
List results = provider.fetchResults(paginator);
for (Person p : results) {
  //do something with the 10 Person objects from 15-25
}

We can also use a Dataset that is a stateful combination of a Paginator and a data provider reference.

DataProvider provider = new SomeDataProvider();
ObjectDataset dataset = new DataProviderDataset(provider);
dataset.setMaxRows(10);
dataset.setFirstResult(35);
List results = dataset.getResults();
for (Person p : results) {
...some code...
}

Each time we call getResults() on the dataset, it will return the same list of results until we move to another page of results or manually invalidate the result set. Every time you call fetchResults on a data provider the list of results is re-fetched each time. The Dataset also implements the iterator interface so you could iterate over the whole set of data and it would go through each row, but load them in batches as sized by the paginator.

Queried Results

Let’s load a result set that uses some filtering and sorting.

QueryProvider provider = new JpaDataProvider(em);
QueryDataset dataset = new QueryDataset(provider);

provider.setSelectStatement("select p from Person p");
provider.setCountStatement("select count(p) from Person p");

//we can also access the provider using
// dataset.getProvider()

//add simple restriction
provider.addRestriction("p.department.id = 4");

List results = dataset.getResultList();
for (Person p : results) {
    System.out.println(p.getName());
}

Alternatively, we could specify the parameters using :

//:param is a magic value for this method call only
provider.addRestriction("p.firstName = :param",someFirstName);

//alternatively

provider.addRestriction("p.firstName = :aFirstName");
provider.addParameter("aFirstName",someFirstName);

A few things to note here. The second method of using a parameter requires two method calls, but you can change the parameter value later on prior to execution and if aFirstName is null, then the restriction won’t be included in the executed final query. Typically, restrictions are excluded at the time of query execution, but if you use the first syntax, the restriction is left out immediately if the value is null since you are setting the parameter as a constant and if the value is null, then it will always be null.

Here are some alternative ways of defining parameters, all of which are subject to the rule that if the parameter is null, then the restriction isn’t added. All these examples can be used with either Hibernate, JPA or JDBC data providers with the only changes being the query specification and the field names in the restrictions.

  //WRONG - if first name is null, then the param value is 'null%' and will be added
  provider.addRestriction("p.firstName like :param",criteria.firstName+"%");

  //CORRECT - this checks one value, but assigns another to the actual parameter
  provider.addRestriction("p.firstName like :param",criteria.firstName,criteria.firstName+"%");

This is really useful where we want to use one value for the null check, but assign another value to the actual parameter so we can use ’starts-with’ in searches by adding a wildcard on the end.

  provider.addRestriction("p.department.id = 4");
  provider.addRestriction("or p.managerFlag = 1");

All restrictions are joined together with “AND”s unless they actually start with a logical operator. Parenthesis can be introduced into the query, but care must be taken that opening or closing parentheses would not be removed in the event of a null parameter.

If you are using JSF or some other EL enabled environment, you can also use EL expressions directly in the queries as long as you attach an ELParameterResolver to the provider.

  provider.addRestriction("p.firstName = #{criteria.firstName}");
  provider.addRestriction("p.lastName = #{criteria.lastName}");

Again, if these expressions evaluate to null then the restriction is not used. This makes it really easy to create a search criteria bean that hooks up to the JSF front end and back end without any additional glue code.

Parameter Resolvers

DataValve has a concept of parameter resolvers that can be used on any data provider that implements the ParameterizedDataset interface. Parameter resolvers are like plugins that provide parameter resolution through code. The ReflectionParameterResolver uses reflection to find parameter values where the property name is the same as the parameter name.

provider.addRestriction("p.firstName like :firstName");
provider.addRestriction("p.lastName like :lastName");
provider.addParameterResolver(new ReflectionParameterResolver(criteria));

Our criteria object has first and last name properties that are used to resolve the parameter values in the restrictions. Again, if the values resolve to null, the restriction is not used when the query is executed.

Also, multiple parameter resolvers can be attached to a provider so you could use an EL parameter resolver and a reflection parameter resolver. This can be useful for mixing it up if you have multiple sources for parameters. You can also combine different combinations of adding restrictions.

provider.addRestriction("p.firstName like :firstName");
provider.addRestriction("p.lastName like :lastName");
provider.addRestriction("p.salesRep.id = #{currentUser.id}");
provider.addRestriction("p.dept.id = ",selectedDepartment.getId());
provider.addParameterResolver(new ReflectionParameterResolver(criteria));
provider.addParameterResolver(new ElParameterResolver());

Ordering Results

Configuring the order is simple, we add the order key values and associate information with each key to indicates how the ordering is executed which in most cases, it is the list of fields we use to order.

provider.getOrderKeyMap().put("name","p.lastName,p.firstName");
provider.getOrderKeyMap().put("age","p.dateOfBirth");
provider.getOrderKeyMap().put("id","p.id");

To order data when we fetch it from the provider, we need to assign a key order value on the paginator used to fetch the data from the provider.

Paginator paginator = new DefaultPaginator();
paginator.setOrderKey("name"); //order by the persons name
paginator.setOrderAscending(false);
List orderedList = provider.fetchResults(paginator);

If you are using a dataset, you can just set the orderKey and orderAscending properties on the dataset instead. These key values can be embedded in your web page and passed back to the server side components without having to worry about SQL injection. If the order key is not recognized as one of the available values in the order key map then no order is used and no SQL is injected.

State management

Paginators and data providers are separate instances while object datasets are made up of a paginator with a data provider reference that keeps a hold of the most recent set of results. The reason for this is so you can modify the degree of statelessness used.

You can make the whole thing stateless with the paginator info being passed between the client and the server. With Wicket, Seam, CDI and Spring Web Flow you might want to keep the paginator state on the server side but keep refreshing the results each time you postback. This can be done by keeping it in a Conversation, a Spring web flow, or a Wicket page. If you want to go fully stateful, you can use the Dataset which includes the paginator and the data provider and caches the recent resultset and put it in a Wicket page, a conversation or a page flow. By default, the JSF Components for paginating a DataValve result set is stateless.

Client Side

Briefly, lets look at the options for creating clients for DataValve datasets. There are components for a simple JSF paginator and a sortable column header for JSF 2.0 in the datavalve-faces module, and a SortableDataProvider for Wicket. For Swing, there is a special TableModel that caches and pre-emptively loads data for display in a Swing JTable. This means you can easily navigate thousands of rows of data in a Swing Table without having a long initial load time or taking up a lot of memory for object storage.

In the DataValve download there are demos for each of these examples in projects that are easy to run using the Jetty plugin for Maven so no server is required. The Wicket demo even demonstrates how different pieces of server side code can be reused with JDBC, CSV and Hibernate driven data providers.

Get Started

In addition to the DataValve project page you can see the documentation in HTML, Single HTML, or PDF. The download includes source that can be built and installed with maven as well as pre-built binaries.