Groovy variables and references don't need to be statically typed. For instance, you can define a variable in the following way:

def myName = "Sam"

The variable myName can contain a String or can later change to an int. def defines a variable or property without delineating a specific type. It is similar to using a type of Object in Java, but the emphasis when using def is that the type isn't important and may change from one context to another.

Groovy supports a concept called GString, which is basically a Java String on steroids. In the earlier example, notice that we were able to create a dynamic String by writing "hello ${name}". This strategy integrates a variable directly within a String without requiring concatenation. You can even invoke methods directly within a ${} block.

Another key concept is that Groovy classes can take named parameters with just a default constructor. For instance, you can instantiate a Groovy class using the following approach:

Class GroovyBean {
    String name
    String favoriteColor
}
def myBean = new GroovyBean([name: 'Joe', color: 'blue']);

There are a few important details in the preceding example. First, notice that we defined a Groovy bean without actually defining corresponding getters and setters (and without using any semicolons!). Groovy defines these for us behind the scenes at runtime. We could reference the name property of the myBean instance with myBean.getName(), but myBean.name is more concise.

Also notice the shortcut we used for passing in a java.util.Map of bean properties. Maps can be defined using the following syntax: [key: value]. A common idiom is to define an empty map as [:]. Similarly, a java.util.List can be defined using the [] notation.

One of Groovy's most significant features is its excellent support for closures. Closures are like methods but can also be referenced by variables or passed as parameters into methods. For instance, you can create a closure and store it in a variable called myClosure using the following code:

def myClosure = {def param ->
  println("The param is ${param}")
}

Notice that closure parameters appear after the first curly brace and are then followed by ->. Closures can be used to dramatically simplify code. For example, you can iterate through a list in Groovy this way:

List myList = ["a","b","c"]
myList.each {curItem ->
    println(curItem);
}

This closure will be passed to the each method for every element in the list. Contrast this approach with using a Java Iterator:

List myList<String> = new java.util.ArrayList();
myList.add("a"); myList.add("b"); myList.add("c");
Iterator<String> myIterator = myList.iterator();
while (myIterator.hasNext()) {
    String curItem = myIterator.next();
    System.out.print(curItem);
}

This is impressive, but it gets better. Imagine we wanted to iterate through a list of Strings, returning only those items that contain the sequence cat. In Groovy, this can be accomplished quite simply:

def stringList = ["I like dogs",
         "I like cats", "I like to scat sing",
         "What is a category", "I have gas"]
def matchingStrings = stringList.findAll {curString ->
    curString.contains("cat")
}

Invoking a closure works in a similar way to invoking a method. You simply reference the closure property, followed by (). You can also call a closure explicitly by referencing the closure and invoking call().

Now that we've covered a few basic Groovy concepts, let's move on to building our Grails persistence tier.

The first step is to install Grails. Head over to http://www.grails.org, and download the latest release. Unzip the downloaded archive and copy everything to a logical location on your hard drive. Next, make sure that everything under the bin directory is executable. If you're using a Unix-based operating system, you can run chmod ug+x ./* from within the bin directory.

Finally, make sure the GRAILS_HOME environment variable is set up. GRAILS_HOME should point to the location where you installed Grails. Also, make sure that you've added the GRAILS_HOME/bin directory to your PATH, so that you don't need to specify the full path to the Grails executables each time you want to invoke a Grails script.

If you are using a Unix-based operating system, we recommend updating your ˜/.bashrc script within your home directory so that you don't need to do this configuration more than once. On a Mac, you can append the following lines to your ˜/.bashrc:

export GRAILS_HOME=/opt/local/share/java/grails/
export PATH=$PATH:$GRAILS_HOME/bin

After you have Grails installed, the next step is to create our gallery application.

Grails ships with scripts that take care of generating boilerplate code to get your application started. The first of these scripts that we will introduce is create-app:

grails create-app grailsGallery

Here, we pass grailsGallery as the only argument. Grails will churn for a few seconds, and voilà! You now have a new Grails application set up and ready to go.

Part of the convention-over-configuration concept is organizing and naming key parts of your application in a standardized way. The create-app script makes this easy by setting up the Grails directory structure for you. After the create-app script completes, you will end up with the following directory structure:

gallery ->
    grails-app
        conf
            spring
                resources.groovy
            Bootstrap.groovy

Datasource.groovy
            Urlmappings.groovy
        controllers
        domain
        i18n
        services
        taglib
        utils
        views

    scripts
    src
        java
        groovy
    test
        integration
        unit
    web-app
        css
        js
        images
        WEB-INF
        index.gsp

