Documentation

Documentation in progress!

The documentation of the version 4.x of the UWS Library will come little by little in the next months.

You can however see the provided examples in order to understand how to build easily a UWS service. 2 methods are proposed in these examples and will be explained in more details later in this online documentation.

A. UWS service

Part 1
  1. Interface UWS Description of this interface, core of the UWS Library.
  2. Job list A UWS service does exist only if it contains at least one job list. This section describes the corresponding class: JobList.
  3. Provided extensions 2 classes (1 abstract and 1 concrete) are provided by the library in order to help building quickly a UWS service. Each implements the interface UWS in a different way in order to offer the most suited solution to library users.
Part 2
  1. File management Since v4.0 all files the UWS library has to deal with are managed in only one class which must implement the interface UWSFileManager.
  2. Backup management As for files, the version 4.0 of the library provides a easy way to backup and restore UWS jobs: UWSBackupManager.
  3. User identification The interfaces UserIdentifier and JobOwner offers the possibility to identify users from an HTTP request and to deal with user permissions easily in the implemented UWS service.

B. UWS factory

  1. Create a job The factory must create a job object each time a new job is asked by a service user. This part describes the class UWSJob and explains how to create instances through the factory.
  2. Fetch parameters When an HTTP request is received by a UWS service, the used HTTP method and the parameters must be extracted in order to identify the UWS action to execute but also to set attributes and parameters in a job. This part explains how parameters are extracted from the request and how to customize this process.
  3. Create a job thread This section explains probably the most important part in the creation of a UWS service: how to specify what jobs must do. This is obviously performed by extending the abstract class: JobThread.
  4. Abstract factory Since job creation and parameters extraction can be easily managed in a generic way, the library provides an abstract class implementing the UWS factory.

C. Job execution & destruction

  1. How does it work? The life cycle of a UWS job is well explained by the IVOA. However, its implementation is a bit more complicated. The main steps are then briefly explained in this section, in preambule of the following section.
  2. Interface ExecutionManager The execution of a job is managed by only one class which must implement the interface ExecutionManager. Let's see it in details and what are the existing implementations!
  3. How to stop a job? Executing a job is easy, but stopping/aborting it is sometimes complicated. Here few internal mechanisms to deal with the ending of a job are explained.
  4. How to set result(s)? At the end of a job execution, one or more result(s) may be reported. Let's see how!
  5. How to report an error? The unfortunate alternate to a result for the end of a job execution is an error. This section explains how to deal with them in JobThread and how to report an error.
  6. Job destruction A UWS job too has a death ^^ This part explains when a job is destroyed and what information/files are also dropped.

D. Errors management

  1. UWS logger Since v4.0, the UWS library integrates a logging mechanism. It is described in this part.
  2. Error writer In addition of job execution error and logging, the UWS service may return an HTTP response with an error in order to inform the user. The format of these responses may be customized.

E. Miscellaneous

  1. Job serialization When a UWS job list, job or one of its attributes is asked using an HTTP-GET request, the UWS service must return an XML document describing the asked resource. Here is explained how this is implemented in the UWS library and how it can be customized in order to return resources in different formats (n.b. JSON format is already supported).
  2. How to watch a job? Unused by default in the library, the ability to watch a UWS job may be sometimes useful. The interface JobObserver offers it. This interface and its usage are explained in this section.
  3. URL interpretation In a REST web-application, resources are reached/modified/deleted in function of the used HTTP method must especially of the URL. The library uses a particular class to interpret or even build UWS URLs.
  4. UWS-1.1 introduction This page describes how to use the new features introduced by UWS-1.1 while using the UWSLibrary.