Copy Page

You are not logged in. Any changes you make will be marked as anonymous. You may want to Log In if you already have an account. You can also Sign Up for a new account.

<h2>Introduction</h2>

<h3>Very simple usage</h3>

<p>An instance of <code>GroovyRestlet</code> is the starting point of everything.</p>

<p>You can programmatically create an instance of <code>GroovyRestlet</code>:</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
GroovyRestlet gr = new GroovyRestlet();//#1

GroovyRestlet grWithSpring = new GroovyRestlet(springApplicationContext); //#2
</pre></td></tr></table>
<p>Constructor method of #2 indicates that this instance of <code>GroovyRestlet</code> will consult Spring's ApplicationContext when constructing its component. So the Spring integration is done.</p>

<p>Alternatively, you can choose to declare <code>GroovyRestlet</code> in Spring bean definition. By this way, <code>GroovyRestlet</code> will automatically use its parent context when constructing its compoents.</p>
<table class="wysiwyg-macro" data-macro-name="code" data-macro-default-parameter="xml" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6eG1sfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
&lt;bean id="groovyRestlet" class="org.lpny.groovyrestlet.GroovyRestlet"/>
</pre></td></tr></table>

<h3>Spring Integration</h3>

<p>When Spring's ApplicationContext is provided, <code>GroovyRestlet</code> will try to consult Spring context for creating its components.<br />
Two special attributes are provided for integrating <code>GroovyRestlet</code> and Spring.</p>
<ul>
	<li><strong>ofBean</strong>: to tell <code>GroovyRestlet</code> that to create a component from Spring context by a bean name;</li>
	<li><strong>ofClass</strong>: to tell <code>GroovyRestlet</code> that to create a component using Spring's <a href="http://static.springframework.org/spring/docs/2.5.x/api/org/springframework/beans/factory/config/AutowireCapableBeanFactory.html">AutowireCapableBeanFactory</a>
<table class="wysiwyg-macro" data-macro-name="info" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2luZm99&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body"><p><code>GroovyRestlet</code> will only use AutowireCapableBeanFactory to create instance indicated by <strong>ofClass</strong> when Spring context is provided. Otherwise it will create an instance of that class using Java reflection</p></td></tr></table></li>
</ul>

<h2>Technical detail</h2>

<h3><code>GroovyRestlet</code></h3>

<p>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 <code>build</code> method.</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
groovyRestlet.build(userDefinedContext, scriptURI);
</pre></td></tr></table>
<table class="wysiwyg-macro" data-macro-name="note" data-macro-parameters="title=Be careful" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vdGU6dGl0bGU9QmUgY2FyZWZ1bH0&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body">
<p>This <strong>userDefinedContext</strong> is only visible for each call of build method. It will be merged into Groovy context and removed after each calling. And variables of <strong>userDefinedContext</strong> can override values of default context. Be careful when doing this.</p></td></tr></table>

<h3><code>RestletBuilder</code></h3>

<p><code>RestletBuilder</code> 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.</p>

<p>To do this programmatically, just set a list of constructor factories after a build instance is created.</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
RestletBuilder builder = new RestletBuilder()

builder.setFactories(yourFactoryList);

groovyRestlet.setBuilder(builder)
</pre></td></tr></table>
<p>Alternatively, you can do this in Spring bean definition</p>
<table class="wysiwyg-macro" data-macro-name="code" data-macro-default-parameter="xml" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6eG1sfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
&lt;bean id="groovyRestlet" class="org.lpny.groovyrestlet.GroovyRestlet">
  &lt;property name="builder" ref="restletBuilder"/>
&lt;/bean>

&lt;bean id="restletBuilder" class="org.lpny.groovyrestlet.builder.RestletBuilder">
  &lt;property name="factories">
    &lt;list>
       &lt;!-- any factory instance -->
    &lt;/list>
  &lt;/property>
&lt;/bean>
</pre></td></tr></table>

<h3>Global variables</h3>