Most of our coding effort will be focused on the grails-app directory, which is where the majority of our Groovy code will live. Before we start getting our hands dirty, let's take a brief tour of the Grails application layout.

Not surprisingly, the grails-app/conf directory holds the application's configuration. Grails was designed to be very modular in nature, so it isn't always necessary to explicitly configure each one of your dependencies. However, since Grails is really a Spring application at its core, the grails-app/conf/spring/resources.groovy file can be used to configure your dependencies. Although this is a Spring configuration file, you'll notice that it isn't in XML format. Grails provides a custom domain-specific language (DSL) to configure your Spring beans, and since this file is essentially executable Groovy code, it can be a lot more flexible than a standard XML-based configuration.

Using the Spring DSL is fairly straightforward. As an example, suppose we want to create an e-mail service, so that we can notify end users via e-mail when new images are added to the gallery. We want to configure the Spring e-mail component within our resources.groovy file so that user can send e-mail from within our application. Here is how this configuration might look:

beans = {
    javaMailSender(org.springframework.mail.javamail.JavaMailSenderImpl) {
       host = 'smtp.prospringhibernate.com'
    }
}

The pattern is fairly intuitive. The bean name is defined first, followed by the class name within parentheses. Properties within the bean are then configured within a closure block, which is the part of the code within curly braces ({}).

If we want to inject our javaMailSender bean into a Grails service or controller, we can simply rely on default autowiring by name, by declaring a property named javaMailSender within the appropriate Grails service or controller class:

class EmailService {
    def javaMailSender
}

Similarly, if we want to reference our Grails EmailService within another bean configured within our resources.groovy file, we use its implicit bean name—in this case, emailService. For instance, we might define a NotificationComponent bean within our resources.groovy file as follows:

beans = {
    notificationComponent(com.prospringhibernate.NotificationComponent) {bean ->
        emailService = ref("emailService")
        bean.factoryMethod = "getInstance"
        bean.singleton = "false"
        defaultNotificationMethods = ["email", "sms"]
    }
}

Notice that we've declared a bean parameter at the top of the block using bean ->. By declaring a bean parameter, we are able to specify more explicit details related to the type of bean we are configuring. In this case, we specified a factoryMethod of getInstance, which ensures that new instances of this bean will be instantiated by calling getInstance(). We have also specified that this is not a singleton bean.

Also notice that we have injected a reference to our EmailService by using the convention ref(" BEANNAME"), where BEANNAME is the name of our EmailService bean. We are able to apply most of our Spring configuration knowledge to this Groovy-based DSL. However, notice the flexibility advantage over XML in the following example:

beans = {
  javaMailSender(org.springframework.mail.javamail.JavaMailSenderImpl) {
    if (Environment.getCurrent() == "production") {
      host = "smtp.prospringhibernate.com"
    } else {
      host = "smtp.dev.prospringhibernate.com"
    }
  }
}

Clearly, interpretable code has its benefits over static XML.

This overview only touches on some of the configuration options for Grails. It is also possible to configure dynamic bean names, as well as specify property placeholders and override configuration.

The grails-app/conf/Config.groovy file is a centralized location for specifying key configuration details about your Grails application. This file contains information about the character encoding your application should use, as well as logging details (using log4j).

Grails leverages the innate concept of environments to facilitate the creation and separation of different development and deployment scenarios. For instance, you will likely need to use a different database (requiring variant configuration details) for development or testing than you would for your production deployment. These concepts are built into the Grails core, making it easy to test with a development database and then deploy your application to production for use with the live database, without needing to remember to swap out the configuration. Environment-specific details are present in several key configuration files.

The Config.groovy file contains an initial block of code to specify the default server URL for production:

environments {
  production {
    grails.serverURL = "http://www.changeme.com"
  }
}

If you want to specify a different URL for development, you can modify the configuration snippet accordingly:

environments {
  production {
    grails.serverURL = "http://www.prospringhibernate.com""
  }
  development {
    grails.serverURL = "http://www.prospringhibernate.com"
  }
}

There are no constraints on the kinds of environments your application defines or uses. You can add as many environments as you see fit. This can come in handy for your organization's development process, build cycle, or testing strategy.

Since most web applications require a database, Grails defines a file specifically for configuring datasource-related details: grails-app/conf/DataSource.groovy. This file also uses a custom Groovy-based DSL, making this configuration clear and concise. The environment concept is built into this file as well. Properties can be configured at a global level if they apply to all environments. Environment-specific configuration, however, should be nested within the appropriate environment block.

