A Day At The Races

My Grails Spy plugin was mentioned in the episode 103 (at 0:18:30) of Grails Podcast. Thanks, Glen and Sven!

While digging through the inner workings of Grails in order to improve my OSGi plugin, it is sometimes necessary to inspect the GrailsApplication object and its companion Spring ApplicationContext(s).

As most of the beans of the Grails WebApplicationContext are constructed at runtime with the help of a BeanBuilder, there is no Spring xml file with bean definitions.

Only the main application context can be inspected, e.g. by extracting it from the generated war file:

jinspect -a target/myapp-0.1.war

In order to browse the dynamic bean definitions I created a little plugin called Grails Spy, which can be used to watch into an application’s guts.

License

The Spy plugin is released under the Apache License 2.0.

Source code and Issues

The source code is hosted at GitHub, issues can be reported here.

Installation

As always, simply execute grails install-plugin spy.

Note: until the Grails plugin page is sync’ed, the plugin can also be installed using
grails install-pluginhttp://cloud.github.com/downloads/jetztgradnet/grails-spy-plugin/grails-spy-0.1.zip

Usage

Simply browse to http://localhost:8080/myapp/spy/ and have a closer look.

Note: this path is NOT PROTECTED, so don’t do this in a production environment! Or at least use one of the security plugins to protect this page.

Screenshots

Eye-candy you say? See below:

GrailsSpy: GrailsApplication

GrailsSpy: ApplicationContext view

GrailsSpy: bean view

Fernando Takai wrote an excellent bash completion script (also available here, originally from Ted Naleid), which makes calling Grails commands much easier.

Some examples:

Within a Grails application directory, listing all available commands:

myapp> grails [tab][tab]
bootstrap create-integration-test generate-controller list-plugins_ set-version
bug-report create-plugin_ generate-views package shell
clean create-script help_ package-plugin_ stats
compile create-service init plugin-info_ test-app
console create-tag-lib install-dependency release-plugin tomcat
create-app_ create-unit-test install-plugin run-app uninstall-plugin
create-controller dependency-report install-templates run-war upgrade
create-domain-class doc integrate-with schema-export war
create-filters generate-all list-plugin-updates set-proxy_


Within a Grails application directory, completing a command:

myapp> grails run-[tab][tab]
run-app run-war


Outside of a Grails application directory, listing all available commands:

home> grails [tab][tab]
create-app create-plugin help list-plugins package-plugin plugin-info set-proxy


Changes

I updated the script to adapt it to new Grails versions and made some minor changes:

* works with plugin provided scripts in Grails version >= 1.1, were plugins are stored under $HOME/.grails/grailsversion/projects/appname/plugins.
* detects the Grails version from $GRAILS_HOME instead of choosing the latest version from $HOME/.grails.
* adapts to different locations of plugins-list.xml, which changed with newer Grails versions
* does not need gawk (which is not installed by default on OSX)

My version of the script was tested with Grails 1.2 and OSX Snow Leopard and can be found at GitHub or below.

Installation

Save the script to an appropriate path (e.g. ~/bin/grails-bash-completion.sh)
[ -r ~/bin/grails-bash-completion.sh ] && source ~/bin/grails-bash-completion.sh

The complete Script

I just wrote a little script to inspect jar and war files, Grails applications and plugins.

Installation

Simply copy the script to somewhere in your path (e.g. ~/bin) and make it executable using
chmod +x jinspect

I tested the script on OSX Snow Leopard, but it should run on other versions of OSX and Linux, too.

Examples:

List all files in a war/jar/zip:
jinspect -l myapp.war

Show contents of some files in a jar/war/zip:
jinspect myapp.war index.html another.txt

List gsp and jsp files in a war:
jinspect -JG myapp.war

Show contents of web.xml file in a war:
jinspect -w myapp.war

Extract and save web.xml file in a war:
jinspect -Xw myapp.war

Show contents of the Plugin class of a Grails plugin:
jinspect -P grails-osgi-0.1.zip

Available options:

jinspect [-hHvxXoawmISMWjJrgGcCpPlLZZZ] jarfile [filename ...]
Options:
-h show help
-v be more verbose
-X save specified files (including path) to the current directory instead of printing them
-l list war contents; specify again to include more information
-x list xml files
-o list properties files
-c list class files
-j list java files
-J list jsp files
-S list js files
-g list groovy files
-G list gsp files
-H list html files
-C list css files
-I list image files
-L list files in lib directory
-M list files in META-INF directory
-W list files in WEB-INF directory
-a show WEB-INF/applicationContext.xml
-w show WEB-INF/web.xml
-r show WEB-INF/grails.xml
-m show META-INF/MANIFEST.MF
-p show plugin.xml
-P show *GrailsPlugin.groovy
-d show manifest headers in nicely formatted way; implies -m
-D display named manifest header; can be used multiple times, implies -m


Script
(also available on GitHub)

The Grails OSGi plugin provides scripts to package a Grails application as an OSGi bundle. Additionally the bundle(s) may be run in an OSGi container assembled ad hoc by the excellent Pax Runner or deployed to a SpringSource DM Server.

License

The OSGi plugin is released under the Apache License 2.0.

Installation

Simply call grails install-plugin osgi to install the OSGi plugin.

Usage:

Creating an OSGi bundle from the Grails application

grails bundle
grails prod bundle

Running the bundle

grails run-bundle
grails prod run-bundle

The application can be accessed at http://localhost:8080/myapp/.

Note: at first start the OSGi runtime is assembled, which may take some time, while Maven is downloading the internet…

Creating a zipped OSGi runtime

grails assemble-osgi-runtime
grails prod assemble-osgi-runtime

Deploy bundle to DM Server

grails dmserver deploy (Not yet implemented)

Getting around the OSGi runtime

The OSGi runtime is based on the Equinox OSGi framework, Pax Web and some additional bundles.

Web Console

The Felix Web Management Console provides excellent insight into the inner workings (see Screenshots). It can be accessed at http://localhost:8080/system/console/ with user “admin” and password “admin”.

Shell Console

The command grails run-bundle drops the user in the Equinox Shell. Typing help shows the available commands.

How it works

In order to be a valid OSGi bundle, the application is war’ed and provided with the necessary bundle manifest headers (see scripts/_Event.groovy for details).
The bundle can be created using grails bundle.

The OSGi runtime is assembled in the target/osgi directory.

Source code and Issues

The source code is hosted at GitHub, issues can be reported here.

Roadmap

• make bundle generation configurable (e.g. include/exclude dependencies, …)
• make OSGi runtime created by grails run-bundle and grails assemble-osgi-runtime configurable
• support auto-reloading of changed artifacts
• use Spring DM instead of Pax Web as Web extender
• remove dependencies from bundle and package them as their own plugins (re-using existing bundles from the SpringSource Enterprise Repository
• export main Grails beans and application context as OSGi service
• export services as OSGi service (via static expose = 'osgi')
• provide access to OSGi BundleContext to artifacts (controllers, services, …)
• implement deployment to DM Server
• consider other deployment options: Apache Karaf, …