The Search for the Holy Grail(s), Page 3
Getting Started with Grails
As with any software, the first thing you need to do with Grails is install it. To do so follow these steps:
- Download the latest Grails distribution from the web site grails.org.
- Extract the relevant archive into a convenient location. If you're organized, this could be in a development sandbox or even simply on your desktop.
- Set the GRAILS_HOME environment variable to the location where you extracted the Grails distribution. Setting environment variables is a rather platform-specific activity, but in Windows this can be via the Advanced tab in the properties of My Computer. Alternatively, if you're running Mac OS X you could add a GRAILS_HOME variable to your .profile file within your home directory (i.e., cd ~).
- In addition, to get the Grails scripts to work from a terminal or command window you need to add the bin directory within Grails to your PATH that will make the Grails scripts visible to the window. To do this, take these steps:
- On Windows append %GRAILS_HOME%bin to the Path variable.
- On Unix append $GRAILS_HOME/bin to the PATH variable.
To validate your installation, open a command window and type the command grails. If you have successfully installed Grails, the command will output the usage help executed in Listing 1.
Note: This listing introduces a convention that will be used throughout the article by using bold to highlight user input.
Listing 1. Grails Command-Line Help
>grails help: Usage: grails [target] Targets: "create-app" - Create a new grails app "create-controller" - Create a new controller "create-service" - Create a new service "create-domain-class" - Create a new domain class "create-taglib" - Create a new tag library class "create-test-suite" - Create a new test suite "create-job" - Create a quartz scheduled job "generate-controller" - Generates a controller from a domain class "generate-views" - Generates the views from a domain class "generate-all" - Generates all artifacts from a domain class "test-app" - Run current app's unit tests "run-app" - Run the application locally and wait "create-webtest" - Create the functional test layout "run-webtest" - Run the functional tests for a running app "shell" - Opens the Grails interactive command line shell "console" - Opens the Grails interactive swing console "war" - Create a deployable Web Application Archive (WAR)
It may be interesting to note at this point that Grails uses the Apache Ant (http://ant.apache.org) build system to power these targets, and throughout the article I will be referring to them as targets (as opposed to commands or operations).
Note: Ant is supported by every modern IDE on the market and is the ubiquitous build system for the Java platform. The advantage being that there is an extremely high level of knowledge of Ant within the Java community, making the Grails build easily customizable if additional functionality is required by your development process.
Now that you've seen what targets are available, let's find out how to run them. Running the targets is a prerequisite to be able to effectively use Grails, so getting this step right will benefit you greatly in the long run. Luckily, it's pretty simple, as you'll see next.
Running the Targets
To execute the Grails targets you simply have to run the grails command followed by the name of the target. For example, to create a new Grails application, you could run the grails create-app command.
An additional feature of Ant is that you can combine targets. For example, if you need to test your application and then create a web application archive (WAR) file for deployment onto an application server you could type this:
grails test-app war
What this will do is execute the test-app target first and if successful will continue on to the war target. This becomes more useful as you get familiar with all the targets available and how they can be combined. It may be worth conducting some experiments of your own to get an idea of what's possible.
Looking back at the list of targets, the create-* targets are convenience targets for setting up a Grails application and creating Grails artifacts. However, unlike a few other frameworks, the targets themselves don't perform any special configuration of their own in the background. This is significant as it allows you to start off using the create-* targets as a learning tool to advance your knowledge of Grails.
Then once you are familiar enough with where everything goes you can create the various classes yourself using your favorite IDE if you so choose. Moving on, the generate-* targets are extremely powerful, allowing the generation of boilerplate code, which is great for both the learning process and getting started quickly.
Of the remaining targets, the most useful are those for executing the Grails application (using the included Jetty application server) for running unit and functional web tests and creating web application archives.
The Obligatory "Hello World!"
So let's get started creating our first Grails application. As is traditional, no article would be complete without a "Hello World!" example, so here it is. To complete your journey through creating a "Hello World!" application you're going to step through the following tasks:
- Execute the grails create-app command to create a basic Grails application.
- Create something called a controller that will handle a web request.
- Use the controller to display some text.
- Run the Grails application and view what you achieved in a web browser.
So let's get going. First up is the creation of a project. Grails provides a target to do just this. Having a common project infrastructure across projects is hugely beneficial, as it ensures newcomers to a project who are already familiar with the way Grails projects are laid out can get up to speed quickly. This allows a developer to immediately focus his attention on the code instead of focusing on understanding how a project fits together.
Projects such as Maven (http://maven.apache.org) have introduced this concept in the Java world. Unfortunately the vast majority of projects still use a custom build system via Ant. It represents one of the graver mistakes made by the designers of the Java Enterprise Edition specification because every Java web project tends to have a different structure and resource layout. Needless to say, this is one mistake that can't be corrected easily, hence Grails ensures that projects are structured in a common way.
To create our "hello" application we need to run the create-app target. This will prompt you for the name of the application you wish to create. Enter the word hello and hit the return key as per the example in Listing 2.
Listing 2. Running the create-app Target
>grails create-app init-props: create-app: [input] Enter application name: hello
Upon completion, the target will have created the "hello" Grails application and the necessary directory structure. The next step is to navigate to the newly created application in the command window using the shell command:
At this point you have a clean slate—a newly created Grails application—with the default settings in place. A screenshot of the structure of a Grails application can be seen in Figure 2.
Figure 2. The "hello" application structure
You can see that Grails contains directories for controllers, domain objects (models), and views.