In the case of our gallery application, here's what our DataSource.groovy file might look like (keep in mind that most of this file is already created for you, so you need to configure only the details that are specific to your application):

dataSource {
    pooled = true
    driverClassName = "org.hsqldb.jdbcDriver"
    username = "sa"
    password = ""
}
hibernate {
    cache.use_second_level_cache = true
    cache.use_query_cache = true
    cache.provider_class = 'net.sf.ehcache.hibernate.EhCacheProvider'
}
// environment specific settings
environments {
    development {
        dataSource {
            dbCreate = "create-drop"
              // one of 'create', 'create-drop','update'
            url = "jdbc:hsqldb:mem:devDB"
        }
    }
    test {
        dataSource {
            dbCreate = "update"
            url = "jdbc:hsqldb:mem:testDb"
        }
    }
    production {
        dataSource {
            dbCreate = "update"
            url = "jdbc:hsqldb:file:prodDb;shutdown=true"
        }
    }
}

Notice that the dataSource property is specified at the top of the file as well as within the environments block. Global details, such as database connection pooling settings and the JDBC driver, are configured globally by placing these details within a top-level dataSource block. Environment-specific details, such as the database URL for the development, test, and production environments, are configured in the dataSource blocks within their respective environments. If you need to use a different JDBC driver for production, you could either move these details within the appropriate environment blocks or simply override the globally configured details within the appropriate environment. Again, the types of environments you can configure are not restricted: development, test, and production are just default environments created by the Grails templates.

The last file we need to cover in the grails-app/conf directory is UrlMappings.groovy. This file provides an amazingly flexible construct for associating URL patterns with a particular controller and action. For example, here's how we might relate the pretty URL /category/panoramas with the CategoryController, specifying that the panaromas category be displayed:

class UrlMappings {
  static mappings = {
      "/$controller/$action?/$id?"{
          constraints {
          }
      }
      "/category/$categoryName"(controller: CategoryController, action: "displayCategory")

      "/"(view:"/index")

      "500"(view:'/error')
  }
}

The mapping we described is actually the second block in this example. The first component of the mapping is the part in quotes. We are essentially defining a regular expression that starts with /category/. The $categoryName defines a parameter name that will be passed to your controller automatically, using the specified chunk of the URL where the parameter name resides. In our example, the part of the URL after /category/ will be extracted and then stored in the parameter named categoryName.

If you look at the first block in the example, you will notice the default URLMapping. In this scenario, we are defining $controller and $action parameters. These are special keywords; instead of denoting a particular parameter, they define the controller to which the matching request should be directed, as well as the corresponding action. In our category listing page example, we haven't defined a $controller within our mapping expression, so we instead specify this explicitly, as follows:

(controller: CategoryController,action: " displayCategory")

Now that we've looked at the Grails application directory structure, let's move on to defining our Grails domain model.

Let's now look at the constraints block. Constraints allow you to better define each field within your domain model, providing clues and requirements to Grails as to how your database schema should be modeled. A number of constraint options are available, but here are some of the most useful:

Some of these constraints can be extremely powerful. For example, the matches constraint allows you to specify a regular expression that will be used to validate the value in the specified field, ensuring it matches the specified regular expression.

The domain-specific constraints, such as email and creditCard, will help to ensure that a field conforms to a valid e-mail address or credit card number, respectively.

If you need a custom constraint, Groovy includes a construct that allows you to define your own. You specify the property, followed by a mapping of constraint types and their corresponding values.

Here is an example:

username(blank: false, maxSize: 255, unique: true)

This will ensure that the username value cannot be left blank and that the database field has a maximum size of 255 characters. Additionally, a unique constraint will also be added to the username database field.

Constraints come into play when you attempt to save a domain entity to the database. If a particular field is not validated, an error will be attached to a dynamic errors property on your domain instance.

Additionally, the constraints defined for each property, coupled with a consistent naming convention, are assembled into error message codes that are automatically used within the default Grails Groovy Server Pages (GSP) templates. For example, if you attempt to save a Person entity without specifying a username, a validation error will be raised and associated within the instance's errors property. Afterward, this error will be properly rendered within the default GSP template, using an error code that is defined in the application's messages.properties resource bundle.

