about java, groovy, grails, software development and more...

Basics of Java's Garbage Collection

2011-03-15T11:52:00.000-07:00

Garbage collection:

Every java program runs as a process and is allocated some memory. The memory allocated to the java process is called process heap.

The java heap i.e. the java object heap, is part of the process heap. The java object heap (also called just java heap) store the java objects i.e. object instances. The java heap can be configured using the several command line parameters.

Garbage collection is the mechanism used by java to reclaim or recollect the space occupied by objects that are not reachable from the program. This is necessary to ensure that the application does not run out of memory.

An object that cannot be reached from any reference within the running program is eligible for garbage collection.

The simplest form of GC iterates through all the references within the running program and marks all the objects that are reachable via those references directly or indirectly. At the end of this process, any object that is not marked, is considered garbage and becomes eligible for collection.

It’s obvious, that in case of this particular algorithm, the duration of the GC is relative of the number of objects referenced by the program.

Generational Collection

In most applications, a larger number of objects are short-lived. i.e. there are relatively few objects that are created when the application is initialized and live until the end; which means, it makes sense for the GC to focus on the objects that are short-lived.

To leverage this common property noticed in most applications, JVM manages the memory in generations i.e. it divides the object memory into groups depending on the age of the objects i.e. short-lived objects would stay in the young-generation and longer-living objects would be moved to the tenured-generation. New objects are allocated in the young-generation and longer-living objects that have survived a good number of collections are then moved to the tenured (older) generation.

There is also a permanent-generation where metadata for classes and methods are stored. The default permanent generation is generally enough, but applications that need to load a large number of classes may want to increase the perm-gen size. This can be done using the XX:MaxPermSize option.

But how does this grouping help?

As we have already seen, the amount of time spent in GC depends on the number of live objects. Since most objects in the young-generation would be short-lived (die quickly after their creation), running a GC on this area should not take very long. There would be only a few live objects that would need to be copied, and hence the GC pause would be significantly small. Also, the young-generation should be optimally sized which would deter the need to garbage collect the objects too soon. If the young-generation is too small, the GC would have to be called too soon, which means a lot of objects in the area would still be alive. The purpose would be defeated. Hence, the young-generation should be big enough to leverage the infant mortality (i.e. most objects will die soon – but not too soon). The young-generation should be around 1/3^rd of the total heap size.

Minor collections:

The young-generation is divided into an area called ‘eden’ where new allocations are made initially and 2 ‘survivor spaces’ which play the part of a copying collector. When the ‘eden’ becomes full, a minor collection takes place.

The minor collection collects the dead objects from eden and any live objects are copied from the eden into one of the ‘survivor space’. If a minor collection runs again, and the eden is again found full, the live objects are copied from eden and the 1^st survivor space to the 2^nd survivor space, so on and so forth.

Thus every minor collection will copy live object from Eden and one of the survivor spaces into the second survivor space. Also, any live objects that have survived a certain number of collections are promoted to the tenured generation.

Note: In case of such generational collection, the collector does not visit the tenured generation objects referred by the young generation objects. There are ways to track inter-generational references (out-of-scope for the purpose of this article)

Major collections:

If the minor collection is not able to reclaim significant amount of memory, a major collection takes place on higher generations. Such collections collect both the generations i.e. the young as well as the tenured.

Note: When we call System.gc(), a major collection is called through. Since major collections take a longer time to run, we should be very careful about using System.gc() since it could have a performance impact.

Collection Strategies:

There are a couple of GC strategies that you can choose from to improve the performance/throughput.

1. Serial collector: What we discussed until now is the serial way of collection also known as ‘Stop-the-world’ collection. As the name suggests, program execution is halted when this kind of collector runs. Advantage is that it guarantees that no new object is allocated and object reachability does not change until the collection finishes. Disadvantage is that program execution is paused. This collection strategy is simplest and least complex. This strategy is useful for applications that are not interactive.

2. Parallel collector: Also called ‘throughput collector’. In this case, parallel collection is done for the young-generation i.e. multiple threads are used for minor collections. The tenured generation collection still remains serial. New object allocations are allowed while collection is being carried out. Various locking mechanisms are used to achieve this kind of parallel behavior. This strategy is preferred in case of multiple processors. This strategy can be enabled using the -XX:+UseParallelGC option. This strategy is suitable for applications with a large set of short-lived data (a large young generation) and multiple processors.

3. Incremental collector: In this strategy, GC is performed in phases. And program execution is resumed between these phases. This strategy can be enabled using the -XX:+UseTrainGC option. This is not being used after Java 1.4 versions.

4. Concurrent collector: In this strategy, most of the collection takes places in parallel with program execution. Pause periods are very short. Concurrent collections are done for both minor and major collections. This strategy can be enabled using the -XX:+UseConcMarkSweepGC option. This strategy is suitable for applications with a large set of long-lived data (a large tenured generation) and multiple processors.

How can GC be monitored?

The following command line options will output the details of GC:

-verbose:gc

-XX:+PrintGCDetails

-Xloggc:gc.log

Heap and generation sizes

Throughput is the percentage of the total run time not spent performing GC.

Pauses are the times when the application execution stops to allow GC to run.

Different applications have different requirements as far as the above two metrics are concerned.

The throughput of the application depends on the memory available. If the generations are small, lesser time will be spent in GC, hence throughput would be higher. Thus throughput is inversely proportional to the amount of memory available. Since collections occur when generations fill up, throughput is inversely proportional to the amount of memory available

Total available memory is the most important factor affecting garbage collection performance.

When the JVM initializes, some space is reserved for the java object heap. This heap size can be specified using the -Xmx option.

-Xms specified the minimum heap size and –Xmx specifies the maximum heap size.

If –Xms is less than –Xmx, then some remainder is allocated to a so-called ‘virtual space’.

This virtual space is adjusted after each collection to maintain the ratio of the ‘available space’ to the ‘space used by live objects’ within a range.

This range can be specified using the - XX:MinHeapFreeRatio and –XX:MaxHeapFreeRatio parameters.

Some other interesting options are :

-XX:NewRatio: ratio of the sizes of the young and old generations.

-XX:NewSize: size of the young generation in bytes

-XX:SurvivorRatio: ratio of the sizes of the eden and the survivor spaces.

-XX:GCTimeRatio: specifies a throughput goal. This option specifies the percentage of time to be spent in program execution instead of garbage collection.

-XX:MaxGCPauseMillis: specifies a max pause goal. Specifies the maximum time the program execution can be halted to allow GC to finish in milliseconds.

-XX:+DisableExplicitGC: If this option is enabled, any call to System.gc() would not result into a garbage collection cycle.

For a detailed list of GC tuning options, visit this link.

Custom error page for your grails application

2011-03-04T01:27:00.000-08:00

I recently added a custom error page to my application, so that the users don't see the stacktrace and are shown a friendly message in case of a runtime error.

I simply added a controller that checks for the environment in which the application is running, and accordingly renders different views:

import grails.util.*;

class ErrorsController {
    def serverError = {
        def env = GrailsUtil.environment;

        if(env == "production")
            render(view:'/serverError')
        else
            render(view:'/error')
    }

    def notFound = {
        render(view:'/notFound')
    }
}

Added a new view file 'serverError.gsp' at \grails-app\views:

<html>
    <head>
        <title>Error on the server</title>
        <meta name="layout" content="main" />
    </head>
    <body>

      <h1 style="margin-left:20px;color:#006dba;" >
            An unexpected error occurred while processing your request. The admin team has been notified.             <br/>
            Please try again, or
              <a href="mailto:abc@xyz.com?
              subject= [${GrailsUtil.environment}] Application Error occured : '${exception?.message?.encodeAsHTML()}'">
              contact
              </a> the IT team

      </h1>

    </body>
</html>

To delegate the request to the ErrorController, add the following line to the UrlMappings.groovy file:

"500"(controller: "errors", action:"serverError") .

Handling 404 Not Found:

If you want to handle the 404 Not Found situation specifically, add the following line to your UrlMappings.groovy file (which you can find at \grails-app\conf)

class UrlMappings {

   static mappings = {
       "/$controller/$action?/$id?"{
           constraints {
               // apply constraints here
           }
       }

       "/"(view:"/index")
       "500"(controller: "errors", action:"serverError")
         "404"(controller:"errors", action:"notFound")
   }
}

The view file notFound.gsp looks like this:

<html>
    <head>
        <title>Page not found</title>
        <meta name="layout" content="main" />
    </head>
    <body>

       <h1 style="margin-left:20px;">
         <p style="margin-left:20px;width:80%">
            Page Requested not found, please check the URL
         </p>
       </h1>
    </body>
</html>

Get started with Spring JMS using ActiveMQ

2011-03-03T02:32:00.000-08:00

Messaging is a mechanism to create and exchange data/information/objects within/between applications. An application that generates some useful data can send it's messages (objects) to an agent and these messages (objects) can then be read from another application. JMS is a Java API that enables applications to be able to communicate with each other using the mechanism described above.

You can read more about JMS here.

In this article, we will see how you can quickly start using JMS using the Spring JMS framework. Spring provides template based APIs which greatly simplify the use of JMS. A lot of work is done behind the scenes which saves the developer time to concentrate on the business requirement.

We will take a look at the important Spring JMS classes and apis as we go through an example. So let's get started!

Step 1: Download and install the JMS provided (ActiveMQ)
The first thing you would need is a JMS provider (which is an implementation of the JMS interface for a MOM - Message Oriented Middleware). There are a lot of providers available, such as Apache's ActiveMQ, IBM's WebSphere M, JBoss messaging, RabbitMQ, Oracle AQ and many others.

For the purpose of this tutorial we will be using ActiveMQ. You can download the zip file and install it using the instructions documented here. Start the provider (open a command prompt to the bin folder of the installation and type 'activemq').

To test the setup, browse to : http://localhost:8161/admin/

To be able to send and receive messages asynchronously, we would first need a queue, which is a destination for the messages. Let's create a fresh queue for our sample application.
Go to the 'Queues' menu on the top of the admin page, and create a new queue called 'orderQueue'.

Step 2: Create a Spring project

You can create a spring project manually or use the STS (SpringSource Tool Suite) like i am using. This IDE helps you get started with Spring projects within no time.
Create a 'Spring Utility Project' using 'File -> New -> Spring Template Project -> Simple Spring Utility Project'.

Type the project name , say 'OrderApp' and choose a base package say - com.test.orderapp

This project type uses maven for dependency management. We would need to add a few dependencies for using spring-jms and activemq.

Open the 'pom.xml' at the root of the project and add the following dependencies:

      <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-jms</artifactId>
            <version>${spring.framework.version}</version>
        </dependency>
        <dependency>
            <groupId>org.apache.activemq</groupId>
            <artifactId>activemq-all</artifactId>
            <version>5.4.2</version>
        </dependency>

Note: Update the version for activemq as per the installation you have used in Step 1.

Step 3: Configure beans in application context
Edit the Spring context file app-context.xml at \src\main\resources\META-INF\spring and add the following to it:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns:context="http://www.springframework.org/schema/context"
     xmlns:jms="http://www.springframework.org/schema/jms"
      xsi:schemaLocation="http://www.springframework.org/schema/beans
                           http://www.springframework.org/schema/beans/spring-beans.xsd
                           http://www.springframework.org/schema/context
                           http://www.springframework.org/schema/context/spring-context.xsd
                           http://www.springframework.org/schema/jms
                           http://www.springframework.org/schema/jms/spring-jms.xsd
                           http://activemq.apache.org/schema/core
                           http://activemq.apache.org/schema/core/activemq-core.xsd">

    <context:component-scan base-package="com.test.orderapp" />
    <context:annotation-config/>

    <bean id="connectionFactory" class="org.apache.activemq.ActiveMQConnectionFactory">
        <property name="brokerURL">
            <value>tcp://localhost:61616</value>
        </property>
    </bean>

    <bean id="destination" class="org.apache.activemq.command.ActiveMQQueue">
        <constructor-arg value="orderQueue"/>
    </bean>

    <bean id="jmsTemplate" class="org.springframework.jms.core.JmsTemplate">
        <property name="connectionFactory" ref="connectionFactory" />
        <property name="defaultDestination" ref="destination" />
    </bean>
