Introduction

Very simple usage

An instance of GroovyRestlet is the starting point of everything.

You can programmatically create an instance of GroovyRestlet:

GroovyRestlet gr = new GroovyRestlet();//#1

GroovyRestlet grWithSpring = new GroovyRestlet(springApplicationContext); //#2

Constructor method of #2 indicates that this instance of GroovyRestlet will consult Spring's ApplicationContext when constructing its component. So the Spring integration is done.

Alternatively, you can choose to declare GroovyRestlet in Spring bean definition. By this way, GroovyRestlet will automatically use its parent context when constructing its compoents.

<bean id="groovyRestlet" class="org.lpny.groovyrestlet.GroovyRestlet"/>

Spring Integration

When Spring's ApplicationContext is provided, GroovyRestlet will try to consult Spring context for creating its components.
Two special attributes are provided for integrating GroovyRestlet and Spring.

Technical detail

GroovyRestlet

As the only entry point of GroovyRestlet, this instance automatically declares a number of global variables in the Groovy context. Users are also be able to provide their special context variables. In order to do that, users can provide a map of customer context when calling build method.

groovyRestlet.build(userDefinedContext, scriptURI);

This userDefinedContext is only visible for each call of build method. It will be merged into Groovy context and removed after each calling. And variables of userDefinedContext can override values of default context. Be careful when doing this.

RestletBuilder

RestletBuilder is a simple implementation of Groovy's FactoryBuilderSupport. By default, all constructor factories are registered. Users are able choose which constructors are to be used freely.

To do this programmatically, just set a list of constructor factories after a build instance is created.

RestletBuilder builder = new RestletBuilder()

builder.setFactories(yourFactoryList);

groovyRestlet.setBuilder(builder)

Alternatively, you can do this in Spring bean definition

<bean id="groovyRestlet" class="org.lpny.groovyrestlet.GroovyRestlet">
  <property name="builder" ref="restletBuilder"/>
</bean>

<bean id="restletBuilder" class="org.lpny.groovyrestlet.builder.RestletBuilder">
  <property name="factories">
    <list>
       <!-- any factory instance -->
    </list>
  </property>
</bean>

Global variables

For convenience, GroovyRestlet add a number of Restlet-related variables to Groovy global context. Users can directly refer them in there building scrpits.

Name

Usage

Example

builder

The reference of a builder

builder.component()

protocol

Shortcut to Restlet Protocol

protocol.HTTP

mediaType

Shortcut to Restlet MediaType

mediaType.TEXT_PLAIN

status

Shortcut to Restlet Status

status.CLIENT_ERROR_NOT_FOUND

challengeScheme

Shortcut to Restlet ChallengeScheme

challengeScheme.HTTP_BASIC

redirectorMode

Shortcut to mode of Restlet Redirector

redirectorMode.MODE_CLIENT_FOUND

routingMode

Shortcut to mode of Restlet Router

routingMode.BEST

transformer

Shortcut to mode of Restlet Transformer

transformer.MODE_REQUEST

global

Special shortcut providing a set of global variables and methods

 

At current moment, you can call global.status(404) to create a CLIENT_ERROR_NOT_FOUND status.

Constructors

Every constructor is support ofBean and ofClass attributes. The value of ofBean must be a Sting. ofBean is only effected when a Spring context is provided. The value of ofClass can either be a String or an instance of Java Class.

According to Groovy Builders, constructors can be nested to each other. In that case, GroovyRestlet will automatically set up Restlet-specific relationship between parent and child instances. But user can disable this feature by setting autoAttach attribute as false.

In Restlet, the Router.attach method returns a Route instance. In order to do some special process on the Route instance, an attribute postAttach which refers to a Groovy closure is provided. For example:

builder.router{
    restlet(uri:"/users/{user}", postAttach:{route->
       //do some post attaching process here
       //...
    })
}

Another important attribute is uri which indicates a URI Template using by Restlet Router.

restlet

The generic constructor for all components of type of Restlet. You can use ofClass attribute to indicate restlet to create an instance of a subtype. When doing that, using attribute consArgs to provide arguments array of corresponding constructor. For example:

builder.restlet(ofClass:"org.restle.Transform", consArgs:[transformer.MODE_REQUEST, sheet] as Object[])

Another important attribute of restlet is handle, which refers to a Groovy closure. Once this attribute provided, this closure will override the default handle method of the Restlet.

builder.restlet(handle:{request, response, self->
   return new StringRepresentation("Hello GroovyRestlet")
})

Sometimes it is necessary to access the instance of Restlet itself. You can do that by appending an additional argument in the closure argument list. GroovyRestlet will automatically pass the calling instance to the closure as shown in above example.

This handle attribute is only effected when neither ofClass nor ofBean attribute is used.

server

A shortcut to create a Restlet Server. Instance of the nested constructor of a server will become the server's target. If more nested constructors are defined, only the last one will be selected.

Attributes:

client

A shortcut to create a Restlet Client.

Attributes:

component

A shortcut to create a Restlet Component. If no VirtualHost is specified, direct children of component constructor will be attached to Component's default VirtualHost. For example,

builder.component{
    application(uri:"")
}

Which is equivalent to Java code:

Component component = new Component();
component.getDefaultHost().attach("", new Application());

application

A shortcut to create a Restlet Application. The direct child of application constructor, without attribute autoAttach as false, will be set as the root of the application instance. If more direct nested constructors are defined, only the last one will be selected.

router

A shortcut to create a Restlet Router. A router constructor can have one or more nested children. Each child will be attached to the router by calling Router.attach method.

filter

A shortcut to create a Restlet Filter.

Attributes

redirector

A shortcut to create a Restlet Redirector.

guard

A shortcut to create a Restlet Guard.

Attributes

directory

A shortcut to create a Restlet Directory. A directory constructor can not nest child.

Attributes:

resource

A shortcut to create a Restlet Resource. A resource constructor can not nest child; and it can be nested in filter and router.

Attributes

resource constructor provides a set of closure attributes for easily handling RESTful calls.

These closures are only effected when no ofClass and ofBean attribute is specified.