Grails Features

Most modern web frameworks in the Java space are convoluted, full of twists and turns, and disregard the Don’t Repeat Yourself (DRY) principles. Grails, built on the concepts brought to the fore by dynamic frameworks like Rails, Django, and TurboGears, dramatically reduces the complexity of building web applications on the Java platform, leveraging already established Java technologies like Spring and Hibernate. Grails is a full stack framework and attempts to solve as many pieces of the web development puzzle through the core technology and its associated plugins. Its features include:

• An easy-to-use Object Relational Mapping (ORM) layer built on Hibernate
• An expressive view technology called Groovy Server Pages (GSP)
• A controller layer built on Spring MVC
• A command line scripting environment built on the Groovy-powered Gant
• An embedded Tomcat container configured for on-the-fly reloading
• Dependency injection with the built-in Spring container
• Support for internationalization (i18n) built on Spring’s core MessageSource concept
• A transactional service layer built on Spring’s transaction abstraction

All of these are made easy to use through the power of the Groovy language and the extensive use of Domain Specific Languages (DSLs).

Grails really has too many features to mention them all. In this section, we’ll highlight some of the more important ones.

Integrated Open Source

Grails does not suffer from the Not Invented Here (NIH) syndrome. Rather than reinvent the wheel, it integrates the best of the best industry-standard and proven open source frameworks, several of which are briefly described in this section.

Creating Collab-Todo application

To create the Collab-Todo application, you need to execute the create-app target using an optional project name on the command line, as shown here:

> grails create-app collab-todo

The entire line in the preceding command line is a command, where create-app is a target. A target is a specific task that you want Grails to execute.

If you don’t supply the project name when using create-app, you will be prompted for one. On execution of this command, Grails downloads the dependencies and creates the application. The output of executing the create-app target is shown here:

|Downloading: D:grails-2.1.0liborg.springframework.uaaorg.springframework.u
| Downloading: D:grails-2.1.0libcom.google.protobufprotobuf-javaivy-2.4.1.x
| Downloading: D:grails-2.1.0liborg.bouncycastlecpg-jdk15jarscpg-jdk15-1
.........
 Created Grails Application at D:devlworkspace/collab-todo

Instead of creating the application from command line, you can use the IDE of your choice. We recommend the Groovy/Grails Tool Suite (GGTS), which you can download from http://www.springsource.org/downloads/sts-ggts.  This book uses the latest version: GGTS 3.0. GGTS provides the best Eclipse-powered development environment for building Groovy and Grails applications. GGTS provides support for the latest versions of Groovy and Grails, and comes on top of the latest Eclipse releases.

To create a new project in GGTS, use the menu options File New Grails Project and enter the project name as “collab-todo”.

After the create-app target has run, or after creating a new project using GGTS, you have a new directory matching the name of your project. This is the root of your new project, and you must make all subsequent Grails command-line calls from within this directory. It’s a good idea to use the cd command to get into the directory now so you don’t forget. Within the new project directory, you will find a structure matching the directory structure shown in Figure 4-6.

As mentioned earlier, the directory structure generated from the create-app target is a part of the Grails practice of convention over configuration. The target provides locations for placing common artifacts. Throughout the book, you will learn details about each directory. For now, Table 4-1 provides a summary of the more important directories.

Running the Application

At this point, you have a functional application that you can run and access via a web browser. It does not do much yet, but running it now will enable you to get instant feedback as you add domain and controller classes.

To run a Grails application, execute the run-app target from your project root directory as shown here:

> grails run-app

The output of executing the run-app target is shown here:

Server running. Browse to http://localhost:8080/collab-todo 

To run the application in GGTS, click on “Grails Command History” as highlighted in Figure 4-7, type “run-app” on the command window, and hit Enter.

Running the run-app target performs some initial project setup by copying files into your web application’s WEB-INF directories. Then it starts a Tomcat web container that listens on localhost port 8080. Tomcat then loads the application, causing the Grails internal classes to get initialized for filtering URL mappings and requests along with GrailsDispatchServlet. To test your app, point your web browser to that URL, as shown in Figure 4-8.

Figure 4-8 shows the default Grails page. As you can see, it is not very interesting; it looks like a static page. However, as you’ll see soon, there is some dynamism to this page. If you want to modify this page, it is the GSP grails-appviewsindex.gsp.

Creating the Controller

A controller handles requests and creates or prepares the response. A controller can generate the response directly or delegate to a view. To create a controller class, use the Grails create-controller target. This creates a new Grails controller class in the grails-app/controllers directory, as well as the unit test for the controller class in test/unit. It also creates a grails-app/views/<controller name> directory if it doesn’t exist already.