</beans>

Let's take a closer look at the beans we've defined in the spring xml.

1. connectionFactory:

A connectionFactory is required to create a connection to the jms provider i.e. activemq. The javax.jms.ConnectionFactory creates a javax.jms.Connection object, which then creates a javax.jmx.Session object which is used for the message exchange between the application and the jms provider. You need to specify the brocker URL , i.e. the URL at which the jms provider is listening.

2. destination:

The destination specifies the queue name to which the messages will be sent. Messages will be stored in and consumed from the destination specified. Destinations can, in general, be of two types: Queue and Topic. Queues represent a point-to-point messaging mechanism whereas Topics represent a publisher-subscriber sort of messaging where a single message is sent to multiple consumers. (we will be working with only queues in this tutorial)

3. jmsTemplate:

This is the class that does most of the jms related work, it creates connection factories, creates Sessions, takes care of the transactions, provides apis for creating and sending messages of different types. The jmsTemplate bean here takes a reference to the connectionFactory and a defaultDestination to which it would direct the messages. If you don't specify any defaultDestination, you can pass the destination in the 'send' methods that jmsTemplate provides. The important methods provided by jmsTemplate are : send, receive, convertAndSend and receiveAndConvert

Step 4: Create the domain class
We will be creating a simple domain class called 'Order' in a package com.test.orderapp.domain as follows:
package com.test.orderapp.domain;

public class Order {

   private int orderId;
   private int customerId;
   private double price;
   private String orderCode;

   public Order(int orderId, int customerId, double price, String orderCode){
       this.orderId = orderId;
       this.customerId = customerId;
       this.price = price;
       this.orderCode = orderCode;
   }

   public int getOrderId() {
       return orderId;
   }
   public void setOrderId(int orderId) {
       this.orderId = orderId;
   }
   public int getCustomerId() {
       return customerId;
   }
   public void setCustomerId(int customerId) {
       this.customerId = customerId;
   }
   public double getPrice() {
       return price;
   }
   public void setPrice(double price) {
       this.price = price;
   }
   public String getOrderCode() {
       return orderCode;
   }
   public void setOrderCode(String orderCode) {
       this.orderCode = orderCode;
   }
}

Step 5: Write the code to send the objects

We will create a simple service class that creates new orders given some information and then sends them.

package com.test.orderapp.producer;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import com.test.orderapp.domain.Order;

@Service("orderService")
public class OrderService {
    static int orderSequence = 1;

    @Autowired
    private OrderSender orderSender;
    public void setOrderSender(OrderSender orderSender){
        this.orderSender = orderSender;
    }

    public void sendOrder(int customerId, double price)
    {
        Order order = new Order(orderSequence, 2, price, "ordercd"+ orderSequence++);
        orderSender.sendOrder(order);
    }
}

Nothing special about the service class. We are wiring the OrderSender class into the service class.
The orderSender class is jms aware and has all the logic to convert and send the domain object as a jms message.

OrderSender.java :-

package com.test.orderapp.producer;

import javax.jms.JMSException;
import javax.jms.MapMessage;
import javax.jms.Message;
import javax.jms.Session;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.jms.core.JmsTemplate;
import org.springframework.jms.core.MessageCreator;
import com.test.orderapp.domain.Order;

public class OrderSender {

    @Autowired
    private JmsTemplate jmsTemplate;

    public void sendOrder(final Order order){
        jmsTemplate.send(
        new MessageCreator() {
          public Message createMessage(Session session) throws JMSException {
               MapMessage mapMessage = session.createMapMessage();
               mapMessage.setInt("orderId", order.getOrderId());
               mapMessage.setInt("customerId", order.getCustomerId());
               mapMessage.setDouble("price", order.getPrice());
               mapMessage.setString("orderCode", order.getOrderCode());
               return mapMessage;
          }
        }
        );
        System.out.println("Order sent - id: "+ order.getOrderId());
    }
}

The OrderSender uses the JmsTemplate's send method to send the object. Notice the use of the MessageCreator class. You can send different types of messages via JMS eg: TextMessage, ObjectMessage, MapMessage (all part of the java.jms package) The most preferred way to send complex domain objects is to use MapMessage to which you can add all the fields of your domain object as key-value pairs. The MessageCreator class is a callback interface for creating a message using the Session object that is passed as a parameter to the createMessage method.
Also note, that we are not specifying the destination in the send method since we have defined a defaultDestination for the jmsTemplate in the spring context. In case you are not going the default way, you can pass a string representing the destination as the first parameter to the jmsTemplate.send() method
for eg:
jmsTemplate.send( "orderQueue", new MessageCreator() ..... )

There are other ways to send messages such as MessageConverter which can also be used to convert between Java objects and JMS messages. The convertAndSend and receiveAndConvert methods of the jmsTemplate class delegate the conversion to the MessageConverter interface. We are not using MessageConverter in this tutorial. Some other time maybe...

Let's update the app-context.xml file to declare two additional bean definitions:

<bean id="orderService" class="com.test.orderapp.source.OrderService" />
<bean id="orderSender" class="com.test.orderapp.source.OrderSender" /

Step 6: Test the message producer
Let's check if we are actually able to send any messages to the ActiveMQ 'orderQueue'. We will create a simple TestJms class as follows:

package com.test.orderapp.runner;
import org.springframework.context.ApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;
import com.test.orderapp.producer.OrderService;

public class TestJms {
    public static void main(String[] args) {

        ApplicationContext ctx = new ClassPathXmlApplicationContext("app-context.xml");
        OrderService orderService = (OrderService) ctx.getBean("orderService");

        for(int i =1; i<=5; i++)
            orderService.sendOrder(1+i, 10.0D+i);
    }
}

At this point, if you run the TestJms class, 5 messages would be sent to the 'orderQueue' queue. If you browse to the http://localhost:8161/admin/queues.jsp page you should see 5 messages enqueued on orderQueue.

Step 7: Consuming JMS Messages

Listening to the jms messages is in fact easier than sending them. All we need to do is define a jms Listener Container in the spring context to which we pass the connectionFactory bean which specifies the jms provider, a reference to the destination which specifies the queue name and we also specify here, which method from which bean needs to be called when a message is recieved.

Add the following to the app-context.xml file:

<jms:listener-container connection-factory="connectionFactory">
<jms:listener destination="orderQueue" ref="orderListener" method="orderReceived" />
</jms:listener-container>

Create a class OrderListener as follows:

package com.test.orderapp.listener;
import java.util.Map;
import org.springframework.stereotype.Component;
import com.test.orderapp.domain.Order;

@Component
public class OrderListener {

    public void orderReceived(Map<String, Object> message) throws Exception {
        int orderId = (Integer) message.get("orderId");
        int customerId = (Integer) message.get("customerId");
        double price = (Double) message.get("price");
        String orderCode = (String) message.get("orderCode");
        Order customer = new Order(orderId, customerId, price, orderCode);
        System.out.println("Order received: "+ orderId + ", customerId: "+ customerId + ", price: "+ price);
    }
}

Simple.

Let's run the TestJms class once again, this time we should see some prints from the OrderListener class too.
Pretty cool, isn't it!

Well, that brings us to the end of the introductory article to Spring JMS, i hope you can now appreciate how much easier it is to write JMS based applications using Spring.

Hope you find this article useful.
Happy coding!

Download the source code of the sample application : OrderApp.rar

Integrating Grails and Hudson

2011-02-25T03:08:00.000-08:00

The best way to ensure consistent code quality and system stability is to integrate your application with a Continuous Integration system. Hudson is one such CI system.

In this tutorial, i will give a small demo on how to integrate Grails with Hudson. I will assume you are familiar with the grails technology and have some basic idea of what continuous integration systems are.
Note: This is not a tutorial on Hudson!

Step 1: Download and deploy hudson.war
Download hudson from the hudson home page. Deploy the war file in your favorite web-server. I am using tomcat for the purpose of this demo. Place hudson.war in the %tomcat_installation%/webapps folder.

Tip: You may want to set an environment variable HUDSON_HOME pointing to a location of your choice where all the hudson jobs, plugins, reports, and all configurations would be stored. By default, hudson places everything in the user's home directory.

Start the web-server and browse to the url : http://localhost:8080/hudson (assuming your server is running on 8080)

Step 2: Install plugins
On the panel on the left side, navigate to 'Hudson -> Manage Hudson -> Manage Plugins'

In the 'Available' tab, look for the following

plugins, tick the checkboxes and install them.

1. Grails plugin
2. Groovy plugin
3. Email-ext plugin
4. Violations plugin (for static code analysis)
5. Cobertura plugin (for code coverage)

Restart the web-server after installations.

We will discuss why we need these plugins shortly.

Step 3: Configure Hudson
Navigate to 'Hudson -> Manage Hudson -> Configure System'.
Set up 'JDK' , 'Grails Builder'. i.e. set up the JAVA_HOME and GRAILS_HOME paths in Hudson to your local installations.

Step 4: Create and configure a new job for your Grails application
Navigate to 'Hudson -> New Job' and choose 'Build a free-style software project'.

To configure the job Open the job, and click on 'Configure' on the left-hand-side panel.

1. Source code Management: Configure the source code. If you are using SVN or CVS, add the urls, credentials and ensure that the src code is available.

2. Build Triggers: You need to decide when you would want to run the builds against the src code. You have options such as 'Polling the SCM' which would keep polling the SCM and fire a build everytime there is a checkin ( you can also specify a cron expression to configure the polling frequency) or you could choose to build the project at regular periods. etc.

3. Build: Add a build step (choose 'Build with Grails').
Choose the grails installation you had setup in Step 3.
Next choose a target - such as 'compile'.
You can add multiple targets seperated by commans.

You can choose the port number, the work directory etc.
Let's say you want to run both: 'grails clean' and 'grails compile' commands:
So your target should now look like: 'clean compile'

You can also setup the 'Post-build Actions' to generate
JUnit test reports, and send email notifications once the
build is done. Save the configuration. You're ready to go!

Click 'Hudson -> 'Project name' -> Build Now.

You can check the output of the build process by clicking on the link shown in the 'Build History' panel on the left. Then click 'Console Output'.

Step 5: Static code analysis
Grails has a plugin by CodeNarc for static code analysis. You will first need to install this plugin in your grails application using the command:

grails install-plugin CodeNarc

And add the following to the Config.groovy file, so that we can use the 'Violations' plugin in hudson to analyze the xml reports generated by this plugin.

codenarc {
        reportName = 'CodeNarc.xml'
        reportType = 'xml'
   }

We would also need to add an additional build step in our job. Add the target 'codenarc' and save the configuration.

Also, in the the 'Post-build Actions' section, check the box agains 'Report Violations' and specify the name of the xml file as follows:

Step 6: Publishing test results and code coverage results
For running tests, we would need to add a new target here 'test-app'. If you want to use code coverage as well. You first need to install the code-coverage plugin which can be done as follows:

grails install-plugin code-coverage

Then set up a new build step and add "test-app -coverage -xml" -with the quotes- in the target field. ( if you don't want to run code-coverage just use 'test-app' as the target )

Also, set up the code coverage report publication in the 'Post-build Actions' section. The code-coverage xmls can be found in the 'target/test-reports/cobertura/*.xml' folder.

That's all you need to do, and a build will be fired everytime there's a checkin, tests would be run, test reports would be published, code-coverage reports would be generated and code analysis reports would also be generated. Well, that's quite a bit for half-an-hour's effort :) Neat!

There's a lot of plugins available in Hudson that you can explore to suite your needs.

Hope you find this article useful.

Happy coding!

