Changes between Version 27 and Version 28 of PluginDevelopmentGuide

09.05.2013 03:46:41 (11 years ago)

Providing a RESTful web service


  • PluginDevelopmentGuide

    v27 v28  
    945945You see the Geomaps plugin consumes 2 plugin services: the //Topicmaps// service and the //Facets// service. Both service interfaces are specified as the `@ConsumesService` argument. Note the array notation with the curly braces `{...}`. Note also the `if` statements in the `serviceArrived` and `serviceGone` hooks. 
     947=== Providing a RESTful web service === 
     949Until here your plugin service is accessible from within the OSGi environment only. You can make the service accessible from //outside// the OSGi environment as well by promoting it to a RESTful web service. Your plugin service is then accessible from external applications via HTTP. (External application here means both, the client-side portion of a DeepaMehta plugin, or an arbitrary 3rd-party application). 
     951To provide a RESTful web service you must provide a generic plugin service first (as described above in [[#Providingaservice|Providing a service]]) and then make it RESTful by using JAX-RS annotations. With JAX-RS annotations you basically control how HTTP requests will be mapped to your service methods. 
     953To make your plugin service RESTful you must: 
     955* Annotate the plugin main class with `@Path` to anchor the plugin service in URI space. 
     957* Annotate the plugin main class with `@Consumes` and `@Produces` to declare the supported HTTP request and response media types. You can use these annotations also at a particular service method to override the class-level defaults. 
     959* Annotate each service method with one of `@GET`, `@POST`, `@PUT`, or `@DELETE` to declare the HTTP method that will invoke that service method. 
     961* Annotate each service method with `@Path` to declare the URI template that will invoke that service method. The URI template can contain parameters, notated as `{...}`. 
     963* Annotate service method parameters with `@PathParam` to map URI template parameters to service method parameters. 
     965As an example let's see how the //Topicmaps// plugin (part of the DeepaMehta Standard Distribution) annotates its main class and service methods: 
     969package de.deepamehta.plugins.topicmaps; 
     971import de.deepamehta.plugins.topicmaps.model.Topicmap; 
     972import de.deepamehta.plugins.topicmaps.service.TopicmapsService; 
     974import de.deepamehta.core.Topic; 
     975import de.deepamehta.core.osgi.PluginActivator; 
     976import de.deepamehta.core.service.ClientState; 
     993public class TopicmapsPlugin extends PluginActivator implements TopicmapsService { 
     995    // *** TopicmapsService Implementation *** 
     997    @POST 
     998    @Path("/{name}/{topicmap_renderer_uri}") 
     999    @Override 
     1000    public Topic createTopicmap(@PathParam("name") String name, 
     1001                                @PathParam("topicmap_renderer_uri") String topicmapRendererUri, 
     1002                                @HeaderParam("Cookie") ClientState clientState) { 
     1003        ... 
     1004    } 
     1006    @GET 
     1007    @Path("/{id}") 
     1008    @Override 
     1009    public Topicmap getTopicmap(@PathParam("id") long topicmapId, @HeaderParam("Cookie") ClientState clientState) { 
     1010        ... 
     1011    } 
     1013    @POST 
     1014    @Path("/{id}/topic/{topic_id}/{x}/{y}") 
     1015    @Override 
     1016    public void addTopicToTopicmap(@PathParam("id") long topicmapId, @PathParam("topic_id") long topicId, 
     1017                                   @PathParam("x") int x, @PathParam("y") int y) { 
     1018        ... 
     1019    } 
     1021    ... 
     1026JAX-RS: Java API for RESTful Web Services