The first thing I did in Spring MVC was to write the perennial CRUD application. After I was done the code was fairly clean but still contained plenty of boilerplate java code. So I wanted to make it generic so I could churn out CRUD's for maintenance tables.

Goals:

1. Only write code that's specific to the Entity I am dealing with in the controller.
2. Make use of <Generics> so I don't have to cast stuff like a caveman from 1997.
3. Have spring figure out URI mapping based on controller names.
4. Write zero bean specific xml.

Anotomy of a CRUD Controller.
Your classic CRUD (Create Update Delete) Controller works with one domain type and needs to do a few things:

1. List items
2. Create items
3. Update items
4. Delete items

As far as controller methods go, you'll generally need to do a few things:

• Set up your backing domain object for your form on creations and edits
• Validate and save results from the form on submission.
• List items from your data store.

The Old Way

Let's look at how we'd accomplish listing items with Spring MVC.

So this method uses my dao to run a query. (Your DAO Service implementation will be different depending on how you access your database.)

It then takes the results of that query and throws it in the ModelMap. Recall the ModelMap is smart and will come up with the correct attribute name. So if selectAll returns a List of Employees it will be added to the model as employeeList. Great. Now we use the @RequestMapping annotation to set our URL mapping to employee/list.

The New Way

Let's look at how we could make this list method generic. We've got two things that explicitly reference our Employee domain object. The URL mapping and the .class we pass to our DAO service.

Solving the URL problem
If we define a generic list method in our abstract controller one option for configuring the specific url in the extending class would be something like this.

I don't like this method, it assumes the person implementing the super class will know that they must override the list method just to set a request mapping. A better method would be if Spring was able to infer the URL map from the implementing controller's class name. ControllerClassNameHandlerMapping to the rescue!

Spring's ControllerClassNameHandlerMapping will take a controller's class name and map it to a URL. I like to mix this with the SimpleUrlHandlerMapping to map views the same way.

Here's how I configure these beans:

So what all this means is that if someone requests: /department/list it will automatically map to a Controller called DepartmentController and the @RequestMapping annotated method called list. There's no need to define a URL mapping in our @RequestMapping annotation, we'll just define a request type instead.

Dynamic entity/domain class

There are many ways we can take care of the problem. The coolest way is to use some neat reflection tricks like so:

So now we have a generic list method:

Creating/Updating

The normal pattern for doing creating and updating in Spring MVC controllers consists of a few methods.

Methods to display the initial form:
These methods simply show the same form view.

I implemented them like this, we assume the view name from the Domain object (entity)'s name:

Now before the form is submitted we need to tell Spring to bind our form to a @ModelAttribute. This is the same as a FormBackingObject in classic Spring MVC.

The way it works is any method annotated with @ModelAttribute will be executed and the returned object bound to any matching forms in a view.

In this view I do one of two things. If we're going to be doing a create I return a new Domain object. This domain object may have some default values set to get initially bound in to the form. If we're doing an update I need to look up the Domain Object from the DAO Service.

Since our @ModelAttribute annotated method will be called on each request I need a way to tell if this is an update request or a create request. An easy way is just to check if our Primary Key parameter is set in the WebRequest.

Here's what a generic @ModelAttribute method looks like:

So we need another abstract method called getPkParam that returns the String representing the domain property that the Primary Key is stored in.
If on your database the primary key is always called "id" then you could certainly implement getPkParam to return "id" every time in the superclass.

So far we have implemented methods that do the following in our superclass: Forward a request to the correct form view and setup the model object to make it available for automatic binding in our view.

The next step is to define what happens when a form is submitted. When a form is submitted we'll have to do 2 things, weather and update or an insert we need to Validate the form and persist the Domain object to the database if validation passes.

Due to the @ModelAttribute annotation the model object will now be available in your view as {$crudObj}. Ideally we would make it available based on the type name so the view was more readable, but that's one of the limitations we have when using annotations is the inability to add dynamic values as parameters.

Let's look at a generic save method:

We have a new abstract method called getValidator(Object obj,BindingResult res) that will return the validator for your Domain class.