<p>For convenience, <code>GroovyRestlet</code> add a number of Restlet-related variables to Groovy global context. Users can directly refer them in there building scrpits.</p>
<table class="confluenceTable"><tbody>
<tr>
<th class="confluenceTh"><p> Name </p></th>
<th class="confluenceTh"><p> Usage </p></th>
<th class="confluenceTh"><p> Example </p></th>
</tr>
<tr>
<td class="confluenceTd"><p> <strong>builder</strong> </p></td>
<td class="confluenceTd"><p> The reference of a builder </p></td>
<td class="confluenceTd"><p> <code>builder.component()</code> </p></td>
</tr>
<tr>
<td class="confluenceTd"><p> <strong>protocol</strong> </p></td>
<td class="confluenceTd"><p> Shortcut to Restlet <a href="http://www.restlet.org/documentation/1.1/api/org/restlet/data/Protocol.html">Protocol</a> </p></td>
<td class="confluenceTd"><p> <code>protocol.HTTP</code> </p></td>
</tr>
<tr>
<td class="confluenceTd"><p> <strong>mediaType</strong> </p></td>
<td class="confluenceTd"><p> Shortcut to Restlet <a href="http://www.restlet.org/documentation/1.1/api/org/restlet/data/MediaType.html">MediaType</a> </p></td>
<td class="confluenceTd"><p> <code>mediaType.TEXT_PLAIN</code> </p></td>
</tr>
<tr>
<td class="confluenceTd"><p> <strong>status</strong> </p></td>
<td class="confluenceTd"><p> Shortcut to Restlet <a href="http://www.restlet.org/documentation/1.1/api/org/restlet/data/Status.html">Status</a> </p></td>
<td class="confluenceTd"><p> <code>status.CLIENT_ERROR_NOT_FOUND</code> </p></td>
</tr>
<tr>
<td class="confluenceTd"><p> <strong>challengeScheme</strong> </p></td>
<td class="confluenceTd"><p> Shortcut to Restlet <a href="http://www.restlet.org/documentation/1.1/api/org/restlet/data/ChallengeScheme.html">ChallengeScheme</a> </p></td>
<td class="confluenceTd"><p> <code>challengeScheme.HTTP_BASIC</code> </p></td>
</tr>
<tr>
<td class="confluenceTd"><p> <strong>redirectorMode</strong> </p></td>
<td class="confluenceTd"><p> Shortcut to mode of Restlet <a href="http://www.restlet.org/documentation/1.1/api/org/restlet/Redirector.html">Redirector</a> </p></td>
<td class="confluenceTd"><p> <code>redirectorMode.MODE_CLIENT_FOUND</code> </p></td>
</tr>
<tr>
<td class="confluenceTd"><p> <strong>routingMode</strong> </p></td>
<td class="confluenceTd"><p> Shortcut to mode of Restlet <a href="http://www.restlet.org/documentation/1.1/api/org/restlet/Router.html">Router</a> </p></td>
<td class="confluenceTd"><p> <code>routingMode.BEST</code> </p></td>
</tr>
<tr>
<td class="confluenceTd"><p> <strong>transformer</strong> </p></td>
<td class="confluenceTd"><p> Shortcut to mode  of Restlet <a href="http://www.restlet.org/documentation/1.1/api/org/restlet/Transformer.html">Transformer</a> </p></td>
<td class="confluenceTd"><p> <code>transformer.MODE_REQUEST</code> </p></td>
</tr>
<tr>
<td class="confluenceTd"><p> <strong>global</strong> </p></td>
<td class="confluenceTd"><p> Special shortcut providing a set of global variables and methods </p></td>
<td class="confluenceTd"><p> </p></td>
</tr>
</tbody></table>

<p>At current moment, you can call <code>global.status(404)</code> to create a <code>CLIENT_ERROR_NOT_FOUND</code> status.</p>

<h3>Constructors</h3>

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

<p>According to <a class="confluence-link" href="/display/GROOVY/Builders" data-linked-resource-id="16958" data-linked-resource-type="page" data-linked-resource-default-alias="Builders" data-base-url="http://docs.codehaus.org">Groovy Builders</a>, 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 <strong>autoAttach</strong> attribute as <code>false</code>.</p>

<p>In Restlet, the Router.attach method returns a Route instance. In order to do some special process on the Route instance, an attribute <strong>postAttach</strong> which refers to a Groovy closure is provided. For example:</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
builder.router{
    restlet(uri:"/users/{user}", postAttach:{route->
       //do some post attaching process here
       //...
    })
}
</pre></td></tr></table>

<p>Another important attribute is <strong>uri</strong> which indicates a <a href="http://www.restlet.org/documentation/1.1/api/org/restlet/util/Template.html">URI Template</a> using by Restlet Router.</p>

<h4><code>restlet</code></h4>

<p>The generic constructor for all components of type of <a href="http://www.restlet.org/documentation/1.1/api/org/restlet/Restlet.html">Restlet</a>. You can use <strong>ofClass</strong> attribute to indicate <code>restlet</code> to create an instance of a subtype. When doing that, using attribute <strong>consArgs</strong> to provide arguments array of corresponding constructor. For example:</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
builder.restlet(ofClass:"org.restle.Transform", consArgs:[transformer.MODE_REQUEST, sheet] as Object[])
</pre></td></tr></table>
<p>Another important attribute of <code>restlet</code> is <strong>handle</strong>, which refers to a Groovy closure. Once this attribute provided, this closure will override the default <a href="http://www.restlet.org/documentation/1.1/api/org/restlet/Restlet.html#handle(org.restlet.data.Request,%20org.restlet.data.Response)">handle</a> method of the Restlet.</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
builder.restlet(handle:{request, response, self->
   return new StringRepresentation("Hello GroovyRestlet")
})
</pre></td></tr></table>
<p>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.</p>
<table class="wysiwyg-macro" data-macro-name="info" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2luZm99&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body">
<p>This <strong>handle</strong> attribute is only effected when neither <strong>ofClass</strong> nor <strong>ofBean</strong> attribute is used.</p></td></tr></table>