Exploring BootStrap.groovy

2011-02-24T02:38:00.000-08:00

You may come across a scenario where you want to carry out a task every time your application starts or stops.

You just need to peep inside your grails-app/conf folder to find a groovy file called BootStrap.groovy.
BootStrap.groovy is a simple plain groovy script with two important closures : 'init' and 'destroy'. These closures are called upon when the application starts up and shuts down respectively.

But. BUT.. The 'destroy' closure is not guaranteed to be called at all times. The destroy closure will be called if your application exits gracefully. But if the web-server crashes or the machine reboots chances are, the 'destroy' closure would not be called. So please do not rely heavily on this one.

Let's consider a scenario where you want to send out an email to your team every time your application starts up or shuts down.

Step 1: Install the mail plugin
Let's use the grails mail plugin to send emails. To install the plugin use the command:

grails install-plugin mail

Step 2: Initialize mail properties in Config.groovy
Add some parameters to your Config.groovy file:

grails {
    mail {
        host = "smtpserver"
        port = 123
        username = 'username'
        password = 'password'
        props = ["mail.smtp.auth":"true",
                 "mail.smtp.socketFactory.port":"465",
                 "mail.smtp.socketFactory.class":"javax.net.ssl.SSLSocketFactory",
                 "mail.smtp.socketFactory.fallback":"false"]

   }
}
grails.mail.default.from = "abc@xyz.com"
grails.mail.disabled=true
app.startup.mail.to = "abc@xyz.com"
environments {
    production {
        grails.serverURL = "http:///localhost:8080/BootStrapTest"
        grails.mail.disabled=false
    }
    development {
        grails.serverURL = "http://localhost:8080/BootStrapTest"
    }
    test {
        grails.serverURL = "http://localhost:8080/BootStrapTest"
    }

}

[ We want to send emails only if the application starts-up or shuts-down in production mode (ofcourse) ]

STEP 3: Update BootStrap.groovy
Edit the BootStrap.groovy file to send emails as follows:

import org.codehaus.groovy.grails.commons.ConfigurationHolder;
import java.util.*;
import java.text.SimpleDateFormat;

class BootStrap {

    def mailService

    def init = { servletContext ->
        println "Application starting up... "

        def toMail = ConfigurationHolder.config.app.startup.mail.to
        def mailSubject = "Application starting up on ${InetAddress.localHost.hostName}";
        String mailBody = '''

            Application started at ''' + new SimpleDateFormat("dd-MMM-yyy hh:mm:ss").format(new Date()) + '''<br/>''' +
            '''<a href=' ''' + ConfigurationHolder.config.grails.serverURL + ''' '> ''' +
            ConfigurationHolder.config.grails.serverURL + '''</a><br/><br/><br/>

            @Note : This is an automatically generated email.
        '''

        sendNotification(toMail, mailSubject, mailBody )
    }

    def destroy = {
        println "Application shutting down... "

        def toMail = ConfigurationHolder.config.app.startup.mail.to
        def mailSubject = "Application starting up on ${InetAddress.localHost.hostName}";
        String mailBody = '''

            Application shutting down at ''' + new SimpleDateFormat("dd-MMM-yyy hh:mm:ss").format(new Date()) + '''<br/>''' +
            '''<a href=' ''' + ConfigurationHolder.config.grails.serverURL + ''' '> ''' +
            ConfigurationHolder.config.grails.serverURL + '''</a><br/><br/><br/>

            @Note : This is an automatically generated email.
        '''

        sendNotification(toMail, mailSubject, mailBody )
    }

    def sendNotification(String toMail, String mailSubject, String mailBody)
    {
        println "### sending email ###"

        mailService.sendMail {
            to toMail
            subject mailSubject
            body mailBody
        }

    }
}

Well, that's about it!

STEP 4: Create a war and deploy it
Create a war file using the command:

grails war

Deploy the war in your favourite web-server and test the print statements and emails.

You could do any startup/shutdown tasks, cleanup etc you want to do using these two closures.
Hope you find this article useful.

Happy coding!

Download the sample code : bootstrap.rar

Problem setting the grails proxy ?

2011-02-21T00:39:00.000-08:00

Issue

If you are using grails on a windows box, you may face an issue while setting the grails proxy using the 'grails add-proxy' command. This is because of the way windows treats any paramters that you pass using the -- option and sets the host name and the port to boolean values.

Resolution

You just need to pass your parameters in double quotes.
Example:

grails add-proxy proxy1 "--host=someproxyserver" "--port= 8080"
grails set-proxy proxy1

Pretty easy!

(Your proxy settings can be found in the %user_home%\.grails\ProxySettings file.
You can try changing this file with correct values manually also)

JDBCException due to stale connections in Grails

2011-02-10T20:56:00.000-08:00

Issue
If your grails application remains idle for too long or the database connections remain idle for too long or the database is restarted you may see the following exceptions:

ERROR org.hibernate.util.JDBCExceptionReporter - No more data to read from socket
ERROR org.hibernate.util.JDBCExceptionReporter - OALL8 is in an inconsistent state
ERROR org.hibernate.util.JDBCExceptionReporter - Io exception: Broken pipe
ERROR org.hibernate.util.JDBCExceptionReporter - Already closed.

These issues are intermittent, that is, they may disappear when you try hitting again.
This issue occurs because the application tries to use a database connection that has become stale and should have been evicted.

Resolution
This problem can be fixed by overriding the default datasource with a DBCP BasicDataSource and setting some DBCP properties.

For my applicatin, i have encrypted my database password used a codec.
This is how my DataSource.groovy looks:
dataSource {

            loggingSql = false
            username = "USERNAME"
            password = "qDKJkZFGtPK2lj54M11OMQ00"
            dbCreate = "update"
            driverClassName = "oracle.jdbc.OracleDriver"
            passwordEncryptionCodec = "com.myapp.encryption.DESCustomCodec"
            url = "jdbc:oracle:thin:@ldap...."
        }

Grails uses the class specified in the property 'passwordEncryptionCodec' to decode the database password.

To fix the jdbc exceptions we are facing, we need to override the datasource bean in \grails-app\conf\springspring\resources.groovy as follows:

import org.apache.commons.dbcp.BasicDataSource
import org.codehaus.groovy.grails.commons.ConfigurationHolder as CH
import org.codehaus.groovy.grails.commons.ApplicationHolder as AH

beans = {
    ssoAuthenticationProvider(SSOAuthenticationProvider) {
        userDetailsService = ref("userDetailsService")
    }

        dataSource(BasicDataSource) {
        def application = AH.application

        if(CH.config.dataSource.passwordEncryptionCodec){
           def codec = application.classLoader.loadClass(
                              CH.config.dataSource.passwordEncryptionCodec)
           password = codec.decode(CH.config.dataSource.password)
        }
        else{
            password = CH.config.dataSource.password
        }
        username = CH.config.dataSource.username
        driverClassName = CH.config.dataSource.driverClassName
        url = CH.config.dataSource.url
        minEvictableIdleTimeMillis=1800000
        timeBetweenEvictionRunsMillis=1800000
        numTestsPerEvictionRun=3
        testOnBorrow=true
        testWhileIdle=true
        testOnReturn=true

        if(driverClassName.contains('oracle'))
           validationQuery="SELECT 1 FROM DUAL"
    }
}

If a passwordEcryptionCodec is specified, the corresponding class is loaded and the password is decoded and then assigned. We then populate the username, driverClassName, and jdbc url of the new bean.
We also set the dbcp properties
minEvictableIdleTimeMillis: The minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor
numTestsPerEvictionRun: The number of objects to examine during each run of the idle object evictor thread
testOnBorrow: The indication of whether objects will be validated before being borrowed from the pool
testWhileIdle: The indication of whether objects will be validated by the idle object evictor
testOnReturn:The indication of whether objects will be validated before being returned to the pool.
validationQuery: The SQL query that will be used to validate connections from this pool before returning them to the caller

Find more DBCP options here.

Note: if you are using different databases for uat, dev and production, you may have to accordingly set the validationQuery per environment. ( For eg, the above query may not work for a dev environment which uses hsql database) Or you could choose to override the bean only in a production database. Whatever suits you best.

java.lang.NoClassDefFoundError when sending async emails in Grails

2011-02-10T19:47:00.000-08:00

Issue
Exception while sending emails in production environment.

If you are trying to send emails from your application asynchronously, using the Mail plugin, in the production environment you may see an exception like:

java.lang.NoClassDefFoundError: org/springframework/mock/web/MockHttpServletRequest

This is because of a bug in the Mail plugin. This plugin uses the MockHttpServletRequest class from the spring framework test jar which is not bundled when you run the 'grails prod war' command.

Resolution

Copy the org.springframework.test-3.0.3.RELEASE.jar from %GRAILS_HOME%\lib into your application's lib folder. By doing this, the plugin will find the MockHttpServletRequest class that it relies on at runtime in production.

RESTful webservices with Spring

2011-02-09T23:37:00.000-08:00

REST (Representational State Transfer) is a stateless architectural style wherein resources are identified and manipulated. by their URIs and transferred over HTTP. A REST web service sends any parameters, data needed by the server within the HTTP headers and body.
In this article, we will build REST webservices with Spring and a client using the Spring RestTemplate to consume the webservice. I will not be going into the details of these technologies, the aim is to rapidly come up with a basic CRUD web-service.

I will be assuming, that you are familiar with the basics of Spring, DI and IoC, REST, and the basic web-application structure in java.

Without much ado, let's begin!

If you've already built a Spring MVC application, writing a REST web-service should come easily. You can find a tutorial on how to build a simple Spring MVC application here.

I will be using the STS IDE (SpringSource Tool Suite). You can use any eclipse installation, or infact just create a similar package structure yourself. The source of the sample application demonstrated in this article is available for download at the bottom of this page.

STEP 1: Create a Spring MVC template project

Select File -> New -> Spring Template Project -> Spring MVC Project.
Choose an appropriate project name, and a base package name eg. CMSService, com.test.cmsservice

The IDE will create a basic web-application skeleton for you to work with.

STEP 2: Add maven dependencies
You will find a maven pom.xml at the base of the project. We would need some additional libraries. Add the following dependencies to your pom.xml:

<dependency>
      <groupId>org.springframework</groupId>
      <artifactId>spring-beans</artifactId>
      <version>${org.springframework-version}</version>
    </dependency>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>spring-context-support</artifactId>
      <version>${org.springframework-version}</version>
      <exclusions>
        <exclusion>
          <groupId>quartz</groupId>
          <artifactId>quartz</artifactId>
        </exclusion>
      </exclusions>
    </dependency>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>spring-core</artifactId>
      <version>${org.springframework-version}</version>
    </dependency>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>spring-test</artifactId>
      <version>${org.springframework-version}</version>
    </dependency>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>spring-orm</artifactId>
      <version>${org.springframework-version}</version>
    </dependency>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>spring-oxm</artifactId>
      <version>${org.springframework-version}</version>
    </dependency>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>spring-web</artifactId>
      <version>${org.springframework-version}</version>
    </dependency>
    <dependency>
      <groupId>cglib</groupId>
      <artifactId>cglib-nodep</artifactId>
      <version>2.1_3</version>
    </dependency>
    <dependency>
      <groupId>javax.xml.bind</groupId>
      <artifactId>jaxb-api</artifactId>
      <version>2.0</version>
    </dependency>

If you are not using maven, you will have to download and add the necessary jars to your classpath manually.

STEP 3: Create a domain class

Create a new package com.test.cmsservice.domain and a simple Customer domain class that has a couple of properties and corresponding getters and setters.

package com.test.cmsservice.domain;
import javax.xml.bind.annotation.XmlRootElement;

@XmlRootElement(name="customer")
public class Customer {

    Long id;
    String firstName;
    String lastName;
    String emailAddress;
    String phoneNumber;

    public Customer(){}

