Remoting Plugin

  • Tags : web services
  • Latest : 1.3
  • Last Updated: 04 September 2012
  • Grails version : 2.0 > *
1 vote
Dependency :
compile ":remoting:1.3"

Documentation Source Issues

Summary

This plugin makes it easy to expose your Grails services to remote clients via RMI, Hessian, Burlap and Spring's HttpInvoker protocol. In addition, you can easily access remote services via the same set of protocols.

Description

Remoting Plugin

If you have ever wanted to access your Grails services via RMI or some other remote protocol, this is your plugin. Grails services can be exposed via the following protocols:

  • RMI
  • Hessian
  • Burlap
  • Spring's HttpInvoker (Java serialisation over HTTP)

Setup

If you run Grails from your IDE, you must also compile the plugin's Java sources:

grails dev package

Also, you will need to setup a UrlMapping for rmi/httpinvoker/hessian/burlap before you can use any exposed service. The default UrlMapping provided by grails will work.

"/$controller/$action?/$id?"{
}

Exporting your service via a remoting protocol

There are two aspects to making a service available to clients via remoting protocols: first, the service must implement an interface - this interface defines the methods that can be invoked by the client. The interface can be anywhere as long as it ends up on the classpath. Typically, either the source file is under src/java or src/groovy , or the compiled class is in a JAR file.

Second, the service must have a static property called expose set to a list of protocols. For example,

class SecurityService implements example.SecurityService {
    static expose = ['hessian', 'rmi']

def authenticate(username, password) { … }

def isPermitted(user, permission) { … } }

The expose property accepts any of these values: 'rmi', 'hessian', 'burlap', and 'httpinvoker'.

You may notice that the configuration is similar to that for the XFire web services plugin. In fact, you should be able to install that plugin and add 'xfire' to the expose list:
static expose = ['xfire', 'rmi', 'hessian']

If you export your service via RMI, it will be available on port 1199 by default. However, you can override this by providing a configuration setting in Config.groovy:

remoting.rmi.port = 22222

Calling a remote service

You can easily access a remote service from your Grails application by creating a normal Grails service and adding a static remote property:

class SecurityService {
    static remote = [
        protocol: 'hessian',
        iface: example.SecurityService,
        host: 'castle',
        port: '9090',
        webcontext: 'security',
    ]
}

This service will be injected into your controllers and other services. Any method calls on the service will be transparently routed to the remote service.

Here is a list of the supported properties:

  • protocol - The protocol to use when accessing the remote service. (Required)
  • iface - The interface that the remote service implements. (Required)
  • host - The host where the remote service is located. (Defaults to 'localhost')
  • port - The port on which the remote service is available. (Defaults to 1199 for RMI, 8080 for all other protocols)
  • webcontext - The name of the webapp containing the remote service, as it appears in the webapp's URL. (A root webapp is assumed by default; ignored completely by RMI)
  • url - The URL of the remote service. This overrides any host , port , and webcontext settings. (Optional)
When using the host , port , and webcontext properties, the plugin assumes that the remote service has been exported via a different instance of itself, and so constructs the service URL accordingly. In this case, the name of your service class must match the name of the exported service. You will see a list of the standard URLs used at the end of the page.

Accessing remote services from other clients

Once you have your server running, you can access your services via the configured remoting protocols. Just point your client(s) at the following URLs, where <host> is the hostname of the server, <app> is the name of you Grails app, and <service> is the class name of the exposed service, for example SecurityService .

ProtocolURL
RMIrmi://<host>:1199/<service>
Hessianhttp://<host>:8080/<app>/hessian/<service>
Burlaphttp://<host>:8080/<app>/burlap/<service>
HttpInvokerhttp://<host>:8080/<app>/httpinvoker/<service>