Andy Gibson » Tutorials

Simple RESTful services in Glassfish Pt 2

Andy Gibson — Mon, 21 Mar 2011 12:39:13 +0000

In part 2 of this article, we are going to create a data driven web service that will return JSON and XML to the client, and then use jQuery to add a new item to the database and display it in our page.

In part 1, we looked at creating simple web services and now we’re going to look at making something more practical and interesting. We’ll start from where we left off with the source code as it was at the end of the part 1 which you can download from here (restwebdemo_pt1) if you want to follow along. If not, the final source can be downloaded from here (restwebdemo_pt2).

First off, we’re going to change the entity manager that is available for injection to be request scoped. To do this, open up DataRepositoryProducer.java and change the @ConversationScoped annotation on the getEntityManager() method to be @RequestScoped. The reason for this is documented here in A Little Less Conversation.

Next we are going to create a simple dao for Course objects, and the only reason to do this is to demonstrate the integration of CDI and the ability to layer your code. Create a new class called CourseDao with the following code.

package org.fluttercode.restwebdemo.bean;

@Stateless
@LocalBean
public class CourseDao {

	@Inject @DataRepository
	private EntityManager entityManager;

	public void save(Course course) {
		entityManager.persist(course);
	}

	public Course update(Course course) {
		return entityManager.merge(course);
	}

	public Course find(Long id) {
		return entityManager.find(Course.class, id);
	}
}

This just injects an entityManager and uses it to locate, save and update Course objects.

Now create a new CourseService bean that will handle the web services. To start with we want to make it a stateless EJB and inject the course Dao. We are going start by re-implementing the method to return the course name for the given id.
```
	@Path("courseName/{id}")
	@GET
	public String getCourseName(@PathParam("id") Long id) {
		Course course = courseDao.find(id);
		if (course == null) {
			return "Course not found";
		} else {
			return course.getTitle();
		}
	}
```

To see this method in action, deploy the application and go to http://localhost:8080/restwebdemo/rest/course/courseName/126. Now we know everything is working and hooked up together, we can look at adding some new functionality.

Let’s start by returning a course with a given id from the service. This is fairly simple given what we already know. The only thing to determine now is what format to return the object as and to convert it to that type. Luckily, Java EE already provides JAXB which can take an object graph and convert it to XML for us as long as we annotate the classes with the annotations to let the JAXB implementation know how to convert it. The same annotations can be used by the body writer that handles JSON.

First we’ll annotate the Course class and make a couple of changes that we need to. Next we’ll create methods to return a Cource object from the service in XML or JSON format.

Open the Course class and add the following annotations to the class.
```
@Entity
@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public class Course extends BaseEntity {
   ...
   ...
}
```
This tells the JAXB processor that this class can be serialized and to access the values using fields in the class. This also means that any other annotations we want to add to control the serialization needs to be applied to the fields.

This is a simple example, so we don’t want to serialize the teacher or enrolled properties which we can do by marking them with the @XmlTransient attributes. Also, remove the @NotNull annotation from the teacher attribute as we will need it blank later. The following code shows the fields with both the JAXB and JPA annotations. JAXB (like JPA) uses default conventions for fields that don’t have annotations :

	@Column(length = 32, nullable = false)
	@Size(max = 32)
	@NotEmpty(message = "title is required")
	private String title;

	@Column(length = 8, nullable = false)
	@Size(max = 8  )
	@NotEmpty(message = "code is required")
	private String code;

	@ManyToOne(fetch = FetchType.LAZY)
	@XmlTransient
	private Teacher teacher;

	@ManyToMany(mappedBy = "enrolled")
	@XmlTransient
	private List students = new ArrayList();

We are just using a simple JAXB model for the sake of the example which is why we aren’t including the Teacher and Student classes.

Now in our CourseService class we will create methods to return the course entity and we will create one for JSON and one for XML.

	@Path("find/{id}/xml")
	@GET
	@Produces(MediaType.APPLICATION_XML)
	public Course getCourseAsXml(@PathParam("id") Long id) {
		return courseDao.find(id);
	}

	@Path("find/{id}/json")
	@GET
	@Produces(MediaType.APPLICATION_JSON)
	public Course getCourseAsJson(@PathParam("id") Long id) {
		return courseDao.find(id);
	}