When a validation error code is found, Grails will attempt to look for the appropriate code within the messages.properties file, starting with the most specific naming convention and moving toward the more generic conventions until a match is found. This ensures that if you don't bother adding a specific error code in your messages.properties file, users will still see a sensible error (something to the effect that the blank constraint for the username field has been violated). However, you can easily override this default message by specifying a blank constraint error code that's specific to the Person class.

The Person domain entity is a fairly simplistic example, as it doesn't really contain any associations or customized mappings. Let's take a look at a more complex entity to see how Grails addresses a typical scenario. Update your domain model, and then we'll dive deeper. Use the grails create-domain-class script to stub out the ArtEntity, Category, and Comment classes, respectively. The Comment class would then be modified as follows:

class Comment {

  String comment;
  Date commentDate;
  Person person;

  static belongsTo = [commentedArt: ArtEntity]

  static constraints = {
    comment(maxSize: 2000, blank: false)
    commentDate(nullable: false)
  }

  static mapping = {
    cache true
  }

}

This class is similar to the Person entity we defined earlier. We've defined a few properties, as well as a constraints block. One addition is the belongsTo field, which provides clues to Grails about the relationship between two entities. In this example, we are defining a parent-child relationship between a Comment and an ArtEntity. We are also defining a property called commentedArt and declaring that this property is of type ArtEntity. We could specify additional belongsTo relationships by appending them to this map. In each case, the key represents the property name, and the value represents the type.

The use of belongsTo also asserts cascading rules. In the previous example, we are declaring that ArtEntity is the parent in this relationship, meaning save and delete operations (on ArtEntity) will cascade appropriately to related Comment instances. This relationship will become clearer after we examine the opposing side, which is the ArtEntity domain class.

class ArtEntity {

    String title;
    String subTitle;
    Date uploadedDate;
    Date displayDate;
    int width;
    int height;
    String media;
    String description;
    String caption;
    ArtData_Gallery galleryPicture;
    ArtData_Storage storagePicture;
    ArtData_Thumbnail thumbnailPicture;
    boolean isGeneralViewable;
    boolean isPrivilegeViewable;

    static hasMany = [categories: Categories, comments: Comment]
    static belongsTo = Category

    static constraints = {
        title(blank:false, maxSize: 255)
        subTitle(blank:true, maxSize: 255)
        uploadedDate(nullable: true)
        displayDate(nullable: false)
        width(nullable: true)
        height(nullable: true)
        media(nullable: true, maxSize: 255)
        description(nullable: false, blank: false, maxSize: 2000)

caption(nullable: true, maxSize: 2000)

    }

    static mappings = {
        cache true
    }

}

This class follows a similar pattern, but uses the hasMany property, which defines a one-to-many association to another class. It can also be used to declare a many-to-many association, as long as one side of the relationship is deemed the owner of the association (through the use of belongsTo).

The hasMany relationship works in a similar fashion to the belongsTo convention. You are defining a map in which the keys correspond to the property (that is, collection) names and the values correspond to the domain class. In our example, we are defining two associations: comments and categories. When Grails deciphers this property, it will create corresponding collections to be used to hold these associations. We can define the type of collection we would like to use by explicitly declaring the collection as a property. For instance, we define our categories association (in our ArtEntity domain class) as a java.util.Set by explicitly defining this property:

Set categories = new HashSet();

You probably noticed the static mappings property defined in each of our example domain classes. This field can be used to enhance the Hibernate mapping that Grails creates and manages behind the scenes. In our example, we just assert that the domain entity be cached, using the CacheManager specified in the Config.groovy file. However, the mapping construct is extremely flexible and can be used to modify many areas of the default Hibernate mapping for a particular domain class. For instance, if you need to override the table name or the default column name or type, the mapping DSL provides a means for this to be accomplished. It is also possible to add caching rules for collections or override the default fetching policy for a collection, specifying whether a particular collection will be lazily or eagerly fetched. You can even specify that one or more columns map to a particular Hibernate UserType.

In our earlier Hibernate example, we defined a hierarchy of ArtData classes (each extended from the ArtData base class). In Grails, implementing polymorphic domain classes is even simpler. Here is our ArtData class:

class ArtData {

  byte[] picture;

  static mapping = {
    cache true
  }

}

And here is the ArtData_Storage class (which extends ArtData):

class ArtData_Storage extends ArtData {

}

That's really all there is to it. By default, Grails uses the table-per-hierarchy strategy, meaning it persists the sum of all the properties across the entire hierarchy into a single table.

Unlike with Hibernate, there is no need to explicitly define a discriminator (to help differentiate between types), as Grails will take care of this. However, Grails is flexible enough to allow you to use a different polymorphic strategy. For example, you could use the custom mapping DSL described earlier like so:

static mapping = {
  tablePerHierarchy false
}

Now that we've defined our Grails domain model, let's move on to persisting and retrieving this data.

Grails injects new functionality into every domain model class to facilitate the Active Record pattern. Unlike with the DAO approach, no methods need to be defined up front. Instead, Grails uses naming conventions to interpret how to interact with the database. Using the name of the method invoked, Grails intuits what type of operation to perform. This is best explained through a few examples.

Getting back to our gallery application, let's define a simple unit test that illustrates saving and loading our Person domain class. Since we want to demonstrate how Grails behaves within a running application, we need to create an integration test, which actually bootstraps a Spring ApplicationContext, so we can test functionality that relies on core Grails features such as persistence. Grails ships with a script that creates the integration test scaffolding for us:

grails create-integration-test Person

After running this command, you will find an integration test stub under test/integration/grailsGallery/PersonTests.groovy. In our test, we are going to verify that we can instantiate, save, and load a Person domain entity:

class PersonTests extends GroovyTestCase {

  ...

  void testSavePerson() {
    Person person = new Person(
        [firstName: "Sam", lastName: "Smith",
         username: "ssmith", password: "1234",
         email: "[email protected]",
         roleLevel: Person.ADMIN_ROLE])

    assertTrue("Person entity is valid and can be saved",
        (person.validate() && person.save()))

    assertNotNull ("person id is null", person.id)

    def loadedPerson = Person.get(person.id)

    assertTrue(
         "Person was successfully loaded",
             loadedPerson != null &&
                 loadedPerson.username != null)
    }

}

This is a very straightforward test. Notice that we instantiate our Person entity using a java.util.Map containing default properties for our Groovy class. After our Person instance is instantiated, we verify that the instance validates and saves successfully. validate() verifies all the requirements specified within our domain model's constraints block. If our domain model does not validate successfully, Grails will set an errors property on our Person instance. The errors property contains details on each validation failure and is an implementation of the org.springframework.validation.Errors interface. This interface is quite useful for tracking and managing form submissions, and should be familiar to users of Spring MVC.

In the event of a validation error, we can iterate through each error to find out exactly what went wrong:

person.errors.allErrors.each {curError ->
    log.error("Error saving Person instance: ${curError}");
}

We can also get an error count this way:

person.errors.errorCount()

Grails ships with a tag library that helps to render errors within a typical form submission. Additionally, the default Grails templates will create GSP views that will automatically render clear error messages in the event of any validation or save failures. Of course, default error messages can be easily overridden by updating the messages.properties file.

At this point, you should have a solid understanding of how to go about saving and loading a domain entity. Unfortunately, that won't get you very far. You'll want to be able to query the database. To demonstrate how that works, we first need to add some data to our database.

Let's return to the PersonTests.groovy file and define a setup() method that will be executed before each of our tests are run and allow us to populate the database with some sample data:

void setUp() {
  def baseNames = [
    "Sam", "Bob", "Heather",
    "Steve", "Sofia"]
  baseNames.each {curName ->
    def person = new Person(
      [firstName: curName,
       lastName: curName,
       username: curName,
       password: "1234",
       email: "${curName}@apress.com",
       roleLevel: Person.USER_ROLE])
    assertTrue (
      "Person entity is valid and can be saved",
      (person.validate() && person.save()))
    assertFalse(
      "There should be no errors on the saved entity",
      person.hasErrors())
  }
}

This method is a little archaic, as we simply iterate through a java.util.List of names and create new Person entities using these names as seed data for each field. Also notice that we've added a new assertion to verify that person.hasErrors() is false. After a save operation, calling hasErrors() is a useful idiom to ascertain that there were no errors preventing the entity from being persisted to the database. You will see this approach used frequently within the default Grails controllers.

Now that we have a way to seed our database with some sample data, let's see how Grails makes querying the database very intuitive.

void testFinders() {

  def foundPeople = Person.findAllByUsername("Sam");

  /* foundPeople should reference a List
             containing one Person entity */
  assertEquals("One person found", 1, foundPeople.size())

  /* singlePerson should refer to a single Person
     entity, and the lastName property
     should be equal to Sam*/
  def singlePerson = Person.findByUsername("Sam")

assertEquals(
    "Lastname is Sam", "Sam", singlePerson.lastName)

  def allPeopleSorted =
    Person.list(max: 3, order: "asc",
        sort: "username", offset: 0);

  assertTrue(
      "Three people returned", allPeopleSorted.size())

  assertEquals(
      "First person in list is Sam", "Sam",
          allPeopleSorted[0].username)

}

