http://code.google.com/p/grails-jaxrs/wiki/GettingStarted#Create_a_project
Overview
This page helps you getting started with the JSR 311 plugin for Grails. It is assumed that you have a basic understanding of Grails and the JSR 311 (JAX-RS: The Java API for RESTful Web Services). The examples in the following chapters have been tested with Grails 1.1.1, 1.1.2 and 1.2.0. For instructions how to download and install Grails refer to the Grails reference documentation section 2.1 . The Using Eclipse section on this page explains how to setup the examples in Eclipse.
Important notice : In order to use this plugin with Grails 1.2.0 checkout the latest development snapshot and install the plugin manually (deployment to Grails plugin repository not done yet).
Hello world
Create a project
grails create - app hello
on the command line. This creates a new directory hello .
Install the plugin
To install the plugin from the Grails Plugin Repository , go to the created hello directory and enter
grails install - plugin jaxrs
This will download the latest released version of the plugin from the Grails Plugin Repository . For further installation options, such as installing a development snapshot, refer to the installation instructions .
Create a resource
To create a JAX-RS resource named test enter
grails create - resource test
import javax . ws . rs . GET
import javax . ws . rs . Path
import javax . ws . rs . Produces
@Path ( '/api/test' )
class TestResource {
@GET
@Produces ( 'text/plain' )
String getTestRepresentation () {
'Test'
}
}
Run the application
To start the application enter
grails run - app
Change the code
import javax . ws . rs . GET
import javax . ws . rs . Path
import javax . ws . rs . Produces
import javax . ws . rs . QueryParam
@Path ( '/api/test' )
class TestResource {
@GET
@Produces ( 'text/plain' )
String getTestRepresentation ( @QueryParam ( 'name' ) String name ) {
"Hello ${name ? name : 'unknown'}"
}
}
When you save the changes the plugin re-initializes the JAX-RS runtime (see also console output). Go to http://localhost:8080/hello/api/test?name=Martin and you should see Hello Martin in the browser window. If you additionally want to factor out the greeting logic into a Grails service, refer to the service injection section for instructions.
Generate WADL
<application xmlns = "http://research.sun.com/wadl/2006/10" >
<doc xmlns:jersey = "http://jersey.dev.java.net/" jersey:generatedBy = "Jersey: 1.1.4.1 11/24/2009 01:30 AM" />
<resources base = "http://localhost:8080/hello/" >
<resource path = "/api/test" >
<method name = "GET" id = "getTestRepresentation" >
<request>
<param xmlns:xs = "http://www.w3.org/2001/XMLSchema" type = "xs:string" style = " query " name = "name" />
</request>
<response>
<representation mediaType = "text/plain" />
</response>
</method>
</resource>
</resources>
</application>
Generating WADL documents only works when the plugin is configured to use Jersey as JAX-RS implementation.
Scaffolding
Create a domain class
To create a Person domain class go to the project's root directory and enter
grails create - domain - class person
class Person {
static constraints = {
}
String firstName
String lastName
}
Generate the REST API
grails generate - resources person
Use the REST API
Start the hello application with
grails run - app
POST / hello / api / person HTTP / 1.1
Content - Type : application / xml
Accept : application / xml
Host : localhost : 8080
Content - Length : 82
<person>
<firstName> Sam < /firstName>
<lastName>Hill</ lastName >
</ person >
HTTP / 1.1 201 Created
Content - Type : application / xml
Location : http : //localhost:8080/hello/api/person/1
Transfer - Encoding : chunked
Server : Jetty ( 6.1 . 14 )
<? xml version = "1.0" encoding = "UTF-8" ?>
< person id = "1" >
<firstName> Sam < /firstName>
<lastName>Hill</ lastName >
</ person >
POST / hello / api / person HTTP / 1.1
Content - Type : application / json
Accept : application / json
Host : localhost : 8080
Content - Length : 58
{ "class" : "Person" , "firstName" : "Fabien" , "lastName" : "Barel" }
HTTP / 1.1 201 Created
Content - Type : application / json
Location : http : //localhost:8080/hello/api/person/2
Transfer - Encoding : chunked
Server : Jetty ( 6.1 . 14 )
{ "class" : "Person" , "id" : "2" , "firstName" : "Fabien" , "lastName" : "Barel" }