Java Stammtisch Carol McDonald

Building a Grails Pet Catalog using Netbeans 6.5 and MySQL

This Catalog Sample app demonstrates the usage of Groovy and Grails to implement pagination of data sets for a Store Catalog.
download Catalog sample code

Overview of the Technologies and Frameworks in the Sample Application

Grails aims to bring the "coding by convention" paradigm to Groovy. It's an open-source web application framework that leverages the Groovy language and complements Java Web development.

Groovy is an agile and dynamic language for the Java Virtual Machine, it compiles to Java bytecode, and it combines popular features from languages such as Smalltalk, Python, and Ruby.

MySQL is the world's most popular open-source database. It offers consistently fast performance, high reliability and ease of use.

The NetBeans IDE 6.5 , in addition to full support of all Java platforms (Java SE, Java EE, Java ME, and JavaFX), has support for software development with PHP, Ajax and JavaScript, Groovy and Grails, Ruby and Ruby on Rails, and C/C++.  Netbeans 6.5 feature highlights for Groovy and Grails:

• Develop pure Groovy apps or use Groovy in Java SE projects
• Groovy editor with code completion, highlighting, and more
• Grails web application framework
• Open existing Grails applications without adding metadata
  

Grails is a Model-View-Controller based framework that simplifies the development of  web applications by reducing the need for configuration files and by generating a lot of the things needed in a database-backed Web application.

The Sample Application

The sample application displays an online catalog of pets sold in a pet store. The image below shows the Catalog Listing page, which allows a user to page through a list of items in a store.

Setting Things Up:

1. If MySQL is already not already installed, then download MySQL  and install it.
   
   
2. Download and install Netbeans 6.5 bundled with Glassfish v3 Prelude.
   
   
3. Download and install Grails.
   
   
4. Start NetBeans IDE.  
   
   
5. In the Netbeans IDE,  select Tools Options Groovy and set the location of the Grails package, which you installed using the Glassfish v3 updatetool.
   
   

Creating the Catalog Database Item table:

1. Download the sample code and extract its contents. You should now see the newly extracted directory as <sample_install_dir>/catalog, where <sample_install_dir> is the directory where you unzipped the sample package. For example, if you extracted the contents to C:\ on a Windows machine, then your newly created directory should be at C:\Catalog.
   
   
2. In the Netbeans IDE,  Click Open Project in the File menu and select the catalog directory you just unzipped.
   The file  "/catalog/grails-app/conf/DataSource.groovy" is configured for  MySQL.
   
   
3. Start the MySQL database as follows:
   • Click the Services tab in the NetBeans IDE.
   • Expand the databases node. You should see the MySQL server database in the list of databases.
   • Right-mouse click on the MySQL server database and select Start.
   
   
4. Create the catalog database as follows:
   • Right-mouse click on the MySQL server database and select Create Database.
   • Enter the database name petcatalog and userid root and password admin. This will open a New Database Connection window. Click O.K. to accept the displayed settings.
   
   
5. Create the tables in the MySQL catalog database as follows:
   • Expand the Drivers node. You should see a driver for the petcatalog database in the list of drivers.
   • Right-mouse click on the petcatalog driver and select Connect.
   • Right-mouse click on the petcatalog driver and select Execute Command. This will open up a SQL command window.
   • Copy the contents of the catalog.sql file in the <sample_install_dir>/Catalog directory and paste the contents into the SQL command window.
   • Click the Run SQL icon (Ctrl+Shift+E) above the SQL command window.
   
   
6. Ensure that the username and password settings in the catalog\grails-app\conf\DataSource.groovy file are the same as the corresponding property settings in NetBeans IDE 6.5 for your MySQL server database.

Running the Sample Code:

1. Run the project as follows:
   
   
   • Right click the catalog node in the Projects window.
     
   • Select Run Project.
     