(note : At this point, I had to switch to using Hibernate as the JPA provider since JAXB didn’t like the interface EclipseLink used for proxying the properties. You can do this using the Glassfish update tool).
If you redeploy the application and browse to http://localhost:8080/restwebdemo/rest/course/find/1/json you should be prompted to save a file, or it will display the text, but the content should be something like :

{"createdOn":"2010-08-27T16:36:57.015-04:00",
  "id":"1",
  "modifiedOn":"2010-08-27T16:36:57.015-04:00",
  "title":"Computing for Beginners",
   "code":"CS101"}

or if you go to http://localhost:8080/restwebdemo/rest/course/find/1/xml you will get an XML version :



	2010-08-27T16:36:57.015-04:00
	1
	2010-08-27T16:36:57.015-04:00
	Computing for Beginners
	CS101

Now we can grab objects from our web service, we should look at creating objects from the service. We add a new method that takes the title and code values, creates a new Course with those values and saves it using the courseDao.

	@Path("create")
	@PUT
	@Produces(MediaType.APPLICATION_JSON)
	public Course createCourse(@FormParam("title") String title,@FormParam("code") String code) {
		Course course = new Course();
		course.setTitle(title);
		course.setCode(code);
		courseDao.save(course);
		return course;
	}

Here I’ve used the FormParam annotations to plug form values into the method call. You’ll notice that using REST conventions, the method to create a course uses the PUT type of request. Now let’s create a page to enter a title and code and create the course. Notice that our method returns the created course so we can return the course back to the user. This is probably not ideal, but suits for the purposes of demonstration. Now lets create a new HTML page to allow for data entry and calling the web service to create the Course.



Insert title here



Message Div


    
    	Create Course
    	
	        Title

    	    

    	
    	
        	Code

This looks a lot code, but not really. We import jquery to help us post our form, and we create our form with the two fields. We use JQuery to add an event handler so when you click submit, it packages up the form, calls our web service with a PUT type of request and grabs the returned object as a JSON object, and displays a message using the values from the new instance obtained from the server. To verify that your course has been created, go to the front page and you should see it listed.

That about wraps it up for this post, the source code can be downloaded from (restwebdemo_pt2), just unzip it, use mvn clean package and deploy the war to glassfish and use the URLs mentioned in the article.

Binding Dynamic Multi-select Checkboxes with JSF

Andy Gibson — Wed, 27 Oct 2010 13:17:06 +0000

This tutorial looks at how JSF makes it easy to create a dynamic list of checkboxes that can be used to select values on the server.

Given a list of strings, we want to display the list of values, each with a check box and be able to select or deselect that item from inclusion in the selected set. We want to do it without having to manually add each checkbox to the page and bind it to a property on the backing bean.

JSF controls can be bound to a value in a map using the syntax #{some.map['someKey']} where someKey can also be an EL expression. This means we can bind a checkbox to a Boolean value in the map. If we have an iterable list of of key values, we can bind multiple checkboxes to different values in a map.

Create a new backing bean called FormBean with the following code :

public class FormBean {

	private List items;

	private Map checkMap = new HashMap();

	public FormBean() {
		items = new ArrayList();
		items.add("Open");
		items.add("Closed");
		items.add("Pending");
		items.add("Suspended");
		items.add("In Progress");
		items.add("Rejected");

		//fill the check map with the items defaulted to unchecked
		for (String item : items) {
			checkMap.put(item,Boolean.FALSE);
		}
	}

	public List getItems() {
		return items;
	}

	public Map getCheckMap() {
		return checkMap;
	}

}

This creates our list of items and populates it with a set of values. The checkMap will be used to track which items are selected and which are not. The map contains a set of String,Boolean pairs.

Add one more method to return a string telling us which items are selected

	public String getSelected() {
		String result = "";
		for (Entry entry : checkMap.entrySet()) {
			if (entry.getValue()) {
				result = result + ", "+entry.getKey();
			}
		}
		return result.length() == 0 ? "" : result.sub string(2);
	}

To get the list of selected items, we iterate through the set of entries and if the value in the map is true, then it is selected and added to the result string.

Our backing bean is complete, now we will create our view
```
	

	
		
		
	

	
```
We iterate through the list of items and for each one, display the caption (the item itself) and a checkbox bound to the Boolean checkMap entry for that item.

Unfortunately, we can’t iterate through the keySet because JSF doesn’t provide for iteration over Sets (next version JSF Expert Group!) so we have to use a separate list as our key. However, this is a nice way of providing a dynamic set of checkbox controls that are bound to dynamic values without having to use any tricks to keep track of control bindings.