Implementation

We now have all the pieces in place.

Finished CrudController<T>

Now if I want to add another CRUD to my application I simply have to do the following:

Implement my abstract CrudController for the Domain class I want to edit. So let's say we wanted a department controller.

It's definition would look like this:

Next I'd define my validator class, it might look something like this:

View set up
If you notice sometimes I pull the view name from the Domain class, this method is obviously assuming a certain directory structure on your view side:

Here's what my view directory looks like:

The last thing I'd do is define my jsp's like this: (You can make your jsp's however you want, i'm just showing some example ones for completeness.)

list.jsp
This page just lists our data using the handy DisplayTag library.

form.jsp
Displays a form for both a new and edit. Notice this pulls from the command object "crudObj" that was set up in the @ModelAttribute("crudObj") annotated method.

Summary

Let's review:

• By using a generic templated base class we reap the benefits of Spring's "configuration by convention" and our controller is more specific and easy to use.
• We take advantage of Configuration by Convention again to automatically have meaningful url's without having to explicitly configure them thanks to Spring's ControllerClassNameHandlerMapping.

The way I created an abstract controller above was just one way to do it, however I believe I've shown that just because your controller classes don't extend an old-style Spring controller class doesn't mean you can't take advantage of inheritance to make your own life easier, even when using annotations.

Bookmark to:

It requires a derby database which you can download from here, simply run the startNetworkServer.bat in the bin directory to start it.

Introduction

Eclipselink is a part of the Eclipse Project. It's an ORM that implements the JPA 1.0 specification, the main commiters on the project are Oracle employees, and Eclipselink is based on the mature Toplink library, in fact Toplink is being renamed Eclipselink for future releases.

Why use JPA?

JPA is the official persistence specification for EJB 3, it's not going anywhere and you're going to have an easier time finding other developers who are familiar with the JPA specification. What's even better is the EclipseLink implementation is the JPA 2.0 reference specification, so there's a good chance some features you enjoy in the EclipseLink implementation will be present in the JPA 2 specification as well.

Why bother with an ORM?

When you're coding an RCP application, chances are you're already passing around Java Beans that represent your data model. If you could have the mapping take place automatically from your database to java beans, it just makes your life that much easier. Once you add the power of libraries like Jface Databinding it's hard to go back to any other method of data access.

Death to XML

Thankfully EclipseLink does not require much XML, the only xml file I create is a persistence.xml that simply lists all my entity classes. A nice editor is included with the JPA Tools plugin that makes managing it simple. All other configuration can be done via annotations.

Tons more after the Jump!

High Level Plug-in Architecture

I like to split my project into 2 main parts. You could put it all in one plugin, but this is how I do it.

UI

This plugin contains all my UI code. Views, Perspectices, Editors, etc. No data access code should occur here though. Instead we'll just use our model plugin. This isn't an RCP tutorial, so I'm going to assume you know your way around the base RCP classes and project set up.

The Model

The model plugin is where all the data access work takes place, from here we can separate 3 main concerns.

Connection Set Up (EntityManagerFactory)
The EclipseLink class that takes care of creating database connection, configuring pooling, or re-using an exisiting datasource as a connection is the EntityManagerFactory.

Configuring your EntityManagerFactory involves specificing the connection, and setting options. Once we're done, you guessed it, we can create EntityManagers!

The call to createEntityManagerFactory takes the name of your "persistence unit", it must match the name you put in your persistence.xml, so in this case it's "comics".

Here's the EntityManagerFactory I created for the Comics example:

Models (EntityManager Usage)
Once we have an EntityManagerFactory we can use that EntityManagerFactory to create an EntityManager. An EntityManager has it's own cache, handles all data access (selects/inserts/updates) and also can manage your transactions (commit/rollback).

I've found that I wrote the same code quite a bit: Obtain an EntityManager from my EntityManagerFactory, begin a transaction, commit a transaction, etc. Rather than write this same code over and over again I find it much easier to simply put this code in a base "Model" class.