This new method helps to illustrate a lot of the flexibility for querying data using Grails' dynamic finder concept. Notice that the way each method name is formatted determines the query that eventually is generated on the database.

In our first example, we run Person.findAllByUsername("Sam"). This type of structure returns all data that matches the field username. Notice that we use camel casing. The format might be better expressed using the following structure:

DOMAIN.findAllBy<PROPERTYNAME>

If you look at the assertions, you will notice that this type of method will always return a collection of objects. Conversely, our next assertion uses the format:

DOMAIN.findBy<PROPERTYNAME>

This method works in a similar fashion but will return only a single object. This claim is validated on our assertion, as we demonstrate that the returned value is a single Person instance, instead of a collection.

Both the findAllBy and findBy dynamic methods can also be expanded, in order to specify modifiers on the property name or provide further constraints. For example, if we wanted to find all users that have first and last names that start with the letter p, this could be expressed in the following method:

Person.findAllByFirstNameIlikeAndLastNameIlike("P%", "P%");

In this example, we first specify a conditional property of firstName and then modify the condition using Ilike. The Ilike modifier is similar to the like modifier but is case-insensitive. Next, we append And to the method name to further constrain the query with an additional property condition.

A similar approach may be taken to find out the number of rows in the database that match a specified set of conditions by using the countBy* dynamic finder method. Based on this example, we can define a method-naming structure that delineates the way in which a dynamic-finder method is formatted:

countBy/findBy/findAllBy<PROPERTYNAME><MODIFIER>AND/OR<PROPERTYNAME><MODIFIER>

The following are some of the modifiers that can be used:

Our next example simply calls Person.list(), which returns all the instances of the Person domain class. However, we also pass in a Map of options that help to define constraints and sorting options on our returned data. These options can also be used for pagination, since you can set the maximum number of items to return (max), as well as an offset. Table 6-1 summarizes the options that can be passed to the list() method.

A Map containing the options listed in Table 6-1 will also work with the findAllBy* methods. For instance, we could request the second page (assuming each page contains ten objects) of Person instances, sorted by name in descending order:

def people = Person.list(sort: "name", order: "desc", max: 10, offset: 10);

The dynamic finder approach described in the previous section works well for most types of queries. However, sometimes having a little more flexibility is important. Grails also provides the find() and findAll() methods, which allow you to utilize arbitrary HQL queries. Find() returns a single entity, and findAll() will return multiple entities. Alternatively, an even more flexible executeQuery() method allows you to define queries that don't return a specific domain entity.

Let's look at an example using HQL. Suppose we want to query for all ArtEntity objects that fall within a particular category. This could be represented using the following query:

List artEntities = ArtEntity.findAll(
 "from ArtEntity artEntity left join
      artEntity.categories as category with
          category.id = :categoryId",
              ["categoryId": category.id])

Notice that we use a left join on the Category domain object, specifying a with constraint for those categories matching the specified category ID.

We use named parameters in this query. As in a typical HQL query, parameter names are represented in the query by prefixing the name with a colon. The parameter name-value mappings are then passed in as a Map (as the second parameter to the findAll query).

Just like standard Hibernate, Grails provides a means to express queries using the Criteria API. However, because we are using Groovy instead of Java, we can take advantage of a Criteria DSL, allowing us to define our query criteria in a more concise and readable way. For instance, we could query for all ArtEntity instances within one of two specified categories that also fall within a particular date range using the following query:

def criteria = ArtEntity.createCriteria()
def currentDate = new Date()
def earlierDate = currentDate - 3
def catName1 = "autumnPicts"
def catName2 = "summerPicts"
def results = criteria.list {
    between('displayDate', earlierDate, currentDate)
    categories {
        or {
            equals("name", catName1)
            equals("name", catName2)
        }
    }
}

The preceding example uses the Grails Criteria Builder, allowing us to express a fairly complex set of restrictions in a very intuitive manner. If you recall the standard Hibernate Criteria API, you should be able to infer most of what is occurring in our example. Criteria disjunctions and conjunctions can be specified using or and and blocks, respectively. Similarly, association criteria may be expressed by defining a block with the association name, which is what our categories block does in the preceding example. Within our categories block is a nested or disjunction, and within that block are our equals restrictions, allowing us to filter those categories that match either of the category names we've specified.