If you want to make the list update when you click an item, just add the f:ajax tag to the checkbox like so :

You can download the working code for this example (JsfCheckMap Demo Source Code) which you can run by unzipping it and in a command line running mvn jetty:run or windows users can just double click run.bat.

Releasing Maven Projects with Git(Hub) in Windows

Andy Gibson — Wed, 06 Oct 2010 12:38:12 +0000

In the process of moving some new and existing projects to GitHub and releasing them using Maven under Windows, I discovered a number of issues that can be tricky to get around. This post is for anyone else with the same problems, and for my own future reference.

First off, most of these issues are Windows related and while I would love to move to Linux and be rid of these problems, its impractical at the moment. Also, if you are a non-Windows user you can still get an idea of what is needed to deploy GitHub projects with Maven.

To avoid a disappointing end to the post, the one problem I couldn’t resolve was releasing multi-module projects with maven. I am still getting the StringIndexOutOfBounds error with msysgit. These instructions are still good for single module deployments though. If anyone has a solution to the string index issue, feel free to post in the comments or drop me a line.

My go to page for remembering how to do release a project with Maven is the Sonatype instructions which covers setting up a Sonatype account and tells you what you need to put in your pom.xml file for it to be released automatically.

If you have done maven releases before with subversion, you will know how easy it is. Once the SCM information is in your pom file, Maven will download the source, tag it to the version you select, commit the tag, build it, and deploy it which is really quite nice as well as updating your development code to the new snapshot version.
If you haven’t done a Maven release before, you will need to set up a PGP key on your machine and post it on a key server (see the Sonatype instructions for more info and links that help).

So at this point, lets assume you have a project ready for release in GitHub (or any other Git repository I guess). You have a PGP key set up on your local machine and added to a public key server. Windows users should also have mSysGit set up, which you probably have if you are developing with Git. Your project should also have the release and deployment information set up as defined in the Sonatype document.

I’ve seen a number of different ways of putting the SCM information in the pom file. Here’s what I used that worked for me. Obviously you’ll need to change the account name.


   scm:git:git://github.com/andygibson/${project.artifactId}.git
   http://github.com/andygibson/${project.artifactId}   scm:git:git@github.com:andygibson/${project.artifactId}.git

Interestingly enough, when I was looking to see what other people were using, there are plenty of projects that still have subversion repositories in their scm information. I guess they probably haven’t changed it over yet because they haven’t done a release.

Roadblocks

There are two main problems that you will hit when releasing with Maven under Windows. The first is that when Maven tries to push the changes back to the Git repository it hangs waiting for the pass phrase for your GitHub SSH key. However, since it never displays a prompt for it, you are stuck waiting for it.

The second problem is exposing your pgp keys to your Git Bash shell. The shell expects the keys to be in a particular folder which doesn’t exist by default (/c/.gnugp).

Setting up SSH-Agent

Start up the Git Bash session (or as OSX and Linux users call it, a shell) and go to your project directory.
Windows users, you need to start up an SSH agent to provide your passkey when needed by the release process.

To do this, in your Git Shell type :

eval `ssh-agent`  //pay attention to the back tick quotes here

which should return a piece of text like Agent pid xyz. This command starts the agent and sets up a couple of environment variables relating to the SSH agent. If you type env | grep SSH you will see the environment variables :

$ env | grep SSH
SSH_AGENT_PID=1234
SSH_AUTH_SOCK=/tmp/ssh-abcdef1234/agent.5678

Windows users will need to manually create the directory c:/tmp/ssh-abcdef1234/agent.5678 otherwise you get and error saying could not open a connection to your authentication agent.
Create the new directory and then add your key to the agent using the following syntax which assumes your Github RSA key is in the c:\.ssh\ directory. If it isn’t then just substitute the directory for your key.

$ssh-add "/c/.ssh/id_rsa"
enter passphrase :

Once you enter the pass phrase, it will be stored for that particular key for the rest of the session. When Git requires the phrase as part of the release it will automatically receive it from the agent.

Note that this set up is only good for the current session. If you open another session and want to do a release in that session, you will need to repeat these steps. I also think it would be a bad idea (or at least pointless) to set up the SSH_AGENT_PID or the SSH_AUTH_SOCK environment variables in any global variables.

So now we have that set up, you should be able to run the mvn release:prepare part of the release. This will grab the source code, update the pom version and push the changes back to the repository.