When you run the project, your browser should display the opening page of the Sample Application (at http://localhost:8080/catalog/).

How to Create the Catalog Sample Application with Netbeans 6.5 and MySQL

Creating the Application

1. Run the "grails create-app" command from the IDE, by using  the IDE "Grails Application" project template to create a new Grails application as follows:
   
   
   • Choose File > New Project (Ctrl-Shift-N) and then select "Grails Application" from the "Groovy" category. Click Next.
     
   • In Project Name, type "catalog"; in Project Location, select the folder where the application will be created. Click Finish.
     
     
     The IDE runs the "grails create-app" command, showing the output in the Output window. The Projects window should show you this:
     
     
     Expand the folders and have a look at the source structure created by the IDE via the Grails scripts. Also look at the generated files and notice that many of them have default values filled in.
     
     

Configure Your Grails app data source for MySQL database

Configuring the data source is a simple matter of changing the values for the desired database and driver and placing the driver jar file in the <..>/lib directory.

1. Download MySQL Connector/J 5.1.6 from here.
2. Extract the bundle and copy the  "mysql-connector-java-5.1.6-bin.jar" to the "lib" directory of your Grails application: catalog\lib.
3. Double click on the file "catalog\grails-app\conf\DataSource.groovy" to edit in order to change the values for MySQL configuration. The updated file looks like this (changes highlighted in red):
   
   
   

   Code Sample from: catalog\grails-app\conf\DataSource.groovy

   dataSource {     pooled = true     driverClassName = "com.mysql.jdbc.Driver"     username = "root"     password = ""   // your mysql password here     dialect = "org.hibernate.dialect.MySQL5InnoDBDialect" } hibernate {     cache.use_second_level_cache=true     cache.use_query_cache=true     cache.provider_class='com.opensymphony.oscache.hibernate.OSCacheProvider' } // environment specific settings environments {     development {         dataSource {             dbCreate = "update"  // one of 'create', 'create-drop','update'             url = "jdbc:mysql://localhost/petcatalog"         }     }     test {         dataSource {             dbCreate = "update"             url = "jdbc:mysql://localhost/petcatalog"         }     }     production {         dataSource {             dbCreate = "update"             url = "jdbc:mysql://localhost/petcatalog"         }     } }

   
   Being in production, it's recommended to use InnoDB tables instead of MyISAM tables. This can be easily specified by using the dialect as explained here. More details about the contents of "DataSource.groovy" can be found here.

Creating the Domain Class

1. use the IDE to run the "grails create-domain-class" script as follows:
   • Right-click on the Domain Classes node and choose New > Grails Domain Class.
     
     
     
   • Name the domain class "Item" and click Finish. The "Item.groovy" domain class is created in the Domain Classes node.
     
     
     
2. Double click on the catalog\grails-app\domain\Item.groovy class to open it in the editor and add the attributes shown in red below to the item class.
   

   Code Sample from: catalog\grails-app\domain\Item.groovy

   class Item {   Long id   String name   String description   String imageurl   String imagethumburl   BigDecimal price }

The Model - Grails Domain Classes

The Model is your application's persistent business domain objects. A Grails domain object instance represents a row in a database table.  The command grails create-domain-class Item generates the Item.groovy class shown below corresponding to the item database table.

After model code generation you have to add the domain object's attributes and relationships.

Code Sample from: domain\Item.groovy

class Item {   Long id   String name   String description   String imageurl   String imagethumburl   BigDecimal price }

SQL  Sample for items table

CREATE TABLE item (   id INT NOT NULL,   product_id BIGINT NOT NULL,   name VARCHAR(30) NOT NULL,   description VARCHAR(500) NOT NULL,   imageurl VARCHAR(55),   imagethumburl VARCHAR(55),   price DECIMAL(14,2) NOT NULL,   primary key (id), );

Groovy with Grails dynamically generates getters and setters and the dynamic methods Item.save(), Item.delete(),  Item.list(), Item.get() to retrieve/update data from/to the db table.

Grails Object Relational Mapping (GORM) is currently built on top of Hibernate but you don't have to know Hibernate to use it.

Creating the Controller and Views

1. use the "grails generate-all" script to create a controller and views for the domain class as follows:
   • Right-click the Controllers node and choose New > Grails Controller.
     
     
     
   • The Item controller and Item views are generated.
     

The Controller

Controllers handle incoming http requests, interact with the model to get data and to process requests,  invoke the correct view, and direct domain data to the view for display.  In Grails, http requests are handled by Controller classes which are made up of one or more action methods that are executed on request and then either render a Groovy Server Page or redirect to another action. Grails routes requests to the controller action which corresponds to the URL mapping for the request. In Grails the default mapping from URL to action method follows this convention: http://host/app/controller/action/id .  For example the URL http://host/catalog/item/list calls the list action method in the item controller class shown below.     Grails Scaffolding provides a series of standardized Controller action methods for listing, showing, creating, updating, and deleting objects of a class.  These standardized actions come with both controller logic and default view Groovy Server Pages. The command generate-all Item generates the Item controller and the List, Show, Create, Edit Groovy Server Pages for the Item domain object. The ItemController list action renders a view with a paginated list of item objects.

Code Sample from: catalog\grails-app\controllers\ItemController.groovy

class ItemController { def index = { redirect(action:list,params:params) }   def list = {     if(!params.max) params.max = 10     [ itemInstanceList: Item.list( params ) ]   } . . .

When a URL has a controller but no action (e.g. http://localhost:8080/catalog/item/  ), Grails defaults to the index action. In the ItemController code the  index action method redirects to the list action.  The ItemController list action method calls the Item.list() method which returns an ArrayList of item objects retrieved from the item database table . If there are more than params.max objects in the table, Grails creates next and previous pagination links automatically. The itemInstanceList variable  is automatically made available to the view by the framework.

After executing code, actions usually render a GSP in the views directory corresponding to the name of the controller and action, for example the list action will render the catalog\grails-app\views\item\list.gsp .



Running the Application

The catalog Grails application is ready to run:.

1. Right-click the application and choose "Run".
   
   
2. When you run the project, your browser should display the opening page of the Sample Application (at http://localhost:8080/catalog/) . If the browser does not open automatically, paste the URL into a browser and then you'll see your application.
   
   
   
   
3. Click the "ItemController" link and you'll see this:
   
   

Modifying The View

The view layer generates a web page, using data from domain objects provided by the controller. In Grails, the view is rendered using Groovy Server Pages. 

Modifying the List View GSP

1. Copy the sub directory images from the sample application directory catalog\web-app\ to your application's catalog\web-app\  directory.
2. Double click on the file "catalog\grails-app\views\item\ list.gsp" to edit in order to modify the item list table. Make the changes highlighted in red):
   

   Code Sample from: grails-app\views\item\list.gsp

   <table>    <thead>      <tr> <g:sortableColumn property="name" title="Name" />         <g:sortableColumn property="imagethumburl" title="Photo" />         <g:sortableColumn property="price" title="Price" />      </tr>    </thead>    <tbody> <g:each in="${itemInstanceList}" status="i" var="itemInstance">         <tr class="${(i % 2) == 0 ? 'odd' : 'even'}"> <td>               <g:link action="show" id="${itemInstance.id}">                 ${fieldValue(bean:itemInstance, field:'name')}</g:link>            </td>            <td>               <img src="${itemInstance.imagethumburl}" alt="Pet" />            </td>            <td>               ${fieldValue(bean:itemInstance, field:'price')}            </td>         </tr>      </g:each>   </tbody>  </table> <div class="paginateButtons"> <g:paginate total="${Item.count()}" /> </div>

   
   The view uses instance variables set by the controller to access the data it needs to render the GSP.
   
   GSP has a GroovyTagLib similar to the  JSP tag library. <g: are GroovyTags.

<g:sortableColumn
          The sortableColumn tag renders a sortable column to support sorting in tables.
   
   <g:each in="${itemInstanceList}" status="i" var="itemInstance">
   
   loops through each object in the itemInstanceList variable, which is an ordered ArrayList of Item model objects,  and assigns each Item model object to the iteInstance variable.
   
   
   <g:link action="show" id="${itemInstance.id}"> ${fieldValue(bean:itemInstance, field:'name')} </g:link>
   the <g:link> GroovyTag creates an html anchor tag href based on the action, id, controller parameters specified. In this example it generates a link to the item/show/id action which when clicked will display the corresponding item details. For example this line will generate the following HTML for the variable item:

   <a href="/catalog/item/show/2">Friendly Cat</a>

   <img src="${itemInstance.imagethumburl}" alt="Pet" />
   sets the HTML img tag to the item's imagethumburl attribute. 
   
   ${fieldValue(bean:itemInstance, field:'price')}
   
   displays the value of the  item 's price attribute .
   
   
   <g:paginate total="${Item.count()}" />
   The paginate tag creates next/previous buttons and a breadcrumb trail to allow pagination of results using the Item.count() domain method.
   
   
3. Save your modifcations in the editor. Click reload current page on your browser. The Item List page should now look like the image below:
   
   

The Show Action Method

In Grails the mapping for the URL http://host/item/show/1  ( http://host/controller/action/id )  will route to the show action in the ItemController passing 1 to the method as the id of the params parameter hash. The show action of the ItemController class is shown below. The ItemController show action renders a view showing the details of the item object corresponding to the id parameter.

Code Sample from: grails-app\controllers\ItemController.groovy

def show = {    def itemInstance = Item.get( params.id )    if(!itemInstance) {       flash.message = "Item not found with id ${params.id}"       redirect(action:list)    }    else { return [ itemInstance : itemInstance ] }  }

The show action method  calls the Item.get() method which queries the items table returning the itemInstance instance variable corresponding to the item with the attribute id (primary key) equal to the  id parameter. This is the equivalent of the following sql : select * from items where id='1' . The itemInstance variable is automatically made available to the Show view by the framework.

Modifying the Show View GSP

After executing code in the action, the show action renders the catalog\grails-app\views\item\show.gsp.

1. Double click on the file "catalog\grails-app\views\item\show.gsp" to edit in order to modify the item show view. Make the changes highlighted in red below:
   
   

   Code Sample from: catalog\grails-app\views\item\show.gsp

   <table>      <tbody> <tr class="prop">              <td valign="top" class="name">Name:</td>              <td valign="top" class="value">${itemInstance.name}</td>          </tr>          <tr class="prop">              <td valign="top" class="name">Description:</td>              <td valign="top" class="value">${itemInstance.description}</td>          </tr>          <tr class="prop">              <td valign="top" class="name">Photo:</td>              <td><img src="${itemInstance.imageurl}" alt="Pet" /></td>          </tr>          <tr class="prop">              <td valign="top" class="name">Price:</td>              <td valign="top" class="value">${itemInstance.price}</td>          </tr>      </tbody>  </table>

   
   ${itemInstance.description}
   
   displays the value of the  item 's description attribute.
   
   <img src="${itemInstance.imageurl}" />
   sets the HTML image tag for the item's imageurl attribute.
   
   ${itemInstance.price}
   displays the value of the  item's price attribute.
   
   
   
2. Save your modifcations in the editor. Click reload current page on your browser.
   The image below shows the resulting page for the url http://host/catalog/item/show/1, which displays the item 1's details:
   
   
   
   

Layouts

Grails layouts  let you put common html on multiple views (for example page headers,  footers, sidebars).  Default layout templates are in the views layouts directory with a file name corresponding to the controller, or you can associate a view with a layout using the "layout" meta tag to your page:

<meta name="layout" content="main">

To replace the Grails logo with a title and parrot image at the top of the Pet Catalog pages,  put this table in the catalog\grails-app\views\layouts\main.gsp  layout page:

Code Sample from: app/views/layouts/main.gsp

<table>   <tr>    <td>Pet Catalog</td>    <td>      <img src="${createLinkTo(dir:'images',file:'pet_logo.jpg')}"/>    </td>  </tr> </table>

The image below shows the result on the show page after modifying main.gsp layout page :





Running you Grails app on Glassfish v2:

Netbeans does not yet support deploying grails app directly to Glassfish, but you can create a WAR file and deploy it on Glassfish as follows:

1. If Jetty is running stop it: click on the IDE Services Tab, Under the Jetty server right-click on the catalog app and select Stop
   
   
2. Right-click on the catalog project node and choose Create War File.
   
   
3. Rename the catalog-0.1.war file to catalog.war. Copy the  catalog.war file from your catalog directory to your Glassfish installation glassfish-v2ur2\domains\domain1\autodeploy  directory. Start Glassfish.
   
   Enter the URL  http://localhost:8080/catalog/  in your browser, you should see the home page of the Sample Application.
   
   

Running you Grails app on Glassfish v3:

GlassFish v3 Prelude is a lightweight Web 2.0 development and deployment platform built on a modular OSGi-based architecture. Developers can benefit from a dynamically extensible and embeddable platform with support for existing Java Web technologies, JRuby, and Groovy. GlassFish Support For Grails Framework adds the Grails framework to the GlassFish application server and allows development and easy deployment of Grails applications. Applications can be deployed in shared or standalone mode. Shared mode allows library reuse and results in much smaller war files.

1. Install the Grails package to Glassfish v3 using the updatetool.   Start the GlassFish Update Center by issuing the following command: GF_install\updatecenter\bin\updatetool. Check the GlassFish Support for Grails Framework checkbox in the GlassFish Update Center and click Install.
2. Read the Glassfish Getting started with Grails.
   

Conclusion

This concludes the sample application which demonstrates how to work with Groovy and Grails  to page through a list of  Item Model objects which are retrieved using Item Controller action methods, and displayed using Item View GSPs.

References

•  MySQL
• Grails framework
  
• Groovy
• Introduction to the Grails Web Framework with Netbeans