I use two types of "Models", one type is your standard Read Only model, I call this class BaseModel, it has some convience methods like selectAll and getNamedQueryResults. The next type of Model I call an "EditorModel" (Because I mostly use it in editors). It has transaction management methods as well as a method called isDirty which can tell me if I have any changes pending to go in the current transaction. This is very useful for editors and any other place you want to do read/write stuff.

I either use these two classes on their own or I extend them to put business specific methods in them -- things like getAllEmployees(), etc.

Entities
An entity represents a persistent object in your database (usually a table or a view). In java terms they are POJO's (Plain Old Java Objects). I usually add property change support to them for use with the JFace Databinding library, but that's not required.

Example Entity (this one implements property change support, that's why I'm extending BaseEntityObject) :

Rememeber: Every entity defined in your model project must be referenced in your persistence.xml.

Generating Entities
The best way to generate your entities is with the Dali JPA Tools plugin, it's available on the standard eclipse update site. After you get Dali make sure you configure your drivers & connections for whatever platform your database uses - oracle,mysql, etc.

You cannot just use the JPA Tools plugin on any ol' project however. Though in the future this limitation will go away. First you must create a special "JPA Project" and immediately converting it to a plugin project.

Then you can then generate your entities by right clicking on your project and selecting JPA Tools->Generate Entities.

Common Gotcha - sharing Entities
When we're talking about OSGi, Entities can not pass the class loader boundry, so you cannot (at this time: September 2008) re-use entities between bundles. This just means the EntityManager you persist an entity with, must be in the same bundle. So I couldn't take common entities and put them in their own bundle, then expect to persist/select to them with an EntityManager defined in another bundle.

This isn't as much of a deal breaker as it sounds at first, you just have to violate DRY for Entity Classes, which aren't all that interesting in the first place. There's nothing stopping you from defining common interfaces or Abstract classes that entities from multiple bundles share.

Selects/Inserts/Updates/Deletes

So how do you do stuff with EclipseLink? Turns out, it's pretty simple. However there are so many different ways to do things, I don't have the room here to go over it. Please read this excellent wiki article to quickly get up to speed. Also any JPA Tutorial will get you caught up on the basics. I'd like to go over how all of this stuff pertains to your run of the mill RCP applications.

Editor Use Case

A common usage scenario with a database driven app is to use a FormEditor to modify a collection of entities. Thanks to EclipseLink we get lots of stuff for free, let's take a look at an example editor class.

Editor Initialization
The init method, here we want to get whatever entities we want to set up our Model, remember our Model basically wraps our EntityManager and contains some convenience methods for dealing with transactions, etc. We need to obtain all of our entities from the entity manager, usually through a simple select query.

So we create a new PublisherEditorModel, which is a simple class I created that handles starting my transaction, then we get our Publisher entity from the model, let's peak inside the PublisherEditorModel class, here we use call the find method on our entity manager, that method takes the class of our Entity and it's primary key.

So now we've got our Publisher Entity, but it's one we obtained from our EntityManager, that means any changes we make to the entity will be followed by the EntityManager. So if we changed a field, then called save on the EntityManager, an update statement would be sent to the database!

You could of course skip the convention of a model class all together and deal with getting the EntityManager directly from your plugin's EntityManagerFactory yourself, but it's much easier to just write that code once.

Checking for changes
One feature of an editor is a dirty state -- you change something, the editor is marked as dirty (A star is added to the editor title). If you save the changes, they go through, if not they're discarded. By using EclipseLink we get this functionality for free. No matter how complicated our model is. In basically one line of code we take care of what used to be a gigantic chore. Now figuring out exactly what the differences are is a bit more complicated, but for our case this works great.

Saving Changes
To save our changes we simply commit our transaction, then start a new one (so editing can continue). Once again, we haven't had to write a single line of SQL. This simple commit will handle, updates, inserts, deletes! This step used to cause me many hours of grief for each new editor, troubleshooting what sort of SQL I had to generate, and in what order. Don't get me wrong, sometimes EclipseLink doesn't generate the SQL you think it should, but it's usually fairly easy to debug what went wrong.

