BlackBox

We actually released this to the Grails plugin repository last week but haven’t had time to blog about this release. There’s a lot of good stuff in this release, some bug fixes and some new features.

Before we dive into the new features there is a short how-to on the wiki. To install the plugin you can just do a

grails install-plugin gorm-couchdb

or download from the Grails Web site.

New Features

Domain objects now assume that there is a design document with the same name as the @CouchEntity type:

@CouchEntity
Customer {
    ...
 }

This will then map to a design document named customer. So a call to Customer.queryView("byName") is the same as Customer.queryView("customer/byName").

Added count() and list() methods that call the count and list view of the domain design document. You can optionally specify the view as the first parameter, e.g. Customer.list("byName"). Also, both methods take the options parameter, so default scaffolding code like the following works:

def list = {
    params.max = Math.min(params.max ? params.max.toInteger() : 10, 100)
    [tripInstanceList: Trip.list(params), tripInstanceTotal: Trip.count()]
}

Added dynamic finders support for list, find, and count methods that take the view name from the method. Instead of calling Customers.list("byName") you can now call Customers.listByName(). The list and count methods only accept options as parameters, for example Customers.listByName(params). The dynamic finder methods assume that the keys are passed first and that the last parameter of type Map contains any options, e.g., Customers.findByName("John Smith", "John Doe", params) will query the customers/byName view for keys that equal “John Smith” or “John Doe”.

The methods findByView() and findByViewAndKeys() were renamed to queryByView() and queryByViewAndKeys() to avoid any potential conflicts.

Added a “typeFieldName” parameter to the @CouchEntity annotation that specifies the name of the type field stored in the JSON document (and CouchDB database).

Added automatic type conversion on list, find, and query results if the name is the same as a field of the domain model. A field like lastUpdated will get returned as a Date object instead of a string that you would have to convert.

Added support for @Transient annotation on transient fields. This is in addition to the already present GORM “transient” support. This also works on “read-only” fields, i.e., bean properties with a getter but no setter.

The plugin now uses jcouchdb’s svenson library for JSON generation and parsing. This gives us a slight performance boost, but more importantly, keeps us inline with future jcouchdb changes and enhancements.

Added a toJSON() method to domain objects that returns a JSON version of the domain object. Note that this could be very different from the one returned by Groovy’s JSON as id becomes _id and version becomes _rev along with other changes.

Bug Fixes

• Now correctly read attachment’s metadata
• Now remove the automatically injected id and version properties, and rewrite the toString() method to use the right fields
• Now allow spaces in id values for bulk operations
• Can now store unicode data in any field (including id fields)

What’s next?

Right now we think we have a fairly stable plugin that we have started using in actual projects and will be improving this as we run into any issues. For me, the first thing will probably be compound key support, where something like project_myProjectName as the id value of my document instead of a generated value. Above and beyond that, handling object relationships is pretty high up there – we’re just trying to figure out the best way to do it.

Our main repository is on Cory’s Github since he’s been doing most of the work at this point and I’ve shifted into more of a project management role.

For bugs, please submit any issues to the bug tracker on Github. New feature and release planning will be on PivotalTracker. We haven’t setup a separate mailing list, but both of us are on the Grails user and dev lists. If you would like to become more involved, contact either of us through the Github system.

Finally, if you are developing a different NoSql Grails plugin we want to talk to you. We want to see if we can coordinate our efforts and if there’s any common ground we can agree on so that we aren’t all reinventing the wheel.

Well, crazy or not I actually (somehow) convinced someone to help me out. And boy did he help! I got some of the basics going and then Cory took off with them. He’s put a lot into this plugin and for that I wanted to publicly thank him.

Now, onto the nitty-gritty. This is an alpha release, so it’s still missing some features (mainly object inheritance and any kind of relational mapping right now). Basically what you can do is to create an object and save it in a CouchDB database. We have some configuration options and some other cool things that you can try out like loading/reloading of views in your database.

Here are some of the basics of what you can do with the gorm-couchdb plugin

• Save a class as a CouchDB document
• Specify the type of document you want to save (special field in the database)
• Save attachments with a document
• Specify a custom id an version field to use for your class/document
• Load and reload .js views directly into your database when they change

There is a short how-to on the wiki. To install it you can just do a

grails install-plugin gorm-couchdb

or download from the Grails Web site.

We’ve switched the main repo over to Cory’s since he’s been doing most of the work at this point and I’ve shifted into more of a project management role. I’ll get to down to some more development of features I really want (like composite keys) in the near future.

For bugs, please use the one on Github, we will be doing all of our release planning over on PivotalTracker. We haven’t setup a separate mailing list but both of us are on the grails user and dev lists. If you would like to become more involved contact either of us through the Github system.

Finally, if you are developing a different NoSql grails plugin we want to talk to you. Primarily we want to see if we can coordinate our efforts and if there’s any common ground we can agree on so that we aren’t all reinventing the wheel.