GWT Sandbox

Browse Source
Requires: gwt-google-apis
Requires: Velocity 1.5

Many thanks goes out to Jason Essington who contributed named queries to this iteration of the Gears ORM project.

For the noobs, Google Gears is a browser plug-in that puts a database engine right in your browser, and the Gears ORM solution presented here is meant to privide an Object Relational Mapping tool for harnessing Gears with GWT. If you have not read the article on Gears ORM Iteration #1, you should go back and read that first. This article starts where that one left off.

As you may recall, the Gears ORM Iteration #1 (GO1) allowed you to use annotations in your data object to specify the underlying database table name, and map columns to properties. In Gears ORM Iteration #2 (GO2) it is the same with the addition of named queries so that you can use where clauses. One notable change is that the findByExample() method has been removed from the resulting DAO due to some logic issues, but since there are now named queries it is unlikely that it will be missed.

The GO2 has been updated to use Velocity templates for code generation. Using templates makes the project easier to maintain and a lot easier to read it if you decide to take a look under the hood.

Let's start with a quick recap. To use GO2 you create a data object and add the appropriate annotations. The following code snippet uses GWT.create() to pass in the data object class, which returns an instance of GearsDataStore. We can then use the GearsDataStore to load and persist data objects in the Gears database.

GearsDataStore ds = (GearsDataStore) GWT.create(Request.class);
 
Request r = new Request();
r.setRequestId(new Long(1234));
r.setShortTitle("This is a short title");
r.setTestData((byte) 168);
 
try {
  ds.save(r);
 
  Request rs = (Request) ds.findById(new Long(5678));
  ds.delete(rs);
}
catch (Exception e) {
  Window.alert(e.getMessage());
}

One change from GO1 is that you no longer need to explicitly call createTable() as this will be done for you, creating the table if it does not already exist. The only time you will need to use createTable() is when you have altered the structure of the table by adding new properties in your data class, in which case you will call deleteTable() followed by createTable().

As mentioned, GO2 now sports the ability to defined named queries. This is done by adding a @gears.namedQuery annotation at the class level in the data object. The annotation takes two arguments; the name of the query, and the sql code to execute. The snippet below is an example of a named query that returns Request objects with a matching short title.

/**
 * @gears.table (name=Requests)
 * @gears.namedQuery (name=findByShortTitle, sql="select :Requests where shortTitle = ?")
 */
public class Request implements GearsDataObject
{
  public static final String FIND_BY_SHORT_TITLE = "findByShortTitle";
  // ...
}

The sql parameter uses the placeholder :Requests in place of a column list and from clause. Note that the name :Requests refers to the underlying table name, and not the name of the data object class.

In the example we included a constant FIND_BY_SHORT_TITLE to hold the name of the query. This isn't required for the mechanism to work, although is a good pattern to follow.

To use the named query you perform a lookup on the name of the named query, which returns a GearsQuery object, then execute it. The following is an example of using the named query we created in the previous example.

GearsQuery q = ds.getNamedQuery(Request.FIND_BY_SHORT_TITLE);
q.setString(0, "Really Short");
Request[] requests = (Request[]) q.execute();

That wraps up iteration #2. I hope you find it useful, and as always comments are welcomed.