Exposing your PGP keys

For the next step, (mvn release:perform) we need to do the actual release which involves building the artifacts, signing them and uploading them. I’m assuming that you already have a project and environment that is correctly configured for release (including the release servers in settings.xml). If not, again, take a look at the Sonatype instructions for info on this.

The problem we’ll encounter here is that when signing the artifacts, the maven gpg signing plugin can’t find the keys from the Git Shell. It is looking in the /c/..gnupg directory while the windows version of gpg puts it in the users Application Data folder in their profile. There are two ways to solve this problem, and both involve locating the directory containing the Gnugpg keys. This folder is likely to be My Documents\Application Data\ which happens to be a hidden folder for many and varies in location depending on the version of windows. However, in that folder is the gnupg folder that contains your keys. The other piece of the puzzle is the GNUPGHOME environment variable in both Windows and Bash which points to the folder containing the keys.

You can either move the windows folder to where the Bash shell expects it, and set the Windows environment variable to point to it which means that if you fix it now, it will be fixed for every session. Windows GPG will find the folder through the GNUPGHOME environment variable and Bash will find it because that is the default place it looks for it.

Alternatively, you can leave the folder alone and set the environment variable in the Git shell to point to the key folder where it is. The only problem with this is that the environment variable will need to be set up each time. However, it leaves the rest of your environment alone.

I guess the third option is if you don’t have a GPG key already set up and are using the Git shell to generate one, you might have to manually create the /c/.gnupg folder manually.

I wanted to move the folder anyway so I went for option one. The choice is up to you, but if you get a message like :

gpg: no default secret key:secret key not available
pgp: signing failed: secret key not available

Its because Gnupg can’t locate the keys you (should have) already set up.

Once I got that these two problems fixed things went fairly smoothly, well, very smoothly in fact, it just worked. Now, hopefully you won’t have the same problems I had!

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.

Conversational CRUD in Java EE 6

Andy Gibson — Mon, 30 Aug 2010 13:07:33 +0000

This tutorial will demonstrate a pattern for creating CRUD applications in JSF and Java EE 6. While this is not the only way of implementing this mechanism, it does promote re-use and can give you essentially zero code CRUD pages requiring just the view code. The goal is to provide a single structure that provides the particular feature of being both stateless or conversational where we might want a conversational edit page and a stateless view page. This pattern is based on the EntityHome pattern that was used in JBoss Seam and carries over well to Java EE 6 with CDI. This is something I use all the time to make view/edit pages really quickly and unlike most of the automatic scaffolding in other frameworks, doesn’t need re-writing to go into production.

Running in a Servlet Container

If you are running this in a servlet container or embedded Jetty, you will need to make the following changes :

Use the jee6-servlet-sandbox archetype which is only available in Knappsack 1.0.5 upwards.
Remove the @Stateless annotations from the EntityManagerDao
Add manual transactions to the entity manager method calls

The servlet version of the source code for this project can be downloaded from here (Crud App Maven Project Zip). Just unzip and type mvn jetty:run

CRUD is an initialism for Create, Retrieve, Update, Delete and is applied typically to entity objects or pieces of data in our application. CRUD probably accounts for about 80% of functions in most systems where users enter, update, view and sometimes delete data.

An entity object starts out by being created and then saved to the database. At a later date, the user may want to view the data and then modify and update the data. When the entity is no longer needed, the data will be deleted. This is the long term lifecycle of our data. When an entity is saved, it is saved with a key, or some reference value used to refer to that entity uniquely. Typically, this is an ID field that is often a number. The ID is assigned to the entity when it is saved and used to identify the entity when we want to retrieve, update or delete the entity.

Create our Application

We’ll start by creating a new application using the Knappsack Maven Archetypes. We’ll use the jee6-sandbox-archetype so we have some data to play with. Because the Knappsack archetypes are fairly new, you might have problems finding them in your IDEs depending on when you updated from Maven Central, so here is the command line to create the project :

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

You can create the app and then import it into your IDE as needed. We are going to start by creating a very simple DAO style bean that will be used to load, save and refresh objects using the JPA entity manager. We will make it a stateless session bean so that it has transactional capabilities. If you are using the servlet container version, see the sidebar above for necessary changes. The downloadable source code uses the servlet container version so you can run it without an application server.

Create a new class called EntityManagerDao

Put the following code in the bean

