The Grails PetClinic Application

Updated:

19.JAN.2007

Graeme Rocher

Introduction

Java web development as it stands today is dramatically more complicated than it needs to be. Most modern web frameworks in the Java space are over complicated and don't embrace the Don't Repeat Yourself (DRY) principals.

Dynamic frameworks like Rails, Django and TurboGears helped pave the way to a more modern way of thinking about web applications. Grails builds on these concepts and dramatically reduces the complexity of building web applications on the Java platform. What makes it different, however, is that it does so by building on already established Java technology like Spring & Hibernate.

Grails is a full stack framework and attempts to solve as many pieces of the web development puzzle through the core technology and it's associated plug-ins. Included out the box are things like:

• 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 Jetty container which is configured for on the fly reloading
• Dependency injection with the inbuilt 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)

PetClinic Sample Application Requirements

The application requirement is for an information system that is accessible through a web browser. The users of the application are employees of the clinic who in the course of their work need to view and manage information regarding the veterinarians, the clients, and their pets. The sample application supports the following:

Use Cases

• View a list of veterinarians and their specialties
• View information pertaining to a pet owner
• Update the information pertaining to a pet owner
• Add a new pet owner to the system
• View information pertaining to a pet
• Update the information pertaining to a pet
• Add a new pet to the system
• View information pertaining to a pet's visitation history
• Add information pertaining to a visit to the pet's visitation history

Business Rules

1. An owner may not have multiple pets with the same case-insensitive name.

PetClinic Sample Application Design & Implementation

Server Technology

The sample application should be usable with any Java EE web application container that is compatible with the Servlet 2.4 and JSP 2.0 specifications.

Database Technology

HypersonicSQL version 1.8.0 is the default database used by Grails, but an alternative database can be configured as per the instruction in the Grails user guide.

Development Environment

The developer will need to obtain the following tools externally, all of which are freely available:

• Grails 1.1 or above
• Java SDK 1.5.x

NOTE: The version numbers listed are those that were used in the development of the PetClinic application. Other versions of the same tools may or may not work.

Download links for the various tools needed are provided in the Downloads section.

Directory Structure

petclinic: the root directory of the project contains build related files
    grails-app: contains main Grails sources
        conf: contains configuration files
        controllers: contains web controllers
        domain: contains domain objects (entities)
        i18n: contains internationalization (i18n) property bundles
        services: contains transactional services that implement business logic
        taglibs: contains tag libraries that serve as view helpers
        utils: contains utility classes
        views: contains views written in Groovy Server Pages (GSP)
              layouts: contains layouts for separating out view logic
              common: contains common view templates
    lib: contains any user provided JAR files
    scripts: contains any user provided scripts
    src: contains additional Java and Groovy sources
    test: contains unit and integration tests
    lib: contains all static web resources

PetClinic Application Design

Logging

Grails supports the use of the Apache Commons Logging API. You can configure logging using the Grails Log4j DSL within the grails-app/Config.groovy file.

Business Layer

The Business Layer consists of a number of basic Grails domain classes representing the application domain objects and associated validation logic that are used by the Presentation Layer.

• org.grails.samples.Speciality Represents the specialization of a particular Vet (dentist, surgery etc.)
• org.grails.samples.PetType Represents the type of pet (dog, cat etc.)
• org.grails.samples.Person provides a superclass for all objects that implement the notion of a person.
• org.grails.samples.Vet is an extension of Person that implements a veterinarian. It holds a List of specialities that the Vet is capable of.
• org.grails.samples.Owner is an extension of Person that implements a pet owner. It holds a List of pets owned.
• org.grails.samples.Pet Implements the notion of a pet. It holds a List of visits made concerning the pet.
• org.grails.samples.Visit Implements the notion of a clinic visit for a pet.

Presentation Layer classes

• org.grails.samples.ClinicController Is a simple controller that displays the welcome page and lists all of the known Vets
• org.grails.samples.OwnerController Handles the core logic for adding, updating and finding owners
• org.grails.samples.PetController Handles the main logic of adding, updating and viewing pets and visits

Logical Views & Implemented Use Cases

• grails-app/views/clinic/index.gsp is the "home" screen. It provides links to display a list of all vets, find an owner, or view documentation.
• grails-app/views/clinic/vets.gsp displays all vets and their specialties.
• grails-app/views/owner/find.gsp is used to find owners by last name.
• grails-app/views/owner/selection.gsp allows user to select from a list of multiple owners with the same last name.
• grails-app/views/owner/show.gsp displays a owner's data and a list of the owner's pets and their data.
• grails-app/views/owner/add.gsp allows the addition of a new Owner
• grails-app/views/pet/add.gsp allows the addition of a new Pet
• grails-app/views/pet/addVisit.gsp allows the addition of a new Visit
• grails-app/views/common/_formField.gsp A template used to render common markup
• grails-app/views/layouts/main.gsp The layout used to include common CSS and markup

Testing

• org.grails.samples.OwnerControllerTests is a simple controller test that extends from grails.test.ControllerUnitTestCase and tests the OwnerController.

Downloads

• Download and install the Grails (examples, including PetClinic are provided)
• Download and install a Java Software Developer Kit, version 1.5 or later

Using the PetClinic Application

Make sure the PetClinic web application is running by typing "grails run-app" from the root of the project and then browse to http://localhost:8080/petclinic.

Deploying the PetClinic Application

Deploy the web application to the server in the usual way. If you need instructions for web application deployment, see the Tomcat documentation for details. The Web ARchive (WAR) file can be created by running the "grails war" command, which places it in the root of the project.

Home