    public Customer(Long id, String firstName, String lastName, String emailAddress, String   phoneNumber){
        this.id = id;
        this.firstName = firstName;
        this.lastName = lastName;
        this.emailAddress = emailAddress;
        this.phoneNumber = phoneNumber;
    }

    public Long getId() {
        return id;
    }
    public void setId(Long id) {
        this.id = id;
    }
    public String getFirstName() {
        return firstName;
    }
    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }
    public String getLastName() {
        return lastName;
    }
    public void setLastName(String lastName) {
        this.lastName = lastName;
    }
    public String getEmailAddress() {
        return emailAddress;
    }
    public void setEmailAddress(String emailAddress) {
        this.emailAddress = emailAddress;
    }
    public String getPhoneNumber() {
        return phoneNumber;
    }
    public void setPhoneNumber(String phoneNumber) {
        this.phoneNumber = phoneNumber;
    }
}

Note the @XmlRootElement annotation at the class level. When a class is so annotated, its value is represented as an XML root element in an XML document. Use of these annotations enables these classes to be mapped to schema with minor changes to the code.

We will also create a CustomerList class that acts as a wrapper class for sending across a list of all the customers in the system.

package com.test.cmsservice.domain;

import java.io.Serializable;
import java.util.List;
import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlRootElement;

@XmlRootElement(name="customers")
public class CustomerList implements Serializable{

    private List<Customer> customers;

    public CustomerList(){}
    public CustomerList(List<Customer> customers){
        this.customers = customers;
    }

    @XmlElement(name="customer")
    public List<Customer> getCustomers() {
        return customers;
    }
    public void setCustomers(List<Customer> customers) {
        this.customers = customers;
    }

}

STEP 4: Create a service class

In a working application, you'd store the customers in a database, but to focus on REST, i will be storing the customers in a static list in the service class (Find a tutorial on Spring Hibernate integration here)

package com.test.cmsservice.service;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import com.test.cmsservice.domain.Customer;

public class CustomerService {

    static HashMap<Long, Customer> customers = new HashMap<Long, Customer>();

    static {
        customers.put(1L, new Customer(1L, "Stephen", "Smith", "Stephen.Smith@xyz.abc", "34545634"));
        customers.put(2L, new Customer(2L, "Mary", "Johnson", "Mary.Johnson@abc.xyz", "32445433"));
    }

    public Customer getCustomer(Long customerId){
        return customers.get(customerId);
    }
    public void saveCustomer(Customer customer){
        customers.put(customer.getId(), customer);
    }
    public List<Customer> getCustomers(){
        return new ArrayList(customers.values());
    }
    public void deleteCustomer(Long customerId){
        customers.remove(customerId);
    }
    public void updateCustomer(Customer customer){
        customers.put(customer.getId(), customer);
    }
}

Pretty basic.

STEP 5: Create a controller class
This is where the interesting part lies. Create a package com.test.cmsservice.web and a class CustomerController as follows:

package com.test.cmsservice.web;

/*import statements ...*/

@Controller
@RequestMapping("customer")
public class CustomerController {

    @Autowired
    CustomerService customerService;

    @RequestMapping(method=RequestMethod.GET)
    public ModelAndView getAllCustomers(ModelMap model)
    {
        List<Customer> customers = customerService.getCustomers();
        CustomerList customerList = new CustomerList(customers);
        return new ModelAndView("customerView", "customers", customerList);
    }

    @RequestMapping(value="/{id}", method = RequestMethod.GET)
    public ModelAndView getCustomer(@PathVariable Long id){
        Customer customer = customerService.getCustomer(id);
        return new ModelAndView("customerView", "customer", customer);

    }

    @RequestMapping(method = RequestMethod.POST)
    public View addCustomer(@RequestBody Customer customer)
    {
        customerService.saveCustomer(customer);
        return new RedirectView("/customerView/"+ customer.getId());
    }
}

The @Controller annotation enables detection when the spring container scans the application at load time and informs the container that the class will behave as a Controller.

The @RequestMapping annotation marks a function that can handle HTTP requests. A request that matches the URL pattern and HTTP method provided in the 'value' and 'method' attributes of the @RequestMapping annotation would be delegated to the corresponding function. In this case, we have used the @RequestMapping annotation at the class level as well. The attributes that are common to all the methods can be specified at the class level.

The @PathVariable annotation provides a means to access the parameters passed in the URI. For eg, an HTTP request to fetch the details of a customer with id '1' would look like this:
http://localhost:CMSService/customer/1
The {id} part of the URI is made available to the method using the @PathVariable annotation.

The CustomerService instance is autowired and will be passed on to the Controller class when the spring context is loaded.
Also notice, that the controller returns a ModelAndView object with a view name 'customerView'. This view is configured in the spring context xml, which we will look at shortly.

[Note: I have implemented only the GET an POST methods, you can also try deleting or updating the customers using the RequestMethod.DELETE and RequestMethod.PUT method attributes in the @RequestMapping annotation on methods.]

STEP 6: Set up the configuration files.
If you are using the STS IDE, you would not need to set up your web.xml file, since this is already done for you. This is how your web.xml should look.

<listener>
        <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
    </listener>

    
    <servlet>
        <servlet-name>appServlet</servlet-name>
        <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
        <init-param>
            <param-name>contextConfigLocation</param-name>
            <param-value>/WEB-INF/spring/appServlet/servlet-context.xml</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>appServlet</servlet-name>
        <url-pattern>/</url-pattern>
    </servlet-mapping>

This basically sends all the requests that are recieved to Spring's DispatcherServlet (which is the Front controller) We are also specifying that the base spring context file is 'servlet-context.xml' file. Let's look at the servlet-context.xml next.

<?xml version="1.0" encoding="UTF-8"?>
<beans:beans xmlns="http://www.springframework.org/schema/mvc"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:beans="http://www.springframework.org/schema/beans"
    xsi:schemaLocation="
        http://www.springframework.org/schema/mvc http://www.springframework.org/schema/mvc/spring-mvc-3.0.xsd
        http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">

    

    
    <annotation-driven />

    
    <resources mapping="/resources/**" location="/resources/" />

    <beans:bean id="jaxbMarshaller"
        class="org.springframework.oxm.jaxb.Jaxb2Marshaller">
        <beans:property name="classesToBeBound">
            <beans:list>
                <beans:value>com.test.cmsservice.domain.Customer</beans:value>
                <beans:value>com.test.cmsservice.domain.CustomerList</beans:value>
            </beans:list>
        </beans:property>
    </beans:bean>

    <beans:bean id="customerView"
        class="org.springframework.web.servlet.view.xml.MarshallingView">
        <beans:constructor-arg ref="jaxbMarshaller" />
    </beans:bean>

    <beans:bean
        class="org.springframework.web.servlet.view.ContentNegotiatingViewResolver">
        <beans:property name="mediaTypes">
            <beans:map>
                <beans:entry key="xml" value="application/xml" />
                <beans:entry key="html" value="text/html" />
            </beans:map>
        </beans:property>
        <beans:property name="viewResolvers">
            <beans:list>
                <beans:bean
                    class="org.springframework.web.servlet.view.BeanNameViewResolver" />
                <beans:bean id="viewResolver"
                    class="org.springframework.web.servlet.view.UrlBasedViewResolver">
                    <beans:property name="viewClass"
                        value="org.springframework.web.servlet.view.JstlView" />
                    <beans:property name="prefix" value="/WEB-INF/views/" />
                    <beans:property name="suffix" value=".jsp" />
                </beans:bean>
            </beans:list>
        </beans:property>
    </beans:bean>

    
    <beans:import resource="controllers.xml" />
</beans:beans>

The <annotation-driven> tag informs the container that it needs to look for annotated classes.

Next we define a jaxbMarshaller bean, to marshall and unmarshall the domain classes. A list of domain classes to be handled is passed next. We also specify a couple of viewResolvers for each mediaType.

Next we define a MarshallingView bean named 'customerView'. This bean takes the jaxbMarshaller bean to transform the object into an xml document. This is the view name being used to construct the ModelAndView objects returned by the controller methods.

Next we define a ContentNegotiationViewResolver. What is content negotiation? It is the concept where the server returns a specific representation of the objects depending upon the content-type it recieves in the request. The ContentNegotiationViewResolver can switch the views depending on the request type (specified by the Accept request header) Several types are supported such as HTML, XML, JSON, ATOM, PDF etc. In this case we have defined 2 supported 'mediaTypes' : xml and html.We also define viewResolvers for each mediaType.

[Note: If you want to render a jsp file instead of the xml format, create a customer.jsp file in /WEB-INF/views, and simply change the view name in the controller class from :

return new ModelAndView("customerView", "customer", customer);
to
return new ModelAndView("customer", "customer", customer);

The UrlBasedViewResolver viewResolver will then find the file customer.jsp in the /WEB-INF/views folder

and render the object. ]

Next, we import the controllers.xml file which specifies the base package for component scanning (to look for annotated classed)

<context:component-scan base-package="com.test.cmsservice" />

STEP 7: Build and Run!
You are now ready to test your Spring REST webservice. Right click the project and click 'Run on Server'.
Browse to http://localhost:8080/CMSService/customer, you should be able to see something like this:

Also try this: http://localhost:8080/CMSService/customer/2

If you are not using the IDE, you can use curl or write a small Spring REST based client which i will explain next.

STEP 8: Write a Spring REST web-service client
Writing a web-service client using Spring REST is pretty easy. The most important class is the RestTemplate class which is meant to be used the way we use JdbcTemplate, JmsTemplate etc.

For this demo, i am adding a client-context.xml to the same project inside the /WEB_INF/spring folder.
client-context.xml

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">

    <bean id="restTemplate" class="org.springframework.web.client.RestTemplate">
        <property name="messageConverters">
            <list>
                <bean                    class="org.springframework.http.converter.xml.MarshallingHttpMessageConverter">
                    <property name="marshaller" ref="jaxbMarshaller" />
                    <property name="unmarshaller" ref="jaxbMarshaller" />
                </bean>
                <bean class="org.springframework.http.converter.FormHttpMessageConverter" />
            </list>
        </property>
    </bean>

    <bean id="jaxbMarshaller" class="org.springframework.oxm.jaxb.Jaxb2Marshaller">
        <property name="classesToBeBound">
            <list>
                <value>com.test.cmsservice.domain.Customer</value>
                <value>com.test.cmsservice.domain.CustomerList</value>
            </list>
        </property>
    </bean>
</beans>

The restTemplate bean is passed the jaxbMarshaller bean which it will use to marshall and unmarshall resources that it sends or recieves. The jaxbMarshaller is passed a list of the domain class.

The RestTemplate has a couple of useful methods that you can use to POST, GET, DELETE and PUT data.
We will use a few of them in our client code:

package com.test.cmsservice.client;

import org.springframework.context.ApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;
import org.springframework.web.client.RestTemplate;
import com.test.cmsservice.domain.Customer;
import com.test.cmsservice.domain.CustomerList;

public class RestClient {

    public static void main(String[] args) {
        ApplicationContext ctx = new ClassPathXmlApplicationContext("client-context.xml");
        RestTemplate restTemplate = (RestTemplate)ctx.getBean("restTemplate");

        addCustomer(restTemplate);
        getAllCustomers(restTemplate);
    }

    public static void addCustomer(RestTemplate restTemplate){
        System.out.println("addCustomer called");
        Customer customer = new Customer(3L, "Bill","Gates", "bill@microsoft.com","234");
        restTemplate.postForLocation(
        "http://localhost:8080/CMSService/customer", customer);

    }

    public static void getAllCustomers(RestTemplate restTemplate){
        CustomerList customers = (CustomerList) restTemplate.getForObject(
                "http://localhost:8080/CMSService/customer", CustomerList.class);
        for(Customer customer: customers.getCustomers()){
            System.out.println("Customer: "+ customer.getId());
            System.out.println("Name: "+ customer.getFirstName() + " " + customer.getLastName());
            System.out.println("Email: "+ customer.getEmailAddress());
        }
    }
}

