CHAPTER 2 ■ GETTING STARTED WITH GRAILS 35 However, since it is a pretty common requirement, we will delve into data sources because you’ll certainly need to configure them; plus, they’ll help you develop your knowledge of environments. The DataSource.groovy File When you create a Grails application, Grails automatically provides a grails-app/conf/ DataSource.groovy file that contains configuration for each environment (see Figure 2-11). You might find this convenient, because it means most of the work is done for you, but you might prefer to use another database such as MySQL rather than the provided HSQLDB database. Figure 2-11. The DataSource.groovy file Defining a data source is one area where the strength of the Java platform becomes apparent. Java’s database connectivity technology, JDBC, is extremely mature, with drivers available for pretty much every database on the market. In fact, if a database provider does not deliver high-quality, stable JDBC drivers, its product is unlikely to be taken seriously in the marketplace. A data-source definition is translated into a javax.sql.DataSource instance that supplies JDBC Connection objects. If you’ve used JDBC before, the process will be familiar, with the first step ensuring that the driver classes, normally packaged within a JAR archive, are available on the classpath. 36 CHAPTER 2 ■ GETTING STARTED WITH GRAILS The DataSource.groovy file contains some common configuration setup at the top of the data-source definition, an example of which is presented in Listing 2-20. Listing 2-20. Common Data-Source Configuration dataSource { pooled = true driverClassName = "org.hsqldb.jdbcDriver" username = "sa" password = "" } The snippet indicates that by default you want a pooled data source using the HSQLDB driver with a username of “sa” and a blank password. You could apply defaults to several other settings. Here’s a list of the settings that the DataSource.groovy file provides: • driverClassName: This is the class name of the JDBC driver. • username: This is the username used to establish a JDBC connection. • password: This is the password used to establish a JDBC connection. • url: This is the JDBC URL of the database. • dbCreate: This specifies whether to autogenerate the database from the domain model. • pooled: This specifies whether to use a pool of connections (it defaults to true). • configClass: This is the class that you use to configure Hibernate. • logSql: This setting enables SQL logging. • dialect: This is a string or class that represents the Hibernate dialect used to communi- cate with the database. Now we get to the interesting bit. Following the global dataSource block, you’ll see envi- ronment-specific settings for each known environment: development, test, and production. Listing 2-21 presents a shortened example of the environment-specific configuration. Listing 2-21. Environment-Specific Data-Source Configuration environments { development { dataSource { dbCreate = "create-drop" url = "jdbc:hsqldb:mem:devDB" } } CHAPTER 2 ■ GETTING STARTED WITH GRAILS 37 test { } production { } } You’ll notice that by default the development environment is configured to use an in-memory HSQLDB, with the URL of the database being jdbc:hsqldb:mem:devDB. Also note the dbCreate setting, which allows you to configure how the database is autocreated. ■Note Hibernate users will be familiar with the possible values because dbCreate relates directly to the hibernate.hbm2ddl.auto property. The dbCreate setting of the development environment is configured as create-drop, which drops the database schema and re-creates it every time the Grails server is restarted. This set- ting can prove useful for testing because you start off with a clean set of data each time. The available settings for the dbCreate property are as follows: • create-drop: Drops and re-creates the database schema on each application load • create: Creates the database on application load • update: Creates and/or attempts an update to existing tables on application load • [blank]: Does nothing The production and test environments both use update for dbCreate so that existing tables are not dropped, but created or updated automatically. You might find it necessary in some production environments to create your database schema manually. Or maybe creat- ing your database schema is your DBA’s responsibility. If either is the case, simply remove the dbCreate property altogether and Grails will do nothing, leaving this task in your or your colleague’s hands. Configuring a MySQL Database Building on the knowledge you’ve gained in the previous section about configuring an alterna- tive database, you’re now going to learn how to set up MySQL with Grails. You’re going to configure Grails to use MySQL within the production environment, and to achieve this you need to tell Grails how to communicate with MySQL. You’re using JDBC, so this requires a suit- able driver. You can download drivers from the MySQL web site at http://www.mysql.com. In this book’s examples, we’ll be using version 5.1.6 of MySQL Connector/J. To configure the driver, drop the driver’s JAR file into the lib directory of the gTunes application, as shown in Figure 2-12. 38 CHAPTER 2 ■ GETTING STARTED WITH GRAILS Figure 2-12. Adding the driver’s JAR file to the application’s lib directory With the driver in place, the next thing to do is configure the Grails DataSource to use the settings defined by the driver’s documentation. This is common practice with JDBC (and equivalent technologies on other platforms) and essentially requires the following information: • The driver class name • The URL of the database • The username to log in with • The password for the username Currently the production DataSource is configured to use an HSQLDB database that per- sists to a file. Listing 2-22 shows the production-database configuration. Listing 2-22. The Production Data-Source Configuration production { dataSource { dbCreate = "update" url = "jdbc:hsqldb:file:prodDb;shutdown=true" } } Notice that the remaining settings (username, password, driverClassName, and so on) are inherited from the global configuration, as shown in Listing 2-20. To configure MySQL CHAPTER 2 ■ GETTING STARTED WITH GRAILS 39 correctly, you need to override a few of those defaults as well as change the database URL. Listing 2-23 presents an example of a typical MySQL setup. Listing 2-23. MySQL Data-Source Configuration production { dataSource { dbCreate = "update" url = "jdbc:mysql://localhost/gTunes" driverClassName = "com.mysql.jdbc.Driver" username = "root" password = "" } } This setup assumes a MySQL server is running on the local machine, which has been set up with a blank root user password. Of course, a real production environment might have the database on a different machine and almost certainly with a more secure set of permissions. Also note that you must specify the name of the MySQL driver using the driverClassName setting. Configuring a JNDI Data Source Another common way to set up a production data source in Grails is to use a container- provided Java Naming and Directory Interface (JNDI) data source. This kind of setup is typical in corporate environments where the configuration of a data source is not up to you, but to the deployment team or network administrators. Configuring a JNDI data source in Grails couldn’t be simpler; specifying the JNDI name is the only requirement. Listing 2-24 shows a typical JNDI setup. Listing 2-24. JNDI Data-Source Configuration production { dataSource { jndiName = "java:comp/env/jdbc/gTunesDB" } } Of course, this assumes that the work has been done to configure the deployment envi- ronment to supply the JNDI data source correctly. Configuring JNDI resources is typically container-specific, and we recommend that you review the documentation supplied with your container (such as Apache Tomcat) for instructions. Supported Databases Because Grails leverages Hibernate, it supports every database that Hibernate supports. And because Hibernate has become a de facto standard, it has been tried and tested against many different databases and versions. 40 CHAPTER 2 ■ GETTING STARTED WITH GRAILS As it stands, the core Hibernate team performs regular integration tests against the follow- ing database products: • DB2 7.1, 7.2, 8.1 •HSQLDB • HypersonicSQL 1.61, 1.7.0, 1.7.2, 1.8 • Microsoft SQL Server 2000 • MySQL 3.23, 4.0, 4.1, 5.0 •Oracle 8i, 9i, 10g • PostgreSQL 7.1.2, 7.2, 7.3, 7.4, 8.0, 8.1 •SAP DB 7.3 • Sybase 12.5 (jConnect 5.5) •TimesTen 5.1 In addition, although not included in the Hibernate QA team’s testing processes, these database products come with community-led support: •Apache Derby • HP NonStop SQL/MX 2.0 • Firebird 1.5 with JayBird 1.01 •FrontBase • Informix •Ingres • InterBase 6.0.1 •Mckoi SQL • PointBase Embedded 4.3 • Progress 9 • Microsoft Access 95, 97, 2000, XP, 2002, and 2003 • Corel Paradox 3.0, 3.5, 4.x, 5.x, and 7.x to 11.x • A number of generic file formats including flat text, CSV, TSV, and fixed-length and vari- able-length binary files • XBase (any dBASE; Visual dBASE; SIx Driver; SoftC; CodeBase; Clipper; FoxBase; FoxPro; Visual Fox Pro 3.0, 5.0, 7.0, 8.0, 9.0, and 10.0; xHarbour; Halcyon; Apollo; GoldMine; or Borland Database Engine (BDE)-compatible database) • Microsoft Excel 5.0, 95, 97, 98, 2000, 2001, 2002, 2003, and 2004 CHAPTER 2 ■ GETTING STARTED WITH GRAILS 41 A few, mostly older, database products that don’t support JDBC metadata (which allows a database to expose information about itself) require you to specify the Hibernate dialect explicitly using the dialect property of the data-source definition. You can find available dia- lects in the org.hibernate.dialect package. You’ll learn more about data-source definitions in future chapters, including Chapter 12. For now, since we have readied our application for the production environment, let’s move on to the next step: deployment. Deploying the Application When you execute a Grails application using the run-app command, Grails configures the application to be reloaded upon changes at runtime, allowing quick iterative development. This configuration does, however, affect your application’s performance. The run-app com- mand is thus best suited for development only. For deployment onto a production system, you should use a packaged Web Application Archive (WAR) file. Doing this follows Java’s mature deployment strategy and the separation of roles between developers and administrators. As a significant added bonus, Grails’ compliance with the WAR format means that IT pro- duction teams don’t need to learn any new skills. The same application servers, hardware, profiling, and monitoring tools that you use with today’s Java applications work with Grails, too. Deployment with run-war If you are satisfied with the built-in Jetty container as a deployment environment, you can quickly deploy your application by setting up Grails on your production environment and then checking out your Grails application from the version-control system you have locally. Once you’ve done this, simply type: grails run-war This command packages up Grails as a WAR file and then runs Jetty using the packaged WAR on port 8080. If you wish to change the port, you can follow the instructions in the “Step 6: Running the Application” section of Chapter 1. As for the Jetty configuration itself, modifying the GRAILS_HOME/conf/webdefault.xml file can customize that. Deployment with a WAR file The run-war command is convenient, but you might want more control over your deployment environment. Or you might want to deploy onto another container, such as Apache Tomcat or BEA WebLogic, instead of Jetty. What you need in these cases is a WAR file. The WAR file is the standardized mechanism for deployment in the Java world. Every Java EE–compliant web container supports the format. But some older containers might have quirks, so check out the http://grails.org/Deployment page on the wiki for helpful info on container-specific issues. To create a WAR archive, use Grails’ war command: $ grails war 42 CHAPTER 2 ■ GETTING STARTED WITH GRAILS By default, if no environment is specified, Grails assumes use of the production environ- ment for a WAR file. However, as with other commands, you can change the environment if needed. For example: $ grails test war Once you’ve run the command, a brand-new WAR file appears in the root of your project directory (see Figure 2-13). Figure 2-13. The gTunes WAR file If the root directory is not a convenient location for the WAR file, you can always change it by specifying the target WAR location as the last argument to the war command: $ grails test war /path/to/deploy/gTunes.war With the WAR file created, you just need to follow your container’s deployment instruc- tions (which might be as simple as dropping the file into a particular directory), and you’re done. Notice how the WAR file includes a version number? Grails features built-in support for application versioning. You’ll learn more about versioning and deployment in Chapter 12. Summary Wow, that was a lot of ground to cover. You generated a simple CRUD interface, configured a different data source, and produced a WAR file ready for deployment. You learned some of the basics about how controllers work in Grails and previewed what is to come with GORM, Grails’ object-relational mapping layer. CHAPTER 2 ■ GETTING STARTED WITH GRAILS 43 You also played with Grails’ support for running different environments and configured a MySQL database for production. All of this should have given you a solid grounding in the basics of working with Grails. However, so far we’ve only touched on concepts such as domain classes, controllers, and views without going into much detail. This is about to change as we plunge head first into the gory details of what makes Grails tick. Starting with Chapter 3, we’ll begin the in-depth tour of the concepts in Grails. As we do that, we’ll begin to build out the gTunes application and transform it from the prototype it is now into a full-fledged, functional application. 45 ■ ■ ■ CHAPTER 3 Understanding Domain Classes Object-oriented (OO) applications almost always involve a domain model representing the business entities that the application deals with. Our gTunes application will include a number of domain classes including Artist, Album, and Song. Each of these domain classes has proper- ties associated with it, and you must map those properties to a database in order to persist instances of those classes. Developers of object-oriented applications face some difficult problems in mapping objects to a relational database. This is not because relational databases are especially difficult to work with; the trouble is that you encounter an “impedance mismatch” 1 between the object-oriented domain model and a relational database’s table-centric view of data. Fortunately, Grails does most of the hard work for you. Writing the domain model for a Grails application is significantly simpler than with many other frameworks. In this chapter, we are going to look at the fundamentals of a Grails domain model. In Chapter 10, we will cover more advanced features of the GORM tool. Persisting Fields to the Database By default, all the fields in a domain class are persisted to the database. For simple field types such as Strings and Integers, each field in the class will map to a column in the database. For complex properties, you might require multiple tables to persist all the data. The Song class from Chapter 2 contains two String properties and an Integer property. The table in the data- base will contain a separate column for each of those properties. In MySql, that database table will look something like Listing 3-1. 1. Scott W. Ambler, “The Object-Relational Impedance Mismatch,” http://www.agiledata.org/essays/ impedanceMismatch.html, 2006. [...]... varchar (25 5) | YES | | NULL | | + -+ + + -+ -+ -+ + -+ + + -+ -+ -+ | Field | Type | Null | Key | Default | Extra | + -+ + + -+ -+ -+ | id | bigint (20 ) | NO | PRI | NULL | | | team_name | varchar (25 5) | YES | | NULL | | + -+ + + -+ -+ -+ Which of these mappings should you use? The answer depends on several factors One of the consequences... (see Listing 3 -2 2) Grails imposes table-per-hierarchy mapping as the default for an inheritance relationship Listing 3 -2 2 The Person Table Representing a Table-Per-Hierarchy Mapping + -+ + + -+ -+ + | Field | Type | Null | Key | Default | Extra | + -+ + + -+ -+ + | id | bigint (20 ) | NO | PRI | NULL | auto_increment | | version | bigint (20 ) | NO | |... return false } }) } } The validator in Listing 3-6 will fail if the password is equal to the firstName property of the User class The validator closure should return false if validation fails; otherwise it should return true The first argument passed to the closure is the value of the property to be validated The second argument passed to the closure is the object being validated This second argument is... foreign key to relate the tables to each other (see Listings 3 -2 6 and 3 -2 7) Listing 3 -2 6 The Car Table + -+ + + -+ -+ + | Field | Type | Null | Key | Default | Extra | + -+ + + -+ -+ + | id | bigint (20 ) | NO | PRI | NULL | auto_increment | | version | bigint (20 ) | NO | | NULL | | | engine_id | bigint (20 ) | NO | MUL | NULL | | | make | varchar (25 5) | NO |... parent class grails. test.GrailsUnitTestCase The GrailsTestUnitCase class is a test harness that provides a range of utility methods to mock the behavior of a Grails application To run the test, invoke the test-app Grails command from the command line The test-app command will run all the unit tests and integration tests that are part of the project To run a specific test, invoke the test-app target... don’t use the create-domain-class command to create your domain class, you can create the test on your own Make sure to put the test in the appropriate directory Listing 3-3 0 The Unit Test for the Artist Class, Generated Automatically class ArtistTests extends grails. test.GrailsUnitTestCase { void testSomething() { } } As you can see from Listing 3-3 0, the default unit-test template extends from the parent... invoke the test-app target with an argument that represents the name of the test to run The name of the test to run should be the test-case name without the “Tests” suffix For example, execute grails test-app Artist to run the ArtistTests test case The test-app target will not only run the tests, but also generate a report including the status of all the tests that were run This report is a standard JUnit... execute the first action in the SampleController Likewise, /sample /second will execute the second action in the SampleController Setting the Default Action You don’t necessarily need to specify the action to execute in the URL If no action is specified, Grails will execute the default action in the specified controller You can identify the default action using the following rules (see Listing 4-3 ): • If the. .. does need to map to an existing schema, the schema will probably not match up exactly to the Grails defaults Imagine that a schema does exist, and that it looks something like Listing 3-1 2 Listing 3-1 2 A Legacy Table Containing Person Data + -+ + + -+ -+ + | Field | Type | Null | Key | Default | Extra | + -+ + + -+ -+ + | person_id | bigint (20 ) | NO... mapping, the parent class must use the ORM DSL to turn off the default table-per-hierarchy mapping 57 58 CHAPTER 3 ■ UNDERSTANDING DOMAIN CLASSES Listing 3 -2 4 The Person, Employee, and Player Tables with Table-Per-Subclass Mapping + + + + -+ -+ + | Field | Type | Null | Key | Default | Extra | + + + + -+ -+ + | id | bigint (20 ) | NO | PRI | NULL | auto_increment . directory of the gTunes application, as shown in Figure 2- 1 2. 38 CHAPTER 2 ■ GETTING STARTED WITH GRAILS Figure 2- 1 2. Adding the driver’s JAR file to the application’s lib directory With the. configured to use an HSQLDB database that per- sists to a file. Listing 2- 2 2 shows the production-database configuration. Listing 2- 2 2. The Production Data-Source Configuration production { dataSource. administrators. Configuring a JNDI data source in Grails couldn’t be simpler; specifying the JNDI name is the only requirement. Listing 2- 2 4 shows a typical JNDI setup. Listing 2- 2 4. JNDI Data-Source