To create the TodoController class, you need to execute the create-controller target using an optional class name, as shown here:

> grails create-controller todo

If you don’t supply the class name, you are prompted for one. The output of executing the create-controller target is shown here:

| Created file grails-app/controllers/collab/todo/TodoController.groovy
| Created file grails-app/views/todo
| Created file test/unit/collab/todo/TodoControllerTests.groovy

Notice that when running the create-controller with the optional class name, you can leave the class name in lowercase, and Grails will automatically uppercase it for you so that it follows the standard Groovy class naming convention.

To create the controller using GGTS, click on the controllers in the collab-todo project hierarchy, and then use New Controller as shown in Figure 4-9. Type “Todo” in the create–controller wizard as illustrated in Figure 4-10.

This creates the controller as well as the unit test for the controller, as illustrated in Figure 4-11.

Listing 4-1 shows the generated TodoController class.

Listing 4-1.  Grails-Generated TodoController Class

package collab.todo
class TodoController {

    def index() { }
}

The TodoController class in Listing 4-1 contains an empty index action. Chapter 5 will explain actions on the controller. We will print a simple response using one of the implicit methods, the render method, which comes with controllers in Grails, as illustrated in Listing 4-2.

Listing 4-2.  Using the render Method

package collab.todo
class TodoController {

    def index() {
 render "create new tasks"
 }
}

Now run the application by typing “run-app” in the command window as explained earlier. After changing TodoController to look like it does in Listing 4-2, refresh your browser to reveal a new TodoController link on the initial page, as shown in Figure 4-12. Clicking on the controller shows the response, as illustrated in Figure 4-13.

Testing the Controller

At the time of creating the controller, Grails also creates unit tests for the controller as discussed earlier. Listing 4-3 illustrates the unit test generated by Grails, and Listing 4-4 tests the controller.

Listing 4-3.  Generated Test

package collab.todo

import grails.test.mixin.*
import org.junit.*

/**
 * See the API for {@link grails.test.mixin.web.ControllerUnitTestMixin} for usage instructions
 */
@TestFor(TodoController)
class TodoControllerTests {

    void testSomething() {
       fail "Implement me"
    }
}

The TodoController class in Listing 4-2 renders a textual response. To test this controller, we assert the value of the response as illustrated in Listing 4-4.

Listing 4-4.  Testing the Controller

package collab.todo

import grails.test.mixin.*
import org.junit.*

/**
 * See the API for {@link grails.test.mixin.web.ControllerUnitTestMixin} for usage instructions
 */
@TestFor(TodoController)
class TodoControllerTests {

    void testSomething() {
                controller.index()
       assert "create new tasks" == response.text
    }
}

To run the test, we use the same command window that we use to run the application. Instead of typing “run-app” in the command window, type “test-app” (you can also type this target on the command line) and browse to the URL presented in the console to view the test report as illustrated in Figure 4-14.

Creating a Domain Class

At this point, the application we created doesn’t really do anything; it just renders a simple textual response. We will move on by creating a domain class. To create a domain class, use the Grails create-domain-class target. This creates a new Grails domain class in the grails-app/domain directory, as well as a unit test for the domain class in test/unit.

To create the Todo domain class, you need to execute the create-domain-class target using an optional class name, as shown here:

> grails create­domain-class todo

If you don’t supply the class name, you are prompted for one. The output of executing the create-domain-class target is shown here:

| Created file grails-app/domain/collab/todo/Todo.groovy
| Created file test/unit/collab/todo/TodoTests.groovy

Notice that when running the create-domain-class target with the optional class name, you can leave the class name in lowercase, and Grails will automatically uppercase it for you so that it follows the standard Groovy class naming convention.

To create the domain class using GGTS, click domain in the project hierarchy and then use New Domain Class as illustrated in Figure 4-15.

Listing 4-5 shows the generated Todo domain class.

Listing 4-5.  Grails-Generated Todo Domain Class

package collab.todo
class Todo {

    static constraints = {
    }
}

The Todo domain class in Listing 4-5 appears to be the most basic of Groovy classes. As you will learn in the next couple of sections and in the next two chapters, there is more to Grails domain classes than meets the eye.

Listing 4-6 shows the Todo domain class after adding the fields shown in the UML diagram in Figure 4-5.