<h4><code>server</code></h4>

<p>A shortcut to create a Restlet Server. Instance of the nested constructor of a <code>server</code> will become the <a href="http://www.restlet.org/documentation/1.1/api/org/restlet/Server.html#setTarget(org.restlet.Restlet)">server's target</a>. If more nested constructors are defined, only the last one will be selected.</p>

<h5>Attributes:</h5>

<ul>
	<li><strong>protocol</strong>: the server protocol</li>
	<li><strong>protocols</strong>: a list of server protocols</li>
	<li><strong>address</strong>: the address of server</li>
	<li><strong>port</strong>: the port of server</li>
</ul>

<h4><code>client</code></h4>

<p>A shortcut to create a Restlet Client.</p>

<h5>Attributes:</h5>

<ul>
	<li><strong>protocol</strong>: the client protocol</li>
	<li><strong>protocols</strong>: a list of client protocols</li>
</ul>

<h4><code>component</code></h4>
<p>A shortcut to create a Restlet Component. If no VirtualHost is specified, direct children of component constructor will be attached to Component's <a href="http://www.restlet.org/documentation/1.1/api/org/restlet/Component.html#getDefaultHost()">default VirtualHost</a>. For example,</p>

<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
builder.component{
    application(uri:"")
}
</pre></td></tr></table>

<p>Which is equivalent to Java code:</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
Component component = new Component();
component.getDefaultHost().attach("", new Application());
</pre></td></tr></table>

<h4><code>application</code></h4>
<p>A shortcut to create a Restlet Application. The direct child of application constructor, without attribute <strong>autoAttach</strong> as <code>false</code>, will be set as the <a href="http://www.restlet.org/documentation/1.1/api/org/restlet/Application.html#getRoot()">root</a> of the application instance. If more direct nested constructors are defined, only the last one will be selected.</p>

<h4><code>router</code></h4>
<p>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 <code>Router.attach</code> method.</p>

<h4><code>filter</code></h4>
<p>A shortcut to create a Restlet Filter.</p>

<h5>Attributes</h5>
<ul>
	<li><strong>before</strong>: a closure to be called when <code>Filter.beforeHandle</code> is called;</li>
	<li><strong>after</strong>: a closure to be called when <code>Filter.afterHandle</code> is called;</li>
	<li><strong>handle</strong>: a closure to be called when <code>Filter.doHandle</code> is called;</li>
</ul>

<h4><code>redirector</code></h4>
<p>A shortcut to create a Restlet Redirector.</p>

<h4><code>guard</code></h4>
<p>A shortcut to create a Restlet Guard.</p>

<h5>Attributes</h5>
<ul>
	<li><strong>scheme</strong>: the challenge scheme, will use <code>ChanllengeScheme.valueOf(&quot;None&quot;)</code> if no <strong>scheme</strong> is provided;</li>
	<li><strong>realm</strong>: the authentication realm</li>
</ul>

<h4><code>directory</code></h4>
<p>A shortcut to create a Restlet Directory. A directory constructor can not nest child.</p>

<h5>Attributes:</h5>
<ul>
	<li><strong>root</strong>: the root uri of the Directory</li>
</ul>

<h4><code>resource</code></h4>
<p>A shortcut to create a Restlet Resource. A resource constructor can not nest child; and it can be nested in filter and router.</p>

<h5>Attributes</h5>

<p><code>resource</code> constructor provides a set of closure attributes for easily handling RESTful calls.</p>
<ul>
	<li><strong>store</strong>: for handling <strong>HTTP PUT</strong> method</li>
	<li><strong>remove</strong>: for handling <strong>HTTP DELETE</strong> method</li>
	<li><strong>accept</strong>: for handling <strong>HTTP POST</strong> method</li>
	<li><strong>represent</strong>: for handling <strong>HTTP GET</strong> method</li>
	<li><strong>head</strong>: for handling <strong>HTTP HEAD</strong> method</li>
	<li><strong>options</strong>: for handling <strong>HTTP OPTIONS</strong> method</li>
</ul>

<p>These closures are only effected when no <strong>ofClass</strong> and <strong>ofBean</strong> attribute is specified.</p>