Andy Gibson » JPA

Deterring “ToMany” Relationships in JPA models

Andy Gibson — Mon, 17 Jan 2011 13:50:38 +0000

This article considers the issues of one to many relationships from the JPA model, and looks at an alternative strategy to provide more efficient and fine grained data access, to build more robust and lightweight applications and web services.

A fairly typical use is to have one entity ‘owned’ by the other in such a way that one entity is said to ‘have’ many instances of the other one. A typical example would be customer and orders :

class Customer {

  @OneToMany(mappedBy="customer")
  private Set orders;

}

class Order {
  @ManyToOne
  private Customer customer;
}

In this trivial example, the order belongs to a customer, and the customer has a set of orders. We don’t have a problem with the ManyToOne relationship, especially as it is required in order to map the order back to the customer. When we load an order we will at most get a single reference to a customer.

No, our problem is with the value we get from customer.getOrders() as this set of order entities doesn’t really serve any useful purpose and can cause more problems than it solves for the following reasons :

Dumb Relationship – It will contain every order for this particular customer when you usually only want a subset of the orders that match a set of criteria. You either have to read them all and filter the ones you don’t want manually (which is what SQL is for) or you end up having to make a call to a method to get the specific entities you are interested in.
Unbounded dataset – How many orders a customer has could vary and you could end up with a customer with thousands of orders. Combined with accidental eager fetching and loading a simple list of 10 people could mean loading thousands of entities.
Unsecured Access – Sometimes we may want to restrict the items visible to the user based on their security rights. By making it available as a property controlled by JPA we lose that ability or have to implement it further down in the application stack.
No Pagination – Similar to the unbounded dataset, you end up throwing the whole list into the pagination components and letting them sort out what to display. In most cases, you need to treat each dataset like it will eventually contain more than 30 records so you really need to consider pagination early.
Overgrown object graph – When you request an entity, how much of the object graph do you need? How do you know which pieces to initialize so you can avoid LIEs? This is often the case with JPA, but is also more relevant when you take account of the needs to serialize object graphs to XML or JSON. Sometimes you might need the relationships and sometimes you do not depending on the context you will be using the data in.
Rife with pitfalls – Who saves and cascades what and how do you bind one to the other? You create an order, and assign the customer, do you need to then add it to the customers list of orders or not. What happens if you forget to add it to the customer and you save the customer? Whatever strategy you pick for dealing with this will no doubt end up being implemented inconsistently.

(Ok, the first four are really different facets of the same problem, that you can’t control the data you are getting back.)

So what use are they? Well, they make it really tempting just to use customer.orders in the view which is suitable for some sets of data. They also allow the relationship to be used in ejbql statements, although the inverse of the relationship can also be used in most cases. Specifying this relationship can also allow you to cascade updates/deletes from the customer to the order, but then so can your database.

Going Granular

The best alternative I’ve found is to provide additional methods to obtain the relational information separate from the model. This more granular approach gives you plenty of ways of obtaining data from the database without the dangers and temptations of bad practices. For example, the Order object still has the Customer reference on it, which we use to obtain lists of orders from the data access layer which can be constrained by customer, time frame, or other criteria depending on where it is being used. Also, it allows data to be fetched when needed without having to define a single initialization strategy using annotations or mapping files. The code that knows what pieces of data it needs will have access to facilities to fetch the specific data it needs. Alternatively, the methods to fetch the data can either be exposed as web services directly or DTO objects can be used to build a data payload to be returned from a single web service that consolidates the calls. Regardless, you don’t need to worry about setting the JPA fetch or XML/JSON serialization policy permanently in the model.

Some examples might be to fetch orders for a customer in different ways.

public List getOrders(Long customerId) {...}
public List getOrders(Long customerId,Date startDate,Date endDate) {...}
public List getOrders(SearchCriteria searchCriteria,int firstResult,int pageSize) {...}

What about `@ManyToMany`

Good question. In most cases I find that what starts as a many to many relationship can usually be modeled as a separate entity because when you create a many to many relationship, there is usually additional information stored with that relationship. For example, a Users and Groups ManyToMany relationship has many users belonging to many groups and vice versa. The membership however also probably has start and end dates and also maybe a role within that group. This also exhibits one of the earlier problems in that user.getGroupMemberships() would return all group memberships past and present whereas you probably only want the active ones. Modeling it as a separate entity means it becomes an entity with two OneToMany relationships.

While there are cases where the many to many relationship is literally just a pair of ids (think blog post tags, many tags to many posts), you could benefit at a later date by using an entity if you decide to add additional information into the relationship.

In summary, moving relational fetches out of the data model and into the data layer means you remove some of the temptations of bad practices and create a library of reusable functions for fetching the data that can be used from different code points.

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.

