A Generic CRUD Facade for your @Entity Beans

CRUD (create-read-update-delete) is a repetitive code in
Java EE projects but it can be isolated in a unique class
through the usage of JPA annotations and Generics - a class I call CRUDEntityFacade.
This is not a new pattern and the goal of this blog entry is just to
prepare you to read my next entries about JAXB and JPA together. I am
doing really nice things with Jersey and Glassfish, and before exposing
complicated inventions I decided to register the basics of the
persistence layer (also very nice for my own future reference).

Complete sample projects

The code I am publishing here is just to avoid you to checkout a
full project and to dig to inspect my CRUD strategy. But if you want to
see this technique in action, please be my guest to checkout one of my
open-source projects. The projects are built by Maven and were created
in Eclipse - but you should be able to run it on your preferred IDE
without any problems. Both projects require minimum Java 6.

• Example #1: the href='https://footprint.dev.java.net/'>Footprint project, what
  includes a RESTful service coded with the Jersey framework. Subversion
  checkout:

  svn checkout
  	https://footprint.dev.java.net/svn/footprint/trunk footprint --username
  	username

• Example #2: the href='https://cejug-classifieds.dev.java.net/'>Cejug-Classifieds
  project, a WSDL first web-service coded with the JAX-WS framework. Subversion
  checkout:

  svn checkout
  	https://cejug-classifieds.dev.java.net/svn/cejug-classifieds/trunk
  	cejug-classifieds --username username

The generic CRUD implemented with generics and JPA annotations

1. Defining the persistence interface containing the persistence
   operations we want to share among the entities. Note that I
   replicated the runtime exceptions because it is an interface and we
   expect interfaces to be the most documented and self-understandable
   artifacts in our project.

   public interface FootprintEntityFacade<T extends
   		AbstractFootprintEntity> {
   	T <strong>create</strong>(T entity) throws EntityExistsException, IllegalStateException,
   			IllegalArgumentException, TransactionRequiredException;
   
   	T <strong>read</strong>(Serializable primaryKey) throws IllegalStateException,
   			IllegalArgumentException;
   
   	T <strong>update</strong>(T entity) throws IllegalStateException,
   			IllegalArgumentException, TransactionRequiredException;
   
   	void <strong>delete</strong>O(T entity) throws IllegalStateException,
   			IllegalArgumentException, TransactionRequiredException,
   			PersistenceException;
   }

2. To define a superclass of all entities. This is an important
   step, since we want to use generics we must have a unique type to pass
   in our interface implementation. The mapped superclass is also useful
   to share the ID attribute.

   @MappedSuperclass
   public abstract class AbstractFootprintEntity implements Serializable {
   	@Transient public static final long serialVersionUID = 196919661993L;
   
   	@Id
   	@GeneratedValue(strategy = GenerationType.AUTO)
   	private long id;
   
   	<font color='gray'>// getters & setters</font>
   }

3. Then we need some entities. I will use an example of the
   Footprint entity that represents Events (JUG meetings, courses or conferences).

   @Entity
   public class FpEvent extends AbstractFootprintEntity {
   	@Transient private static final long serialVersionUID = 196919661993L;
   
   	@Column(nullable = false)
   	private String name;
   
   	@Column(nullable = true)
   	private String website;
   
   	@Version
   	private long updatedTime;
   	
   	<font color='gray'>// getters & setters</font>
   }
   	

4. Now an important step, the realization of our generic CRUD
   interface to our Event Entity. In theory this empty interface is not
   necessary, but my experiments proved that this is the best way to
   go. It opens a chance for the customization of the persistence
   interface and - the main reason - it avoids conflicts between different
   entity instances using a same interface. You will have 1 empty interface
   for each Entity in your project, an oddity I couldn't get rid off - if you
   know how to avoid it, please tell me.

   @Local
   public interface EventFacadeLocal extends FootprintEntityFacade&lt;<strong>FpEvent</strong>&gt; {
   }
   	

5. Now we just need to implement the CRUD. A special note about the
   empty constructor, that uses reflection to get the class of the generic
   type - this is the hidden trick that makes the magic possible.

   @Stateless
   public class CRUDEntityFacade<T extends AbstractFootprintEntity> implements FootprintEntityFacade<T> {
   
   	private transient final Class<T> entityClass;
   
   	@SuppressWarnings("unchecked")
   	public CRUDEntityFacade() {
   		entityClass = (Class<T>) ((java.lang.reflect.ParameterizedType) this
   				.getClass().getGenericSuperclass()).getActualTypeArguments()[0];
   	}
   
   	@PersistenceContext(name = "footprint")
   	protected transient EntityManager manager;
   
   	public T create(final T entity) throws EntityExistsException,
   			IllegalStateException, IllegalArgumentException,
   			TransactionRequiredException {
   		manager.persist(entity);
   		manager.flush();
   		return entity;
   	}
   
   	public T read(final Serializable primaryKey) throws IllegalStateException,
   			IllegalArgumentException {
   		return manager.find(entityClass, primaryKey);
   	}
   
   	public T update(final T entity) throws IllegalStateException,
   			IllegalArgumentException, TransactionRequiredException {
   		manager.merge(entity);
   		manager.flush();
   		return entity;
   	}
   
   	public void delete(final T entity) throws IllegalStateException,
   			IllegalArgumentException, TransactionRequiredException,
   			PersistenceException {
   		manager.remove(entity);
   		manager.flush();
   	}
   }
   	

6. Now we need to create a concrete implementation of the facade interface. Again an empty type, where you can add your customs methods if any. You will never instantiate this type manually, but it will be used by the generics mechanism to have different types for different facades.

   @Stateless
   public class EventFacade extends CRUDEntityFacade<FpEvent> implements
   		EventFacadeLocal {
   }
   	

7. It is done, now we can persist any entity of the type
   AbstractFootprintEntity (remember to create the empty sub-interface for
   each new entity you want to persist). Below you find an example of the
   CRUD usage in a Jersey resource:

   @Path("/event")
   public class EventResource {
   	@EJB
   	private <strong>EventFacadeLocal</strong> eventFacade;
   
   	@Produces( { MediaType.APPLICATION_XML })
   	@Consumes(MediaType.APPLICATION_XML)
   	@POST
   	@Path("/test2")
   	public FpEvent postJAXBElement(FpEvent e) {
   		return eventFacade.<strong>create</strong>(e);
   	}
   }

In my next entries I will show you how to use dual annotation
(JAXB + JPA) in order to minimize the impedance mismatch between the
persistence layer and the serialization of element used in the services
endpoints - REST or SOAP.