So, our entities we got from our entity manager we expose to our FormPages in the editor, we then bind those very entities to UI controls, either using JFace databinding or by hand -- whichever way you prefer.

Review
That's really all there is to tying a simple editor to a database. Let's review:

1. Obtain an EntityManager and begin a transaction
2. Obtain all the entities you need from the EntityManager, either through the find method, a JPQL query or a Native SQL Query, or combination of these methods.
3. Leverage EclipseLink's UnitOfWork class in your isDirty method.
4. In your form pages, bind Entities to UI controls.
5. Commit your transaction when save is called.

Caching in a Thick Client

Traditionally one of the major benefits you get when using an ORM library and with EclipseLink especially is the ability to have a shared in memory cache. The benefits in a server side web application are immense, when we're dealing with a client side thick application. Caching just gets in our way in most cases. The reason for this is obvious: In a web application EntityManagers across users sessions can all easily share the same cache, since they all reside on the same server (usually).

However in a thick client each user is an island. When I make an update to the database, I update my very own Shared Cache, however Mary who is sitting 2 cubes over still has her own cache that's oblivious to my changes. It's imperative that she receive fresh data all the time!

Fresh data from a find call
Calling find on the EntityManager is the easiest way to get a handle on an Entity. However, you're not gauranteed to hit the database on this call. After our find we just need to call refresh to refresh the Entity from the database. I created a method called findFresh that I put in my Base Model class, here's how it looks:

In EntityManager Setup
You can turn off the Shared Cache EntityManager wide, to stop regular JPQL queries from hitting the shared cache, this is called putting your EntityManager in "Isolated Mode", just set it in the properties map you pass to the createEntityManagerFactory method.

I just set the property like this:

Fresh results from Queries
Just to be sure when I execute any Query - Native or otherwise I set the Query Hint to not use the cache, I created a little helper method I through in a util class like this:

When dealing with NamedQueries you can use the @CacheHint annotation to set the hint.

Conclusion

Before using EclipseLink in my business critical RCP applications, we were using all home grown DAO. We successfully ported our old applications to EclipseLink in a matter of months and that was using alpha code. Looking back all the developers agree we couldn't live with out it. It's amazing what the simplicity of being able to focus on your actual business logic and not SQL generation can do to you, coding is fun again. Thanks EclipseLink!

Bookmark to:

This tutorial will show how to use prototype to return JSON data to your jsp.

Prerequisites

This tutorial will be Struts-centric, but really is adaptable to any Java/J2EE platform. I'm not going to include any DB Layer specific code since that seems to change so much, but you should know how to take a query result and put it in a hash map.

The Goal

Create a Struts Action class that queries the database and returns the result in a JSON object back to a JSP with as little fuss as possible.

The JSP

In this example, I want to populate a text box in my form with data returned from an AJAX request in the background. For example, sometimes you want to pull out a person's name based on some internal ID. This saves our user from having to type it in by hand and also eliminates spelling mistakes.

So let's assume we have a text box where the user would type in the id as well as a text box where they would type the full name, the code would look something like this

We'll then have a javascript function that uses prototype to create an AJAX request that hits a struts action to to the database look up, then populates the fullName text box with the fullName property from the returned JSON object.

The Java

Our goal here is to do some work and put that work in a JSON object, for me the easiest way is to just query the DB and throw the results into a hashmap or java bean. To do the JSON lifting in this example I use the open source json-lib. If an error occurs we'll put error text in a key in the JSON object called executeError so that we can display that in our javascript.

So that's all there is to it, as you can see it's pretty simple stuff but quite powerful. I like to create utility classes that return a whole bunch of info from a query, they're quite handy to have around to quickly display information in your web app without having to do a lot of leg work of new windows and new jsp pages, etc.

Extra struts-config.xml Stuff

If you're using struts you need to forward to a jsp of some sort, this is just going to be an empty JSP page, the JSON info is stored in the response header, anyway here's what your struts-config.xml entry might look like for this action.

Bookmark to: