Adding External Jar to Grails

One option for object type of Dates is LocalDate type (org.joda.time package),however , it  doesn’t come part of Grails stack. In order to use it in Grails projects, it’s necessary to install and configure the external dependency package – org.joda.time.LocalDate. This post covers steps how to add an external Jar( i.e. org.joda.time) in your Grails project

Step 1. Retrieve Dependency

Grails is using Ivy as its dependency manager to organize dependencies in single location locally while documenting. The Ivy dependency manager will load the dependency locally with following command:

>grails install-dependency nameOfDependency

Before calling this command, lets find out the name of dependency for our new data type ‘LocalDate’. To do so, we look in shared centra repo such as maven2 repository for instance.. It hosts nearly of 90% of Java’s open source libraries, so chances are high it will host the dependency – org.joda.time.LocalDate

The maven2 repository search locates the dependency of interest if using keyword ‘joda time’. To locate name, click on the version of the dependency and under ‘Dependency Information’ there is grails name for this dependency as shown here:

As you can see, it specifies Grails framework(green line) along the actual dependency name (red line)

With the name, its time to download the dependency as follows:

>grails install-dependency joda-time:joda-time:2.1

This will make ivy manager go grab the dependency from shared central repo such as maven2 repo and install it in local Ivy repo that way caching it. If you like to check what’s in the Ivy local repo cached, look into .ivy2/cache folder (by default in home directory)

Step 2. Add Dependency to Grails Project Class Path

Once in local Ivy repo, it necessary to tell the particular grails project to use it or, in another words, add it to the class path of the particular Grails project. In order to do that, update  the ‘dependencies’ section in the BuildConfig.groovy as following:

dependencies {
   ...
   compile 'joda-time:joda-time:2.1'
   ...
}

With this, the particular Grails project will know to include your new dependency

Step 3. Refresh and Compile

First, refresh the dependencies as following:

>grails refresh-dependencies

This takes the dependency(.jar) from the local Ivy repo(.ivy2/cache) and moves into grails Ivy repo(.grails/ivy-cache by default home directory) making it in class path for grails to find at compile time.
Next, compile the dependency with command

>grails compile

This grabes the configured dependency name in BuildConfig.groovy(Step2), locates the jar in local Ivy grails repo(.grails/ivy-cache) and compiles

Step 4. Verify

Afterwards, to verify that the particular grails project includes the dependency and the right version, look it up in grails dependency report. To generate report run the following:

>grails dependency-report

This will generate report that you open in any browser. In the report, in the ‘compile’ section you should see your new dependency listed as follows:

To Summarize

A single picture worth more than 1000 words, so graphical summary:

Other

1. Note on Configurations
Besides BuildConfig.groovy also ‘application.properties’ contains configuration of dependencies such as plugins. If in both places there are configuration for the some plugin for instance than the ‘application.properties’ config supersedes the Buildingconfig.groovy configurations
2. Hibernate Support
To ensure that the LocalDate is persistant in the Database accordingly, lets add the hibernate support (in BuildConfig.groovy)

dependencies {
...
compile('joda-time:joda-time-hibernate:1.3') {
            excludes 'hibernate', 'joda-time'
        }
...
}

Troubleshooting

Sometimes the ‘compile’ doesn’t seem to compile the new dependency right the way. To see what is being compiled, turn on the logging in BuildConfig.groovy:

grails.project.dependency.resolution = {
 ...
  log 'info'
...

By setting the log level to ‘info’, the process of compile, build, etc is logged in the console output.

Useful Links