JAX-RS or THE way to do REST in Domino Part 3

In the last segment of this series I pointed you to use a couple of resources from  my github as templates, but didn’t really specify how those work or how to add your own services.  I hope to finish the series today with some explanation of those resources.

Web.xml

The Web.xml is the configuration in all Java EE apps.  It basically sets up the configuration for the application.  The application I have specified has a single servlet, which is defined by the wink framework.

org.apache.wink.server.internal.servlet.RestServlet

This servlet looks for a class of type “javax.ws.rs.core.Application”

So your application will need a class that extends it.  In the web.xml its specified in the init-param

<init-param>
<param-name>javax.ws.rs.Application</param-name>
<param-value>com.tobysamples.demo.wink.HelloWorldApplication</param-value>
</init-param>

The web.xml also has a servlet mapping basically specifies what url the servlet will live at.  In the example it is “/rest*/  which basically means if the url has that pattern in it it will call the servlet and pass in the rest of the url for routing.

HelloWorldApplication.java

This is the aforementioned class that is referenced in the web.xml.  The only thing it really does is overrides the getClasses Method and returns back a Set of classes that contain Resources which are basically the rest services that are defined.

HelloWorldResource.java

This is basically the meat of the service.  It specifies two methods one for a GET request annotated by the @GET above it and one for a POST request, annotated by the @POST above it.  So in this class we specify what URL it will live at with the annotation above the class declaration

@Path(“/helloworld”)

JAX-RS methods need to return a “javax.ws.rs.core.Response” object.  We are creating and returning this object in both of these methods, JAX-RS has some nifty functionality for sending back different http codes and http headers.  For instance you can see in the getMessage method I am returning back a 200 http status code with a content-type http header of application/json

ResponseBuilder builder = Response.ok(jjo.toString(), MediaType.APPLICATION_JSON);

JAX-RS is the standard way of doing REST services in the Java EE world, so there are all kinds of plugins and documentation/blogs out there with tips and tricks of how to use it once you have it setup.  I would recommend the java doc and the tutorial from Oracle on how to get started for some beginner lessons.  I know sometimes writing a xAgent or even a plain old agent is quicker, but to ensure that your code is decoupled and will even work outside of an XPages context this is probably your best way of creating a rest service.  Even IBM realized this as this is how DAS services is built in Domino.

Advertisements

2 thoughts on “JAX-RS or THE way to do REST in Domino Part 3

  1. I wonder if it wouldn’t be easy to store the jax-rs library in the NSF and register the paths in a configuration file or anything. mostly having something other than NSF deployed on a hosted Domino server is a difficult request

  2. I haven’t looked into it very extensively, but I think it would be difficult to do this as getting the code loaded at the right time before the app starts may be a challenge.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s