Mollusca Code

For a client/server application I’m currently developing, I chose grails (www.grails.org) as the framework to develop the web application and webservice part. Grails is a framework very similar in concepts to Ruby on Rails, which I personally like a lot for it’s convention over configuration attitude.

The main downside of grails, as far as I’m concerned is the huge amount of *.jar dependencies that it comes along with. This is, as long as applications do not stray from the standard data types of a web framework, very well hidden from the developer.

In this blog post I will outline a few points, on how to save geo-spatial points (no pun intended) using grails.

For said application, I have to save GIS spatial data in the database and I want to access them from the web application. I also want to call the special GIS-related stored procedures on the server. This seemed to be very hard at first, since almost no documentation on the topic can be found, especially in the documentation of the grails framework (not only for GIS data, but also for other custom data types, that is). On the mailing lists of Hibernate and Spring (libraries both used by grails), no working solutions could be found, but only the problem statements.

Digging deeper however revealed the solution to the problem, which I’m going to present now.

Let’s say we want to create a webapp, that can do the following things:

Store upcoming and past events, whereas each event has:

• A Date,
• a title,
• a description,
• and a location (This will be the GIS data)

and store members with:

• Events they are attending.
• A name.
• A birthday.

I suppose creating a web-app using grails is already clear to readers at this point.

The domain classes

Let’s have a look at the domain classes, shall we?

# Event.groovy
class Event {
    String name
    String description
    Date date

    static hasMany = [participants : Participant]
    static belongsTo = [creator : Participant]

    public void findWithinLimit(double distance){
    }
}

# Participant.groovy
class Participant {
    String name
    Date birthDate

    static hasMany = [events : Event]
}

I intentionally left out the GIS attribute of the event class. You can easily start off with this as your domain classes and add GIS functionality later.

Adding GIS functions to PostgreSQL

Now, lets add the GIS functionality to the database. Assuming you use PostgreSQL this can be done in the following way:

1. Add the plpgsql language to the database (createlang command on shell)
2. Execute the update script on the database (my database is called geoEvent) to add the PostGIS functions and data types. On my computer that script is called lwpostgis.sql and sits in /usr/share. I execute the script using pgadmin3, which is my method of choice to work with postgresql databases…

This will make your database ready to store GIS data.

Now, first things first. Let’s add all the libraries we need to make grails aware of the data types we’re going to be using.

You’ll need:

• hibernate-spatial.jar (find this on the hibernatespatial site)
• hibernate-spatial-postgis.jar (same site)
• jts-1.8.jar (JTS site)
• postgis_1.4.0.jar (PostGIS site)
• postgresql-8.2-VERSION.jdbc3.jar (it may be possible to run this with jdbc4, but I haven’t tested that one yet. Version works fine, however)

Enough libraries. ;)

Adding GIS to the domain classes

Now let’s get those GIS data types into the domain classes.

# Event.groovy
import com.vividsolutions.jts.geom.Point
class Event {
    String name
    String description
    Date date
    Point location

    static hasMany = [participants : Participant]

    public void findWithinLimit(double distance){

    }
}

Hooooold your horses, we’re not yet ready to fire up the grails app again. :D

Bind hibernate

You will first have to tell hibernate, that there is new data types that are mapped to the database in a certain way.

In grails-app/conf/hibernate create a file called hibernate.cfg.xml

<hibernate-configuration>
  <session-factory>
    <!-- SPATIAL SQL dialect -->
    <property name="dialect">
      org.hibernatespatial.postgis.PostgisDialect
    </property>

    <!-- Echo all executed SQL to stdout -->
    <property name="show_sql">false</property>

    <mapping resource="Event.hbm.xml" />
  </session-factory>
</hibernate-configuration>

This tells hibernate, that there is a special SQL dialect to learn and that there is a mapping for the type Event (This is by convention, I’d say).

Event.hbm.xml looks like this:

<hibernate-mapping>
  <class name="Event" table="event">
    <id name="id" column="id">
      <generator class="native" />
    </id>
    <property name="location" 
      type="org.hibernatespatial.GeometryUserType">
      <column name="location" sql-type="GEOMETRY" />
    </property>
    <property name="name" />
    <property name="description" />
    <property name="date" />
  </class>
</hibernate-mapping>

That’s it! Now you can fire up your application again and shine with GIS data. At least it seems that way. The tables all get created in the database, the attributes are all there and so are the foreign keys and link tables. Read on the next page how to add data to your database using your grails scaffolds.

Ticket to forms and back

To have grails render your Point in a way, that a user can add new data to the database using the scaffolded code you will have to add a PropertyEditor (which is a concept from the Spring framework…).

A property editor tells your application, how to translate a certain data type into String format and back. This doesn’t look so bad after all:

package com.vividsolutions.jts.geom;

import java.beans.PropertyEditorSupport;
import com.vividsolutions.jts.geom.Point;
import com.vividsolutions.jts.io.ParseException;
import com.vividsolutions.jts.io.WKTReader;

public class PointEditor
        extends PropertyEditorSupport{

       private Point point;

    @Override
    public String getAsText() {
        point = (Point) super.getValue();
        return String.format("POINT(%f %f)",
                    point.getX(), point.getY());
    }

    @Override
    public void setAsText(String text)
                throws IllegalArgumentException {
        WKTReader reader = new WKTReader();
        try {
            point = (Point)reader.read(text);

            super.setValue(point);
        } catch (ParseException e) {
            e.printStackTrace();
        }
    }
}

Now, grails will pick up this PropertyEditor automatically, iff you put it in the correct place. You will have to put it in same directory as the class you are trying to render and parse from a String. So this goes into the src/java/com.vividsolutions.jts.geom package. This will enable you to render and enter Points as Strings of the form:

POINT(48.8 8.8)
POINT(20 30 40) // 3d-Point

That’s quite enough for today. I will follow this post up with a tutorial on how to use the stored procedures to find nearby Points efficiently, as is already hinted in the code by the function findWithinLimit(distance).