package org.fluttercode.demo.crudapp.bean;

import javax.ejb.Stateless;
import javax.inject.Inject;
import javax.persistence.EntityManager;
import java.io.Serializable;

import org.fluttercode.demo.crudapp.qualifier.DataRepository;

@Stateless
public class EntityManagerDao implements Serializable {

	@Inject
	@DataRepository
	private EntityManager entityManager;

	public Object updateObject(Object object) {
		return entityManager.merge(object);
	}

	public void createObject(Object object) {
		entityManager.persist(object);
	}

	public void refresh(Object object) {
		entityManager.refresh(object);
	}

	public  T find(Class clazz, Long id) {
		return entityManager.find(clazz, id);
	}

	public void deleteObject(Object object) {
		entityManager.remove(object);
	}

}

We inject a conversational entity manager into the bean and create methods for create, finding, updating, and removing entities. The DataRepository annotation is a Qualifier that is defined by the archetype and used to access the application’s default data source.
All this bean really does is provide transaction support on our method calls to the entity manager. It is not a part of the key pattern, just a mechanism we can use to persist objects transactionally. While this Dao will work for any JPA entity, it is common practice to create Dao objects specific to individual types where you can add helper and additional methods specific to that type.

Our home bean

Now we have our support code set up, on to the main feature! We will create a generic home bean that will take an Id and when requested, load the entity bean for that Id. If no Id is available, then we assume a new entity is to be created. Once loaded or created, the entity will be accessible from our JSF pages where we can display or edit the information.

Create a new class called org.fluttercode.demo.crudapp.bean.HomeBean. This will be our generic home bean that we use to load and hold our entities.

Add the following code to make the bean generic and give it an id and entity attribute.

package org.fluttercode.demo.crudapp.bean;

import java.io.Serializable;
import javax.inject.Inject;
import org.fluttercode.demo.crudapp.model.BaseEntity;

public class HomeBean implements Serializable {

	@Inject
	private EntityManagerDao entityManagerDao;

	private Long id;
	private T instance;
}

Our bean will use the injected EntityManagerDao we just created. The BaseEntity class is a base entity class implemented in the archetype and has the common Id attribute.

Now we want to add the getter method for the instance. What we want to do here is lazy load or create the bean when it is needed. The assumption is that you won’t request the bean until the home bean has been set up i.e. The id is properly set. The second assumption is that if you request the instance without the Id being set, you are actually creating a new instance.

We’ll implement this in the getter that calls two other methods, one to create and return a new entity and another to load it. We’ll also add the getters and setters for the Id.

public T getInstance() {
	if (instance == null) {
		if (id != null) {
			instance = loadInstance();
		} else {
			instance = createInstance();
		}
	}
	return instance;
}

public Long getId() {
	return id;
}
public void setId(Long id) {
	this.id = id;
}

The create or load methods are fairly simply but rely on some reflection magic to get the generic parameter type :

public T loadInstance() {
	return entityManagerDao.find(getClassType(), getId());
}

public T createInstance() {
	try {
		return getClassType().newInstance();
	} catch (Exception e) {
		e.printStackTrace();
	}
	return null;
}

private Class getClassType() {
	ParameterizedType parameterizedType = (ParameterizedType) getClass()
			.getGenericSuperclass();
	return (Class) parameterizedType.getActualTypeArguments()[0];
}

When we edit our entity, we will want to either save the changes, or undo them. We will add two methods to do this, save and cancel and a third utility method called isManaged().
```
public boolean isManaged() {
  return getInstance().getId() != null;
}
public String save() {
	if (isManaged()) {
		entityManagerDao.updateObject(getInstance());
	} else {
		entityManagerDao.createObject(getInstance());
	}
	conversation.end();
	return "saved";
}

public String cancel() {
	conversation.end();
	return "cancelled";
}
```
We end the conversation when we are done with the data which is when we either save or cancel the changes. Once the conversation is ended, it will be destroyed at the end of the request.
One last method we want to add is called initConversation that checks to see if we are in a long running conversation, and starts one if we are not. In theory we could put this method anywhere, but here is a good a place as any. We also need to add a Conversation attribute into which we will inject the current conversation.
```
  	@Inject
  	private Conversation conversation;
  	...
  	...
  	...
	public void initConversation() {
		if (conversation.isTransient()) {
			conversation.begin();
		}
	}
```