The client code is pretty straightforward. We are first adding a customer using the postForLocation method which takes the web-service url and the object to be POSTed.
We then fetch the list of all the customers by using the method getForObject which returns a CustomerList object.
Try your hand at the put, delete, exchange methods of the RestTemplate class for deleting and updating the customers using the webservice.

Download the source code of the demo

Hope you find this article helpful.
Happy coding!

Read from a database and write into an xml using Groovy

2011-02-07T21:11:00.000-08:00

You may come across a use-case where you need to read some data from a database and generate an xml report or file that needs to be sent across to be processed by some other system.

Doing this using a java program could be relatively overwhelming; with Groovy you can do this in a matter of minutes!

Let's take a look at how you can convert data returned from a sql query into an xml file.

For this example, i am fetching some employee details from a MySQL database. The details of the database are read from a property file. The database i have used for this sample has two tables Employee and Department.

import groovy.sql.Sql
import groovy.xml.MarkupBuilder
import java.text.SimpleDateFormat
import java.util.Properties

class DatabaseToXML {

static void main(args) {

SimpleDateFormat runDateformat = new SimpleDateFormat("yyyyMMdd")
String runDate = runDateformat.format(new Date())

def props = new Properties()
     new File('application.properties').withInputStream {
        stream -> props.load(stream)
     }

String outFolderName = (props["OUTPUT_FOLDER"]==null)?"."+File.separatorChar : props["OUTPUT_FOLDER"]
File outputFolder = new File(outFolderName)
if(!outputFolder.exists())
      outputFolder.mkdir()

String fileDate = runDateformat.format(new Date())
String empFileName = outFolderName + File.separatorChar + "employees_" + runDate + ".xml"

def sql = Sql.newInstance(props["DB_URL"],props["USERNAME"],props["PASSWORD"], props["DRIVERCLASS"])

def empQuery = """
        SELECT e.id, e.first_name, e.last_name, e.email_address, e.designation,
    d.dept_name FROM employee e, department d
    where d.id = e.dept_id
        """

def xml = new MarkupBuilder(new FileWriter(new File(empFileName)))

xml.employees(){
      run_date(fileDate)
      sql.eachRow( empQuery as String ) {
         row ->
            employee(){
            first_name(row.first_name)
            last_name(row.last_name)
            email_address(row.email_address)
            designation(row.designation)
            dept_name(row.dept_name)
          }
       }
    }
}
}

That was easy! The 'Sql.newInstance ...' statement connects to the database using the parameters passed to it and stores it in the variable 'sql'. We then use the sql.eachRow to fetch the rows from the database. To create the xml file we are using the MarkupBuilder class that supports Groovy's builder pattern. Find more options here.

To make this script you would need to add the mysql connector lib to the classpath.

SET CLASSPATH=./lib/mysql-connector-java-5.1.12-bin.jar

Run the script using the command :

groovy DatabaseToXML.groovy

The xml file in my case looks like this:

Download the source code for the above example here: db_to_xml.rar

Hope you find this useful. Happy coding!

Add search to your grails application using the searchable plugin

2011-02-07T10:18:00.000-08:00

If you're building a web application, you're most certainly going to need some 'search' capabilities in your application. The searchable plugin is an amazing plugin that is built using Compass search engine and lucene. This plugin enables you to make your domain classes without writing almost any code. In this article we will be discussing how you can install and use this plugin, and also discuss some issues around it.

We will be creating a simple grails application, a couple of domain classes, and then we will explore the 'searchable' plugin. (find the source code of the sample application at the end of the article)

Let's get started!

STEP 1: Create a grails app and install the searchable plugin
We will create a very simple basic application. To learn how to install and get started with grails please take a look at the blog article 'Build your first grails application'.
Open a command prompt and create your sample application:

grails create-app empsys
cd empsys
grails install-plugin searchable

STEP 2: Create your domain classes
Now let's create some domain classes which we would make 'searchable'. To create the domain class use the command:

grails create-domain-class Employee
grails create-domain-class Department

Let's add some fields to our domain classes.
Employee.groovy

package empsys

class Employee {

    static searchable = true
    static embedded = ['dept']

    Department dept
    String empCode
    String firstName
    String lastName
    String emailAddress
    String phoneNumber
    String designation
    Date birthDate
    Date joiningDate

    static constraints = {
        empCode(blank: false, unique: true)
        firstName(blank: false)
        lastName(blank: false)
        emailAddress(blank: false, email:true)
    }
}

Department.groovy

package empsys

class Department {

    static searchable = true

    String deptCode
    String deptName
    String description

    static constraints = {
    }
}

Note the statement 'static searchable = true'. This is necessary if you want to be able to search the objects of the domain class. (we will shortly discuss the 'static embedded' statement)

STEP 3: Create controllers and views for the domain classes
To create the controller and views for your class use this command:

grails generate-all empsys.Department
grails generate-all empsys.Employee

At this point, you can run the application using the command: grails run-app

You can now test the plugin, run the application, create some test data i.e. add some departments and employees to your system. Browse to : http://localhost:8080/empsys/searchable and try searching for the employees ( and departments) you just added to your system. How cool is that!

Tip: you may want to change your datasource.groovy to save into an hsqldb file instead of the default memdb or you'll loose all your test data. (url = "jdbc:hsqldb:file:devDb")

STEP 5: Customize the controller and the views
In addition to the 'searchable' controller which searches all the 'searchable' domain classes, you'd typically need a search box and a button on the '/employee/list' page to search for employees. You can easily do this, by using the views and controllers generated by the plugin. The controllers and views generated by the plugin can be found at:

%USER_HOME%\.grails\1.3.4\projects\empsys\plugins\searchable-0.5.5.1\grails-app

Copy the content of SearchableController.java, change the function name from 'index' to say 'search' and copy it to your EmployeeController.java.

/* add this import statement for the searchable plugin to work */
import org.compass.core.engine.SearchEngineQueryParseException

class EmployeeController {
static String WILDCARD = "*"
def searchableService

.........
def search = {
        if (!params.q?.trim()) {
            return [:]
        }
        try {
            String searchTerm = WILDCARD+ params.q + WILDCARD
            return [searchResult: Employee.search(searchTerm, params)]
        } catch (SearchEngineQueryParseException ex) {
            return [parseException: true]
        }
    }
def indexAll = {
        Thread.start {
            searchableService.index()
        }
        render("bulk index started in a background thread")
    }

    def unindexAll = {
        searchableService.unindex()
        render("unindexAll done")
    }
......
}

[Note: We've made a small change to the default search functionality provided here. We are appending the search term with a wildcard '*' so that even if the user enters part of the employee's first name or last name or any other field, the employee is featured in the search results. ]

Let's add a search box and a button on the employee/list.gsp page. Add the following code to \views\employee\list.gsp file after the navigation buttons:

<div class="nav">
            <span class="menuButton"><a class="home" href="${createLink(uri: '/')}"><g:message code="default.home.label"/></a></span>
            <span class="menuButton"><g:link class="create" action="create"><g:message code="default.new.label" args="[entityName]" /></g:link></span>
        </div>
        <div class="body">
        <g:form action="search" method="get">
            <g:textField name="q" value="${params.q}"/>
            <g:submitButton name="search"/>
        </g:form> ......

We also need to create a new gsp view to display the results of the search. This page takes most of its code from the %USER_HOME%\.grails\1.3.4\projects\empsys\plugins\searchable-0.5.5.1\grails-app\views\searchable\index.gsp file and the views\employee\list.gsp page. I am not copying the code here since it's pretty long and would make the article look ugly :) But you can find the source attached at the bottom of the post.

Once you have fixed your views, you should be able to see something like this:

And the search result page would look like this:

It's time to now go back to the Employee.groovy file
We had added a line 'static embedded = ['dept']' to our Employee domain class. Here we are making use of 'composition'. Since the Department class is also 'searchable' and we have used composition, you will be able to search for the all employees belonging to a certain category using the above screen. i.e. If your employee belongs to a department with department name 'Finance', on searching the text 'Finance' the employee will show up in the results.
You can read more about the searchable-reference and searchable-components here.

The plugin provides loads of options to customize the search to suit your requirements for eg: query mechanisms, builders, mappings etc. There are a couple of mappings you can add to the 'static searchable' closure. eg: if you want to exclude some fields from the search or you want to boost a certain field while searching, update your closure as follows:

static searchable = {
        /* we don't wish the id and version to be 'searched'
              or added to the index */
            except = ['id', 'version']
        empCode boost:2.0
        }

In this article, we've implemented a very basic search functionality for our domain classes. There's a lot of stuff in this plugin that you can explore and use in your application.

Hope you find this article useful.

Happy coding !

Download the source code of the sample search application : empsys.rar

Spring Hibernate Integration

2011-02-01T23:48:00.000-08:00

In this article, I will be demonstrating how you can integrate hibernate with your Spring application. We will not be discussing hibernate and Spring in any detail. The focus is to get you started with an Spring application that persists data into a database using the hibernate ORM layer.

I will safely assume that you are familiar with Spring, hibernate, SQL, maven. For the purpose of this demo, i will be using the MySQL database, STS (SpringSource Tool Suite) or Eclipse with Spring support plugins installed. If you are not using any IDE, you just need to create some folders and config files yourself. But i see no reason why you shouldn't since it will really speed your development process.
(find the source code of the sample application at the end of the page)

So Let's get started!

STEP 1: Create a Spring hibernate Utility project I am using STS for creating my project; STS is a customized eclipse environment. You can use your favorite eclipse installation, for sake of ease, install the Spring plugins and you're ready to go. If you are going the manual way, nothing to worry about. Just a few folders and config files to be created.

Choose the 'Spring Template Project' from the File -> New menu or the dashboard.

From the Template Selection dialog, choose 'Simple Spring Hibernate Utility Project'

Type in a project name and a base package name ( eg. EStore and com.test.estore respectively) and press Finish. You will see that the following code structure has been generated for you

A few configuration files will be genereated here. You will find a pom.xml at the base folder of the project. This is where we will add the maven dependencies in a short while. You will also find the app-context.xml which is the base spring config file at /src/main/resources/META-INF/spring. Any property files needed for the project can be placed inside /src/main/resources/META-INF/properties.

The maven configuration file - pom.xml will already have all the dependencies for using Spring and hibernate. Since we are using the mysql database, we will need to add the following dependency to use the mysql connector:

        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <version>5.1.12</version>
        </dependency>

If you are not using the IDE, you will have to add a couple of dependencies to your pom.xml. Please refer the pom.xml in the source code attached at the end of the article.

STEP 2: Create a domain class

We will create a simple domain class called Product in a seperate package 'com.test.estore.model'. Each domain class maps to a table in the database. Let's take a look at the code and i then walk through the code.

@Entity
@Table(name = "Product")
public class Product {

    private Integer productId;
    private String productCode;
    private String name;
    private String description;
    private Double price;

    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    @Column(name = "ID")
    public Integer getProductId() {
        return productId;
    }
    public void setProductId(Integer productId) {
        this.productId = productId;
    }

    @Column(name = "NAME", nullable = false, length = 50)
    public String getName() {
        return name;
    }
    public void setName(String name) {
        this.name = name;
    }

    @Column(name = "CODE", nullable = false, unique = true, length = 20)
    public String getProductCode() {
        return productCode;
    }
    public void setProductCode(String productCode) {
        this.productCode = productCode;
    }

    @Column(name = "DESCRIPTION")
    public String getDescription() {
        return description;
    }
    public void setDescription(String description) {
        this.description = description;
    }

    @Column(name = "PRICE")
    public Double getPrice() {
        return price;
    }
    public void setPrice(Double price) {
        this.price = price;
    }

}

As you see, Product is a very simple POJO with a few additional annotations. The @Entity annotation specifies that this class is persistent and the @Table annotation specifies the name of the table to which it will be mapped. Please note that the @Table annotation is not compulsory.

