A. Getting started

2. Writing the servlet

A UWService is a Web-Service. Since this library is developed in Java, a UWService will be implemented by a HttpServlet. This part of the tutorial explains how to write a Servlet using this library to create and to manage a UWService.

To execute a servlet, Tomcat must be installed on your server. This UWS library has been tested with the versions 6 and 7 of Apache/Tomcat.

The HttpServlet class

It lets defining a dynamic web-resource for the protocol HTTP. Since this class is abstract, you must override it. There is already one constructor with no parameter. In the most cases it is not needed to override it or even to add more constructor.

It has several methods but only three of them will interest us:

Warning

The same HttpServlet is used for all clients. It means that all class attributes will have the same value for all clients. So beware of the way you use them !

UWSTimers

UWSTimers is the name of the servlet we want to create in this tutorial. It will have only one attribute whose the type has been choosen in the previous part: BasicUWS<JobChrono> uws. Now all we have to do is to initialize this variable and to forward it all requests the servlet receives.

JobChrono is the type of the job our UWS must manage. It will be defined in the next part of this tutorial.

Initializing the UWS

The initialization of a UWS must be done at the first request sent to the servlet. So our UWS will be initialized in the init(ServletConfig) method of the servlet UWSTimers: 

@Override
public void init(ServletConfig config) throws ServletException {
	super.init(config);
	try{
		// Create the UWS [required]:
		uws = new BasicUWS<JobChrono>(JobChrono.class);
		
		// Set a description [optional]:
		uws.setDescription("This UWS aims to manage one (or more) JobList(s) of JobChrono." +
							"JobChrono is a kind of Job whose the execution task consists to wait a given time" +
							"before executing an action.");
		
		// Create the job list "timers" [required]:
		uws.addJobList(new JobList<JobChrono>("timers"));
	}catch(UWSException ex){
		throw new ServletException(ex);
	}
}

Forwarding requests to the UWS

Forwarding request to the UWS is actually easier than meets the eye ! AbstractUWS has been designed to be able to interpret HTTP servlet requests and to answer them in consequence. So to do that, you have only to call the method AbstractUWS.executeRequest(HttpServletRequest, HttpServletResponse). This method can interpret any kind of request, whatever is the HTTP method (GET, POST, PUT or DELETE). If a request is invalid - according to the IVOA Recommendation - this method throws an exception which specifies the HTTP error code in addition to a message.

Here is the service(HttpServletRequest, HttpServletResponse) method of UWSTimers in which requests are forwarding to our UWS: 

@Override
protected void service(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
	try{
		// Forward the request to the uws [required]:
		uws.executeRequest(req, resp);
	}catch(UWSException uwsEx){
		// Display properly the caught UWSException:
		resp.sendError(uwsEx.getHttpErrorCode(), uwsEx.getMessage());
	}
}

Customize your UWS

By using this UWS library, the minimal code of a servlet implementing a UWService is only limited to the above code (except for the uws description which can be omitted). But so that making more controls while using the UWS, the full source code of UWSTimers is a little longer than the explained one. For instance the execution duration and the destruction time have a maximum and a default value. Besides each user of this UWS is identified so that they can manage only their own jobs.

All customizations of your UWS should be done at its initialization, in the init(ServletConfig) method. Besides the part D. How to customize a UWS ? lists and explains the most usefull UWS customizations. However to help you writing quickly your servlet you can download the following template. It contains the above minimal code and some UWS customizations.