This wraps up the coding of our HomeBean that we will use as the backing bean for CRUD pages. Now let’s try out our new bean by implementing it for our Student entity class and create a page to view and edit our students.

Start by creating a new class called org.fluttercode.demo.crudapp.view.StudentHome. We add two class level annotations, one to name the bean so JSF can access it through an EL expression and another to give it a scope.
```
package org.fluttercode.demo.crudapp.view;

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

import org.fluttercode.demo.crudapp.bean.HomeBean;
import org.fluttercode.demo.crudapp.model.Student;

@Named
@ConversationScoped
public class StudentHome extends HomeBean{

}
```
We subclass the HomeBean and give it our Student class type to tell it what kind of entity we want it to handle. We have given this bean a conversation scope for reasons we’ll see later.
For our view, create a new page called studentView.xhtml with the following content :
```
	
		
			
		
		
			
			

			
			

			
			

			
			

			
			
		
	
```
Everything up to the f:metadata tag is boilerplate which includes pulling the template into the page. The f:metadata tag tells JSF to take a parameter called id and put it in the studentHome.id attribute. This is done before the page is rendered as part of our initial setup for the bean so we know which entity to load.

In the view code we bind our text output components to attributes on the instance in the student home bean. We also styled the components so we can alter the display using CSS styles.
At the bottom we have added a couple of links using the new JSF 2.0 h:link component to an as yet unwritten JSF page called studentEdit.xhtml. In the first link, we get JSF to pass in the view parameters automatically which in this case is the student Id value. Our second link is to create a new student which means we call the same studentEdit.xhtml page without passing the id as a parameter which we do by leavinging the includeViewParams attribute set to false.