The @Column annotation specifies the name of the column to be mapped with the field in the class. Again, it is NOT necessary to specify the @Column annotation unless you want the column name to be different than the field name. Every field in the class will be by default persisted into a column of the table, unless specifically annotated with the @Transient annotation. In addition to the name, you can also specify whether the column is nullable, unique, length restrictions etc.

The @Id annotation specified the identity property of the class. In hibernate, every table needs to have this unique key. There are different strategies available for generating the values for this field. In this case, we are using GenrationType.Auto.

These annotations can be added over the fields of the getters/setters. The placement of the @Id annotation determines which strategy will be used. In this particular case for eg, since the @Id annotation is placed over the property getter/setter, the property access strategy is used instead of the field access.
(Field access means: hibernate will access the field directly using reflection.
Property access: hibernate will use the get/set pair to access the value - property access is the default)

Let's now move to the next step and create the data access layer.

STEP 3: Create the DAO layer
Now that our model class is ready, let's create the DAO interface and it's implementation in a package say : 'com.test.estore.dao'
IProductDAO.java

package com.test.estore.dao;
import com.test.estore.model.Product;

public interface IProductDAO {
    public void save(Product product);
    public void update(Product product);
    public void delete(Product product);
    public Product findByProductCode(String code);
}

ProductDAO.java

package com.test.estore.dao;
/*import statements*/

@Repository("productDao")
public class ProductDAO implements IProductDAO {

   private HibernateTemplate hibernateTemplate;

   @Autowired
   public void setSessionFactory(SessionFactory sessionFactory) {
       hibernateTemplate = new HibernateTemplate(sessionFactory);
   }
   public void save(Product product) {
       hibernateTemplate.save(product);
   }
   public void update(Product product) {
       hibernateTemplate.update(product);
   }
   public void delete(Product product) {
       hibernateTemplate.delete(product);
   }
   public Product findByProductCode(String code) {
       List products = hibernateTemplate.find(
               "from Product where productCode = ?", code);
       return (Product) products.get(0);
   }
}

The ProductDAO class is quite self explanatory, there're just two points worth writing about.
1. Notice the @Repository annotation on the ProductDAO class. @Repository is a specialized @Component type. @Repository indicates that the class acts as a repository or a data access object. This enables transparent exception translation. And it also provides a more clear scope for applying a pointcut or an aspect for future support.

The @Autowired annotation indicates that the sessionFactory bean is injected into the ProductDAO by the spring container.

STEP 4: Create the service layer
Now that we have the DAO layer in place, it's time to setup the service layer. The service layer is pretty straightforward:
IProductService.java

package com.test.estore.service;
import com.test.estore.model.Product;

public interface IProductService {
    public void save(Product product);
    public void update(Product product);
    public void delete(Product product);
    public Product findByProductCode(String code);
}

ProductService.java

package com.test.estore.service;

/* import statements */ ....

@Service("productService")
public class ProductService {

        @Autowired
        ProductDAO productDAO;

        public void save(Product product){
            System.out.println("save called");
            productDAO.save(product);
        }
        public void update(Product product){
            productDAO.update(product);
        }
        public void delete(Product product){
            productDAO.delete(product);
        }
        public Product findByProductCode(String code)
        {
            return productDAO.findByProductCode(code);
        }
}

STEP 5: Configuration files
The most important configuration file in this application is the base Spring context xml. For the sake of clarity, we will place all the hibernate related configuration in a separate configuration file - hibernate.xml. We will define the datasource bean and the sessionFactory bean in hibernate.xml. We will be storing the database details in a property file and read the property file in the context xml. Let's take a look at these configs:

application.properties

jdbc.driverClassName=com.mysql.jdbc.Driver
jdbc.url=jdbc:mysql://localhost:3306/spring_hibernate
jdbc.username=root
jdbc.password=password

hibernate.xml

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd">

    <bean
        class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
        <property name="location">
            <value>application.properties</value>
        </property>
    </bean>

    <bean id="dataSource"
        class="org.springframework.jdbc.datasource.DriverManagerDataSource">
        <property name="driverClassName" value="${jdbc.driverClassName}" />
        <property name="url" value="${jdbc.url}" />
        <property name="username" value="${jdbc.username}" />
        <property name="password" value="${jdbc.password}" />
    </bean>

    <bean id="sessionFactory"
        class="org.springframework.orm.hibernate3.annotation.AnnotationSessionFactoryBean">

        <property name="dataSource" ref="dataSource" />
        <property name="annotatedClasses">
            <list>
                <value>com.test.estore.model.Product</value>
            </list>
        </property>
        <property name="hibernateProperties">
            <props>
                <prop key="hibernate.dialect">org.hibernate.dialect.MySQLDialect</prop>
                <prop key="hibernate.show_sql">true</prop>
                <prop key="hibernate.hbm2ddl.auto">create</prop>
            </props>
        </property>
    </bean>
</beans>

In the above config, we read the database details from the property file and create the dataSource bean. Here we don't need any hibernate.cfg.xml file, we declare the hibernate sessionFactory bean in the xml file to which we pass the dataSource bean. We also list down the list of all the 'annotatedClasses' in the application i.e. all the model classes (just like we specify the mapping files in the hibernate.cfg.xml file).
Also in this case, we want to create the table when we run the application the first time, and hence the value of 'hibernate.hbm2ddl.auto' has been set to 'create'. This is all we need to do to set up the configs for our database.

Next we need to setup the core spring config - app-context.xml

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:context="http://www.springframework.org/schema/context"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
                           http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
                           http://www.springframework.org/schema/context
                           http://www.springframework.org/schema/context/spring-context-2.5.xsd">

    <import resource="hibernate.xml"/>
    <context:component-scan base-package="com.test.estore" />
</beans>

The first line imports the hibernate config file. Also, we need to tell the Spring container that it needs to look for annotated classes. To do this we need to use the component-scan tag and pass to it the base package - this is where the container starts it's search from.

STEP 6: Write the test application
Now that we're done with almost everything, we need to test the application. All we need is a simple class with the main method that loads the spring context and tries to persist a Product into the database

package com.test.estore.app;

/* import statements */ ..

public class RunEStore {

    public static void main(String[] args) {
        ApplicationContext ctx = new ClassPathXmlApplicationContext("app-context.xml");

        ProductService productService = (ProductService) ctx.getBean("productService");
        Product product1 = new Product();

        product1.setName("maggie noodles");
        product1.setDescription("noodles made out of flour");
        product1.setProductCode("MAGG_NOODLES");
        product1.setPrice(30D);

        productService.save(product1);

        System.out.println("Product saved: "
                + productService.findByProductCode("MAGG_NOODLES").getName());
    }
}

So, we're ready to go.. wait , not yet!

STEP 7: Where's the database?

We first need to create the 'spring_hibernate' schema that we specified in the application.properties file :

Now we're ready to go. Run the RunEStore class, a table called 'Product' would be created and a row would be added to the table.

This was a very very basic example. You would mostly use hibernate in a Spring MVC project; you need to follow the same steps, just a few configurations would need to change and additions to the pom.xml file would be needed.
There's a lot more to Spring hibernate such as exception handling, one-to-many, many-to-many relationships. Another article, another day.

Hope you found this demo useful.
Happy coding!

Download the sample application : EStore.rar

Get started with Spring MVC

2011-02-01T03:11:00.000-08:00

Spring MVC, one of the modules of the core Spring framework, is a web-application development framework. As the name suggests, Spring MVC is an implementation of the Model(M), View(V), Controller(C) design pattern, which is based on request delegation and separation-of-concerns.
I am assuming, that if you have reached this article and are about to use it, you would be familiar with the basics of web-application development and the Spring framework in general. And Java of course ;)

I will briefly introduce you to the basics of how Spring MVC works and then will build a simple web-application (find the sample application source code for download at the end of the page).

Spring MVC web-flow

Spring MVC uses a request delegation model, where all the incoming requests are delegated to a 'Front Controller' called DispatcherServlet. This servlet has no business logic; it's sole purpose is to route the request across the system. The servlet uses different strategies (HandlerMapping) to determine the controller to which the incoming request needs to be delegated. The request is then sent to the controller determined by the HandlerMapping. The controller would typically call service class methods that contain all the business logic, and after all the necessary processing is done, the controller returns a logical view name and a model back to the DispatcherServlet. The DispatcherServlet, again uses several strategies (ViewResolver) to determine which View needs to be used to render the model. The model is rendered using the view returned from the ViewResolver and the response is sent back to the user.

These components are wired together using the Spring IoC and Dependency Injection mechanisms.

There are two approaches that you can use to build your web application.
1. use xml configuration files.
2. use annotated java classes.
Although you cannot completely give up configuration files, you can save your self quite a bit of xml slurping by using java annotations.
You can also mix and match and use a hybrid of both the approaches. Whatever suites you best.

Since annotation based controllers are gaining popularity and are favored by most java developers, i will be using this approach through most part of the demo.

So, it's time to get started!

Spring MVC sample applicaiton : Customer Management System

There are a lot of IDEs available with Spring support that enable you to fasten your development process.
I will be using the SpringSource Tool Suite that can be downloaded from here. STS is an enhanced eclipse environment specially designed for Spring support. But you can also use your eclipse installation, and install some plugins for Spring support.

STEP1: Download and unzip STS and create a new project using the 'Spring Template Project' option on the dashboard. This template will generate quite a bit of boilerplate code for you, so you can concentrate on your application logic.

Choose 'Spring MVC project' from the Template Selection screen. Type a project name and a top-level package name

STEP 2: Configuration files. You will find a couple of xml configuration files have already been created for you. Let's take a look at the most important ones.

a) web.xml

The DispatcherServletis declared in web.xml. You also need to specify the url-pattern to determine which requests are to be routed to the DispatcherServlet. In this case, all requests will be routed to DispatcherServlet ('/'). The DispatcherServlet needs to load the spring ApplicationContext, and the base configuration xml name is passed via the init-param. If nothing is passed, it will look for a file names <servlet-name>-context.xml in the classpath by default. Here's a snippet from the web.xml file:

   <servlet>
   <servlet-name>appServlet</servlet-name>
        <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
        <init-param>
            <param-name>contextConfigLocation</param-name>
            <param-value>/WEB-INF/spring/appServlet/servlet-context.xml</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>appServlet</servlet-name>
        <url-pattern>/</url-pattern>
    </servlet-mapping>

Note: If you are not using the STS, you will need to add these servlet mappings to your applications web.xml file yourself. (as i said, the IDE saves does a lot of writing for you.)

b) servlet-context.xml

This is the base configuration file of your Spring MVC application. As mentioned earlier, we will be using the annotation based mechanism for declaring our Controllers, we need to specify this in the servlet-context.xml by specifying the annotation-driven tag. Also, we will be using the InternalResourceViewResolver to resolve the view to be used to render the model using a logical view name. So if the logical view name is 'index', the application will look for the following file: /WEB-INF/views/index.jsp

<annotation-driven />

<beans:bean class="org.springframework.web.servlet.view.InternalResourceViewResolver">
<beans:property name="prefix" value="/WEB-INF/views/" />
<beans:property name="suffix" value=".jsp" />
</beans:bean>

<beans:import resource="controllers.xml" />

In the controllers.xml file, you will see an entry

<context:component-scan base-package="com.test.cms.web" />

This entry specifies that the Spring container needs to perform a component scan to look for annotated java classes, and this scan needs to begin from the base-package. Thus this basically tells the application, that it should expected @Controller annotated classes.

Note: If you are not using the STS Spring MVC template, you will have to write your configuration files yourself. The IDE saves you quite a few keystrokes. Strongly recommended.

STEP 3: Write your first Controller & Test!
A simple controller would already be created in your project - HomeController. Infact, at this point, you can try to run the application. Right click the project, click 'Run as' , and then 'Run on server'. When the server has started successfully, try to access http://localhost:8080/CMSApp/, you should be able to see something like this ->

