A. Getting started
1. Choosing the "type of UWS"
This UWS library provides five classes which are able to represent a UWS: AbstractUWS, BasicUWS, ExtendedUWS, QueuedBasicUWS and QueuedExtendedUWS. The first one is an abstract class whereas the four others are its sub-classes. Depending of your needs you are going to use one class rather than another one, hence this first step: Choosing the "type of UWS". So that helping you to make your choice, lets introduce these classes...
AbstractUWS
The main goal of a UWS is to manage a set of jobs lists in addition to all jobs resources. AbstractUWS already defines all methods required to easily manage its jobs lists. Particularly you can add new jobs list thanks to the method: addJobList(JL). Besides, it may also manage an execution queue. That implies that some jobs may be put in a QUEUED state until enough resources has been freed. Obviously all default behaviors of a UWS described by the IVOA Recommendation are already fully implemented.
The only abstract method of AbstractUWS is createJob(Map<String, String> params). It lets creating a new job with the given parameters each time a such request is sent to the UWS. This function is abstract because the type of job to create is not predictable in a generic way. For that, a concrete service is needed ! That means you would have to make an extension of AbstractUWS for each service.
However in spite of extending AbstractUWS at each time, you can use one of its default sub-classes: BasicUWS, ExtendedUWS, QueuedBasicUWS or QueuedExtendedUWS. Below a simplified class diagram of all theses classes:
BasicUWS and ExtendedUWS
BasicUWS and ExtendedUWS propose a simplified definition of a UWS. So you will never need to extend AbstractUWS ! Indeed both have been designed so that each jobs list can manage ONLY ONE GIVEN kind of job. Their only difference lies in the fact that in BasicUWS ALL managed jobs lists MUST be of ONLY one given type of job, whereas ExtendedUWS allows that each jobs list may be of a different type of job.
Let's take some examples:
- To make a UWS which manage ONE jobs lists of JobA, you may use BasicUWS:
BasicUWS<JobA> uws = new BasicUWS<JobA>(baseUWSUrl, JobA.class); uws.addJobList(new JobList(jlUrl_A));
- But to make a UWS which manages TWO (at least) jobs lists, the first of JobA and the second of JobB, you may use ExtendedUWS:
ExtendedUWS uws = new ExtendedUWS(baseUWSUrl); uws.addJobList(new JobList(jlUrl_A), JobA.class); uws.addJobList(new JobList(jlUrl_B), JobB.class);
IMPORTANT
These both classes use the Java Reflection in their method createJob to create the jobs of the good type. Hence: JobA.class and JobB.class. Thus they expect to find the constructor of AbstractJob with only one parameter (of type Map): see AbstractJob(Map<String, String>). So the used job types must have at least this constructor to be correctly managed with BasicUWS, ExtendedUWS and their sub-classes !
QueuedBasicUWS and QueuedExtendedUWS
QueuedBasicUWS and QueuedExtendedUWS extend respectively BasicUWS and ExtendedUWS. They just have one additional functionnality: they can manage an execution queue. A job is going to run only if there are less running jobs than a given number. Otherwise the job is put in a queue until a running job ends. The maximum number of running jobs may be initialized at the creation of the UWS and may be changed afterwards with setMaxRunningJobs(int).
IMPORTANT
As for BasicUWS and ExtendedUWS, the used job types must have at least the constructor of AbstractJob with only parameter of type Map<String,String> !
Which one choosing ?
As said previously to make a UWS you always need an instance of an AbstractUWS sub-class. You have two solutions: either you extend AbstractUWS or you use directly one of its sub-classes. To help you determining which solution is the best you can ask yourself the two following questions:
-
«May my UWS have to manage different kinds of job ?»
- YES: ExtendedUWS or QueuedExtendedUWS
- NO: BasicUWS or QueuedBasicUWS
- «Need I an execution queue ?»
- YES: QueuedBasicUWS or QueuedExtendedUWS
- NO: BasicUWS or ExtendedUWS
In our example, we will use only one kind of job and we do not require an execution queue (because a timer does not take much resources). So we will use BasicUWS !