Note that the h:form tag isn’t necessary, but will make the next step easier and allow us to add form controls to this form should we want to.
If you are running JBoss Developer Tools or Netbeans, you should be able to see the Student attributes in the auto-completion (very cool). If you open this page in a browser with an id (http://localhost:8080/crudapp/studentView.jsf?id=3) you will see the following person displayed :

We did change two of the archetype CSS styles in the file screen.css to the following :
```
.caption {
	float: left;
	width: 100px;
	padding-top : 2px;
}

.value {
	display : block;
	margin-bottom : 8px;
	margin-right: 8px;
}
```

As you can see, we can display the student details for the given id. The page for editing this person is very similar, so similar in fact that we are going to start by copying the student view page and making 3 line changes and adding a page event.

Copy the studentView.xhtml file and paste it in the same folder with the name studentEdit.xhtml. Open it up and make the following changes (highlighted in the source) :
- Change the outputText components bound to attributes to inputText components.
- Add the preRenderView event the the f:metadata tag.
- Set the rendered attribute on the ID label and value since new entities don’t have a value to display
```
	
		
		
	
	
		
		

		
		

		
		

		
		

		
		
		
	
```
If you launch this page now (http://localhost:8080/crudapp/studentEdit.jsf?id=3), you will see that we have an editor filled with the attribute values that can be changed.

That was pretty easy! The reason being is that we re-used the StudentHome bean in our edit page because it performs the same role in providing the requested entity based on the bean’s id value. We don’t need to tell the home bean that it is being used somewhere else because the page pulls the bean into the page.

Conversational or Not?

It’s important to notice that in the view page we do not call the method to initialize the conversation. Conversational beans that are not in a long running conversation are reduced to request scoped because the conversation context is destroyed at the end of the request if it is not marked as long running. This means that our view page is fairly stateless since the StudentHome bean used in this page is effectively request scoped. This is actually a good thing since when we press the refresh button, the page is regenerated from scratch instead of using an older version of the data held in the conversation.

On the other hand, the edit page does call the initConverstion method which starts a conversation. This means that the edit page is conversational which is good because it carries the state from one request to the next without relying on our page to support that state or having to reload it each time. Without the conversation we would have to manually propagate the id value from one request to the next, and possibly other values that are a part of the entity but not edited on the page. For example, if we had an addedDate attribute, we might want to display it, but not edit it, but without conversations we have to resort to either putting it in a hidden field in the form, or re-loading the object to get the value on postback. Otherwise how can we have the right value when we save the edited entity to the database?

This dual nature of the conversation scope is a very useful feature of CDI (and Seam before it) because it allows one bean to act in two different scopes depending on whether the conversation is long running or not which is ideal for view and edit pages.

This is a simple design that can be re-used anywhere you need to edit an entity with little or no code changes.

You can download the servlet version of the demo project from here (Crud App Maven Project Zip). Just unzip it and run mvn jetty:run

Additional Points

Here are some addition points that are not a core part of the demonstration but flesh things out a bit more. All these changes are included in the maven project that can be downloaded.

Do we need an Entity Manager DAO?

Here we used a simple DAO to wrap calls to the EntityManager. There’s no reason you couldn’t make your Entity Home bean an EJB, inject the entity manager and persist the entities directly. With a separate entity manager DAO it makes writing code for servlet containers cleaner since the explicit transactions are bundled in the DAO. Also, it is possible to write one DAO bean for Java EE 6 servers and another for Servlet containers and switch between them using @Alternative.

Deleting is a part of CRUD

I left deleting out primarily because it is fairly simple and the focus was really on the retrieve and update pieces which is often trickier. To implement delete, we add a method to the HomeBean to end the conversation and delete the item.

public String delete() {
	entityManagerDao.deleteObject(getInstance());
	conversation.end();
	return "deleted";
}

Now we just need to add a button to call the delete method from the edit page.

When we click the button, we delete the entity, and return the action value “deleted” for which, in the next section, we’ll add navigation to the home page.

Finding your way around

We haven’t included any navigation here so when you save or cancel changes, you stay on the same page. So far I’ve left it out because it isn’t central to the CRUDness of the tutorial. However, we can easily add some navigation in faces-config.xml.

	
		/studentEdit.xhtml
		
			saved
			/studentView.xhtml
			
		

		
			cancelled
			#{studentHome.managed}
			/studentView.xhtml
			
		

		
			cancelled
			#{!studentHome.managed}
			/home.xhtml
			
		

		
			deleted
			/home.xhtml

Notice that when we cancel the changes, we go to either the view page or the home page depending on whether the entity exists in the database.

Better Homes

Let’s also add on a better home page so you can see and select different students. Add the following method to the DataFactory.java class that comes with the archetype.

	@Produces
	@Named("students")
	public List getStudents() {
		List students = entityManager.createQuery(
				"select s from Student s").setMaxResults(20)
				.getResultList();
		return students;
	}

Open up the the home.xhtml page and change the content to :



	
		Courses
		
			
				
					Id
				
				#{v_student.id}
			

				
					Name

This will list all the students and let you edit them or add new ones. The project source that can be downloaded (Crud App Maven Project Zip) includes these changes plus validation error messages on controls.

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.

Installing the Knappsack Archetypes

Andy Gibson — Sun, 01 Aug 2010 16:43:42 +0000

This is a brief guide to downloading and installing the Knappsack Maven Archetypes for Java EE 6.

Updated – 12th August 2010

The archetypes are now in the Central Maven Repository so there is no need to manually install them.

Download the Knappsack Maven Archetypes from here
Unzip the downloaded file into a temporary directory
Open a command prompt and navigate to the directory you unzipped the archetypes to.
In the directory, type the command :
```
mvn clean install
```
The archetypes will then be installed and ready for creating new projects.

To learn more about the archetypes read this guide. To see all Knappsack related content, click here.

Once you have installed the Knappsack Maven Archetypes you can delete the original source since they have been compiled and installed into your Maven repository.

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.

Implementing User Selectable Themes In JSF

Andy Gibson — Wed, 28 Jul 2010 16:44:36 +0000

Prerequisites

Install Maven
Install the Knappsack Archetypes

Many web applications offer users the option to change the appearance of user interface. One of the easiest ways to implement this is by offering different page color schemes by selecting different css style sheets. This article describes how to implement themes in JSF using CDI backing beans that the user can select as their default theme.

Download project source

Each style sheet implements a different color scheme and when they user picks a theme, you simply have to provide the style sheet assigned to that theme. The application will be based on an existing archetype, so we’ll start by creating a new Maven application using the jee6-sandbox-demo-archetype.

As it is, the application has a stylesheet called screen.css which includes color information for the pages. We want to add another style sheet that overrides those color choices for the elements that we want to change per theme.

Of course, we could change much more css than the colors in the theme style sheet, we could change the layout and sizing information also, but the tradeoff is that the more content we put into the theme stylesheet, the more content we have to duplicate in each theme, and the more we have to change each time there is a minor change. We could resolve this problem by giving the user two different theming option, the first would select the layout stylesheet and the other would select the color stylesheet.

In the package explorer locate the bean package and right click on the package folder.
Select New->Class and in the class dialog, enter StyleBean as the name of the class

This bean will hold the value of the current theme name and return the style sheet name to our view. It will also hold the list of available style sheets.
We’ll start by annotating the bean with the @Named annotation so we can reference it from our JSF view pages and make the bean @SessionScoped so it will remember the settings between each request.
Since our bean is session scoped, it needs to be passivation capable which means adding the Serializable interface to the implements clause.
We add fields for the currently selected theme, and also a theme map which will contain the name of the themes and the stylesheet associated with it. Getters and setters for the theme have been omitted.

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

@Named("styleBean")
@SessionScoped
public class StyleBean implements Serializable {

	private String theme;

	private Map themeMap;

	public StyleBean() {
		themeMap = new LinkedHashMap();
		// read this list from the db or something
		themeMap.put("Default", "default.css");
		themeMap.put("Blue", "blue.css");
		themeMap.put("Green", "green.css");
	}

}

Because JSF cannot iterate over a Map or Set we need to convert the list of theme names into a List. We do this with another method that we annotate with the @Produces method to indicate that this produces values. We give it the name themes and make it application scoped so this will be produced only once per application.
```
	@Produces
	@Named("themes")
	@ApplicationScoped
	public List getThemes() {
		return new ArrayList(themeMap.keySet());
	}
```
We have one more method to implement and that is the method that returns the name of the CSS stylesheet for the selected theme. We do this by using our theme Map as a lookup to get the filename


	public String getThemeCss() {
		return themeMap.get(getTheme());
	}

If you get an error at this point you forgot to put in the getter/setters for the theme field.

Now we have put all our code together in one bean, given that bean a name so it can be referenced from JSF, and implemented the list of themes and converting themes to a CSS file name. It’s time to implement our options page that lists the themes available and lets the user select one.

Create a new JSF page called options.xhtml and paste in the following code :
```
	
		
			
				
					
						
					
				
				
			

		

	
```
Most of this code is boilerplate so I’ve highlighted the relevant parts. The list box that is wrapped by the property component, takes the list of themes from our themes producer and is bound to the theme property of our styleBean. When the user selects an item and clicks the Update button the theme property is set to the name of the selected theme.Since this is stateful, the new value holds across page requests so next time the page is rendered we can look at the themeCss property to get the file name of the css file for the selected theme.
To render the css style sheet we need to add it to the style sheets in the header. Open up the template.xhtml file and locate the line with . Underneath it, add a new line to include our user selected style sheet.
Now the only thing left is to create the additional stylesheets for our themes. In the src/main/webapp/resources/css/ folder create a new stylesheet called default.css but leave it blank.

Create a new stylesheet called blue.css with the following content :


body {
	background-color: #E0E0FF;
	color: #102040;
}

#header {
	background: #204080;
	color: #f0f0fF;
}

.panel {
	border: 1px solid #D0D0F0;
	background: #f0f0ff;
}

.panel h1 {
	background: #e0e0f0;
	border-bottom: solid 1px #D0D0F0;
	color: #102040;
}

.odd {
	background: #f0f0fF;
}

.even {
	background: #f7f7ff;
}

.dataTable th {
	background: #204080;
	color: #f0f0ff;
}

Add one more stylesheet called green.css with the following content :

body {
	background-color: #E0FFE0;
	color: #104020;
}

#header {
	background: #208040;
	color: #f0fFF0;
}

.panel {
	border: 1px solid #D0F0D0;
	background: #f0fff0;
}

.panel h1 {
	background: #e0f0e0;
	border-bottom: solid 1px #D0F0D0;
	color: #104020;
}

.odd {
	background: #f0fFf0;
}

.even {
	background: #f7fFf7;
}

.dataTable th {
	background: #208040;
	color: #f0fff0;
}

If you deploy the application now and go to the http://localhost:8080/jsfthemes/options.jsf you can pick a different theme,click update and the application will start rendering pages with the new themes.

Extending the Implementation

There are a number of ways we can improve this implementation, especially since we are keeping the list of styles and the selection information in a backing bean in the session. Chances are that the session already has some kind of User entity, and it would be a good idea to store the selected theme, or better yet, the name of the css file as part of the user profile. The list of themes is only needed when the user is on the options page and is only used to provide the list of themes and to convert from the theme name to the css file. It would be easy to re-implement these as request scoped elements once the state is moved to the user entity.