Demo Application Using JSF, JPA, CDI with Jetty

Andy Gibson — Tue, 24 Aug 2010 13:51:50 +0000

The previous version of the Knappsack Maven Archetypes included archetypes for creating projects using JSF, JPA, CDI and Bean Validation that can run in a servlet container such as Jetty or Tomcat. In order to put it through its paces I decided to create a little test social bookmarking application that lets users create accounts, and when logged in, add bookmarks and tag them. Users that are not logged in can view the bookmarks and filter them by user or tag, and the results are paginated.

The demo application is now included in the latest version of the Knappsack archetypes (1.0.5) which are in the central repository. The GAV information is :

org.fluttercode.knappsack
jee6-servlet-demo-archetype
1.0.5

Or you can just create a new application from the command line with :

mvn archetype:generate -DarchetypeGroupId=org.fluttercode.knappsack -DarchetypeArtifactId=jee6-servlet-demo-archetype -DinteractiveMode=false -DarchetypeVersion=1.0.5 -DgroupId=org.application -DartifactId=bookmarxrus -Dpackage=org.application

This lets you create a new instance of the demo application from the archetype so you can play with it (and break it!).

Alternatively, if you just want to poke around, you can just download the projects maven source from here (Bookmarking Java EE 6 Servlet Demo) , unzip it and use mvn jetty:run to start the app with the embedded Jetty instance and go to http://localhost:8080/bookmarxrus/.

The demo comes with pre-built data and a list of users, tags and URLs to get started with.

Try Java EE 6 without the commitment

Andy Gibson — Thu, 12 Aug 2010 15:24:22 +0000

The latest version of the Knappsack Maven Archetypes now supports creating Java EE 6 applications for servlet containers. These projects includes configuration for core Java EE 6 technologies such as JSF, CDI, JPA and Bean Validation and can be run from the command line using the embedded Jetty and Tomcat servlet containers.

Also with this latest release, all the archetypes are available in the Central Maven Repository which means you can dive straight in and create a new Maven project using these archetypes :

In the command line, or in a script file, issue the following :

mvn archetype:generate -DarchetypeGroupId=org.fluttercode.knappsack -DarchetypeArtifactId=jee6-servlet-minimal-archetype -DinteractiveMode=false -DarchetypeVersion=1.0.4 -DgroupId=org.application -DartifactId=servletminimal -Dpackage=org.application

This will create the new project based on the java ee 6 minimal servlet archetype.

Go into the directory using cd servletminimal
In the project directory, issue the command mvn clean jetty:run
Navigate to http://localhost:8080/servletminimal/
Tinker away with it

Knappsack Archetypes Part 2

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

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

The Java EE 6 Minimal Archetype

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

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

Layered code

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

Producing Entity Managers

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

Service Beans

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

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

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

JPA Model

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

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

JSF Content

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

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

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

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

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

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

Using the app for yourself

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

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

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

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

Knappsack Archetypes are now in the Maven Central Repository

Andy Gibson — Thu, 12 Aug 2010 14:48:20 +0000

I have finally got around to putting the Mavan Java EE 6 Archetypes into the Maven Central Repository. This means you no longer have to manually download and install the Archetypes, they should be available for you to use out of the box. In some cases, depending on how you are creating your projects, you may need to refresh or update your Repository indexes in the IDE before they are visible.

In Eclipse (with m2Eclipse installed), you open the Maven Repositories view, locate the Central Repository in the global repositories, and right click and select update index to make the archetypes available.

To create a new project from the command line, you can copy the following command into a script or batch file and edit it to setup your own group and archetype values.

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

The new version includes the archetypes for creating Java EE 6 applications in servlet containers which lets you play around with CDI, JSF, JPA, validation and other JEE 6 technologies using an embedded servlet container from the command line.

Knappsack Archetypes Part 1

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

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

The Java EE 6 Archetypes

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

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

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

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

The jee6-basic-archetype

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

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

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

Web folder structure and content

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

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

Servlet Schema Version

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

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

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

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

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

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

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

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

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

FlutterCode.com released

Andy Gibson — Tue, 29 Jun 2010 02:48:18 +0000

I’ve been fairly quiet over the last couple of months as I’ve been working on a few items, working on a new site and working on getting two new Open Source projects final and out the door.

I’ve renamed Spigot to DataValve, and moved it to the new site FlutterCode.com which will also host my other project called Knappsack which is a set of Maven archetypes for Java EE 6.

The new site will be home to most of my tutorials, articles and other writings, as well as possibly some screencasts and even podcasts. It will in essence be a pure java development site. This blog will go a bit quieter and contain less development stuff, although most opinion will get put out here instead of over there. I’ll also be copying some of my tutorials over there from this blog.

