Changes between Version 27 and Version 28 of PluginDevelopmentGuide

Timestamp:

09.05.2013 03:46:41 (12 years ago)

Author:

jri

Comment:

Providing a RESTful web service

PluginDevelopmentGuide

@@ -944 +944 @@
 
 You 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.
+
+=== Providing a RESTful web service ===
+
+Until 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).
+
+To 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.
+
+To make your plugin service RESTful you must:
+
+* Annotate the plugin main class with `@Path` to anchor the plugin service in URI space.
+
+* 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.
+
+* Annotate each service method with one of `@GET`, `@POST`, `@PUT`, or `@DELETE` to declare the HTTP method that will invoke that service method.
+
+* 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 `{...}`.
+
+* Annotate service method parameters with `@PathParam` to map URI template parameters to service method parameters.
+
+As an example let's see how the //Topicmaps// plugin (part of the DeepaMehta Standard Distribution) annotates its main class and service methods:
+
+{{{
+#!java
+package de.deepamehta.plugins.topicmaps;
+
+import de.deepamehta.plugins.topicmaps.model.Topicmap;
+import de.deepamehta.plugins.topicmaps.service.TopicmapsService;
+
+import de.deepamehta.core.Topic;
+import de.deepamehta.core.osgi.PluginActivator;
+import de.deepamehta.core.service.ClientState;
+
+import javax.ws.rs.GET;
+import javax.ws.rs.PUT;
+import javax.ws.rs.POST;
+import javax.ws.rs.DELETE;
+import javax.ws.rs.HeaderParam;
+import javax.ws.rs.Path;
+import javax.ws.rs.PathParam;
+import javax.ws.rs.Produces;
+import javax.ws.rs.Consumes;
+
+
+
+@Path("/topicmap")
+@Consumes("application/json")
+@Produces("application/json")
+public class TopicmapsPlugin extends PluginActivator implements TopicmapsService {
+
+    // *** TopicmapsService Implementation ***
+
+    @POST
+    @Path("/{name}/{topicmap_renderer_uri}")
+    @Override
+    public Topic createTopicmap(@PathParam("name") String name,
+                                @PathParam("topicmap_renderer_uri") String topicmapRendererUri,
+                                @HeaderParam("Cookie") ClientState clientState) {
+        ...
+    }
+
+    @GET
+    @Path("/{id}")
+    @Override
+    public Topicmap getTopicmap(@PathParam("id") long topicmapId, @HeaderParam("Cookie") ClientState clientState) {
+        ...
+    }
+
+    @POST
+    @Path("/{id}/topic/{topic_id}/{x}/{y}")
+    @Override
+    public void addTopicToTopicmap(@PathParam("id") long topicmapId, @PathParam("topic_id") long topicId,
+                                   @PathParam("x") int x, @PathParam("y") int y) {
+        ...
+    }
+
+    ...
+}}}
+
+
+
+JAX-RS: Java API for RESTful Web Services
+http://jsr311.java.net/nonav/releases/1.1/spec/spec.html