If you are not using Maven, you would need these libs in your classpath:

If you are not using the STS IDE, you simply need to create a controller class that looks like this:

@Controller
public class HomeController {

    @RequestMapping(value="/", method=RequestMethod.GET)
    public String home() {
        logger.info("Welcome home!");
        return "home";
    }

}

and a jsp file named 'home.jsp' in /WEB-INF/views/home.jsp that prints a welcome message.

But how real is our application right now? Not very. Let's add some business logic to it.

STEP 4:Create a service and a domain class
We will create a few simple pages to add customers to the system, and list all the existing customers. The application can be enhanced further to support all the CRUD operations. But create and list should be just fine to begin with.

Since we are here to learn about Spring MVC, i will keep the service class really simple. The service class will contain the business logic to list and save customers. For simplicity sake, we will not be persisting any data to a database, instead we will add the customers to a static list; avoiding any database setup.

A very basic Customer class that looks like this:

The service class would typically lie in a separate package say : com.test.cms.service
A snippet from CustomerService.java

public class Customer {
    String firstName;
    String lastName;
    String gender;
    String emailAddress;
    String phoneNumber;

    public String getFirstName() {
        return firstName;
    }
    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }
     ....
   //remaining getters and setters
     ....
}

The service class looks like this:

public class CustomerService {

    static ArrayList<Customer> customers = new ArrayList<Customer>();

    public void addCustomer(Customer customer) {
        customers.add(customer);
    }
    public ArrayList<Customer> listCustomers() {
        return customers;
    }
}

CustomerService is a simple class with functions to add a new customer to a statically maintained arraylist and to return a list of all existing customers.

STEP 5: Create a Controller for handling multiple actions.
This is where the heart of the tutorial lies. The CustomerController class is annotated with the @Controller annotation so that it is scanned by the Spring container at startup.

@Controller
public class CustomerController {

    @Autowired
    CustomerService customerService;

    @RequestMapping(value = "/customer", method = RequestMethod.GET)
    public String listCustomers(ModelMap model) {
        ArrayList<Customer> customers = customerService.listCustomers();
        model.addAttribute("customers", customers);
        return "listCustomers";
    }

    @RequestMapping(value = "/customer/create", method = RequestMethod.GET)
    public String createCustomer(ModelMap model) {
        Customer customer = new Customer();
        model.addAttribute(customer);
        return "createCustomer";
    }

    @RequestMapping(value = "/customer/create", method = RequestMethod.POST)
    public String addCustomer(@ModelAttribute("customer") Customer customer) {
        customerService.addCustomer(customer);
        return "redirect:/customer";
    }
}

and add the following to servlet-context.xml

<beans:bean id="customerService" class="com.test.cms.service.CustomerService" >
</beans:bean>

The customerService has been autowired into the controller class. The container will look for a bean of type customerService and wire it with the controller.
Next, notice the @RequestMapping annotation. Any request that matches the URL pattern and request method provided in the 'value' and 'method' attributes would be delegated to the corresponding method.
When the user hits http://localhost:8080/cmsapp/customer, the listCustomers() method is executed.
This method has access to a ModelMap object to which objects can be added using the addAttribute method, and can be passed on to the 'view'. There are a handful of other approaches you could use. For example @RequestParam which you can use to read parameters directly from the request. To access a particular model attribute from the incoming 'post' request, the @ModelAttribute is used. The logical name of the view is returned which leads to the view jsp to be used to render the attributes added to the ModelMap. In this case, we have the listCustomer.jsp and createCustomer.jsp view files. Let's take a look at the jsp files next

STEP 6: Create the view files
The view files are simple jsp files, which render the model that is passed on to them.
The list.jsp file iterates through the 'customers' list passed to it and formats them into a table. A snippet below:

<table border="1">
    <tr>
        <th>Name</th>
        <th>Email</th>
        <th>Phone</th>
    </tr>
    <c:forEach items="${customers}" var="customer">
        <tr>
            <td>${customer.firstName} ${customer.lastName }</td>
            <td>${customer.emailAddress}</td>
            <td>${customer.phoneNumber}</td>
        </tr>

    </c:forEach>
</table>

And the createCustomer.jsp file has a form and a submit button.

<form:form method="POST" commandName="customer">
    <table>
        <tr>
            <td>First Name :</td>
            <td><form:input path="firstName" /></td>
        </tr>
        <tr>
            <td>Last Name :</td>
            <td><form:input path="lastName" /></td>
        </tr>
        <tr>
            <td>Gender :</td>
            <td><form:radiobutton path="gender" value="male" label="M" /> <form:radiobutton
                path="gender" value="female" label="F" /></td>
        </tr>
        <tr>
            <td>Email Address :</td>
            <td><form:input path="emailAddress" /></td>
        </tr>
        <tr>
            <td>Phone Number :</td>
            <td><form:input path="phoneNumber" /></td>
        </tr>
        <tr>
            <td colspan="2"><input type="submit"></td>
        </tr>

    </table>
</form:form>

We're now finally ready to run our application!

STEP 7: Run the web-application
Right click your project and run the application on the tc server. Browse to http://localhost:8080/CMSApp/customer/create and you should see :

Enter the details and press the submit button and you would see a list of existing customers

There you go! You have your first Spring MVC application up and running.

This is a very basic application. Spring provides a lot of capabilities that you can explore. You can add validations to your fields, use themes, add locale support; the list is long.

Hope you find this article useful.
Happy coding!

Download the sample application : CMSApp.rar

Build your first grails application

2011-01-24T03:29:00.000-08:00

Grails is an open source web application framework, that has been built with the aim to enable rapid application development (RAD). Grails uses groovy as it's primary programming language. It uses Convention over Configuration to speed up the process of web application development. Grails takes its inspiration from Ruby on Rails but for the java world. Grails runs on the JVM and brings the power of the scripting world since it uses groovy which is a dynamic language built on top of java. Read more about grails and it's features here.

In this article we will quickly build an application using Grails. You will be surprised to see that you have your web-app running within 15 minutes, save data to the database, even deploy you application on your favourite application server! Enough talking, let's get into action.
( find a download link for the source code of the sample plugin at the bottom of the page)

System Requirements

1. JDK 1.5 or above (for Grails 1.2 and above)
2. JAVA_HOME enviroment variable should be set, pointing to the correct jdk installation.
3. download and unzip the grails zip file into a folder of your choice.
4. create an environment variable GRAILS_HOME which points to the folder created in the step above.
5. Add GRAILS_HOME/bin and JAVA_HOME/bin to the PATH environment variable.

STEP 1: Create your web-application:

1. Open a command prompt at the location where you want to create your application.
2. Type the following command to create an application named 'estore'

grails create-app estore

Change directory to your application:

cd estore

We can see that the script creates the basic structure of the web-app, reducing the time and effort of the developers. Grails also downloads some plugins such as hibernate, tomcat etc. In case you face any issues you probably need to check your internet connection or setup you proxy.

Also, notice the environment (highlighted in the screenshot). The environment is set to 'development' mode.
Grails lets you configure your application for different environments, 'development' is the default environment. We will discuss these enviromnents in a short while.

The create-app command will create the following structure for you:


Grails application structure

As you see, grails has already done a lot of work for you! In fact, you already have a web application that you can try launching using the command 'grails app'. But as it is right now, the web-application would not be of much use.
Let's take a closer look at what grails has created for us. The folder with which you are going to work the most is 'grails-app'. Inside this folder, grails has created for us folders where we place our model (M-domain), views (V) and controllers. In addition to these, there's a folder for the service classes, taglibs, message property files (i18n) and configuration files.

Domain: This is where you'll place your domain classes (i.e. the models).
These are POJOs with some additional attributes such as 'mapping' which specifies the relationship the class holds with other domain objects, 'constraints' which specifies the constraints on the fields of the domain objects, etc. You don't need to provide getters and setters for all the fields.
Controller: This is where your controller classes will lie.Controllers handle requests and generate the response either themselves or delegate the request to a view. Every controller class name must end with 'Controller'. You can easily create a controller by creating a class who's name ends with 'Controller'. Or you could use the commands provided by grails which we will see in a moment.

Services: This is where you should place business logic. Every service class ends with 'Service'. You can create a service by simply creating a class who's name ends with 'Service' inside the service folder or you can use the commands provided by grails. To use this service in a controller or domain class you simply need to declare a variable named the same as your service, and the service will be automatically injected by spring at application startup. These services are by default singleton, i.e. the same instance of the service is used across the application. However, the scope of the service can be changed

Views: Views in grails are .gsp files which are very similar to jsp files. Controllers use 'convention mechanism' to delegate the request to the appropriate view. Grails uses SiteMesh for its layouts. Thus you can very easily specify the basic layout of your application in the grails-app/views/layout/main.gsp. You will see that you already have the main.gsp file generated for you when you create a fresh new application.

Taglibs: This is where you can add your custom tags but without the need to update any TLDs or any other configuration. Remember 'convention over configuration'. You can create a taglib by simply creating a class ending with 'TagLib' in the taglib folder or use the grails command which we will discuss just in a while.

Configuration Files: Although grails follows the 'Convention over configuration' paradigm, you need some basic configuration for your databases, working directory, logging, emails etc. All your configuration files would be placed inside 'conf'. There are a couple of configuration files but for now lets take a closer look at the important configuration files.

1. DataSource.groovy: As discussed earlier, grails allows you to configure your application for different environments using just a single file. Thus you don't need to maintain multiple copies of your property file per environment. You can place all your configuration inside one file, and you could even provide some common properties that remain unchanged across environments. Grails provides you with an in-memory HSQL database so you can quickly get started with your application and leave the task of choosing, installing and setting up a database for later. You can change the HSQL configuration to save data to a file, so you can see your test data in between application runs.
change the url to:

url = "jdbc:hsqldb:file:testDb"

/* NOTE: For this tutorial, i have changed my applications url to the above, so that i don't have to re-generate my test data. */

2. Config.groovy: This is the config file where you can specify any application specific properties, environment specific log4j properties etc. The properties specified in this file can be read from any application code using ConfigurationHolder.
For example, the following property:
email.notification=test@test.com
can be read using the following code:

import org.codehaus.groovy.grails.commons.ConfigurationHolder
....
....
sendNotification(ConfigurationHolder.config.email.notification, 'some test email')

3. BootStrap.groovy: This file has two methods, init & destroy, which are invoked on application startup and shutdown. So if you need to run some initialization code at startup or some clean up tasks at shutdown, this file is you will need.
Now that you are familiar with the structure of your grails application, let's move ahead ...

STEP 2: Create your first domain class

Let's create a domain class Product for our estore:

grails create-domain-class product

/*( NOTE: For the purpose of this tutorial, i am using the default package, i.e. i have removed any package structure, i.e. removed the 'package estore' line from the file and placed the Product.groovy file at grails-app/domain directly.)*/

Let's add some fields to the Product class so that it looks like this:

package com.estore

class Product {

   String name
   String description
   Double price

    static constraints = {
       description(nullable: true)
       name(blank: false)
       price(min:0D)
    }
}

As you can see here, we have added a few fields to the Product class and in addition also added some constraints. By default, all fields are Non-nullable. So here, we make description a nullable field, and also add a constraint to the minimum value of the price field.

STEP 3: Create a controller and views for the domain class

We would need some pages in our application to add/update/delete/list all the products in our store. There are two ways we can do this
1. Create a controller: Generate the controller and use scaffolding to generate the views at run-time.
Run the command:

grails create-controller com.estore.Product

Now open ProductController.groovy, and add the following code to it:

package com.estore

class ProductController {

def scaffold = Product
}

Here, we are using the 'scaffolding' mechanism, where grails generates the views at run-time. At this point, you are ready to run the application and test it using 'grails run-app'. But, i would suggest you first read the second way to do this before you try this one.