Listing 4-6.  Todo Domain Class After Adding Attributes, Constraints, and the toString() Method

 1. class Todo {
 2.
 3.   String name
 4.   String note
 5.   Date createdDate
 6.   Date dueDate
 7.   Date completedDate
 8.   String priority
 9.   String status
10.
11.   static constraints = {
12.     name(blank:false)
13.     createdDate()
14.     priority()
15.     status()
16.     note(maxSize:1000, nullable:true)
17.     completedDate(nullable:true)
18.     dueDate(nullable:true)
19.   }
20.
21.   String toString() {
22.     name
23.   }
24. }

In Listing 4-6, you see that lines 3-9 are several fields of both String and Date types that you would expect to find in a Todo domain class. However, there are some additional properties you don’t see that are implicit to a Grails domain class by convention. They include the id and version properties.

The id property, as you might expect, represents a unique auto-incrementing identifier and is null until the object is initially saved. The version property is a Hibernate mechanism for managing optimistic locking. Each time an object is saved, its version number gets incremented, and like the id, it is initially null. Before Hibernate saves any object, it first checks the version number in the database, and if the versions don’t match the object about to be saved—meaning it was already modified since the last read—Hibernate will throw an org.hibernate.StaleObjectStateException.

Lines 11-19 demonstrate the Grails construct of constraints. These are basically rules governing the values of the properties. For example, line 12 states the name property is required and may not be empty using a blank:false constraint, while the note, completedDate, and dueDate properties on lines 16-18 are allowed to be null. Also, note that the note property on line 16 has a maximum length of 1,000 characters. In addition to constraining the properties, the constraints dictate the order of fields on the edit pages as well as the types of HTML form fields rendered by the Grails scaffolding. The order of the constraints represents the order of the fields on the page. While a String is usually represented by an HTML input field of type text, a String property with a maxSize is usually rendered as an HTML input field of a text area to support the larger amounts of input data.

Domain classes can also have behavior implemented as methods. Lines 21-23 show the toString() method being overridden. The default toString() behavior of a Grails domain class is to print the class name followed by a colon and the object ID. To make the toString() a little more helpful, line 21 prepends the name property of the Todo instance.

This section has not even scratched the surface of domain classes. You will learn more about them in Chapter 6.

Dynamic Scaffolding

As explained earlier, the dynamic scaffolding generates controller actions and views for CRUD applications at runtime. To dynamically scaffold a domain class, we need a controller. We created a controller (TodoController) in Listing 4.1. To use the dynamic scaffolding, change the index action to a scaffold property and assign it the domain class, as shown in Listing 4-7. That’s all there is to it. This causes List Page, Create Page, Edit Page, and Show Page views, as well as delete functionality, to be generated for the specified domain class.

Listing 4-7.  Dynamic Scaffolding-Enabled TodoController

package collab.todo
  class TodoController {
  static scaffold = Todo
}

After changing TodoController to look like it does in Listing 4-7, refresh your browser and click the TodoController link on the welcome page.

Selecting the TodoController link brings you to the Todo List page shown in Figure 4-16.

From the list page shown in Figure 4-16, you have the ability to create new domain objects (as shown in Figure 4-17 ) by clicking the New Todo button on the navigation bar.

The save page displays the list of properties in the order in which the constraints are ordered as shown in the Create Todo page in Figure 4-17. Note that the Grails scaffolding displays the edit fields in the appropriate date type format. A string is displayed as an HTML text input field, while createdDate is displayed as a series of drop-downs for the day of month, month, year, hour, and seconds. In addition, the note property is displayed as an HTML text area input due to the maxSize constraint. That’s not all: the Grails scaffolding is also smart enough to use the constraints for doing form validation, as shown in Figure 4-18.

Notice in Figure 4-18 that a validation message is displayed at the top of the page if the form is submitted with an empty name. The blank:false constraint makes the name property required.

Figure 4-19 shows a read-only view.

The Show Todo page displays all the properties and values. It also provides access to the Edit Todo page, as shown in Figure 4-20, where you can delete the domain object.

The Edit Todo page, shown in Figure 4-20, is really the same as the Create Todo page, except the data is repopulated with the domain object values, and it has Update and Delete buttons at the bottom of the page.

Static Scaffolding

Dynamic scaffolding is particularly useful in testing the domain class and developing the prototype, but you may want to customize the logic and views. You can use static scaffolding for this purpose. Static scaffolding can also serve as a great learning tool, for instance, to understand the mechanics of a CRUD application. To generate the controller for the domain class Todo using static scaffolding, use the following command:

> grails generate-controller  collab.todo.Todo

With this command, Grails generates the TodoController class inside grails-app/controllers. The generate-controller command is different from the create-controller command introduced earlier, in that the create-controller command creates an empty controller with a default action index(), while the generate-controller command creates the controller with all the code for the CRUD operation. Similarly, to generate views, use the following command:

> grails generate-views  collab.todo.Todo

With this command, Grails generates .gsp files inside grails-app/views/todo.

Grails also provides the possibility to generate both controllers and views in one command, like so:

> grails generate-all  collab.todo.Todo

One important thing to keep in mind when using static scaffolding: because all the controller code and views code are generated for the domain class, Grails will not update this code if the domain class is changed, and will relinquish this responsibility to the developer.

package collab.todo
class Category {
  String name
  String description

  static constraints = {
    name(blank:false)
  }

  String toString() {
    name
  }
}

package collab.todo
class User {
  String userName
  String firstName
  String lastName

  static constraints = {
    userName(blank:false,unique:true)
    firstName(blank:false)
    lastName(blank:false)
  }

  String  toString () {
"$lastName, $firstName"
  }
}

package collab.todo
class CategoryController {

  static scaffold = Category
}

package collab.todo
class UserController {

  static scaffold = User
}

D:devlworkspacecollab-todo>grails stats

+−−--------------------+−−-----+−−-----+
 | Name                 | Files |  LOC  |
 +−−--------------------+−−-----+−−-----+
 | Controllers          |     3 |    12 |
 | Domain Classes       |     3 |    54 |
 | Unit Tests           |     6 |    60 |
 +−−--------------------+−−-----+−−-----+
 | Totals               |    12 |   126 |
 +−−--------------------+−−-----+−−-----+

Creating Domain Relationships

At this point, you have three standalone domain classes—Todo, Category, and User—with no relationships between them. But remember that the UML diagram in Figure 4-5 showed that users had user-defined categories as well as todos that were organized by categories. Now it’s time to represent those one­to-many relationships between the domain classes using the belongsTo and hasMany properties.

Listing 4-12 shows the new Todo class, which shows the relationships with User and Category.

Listing 4-12.  Todo Domain Class with Relationships to the User and Category Domain Classes

class Todo {
  String name
  String note
  Date createdDate
  Date dueDate
  Date completedDate
  String priority
  String status
  User owner
  Category category

  static belongsTo = [User, Category]

  static constraints = {
    name(blank:false)
    createdDate()
    priority()
    status()
    note(maxSize:1000, nullable:true)
    completedDate(nullable:true)
    dueDate(nullable:true)
  }

  String toString() {
    name
  }

}

Notice in Listing 4-12 that the relationship is defined with the belongsTo property to the User and Category classes. We’ve also added new owner and category properties. belongsTo tells GORM to delete the todo if either the associated user or the category is deleted. Scaffolding renders these relationships as the select fields on the Create Todo and Edit Todo screens, as shown in Figure 4-21.

Like the Todo class, the Category class has a belongsTo relationship with User, but it also has a collection of Todos, as shown in Listing 4-13.

Listing 4-13.  Category Domain Class with Relationships to the User and Todo Domain Classes

class Category {
  String name
  String description
  User user
  static belongsTo = User
  static hasMany = [todos: Todo]

  static constraints = {
    name(blank:false)
  }

  String toString() {
    name
  }

}

Notice that in addition to belongsTo associated with User, Category contains a hasMany property, which is a map designating a one-to-many relationship with the Todo class. Also, the collection is available via the todos property.

Finally, the User class in Listing 4-14 has now defined its relationships with Todo and Category.

Listing 4-14.  User Domain Class with Relationships to the Todo and Category Domain Classes

class User {
  String userName
  String firstName
  String lastName

  static hasMany = [todos: Todo, categories: Category]

  static constraints = {
    userName(blank:false,unique:true)
    firstName(blank:false)
    lastName(blank:false)
  }

  String  toString () {
    "$lastName, $firstName"
  }

}

As shown in Listing 4-14, the changes required to include the relationships with the Todo and Category classes only take a single line. The hasMany property identifies collections named todos and categories.

As stated earlier, when you run the application, Hibernate creates a database schema based on domain classes. Figure 4-22 shows an entity relational diagram of the domain classes so far.

Notice that the entity relational diagram looks almost identical to the UML diagram shown in Figure 4-5. Hibernate creates three tables with table names based on the class names. It also creates fields for each of the properties using underscores instead of CamelCase. Also, notice the id and version columns are the Hibernate columns for object identity and optimistic locking. Hibernate also creates foreign keys to represent the relationships between the domain classes.

During development, out-of-the-box Grail uses a Tomcat web container and an embedded H2 database. However, many operational environments use other web containers or applications servers and use server-based databases. In Chapter 12, we will look at how to package and deploy an application to an alternative operating environment.