Changes between Version 27 and Version 28 of PluginDevelopmentGuide


Ignore:
Timestamp:
09.05.2013 03:46:41 (8 years ago)
Author:
jri
Comment:

Providing a RESTful web service

Legend:

Unmodified
Added
Removed
Modified
  • PluginDevelopmentGuide

    v27 v28  
    944944 
    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. 
     946 
     947=== Providing a RESTful web service === 
     948 
     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). 
     950 
     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. 
     952 
     953To make your plugin service RESTful you must: 
     954 
     955* Annotate the plugin main class with `@Path` to anchor the plugin service in URI space. 
     956 
     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. 
     958 
     959* Annotate each service method with one of `@GET`, `@POST`, `@PUT`, or `@DELETE` to declare the HTTP method that will invoke that service method. 
     960 
     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 `{...}`. 
     962 
     963* Annotate service method parameters with `@PathParam` to map URI template parameters to service method parameters. 
     964 
     965As an example let's see how the //Topicmaps// plugin (part of the DeepaMehta Standard Distribution) annotates its main class and service methods: 
     966 
     967{{{ 
     968#!java 
     969package de.deepamehta.plugins.topicmaps; 
     970 
     971import de.deepamehta.plugins.topicmaps.model.Topicmap; 
     972import de.deepamehta.plugins.topicmaps.service.TopicmapsService; 
     973 
     974import de.deepamehta.core.Topic; 
     975import de.deepamehta.core.osgi.PluginActivator; 
     976import de.deepamehta.core.service.ClientState; 
     977 
     978import javax.ws.rs.GET; 
     979import javax.ws.rs.PUT; 
     980import javax.ws.rs.POST; 
     981import javax.ws.rs.DELETE; 
     982import javax.ws.rs.HeaderParam; 
     983import javax.ws.rs.Path; 
     984import javax.ws.rs.PathParam; 
     985import javax.ws.rs.Produces; 
     986import javax.ws.rs.Consumes; 
     987 
     988 
     989 
     990@Path("/topicmap") 
     991@Consumes("application/json") 
     992@Produces("application/json") 
     993public class TopicmapsPlugin extends PluginActivator implements TopicmapsService { 
     994 
     995    // *** TopicmapsService Implementation *** 
     996 
     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    } 
     1005 
     1006    @GET 
     1007    @Path("/{id}") 
     1008    @Override 
     1009    public Topicmap getTopicmap(@PathParam("id") long topicmapId, @HeaderParam("Cookie") ClientState clientState) { 
     1010        ... 
     1011    } 
     1012 
     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    } 
     1020 
     1021    ... 
     1022}}} 
     1023 
     1024 
     1025 
     1026JAX-RS: Java API for RESTful Web Services 
     1027http://jsr311.java.net/nonav/releases/1.1/spec/spec.html