2. Generate controller and views: Generate both the controller and the views on your disk.
Run the command:

grails generate-all com.estore.Product

Here, you will find that 4 files have been generated at grails-app\views\product namely create.gsp, list.gsp, edit.gsp and show.gsp. And the controller will have multiple 'actions'. These actions will be called depending on the URI that is requested.

Run the application using the command:

grails run-app

Browse to : http://localhost:8080/estore/product/create
(
Notice the URI:
estore- application name
product- controller name
create- action name
)

You should be able to see something like this:

[ Try this: Try creating a product with a negative price value or a blank aname. Without writing a single line of code, you see your domain-class constraints being validated on the UI! That's grails for you :) ]

STEP 4: Adding relationships to your domain class

Let's enhance our store, and add categories to it. Products can belong to a certain category. And a category can have multiple products. So here we have a many-to-one relationship.
Create a new domain class called Category:

grails create-domain-class com.estore.Category

Add the following code to Category.groovy

package com.estore

class Category {

    String name
    String description

    static hasMany = [products: Product]

    static constraints = {
        name(blank:false)
        description(nullable:true)
    }
}

And add the following line to Product.groovy

Category category
static belongsTo = Category

Note: If you don't add this line to Product.groovy, the deletes would not be cascaded. We will not be getting into the details of how GORM works since it's out of the scope of this article.

Now create the views and controller for the Category domain class

grails generate-all com.estore.Category

Repeat the above command for com.estore.Product as well, since we've added a new field to the class, we need this to be reflected in the view.

Run your app, you should see there are two controllers, and your product/create page looks like this:

For better presentation, make a tiny change to grails-app/views/product/create.gsp ( and editp.gsp)
Change

<g:select name="category.id" from="${com.estore.Category.list()}" optionKey="id" value="${productInstance?.category?.id}" />

to

<g:select name="category.id" from="${com.estore.Category.list()}" optionKey="id" optionValue="name" value="${productInstance?.category?.id}" />

STEP 5: Create a service class

You can create a service class by either creating a class ending with 'Service' in the services folder or use the command:

grails create-service utility

To use this service in CategoryController.groovy just add this line to the file:

class CategoryController {

def utilityService
....

That's all you need to be able to use a service. You should add all your business logic to the service class and call it from the controller and domain classes.

So, that didn't take long now, did it ? ;)

Hope you find this article useful. Happy coding!

Download source code (estore.rar)

Welcome Grails to your life!

2011-01-20T03:13:00.000-08:00

We all know how painful web development in java can be! Maintaing endless configuration xml files, writing hibernate layers & complex build scripts for compiling & packaging can make your experience of developing a web app in java nightmarish. But we would not want to sacrifice the capabilities and power of the Java platform for the sake of ease and agility.

And this is where web frameworks like Grails fit in. These framework take care of the overhead tasks such as configuration, builds, integration, and enable us to concentrate on our business requirement.
If you are looking for a framework that supports agile development and enables RAD (Rapid application Development), Grails could be your first choice!

Grails is an open source web framework that uses Groovy as it's primary programming language. Grails was inspired by Ruby on Rails, but mainly for java developers. This does not mean, you should not try this framework if you're not from a java background, but Java developers would find themselves productive from day 1.

Features of Grails that enable RAD are:

Convention over Configuration: You don't have to maintain huge complex configuration files to setup your application. Grails uses conventions to determine the role of classes instead the application and how they interact with the each other.
Groovy: Groovy is a agile dynamic scripting language built on top of the Java language. Groovy code is very similar and much terser than Java, which means almost-zero learning curve, and lesser code to write and maintain. Groovy is a dynamic language, uses meta-programming. And it brings the power of scripting languages to the java world.
Grails doesn't suggest you to use MVC, to forces you to use MVC (which is great, btw!). But using the MVC pattern in Grails is much simpler than in any other web framework. There is absolutely NO need for any configuration. You don’t have to specify in any configuration files which class is a model or a controller, or specify which view file will be used for a certain action. Grails determines all the information by the virtue of the class names and the location of the files.
Code Generation & synthesis: Grails generates considerable amount of code making the process faster and easier for the developer. It not only generates code, but also allows code synthesis. In case of code generation, some bits of code is actually generated on your disk. But in case of code synthesis, the code/feature is available dynamically at runtime. Grails makes use of Groovy's meta-programming capabilities to enable code synthesis. One of the ways in which Grails does this is GORM( Grails Object Relational Mapping) .

If you have a model (M of MVC) class say Author that has fields ‘firstName’, ‘lastName’, grails will add dynamic finder methods that you can use. Eg:-

Author.findByFirstName("Michael")

Author.findByLastNameLike("M%"),

Author.findByFirstNameIlikeAndLastName("m%", “Davis”)

DRY (Don't repeat yourself): Enables you to reuse code as much as possible. It also enables you to reuse java code.
Grails makes use of technologies such as Hibernate, Spring, JDBC, Sitemesh, Ajax. These compoments are already accepted and test technologies, which means strong support and faster development.
GORM (Grails Object Relational Mapping) is Grail’s ORM implementation. But as in case of hibernate, you don’t need to write any hbm configuration files (although you can if you want to) you can also use java for writing your domain classes. GORM provides many dynamic methods that come in very handy and also nearly eliminates the need to know the details of how hibernate works (although I personally believe, it makes a world of a difference if you do), easy way to add validations to your domain object, clear and precise way of specifying the relationship between your domain objects.
Comes with a built-in web server which leads to higher productivity during the development phase.
It has an in-memory database. You can push the choice of a database for your application to as late in the product life cycle as you wish and continue development and testing using the in-memory db.
Building the web-application is as easy as a single command at the command prompt!
It has an extensible plugin system which has lead to strong community support and acceptance. Again, this enables code reuse. There is a sea of plugins to choose from eg. Logging, security, Yahoo UI toolkit etc.
Good unit, integration and functional testing support.
Most suited for CRUD (create-retrieve-update-delete) type of applications.

I was personally surprised to see the speed at which I was able to come up with a stable application using Grails. If you are using the agile development methodology, you will be able to appreciate the benefits of using Grails. Grails as a technology brings the 'agile methodology' to web-application development. You will be able to reliably and efficiently change an entire functionality or feature in a matter of 2 to 3 days, that you may otherwise take a week in plain java. This enables you to seek feedback from your customers, quickly implement the changes and get back to them to repeat the cycle. This will lead to increased customer satisfaction & better clarity.

Although the framework does not guarantee a stable and robust application, but surely leaves you enough time and resources to ensure that you can strive for one. So the next time you have to develop an application with stringent time lines, you know what to try ;)

Having said that, you have to TRY it, to believe it.

Create your first grails plugin

2011-01-17T02:25:00.000-08:00

Crucial to the success of grails, is its support for plugins. Grails was designed keeping pluggability in mind right from the start. Ease in development, testing, building and distribution of plugins has led to a larger community interest in the framework, with loads of plugins available for developers to choose from.

If you’ve worked with grails, chances are you’ve used at least one grails plugin such as hibernate, logging, acegi, grails UI, mail, searchable etc. Grails maintains a plugin repository that you can search to find a plugin most suitable for your requirements. But have you ever found yourself in a situation where you’re rewriting the same code in multiple views, or duplicating code between controllers and services and even between multiple grails applications? If yes, this could be your chance of trying your hand at a plugin!

I’m presenting a very basic tutorial to create a very simple grails plugin, with a service and a taglib that can be reused across grails applications.( find a download link for the source code of the sample plugin at the bottom of the page)

This sample is tested using the following specifications:

grails version: grails-1.3.4
JDK version: jdk1.6

Let’s get started.

1. Choose a folder for your plugin source code.

2. To create a plugin named ‘customplugin’, use the following command at the command prompt.

grails create-plugin customplugin

This would create a structure such as this:

The plugin structure is almost exactly the same as a normal grails application. Thus you can add controllers, services, views, taglibs to your plugin just as you'd add them to a grails application.

You will find an additional file CustompluginGrailsPlugin.groovy at the root folder. This is the file that contains all the information or metadata for your plugin.

You can specify the version number, grails version that your plugin will work with, auther name, etc. Your plugin could depend on other plugins, for instance, you could write a plugin that works with database events which might need the hibernate plugin, such dependencies can be specified in this file. There are also several hooks (events) that are provided, which you can use to perform certain actions or load classes. For eg, if your plugin wants to make some changes/additions to the web.xml, you could plug that code in the doWithWebDescriptor closure provided. For the purpose of this tutorial, we are going to stick to the basics; we won't be using any of these hooks ( accounts for another article.. goes into my diary..)

3. Now let's create a service in the plugin. Use the following commands

cd customplugin
grails create-service conversion

4. Add the following code to the conversionService. This service has two functions for converting value in celcius into fahrenheit, an

         class ConversionService {
    static transactional = false

    def convertCelciusToFahrenheit = { tempInCelcius ->
        def tempInFah = ((9.0/5.0) * tempInCelcius )+ 32
        return tempInFah
    }

    def convertFahrenheitToCelcius = { tempInFah ->
        def tempInCelcius = (tempInFah - 32) * (5.0/9.0)
        return tempInCelcius
    }
}

5. Let's also add a tag library to the plugin. This library can be used to display navigation bread crumbs at the top of all the pages in the application.

grails create-tag-lib BreadCrumb

Add the following code to the file BreadCrumbTagLib:

      class BreadCrumbTagLib {

    static namespace="brcr"

    def breadCrumb = {
        out << "<a href='${request.getContextPath()}'>Home</a>"

        if(controllerName)
            {
                out << " -> <a href='${request.getContextPath()}/${controllerName}'>    \\
                ${controllerName}</a>"

                if(actionName)
                    out << " -> ${actionName} "
            }
    }
}

Notice the namespace in the above code. If you do not provide any namespace, you should be able to use 'breadCrumb' using <g:breadCrumb>. But if you want to change that to something specific, you can provide a namespace. For this example, we would need to use:
<brcr: breadCrumb />

6. We've added enough code to our plugin, let's package it now, use this command at the root folder of the plugin code:

grails package-plugin

You will see a file named grails-customplugin.zip at the root folder
7. To test if we're able to use the plugin correctly, let's now create a small grails application :

grails create-app myapp

8. To install the plugin created in step 6:

cd myapp
grails install-plugin <path_to_the_plugin>\grails-customplugin.zip

9. We will now create a simple controller to test the conversionService from the controller. We can simply consume the service by declaring a conversionService variable in the controller just as we do in a usual grails application. To create the controller:

grails crete-controller convert

add the following code to the controller:

         class ConvertController {

    def conversionService

    def index = {
        redirect(action:'convert')
    }

    def convert = {
        def result

        if(params.degrees)
            {
            result = convertionService.convertCelciusToFahrenhiet(params.degrees.toInteger())
            params.result= result
            }

        [result: result, degrees: params.degrees]
    }
}

10. Create the convert.gsp file in myapp/grails-app/views/convert folder which will take an input from the user in celcius, pass it on to the controller, which will call the service from the plugin and convert the value into fahrenheit and will send back the result to the view.

convert.gsp

         <g:form action="convert" method="post" controller="convert"><br/>
Celcius : <input type="text" class="text" size="60" id="degrees" name="degrees" value="${degrees}"/>
<br/>
<div>
     <span class="button"><g:submitButton name="convert" class="save" value="Convert" /></span>

</div>
<div>
<g:if test="${result}"><br/>
${degrees} celcius is equal to ${result} fahrenheit
</g:if>
</div>
</g:form>

To use the taglib, add <brcr:breadCrumb> to the layout file 'main.gsp' just before <g:layoutBody>.

11. Run the application using grails run-app and browse to http://localhost:8080/myapp/convert

There you go! you're first grails plugin in action

This is a very simple example for getting started with a basic skeleton for a plugin.
Hope you find this article helpful

Download plugin source code (customplugin.rar)
Download application source code (myapp.rar)