I’m aiming to create a fairly cohesive tutorial site, aided in part by the Maven Archetypes which will give me a firm base onto which I can build tutorials without having to start from scratch, but one archetype is a sandbox Java EE 6 app with project configuration, a demo model and some test data. The sandbox app will let developers create a new skeleton java EE 6 application they can play with. Building on that, there is a sandbox-demo application which as an archetype that creates a full working demo CRUD application using Java EE 6 so developers can see how all the different pieces of Java EE 6 go together. It includes features such as conversations, JPA CRUD, page parameters, CDI injection and events.

Again, I have to say it, but Open Source is Hard. In the past couple of months, I have been working on a whole new site, getting 2 projects ready to roll with documentation and site content to boot as well as working a job, and having some kind of life.

Now it’s out, I can start to focus a little more on getting some more Java EE 6 tutorials and articles out.

A Guide to Spigot For Seam Developers

Andy Gibson — Tue, 06 Apr 2010 17:00:57 +0000

Note : Spigot has been renamed to DataValve.

(Edit : I renamed this post so it doesn’t seem like Spigot is just for Seam, Spigot can be used with different frameworks or without any at all. However, I wrote this post since Spigot is so familiar to the Seam EntityQuery that it should be easy for Seam users to get the idea)

Seam developers should become familiar with Spigot concepts fairly quickly since they are very similar to those found in the Seam EntityQuery which was one of the main inspirations for the framework. If you imagine taking the entity query class and splitting it in two, one part to keep hold of state and the other to actually fetch the data. The stateful part is the Paginator that keeps track of what the current ordering of the data is, what is the current page and how big the pages are. The stateless part takes the Ejbql and the pagination information and returns a subset of the data. Now imaging that the data provider has the JPA pieces taken out and replaced with an abstract fetchResults method. This method is implemented in subclasses for specific data providers for text files, sql queries, jpa queries, native jpa queries, xml files, comma delimited or just an in memory dataset.

I also abstracted the concepts of parameterization and parameter resolution so you can have parameters on data providers that are no t query based and your parameters can be resolved using different mechanisms such as EL, reflection, a map, or using custom parameter resolution.
So really, for Seam developers, its like a Seam EntityQuery that doesn’t just use JPA, but uses any kind of data source you want but still returns just a list of objects.

Spigot works nicely with CDI and there is even a demo of it in the distribution that uses JSF and was generated using the Weld maven archetypes. Also, there is a Seam Jpa Dataset Adapter that you can use as a direct replacement for the EntityQuery which will adapt the entity query calls to the underlying data provider calls so you can have a seam-less transition if you want to switch over. This is still a little in-progress, but works. The one area that isn’t implemented is the sorting, which may not be possible, but I still need to add in the methods to the adapter even if they don’t do anything. The other issue is of course the configuration of the query from components.xml using the Seam Framework tags. However, you can define the query using regular component xml tags to define the Ejbql, restrictions and page sizes.

Two things to note if you start using Spigot in place of the entity query. All rows are returned by default, and you need to specify both a select statement and a count statement. I separated those two out so you can put join fetch phrases in the select statement without it breaking the count statement. There is an init method that you can use to set both of these statements for a class type.

Spigot 0.9.CR1 released

Andy Gibson — Tue, 06 Apr 2010 13:07:55 +0000

Note : Spigot has been renamed to DataValve and is hosted over on FlutterCode.com.

It’s been a while since I’ve posted anything new as I’ve been busy with a new Open Source software project called Spigot. It’s a java library that sits between your application code and your data sources (Hibernate, JPA, JDBC or any arbitrary source of data) and helps with things like pagination and sorting using a common interface so you can switch out data providers and use alternatives.

For query language data providers, Spigot also facilitates excluding restrictions from WHERE clauses when parameters are resolved to null. Parameters are handled using parameter resolvers so there is more than one way to parameterize the query including EL expressions, reflection or a value map on the data provider.

Spigot also provides a few other add-ins like converting any dataset into an in-memory dataset that can itself be paginated and sorted and shared across an application (such as commonly used data in a web application). The IndexedDataProviderCache can give you random access into a dataset with caching and look ahead loading. This lets you hook a dataset with thousands of rows up to a Swing JTable with an instant response and a very small memory footprint since it doesn’t need to load all the objects at once as the provider will load the records as needed and cache the results. This is demonstrated in the Swing Demo in the download. There are also demos for Wicket and CDI with JSF.

You can ready about why I created Spigot in the documentation

Spigot is currently hosted on Project Kenai, where you can download the release, view documentation online or read about 10 ways Spigot helps developers.