backup file.

The previous commit was only applied on the whole backup file.

Instead of writing the new backup content in the final backup file directly,
write it first in a temporary file and then change the files name.

This fix prevents incomplete backup files (particularly in case of one backup
file per user) when stopping/restarting by force.

When a custom key was encountered, the library tried to fetch its value as a
String...but it is not always a String. Instead, now it is fetch as an Object
(possibly a JSONObject or JSONArray).

The UWS-1.x standard defines the quote as an ISO-8601 date. UWS-Lib stores it
as a number of seconds (i.e. estimated job duration).

This fix ensures that this integer/long quote value is returned as a date.

Note: The backup and restoration processes are not affected by this change.
      The backup file format is still the same: a quote stored as a long value.

It is possible to choose how the blocking mechanism should behave
(e.g. what the max. waiting period, how many requests can be blocked
in the same time, what happen when the blocking times out, ...).

Indeed, the policy to apply must actually be an extension of the interface
BlockingPolicy. Already two implementations are provided in the library
(LimitedBlockingPolicy and UserLimitedBlockingPolicy), but a custom policy
can perfectly be created and apply to a UWS service.

By default, no policy is set. In such case, the service will block the time
specified by the user, which may be -1 (i.e. wait indefinitely). A
BlockingPolicy can help controlling the waiting/blocking process and protect
the resources of the server.

- PHASE: list only jobs in the specified PHASE. If this parameter is repeated
         jobs matching any of the specified phases will be returned.
- AFTER: list jobs created after the specified ISO-8601 date (included).
         If this parameter is repeated, only the most recent date is retained.
- LAST: list the N-th most recently created jobs, ordered by descending
        creation time

These filter parameters are additive: their constraints are joint as with an
AND operator (except for PHASE parameters ; see above).

If no filter is specified, all jobs EXCEPT the ARCHIVED ones are listed. The
only way to list ARCHIVED jobs is to use PHASE=ARCHIVED (with or without other
filter parameters).

The filtering API has been made in a generic manner so that it is easily
possible to create and add new filters. See the interface JobFilter and the
class JobListRefined for more details.

and ALWAYS_ARCHIVE.

When archiving a job, its former phase is stored in jobInfo under the name
'oldPhase' if no jobInfo is already set.

Archiving a job means that all input files and results are destroyed ; the
error summary and jobInfo (even if it is a file) are kept.

Each archive operation ends with a log message ; in ERROR if failed or in
INFO if successful.

This commit also includes the following things:

    - reformat on 80 characters width the Javadoc of all modified classes

	- fix a bug with the phase transitions: since it is not possible any more
	  to go from PENDING to EXECUTING directly, UWSJob.start(...) must first
	  ensure to be on QUEUED phase. This bug has also been fixed in TAPJob.
	  Similarly, before going into ARCHIVED phase the job must be set into
	  ABORTED phase if not already in a final phase.

A JUnit test case has been added in order to check that all possible phase
transitions are respecting the UWS-1.1 standard. However, there is anyway
a bit more freedom for some of them:

    - it is possible to go to and come from UNKNOWN at any time, whatever is
	  the source or target phase.

	- it is possible to go to ERROR or ABORTED from the phases HELD and
	  SUSPENDED. This fact was not specified in the State Machine figure of the
	  UWS standard but the following sentence at section
	  "2.1.3 Execution Phase" (page 7) should allow that:
	  "At any time before the COMPLETED phase a job may either be ABORTED or
	   may suffer an ERROR."

	- the UWS-1.1 document has an inconsistency about the HELD phase. At
	  section "2.1.3 Execution Phase" (page 7), the following sentence implies
	  that it is only possible to go to HELD from PENDING (because it would not
	  be possible to queue the job). And so, when PHASE=RUN is sent by the UWS
      client, if now possible, the job should go in phase QUEUED. However the
	  State Machine figure suggests that it is possible to go to HELD only from
	  EXECUTING and that a PHASE=RUN would make the job go back to EXECUTING (if
	  now possible). Because of this inconsistency, the UWSLibrary made possible
	  the following transitions: PENDING/EXECUTING->HELD->QUEUED/EXECUTING.

(note: a figure illustrating the phase transitions supported by the
       UWSLibrary-4.3 has been created in the directory `img` of the
	   UWS-Tutorial website under the file name `state_machine.png`...which of
	   course will be visible only when uwslib-4.3 will be released)

Besides, this commit also include almost a full rewriting of the Javadoc of
JobPhase and ExecutionPhase. The Javadoc of UWSJob has just been reformated
so that comments do not exceed 80 (+2) characters. This reformating aims to
improve the human reading of the Javadoc while looking at the source files ;
however this should not affect much the HTML version of the Javadoc.

This property is displayed in the XML and JSON serialization of a job item.
It is also backuped and restored from a UWS backup file.

/!\ WARNING: Small modification of the API! Since creationTime must be
             set by the UWS service at creation of a job, this date must also
             be imported at backup restoration. Hence the modification of the
             interface uws.service.UWSFactory and its implementations
             (particularly tap.AbstractTAPFactory). Similarly the class
             uws.job.UWSJob and tap.job.TAPJob have underwent exactly the same
             modification in one of their constructors.

This commit also adds the new optional jobRef items: creationTime, runID and
ownerID in the XML and JSON serializations.

<job>.

This commit also:

    - set the version of the UWS protocol to 1.1 (cf UWS.VERSION)
	- add a static constant for the standardID (cf UWS.STANDARD_ID)
	- add a xlink:type and xlink:href for jobListRef in the uws XML
	- set the @version Javadoc attribute of all modified classes to 4.3
	  (scheduled version of the UWSLibrary supporting UWS-1.1)

serialization of all results if such information are available.

This commit also fix few comments about the result's XML serialization.

The processing of xlink:type of a result reference is made similar as the one of
jobRef.

This commit also includes the 2 following points:

    - for (really really tiny) optimisation purpose, replace String by a
	  char when there is only one character to append to a StringBuffer

	- add a bit more details about Result.type in the Javadoc (it should be
	  a xlink:type and not a random custom type)

Until now, it was possible to destroy the job by posting ACTION=DELETE
with a URL like below:

    {root-uws}/{job-list}/{job-id}/foo/bar

That is completely wrong. The correct URL for this action must always be:

    {root-uws}/{job-list}/{job-id}

This commit fixes this error in UWSServlet and UWSService.

The configuration of the DestructionTimeController was never effective
in the UWSServlet with a configuration file: the wrong instance was set.

synchronized although the collection of observers is synchronized (Vector) ;
using an Iterator ensures the synchronization and avoids concurrency problems.

  - uws.service.UWS.VERSION  (static final)
  - tap.resource.TAP.VERSION (static final)

Dealing with several protocol versions in the same time is quite difficult and
may significantly alter the libraries API in an unstable way. That's why, for
the TAP and UWS libraries, only one version is implemented (i.e. the last one).
To use a older version of the protocol, one must use an older version of the
corresponding library.

About the versioning of the ADQL standard, there is no need to set any version
number somewhere because a different ADQL version implies a different grammar.
It means that a different parser is required for each ADQL version. For the
moment, there is only one version, so no need to change anything to the ADQL
library about ADQL version. Later, ADQLParser should become an interface and
a factory will have to be used in order to get the parser corresponding to the
desired ADQL version.

This commit resolves partially the issue #28

Ideally, there should be an implementation of UWSLog and TAPLog working with
Log4j and another for SLF4J (and eventually for other logging mechanism).
Additionally, an implementation storing log messages in database would be
interesting. All these ideas may be implemented in UWSLib and TAPLib in a
future version.

_This commit aims to fix the issue #47_

and HashMap more generic by returning resp. a List and Map instead.

Additionally when an XML document is submitted in an HTTP POST request
(i.e. with the Content-Type = (text|application)/(.+-)?xml), this is
immediately set as a jobInfo in the created job.

This class is using static attributes of type DecimalFormat.
Unfortunately this type of objects can NOT be accessed by multiple
threads simultaneously: it is not thread-safe. Parsing errors,
mostly during TAP uploads, have been experienced for this reason.

To solve quickly this issue, the main static public functions of
ISO8601Format have been synchronized.

47d36bfb
In the UWS and TAP configuration files the executionDuration has to be
provided into milliseconds. But the UWS parameter MUST be in seconds.
So now, UWS is still keeping this duration in seconds (in its
ExecutionDurationController) but TAP keeps it in milliseconds (in order
to avoid unexpected silent modification of the API) and converts it into
seconds for its controller (i.e. TAPExecutionDurationController), for the
default home page and for the Capabilities page.

set.

request which has initiated the job creation. Actually the HTTP request is
generated as before, and then, if a job is created, it is set to the ID of the
HTTP request. This modification aims to greatly help the log analysis.

ID set by the TAP library was replaced by the one of the TAP library. The
consequence was a possible bad logging and since the ID is a timestamp, the
ID of the request was indicating a time posterior to a job creation.

UWS service.

dates with no seconds, but also with no day or month. Representations in
days of year or weeks of year were not possible as well. Check out the
ISO8601Format class' Javadoc for more details.

1) [TAP & UWS] ]MAJOR BUG FIX: The abortion of an SQL query is now correctly
implemented. Before this fix, 2 mistakes prevented this clean abortion:
  a/ The thread was not cancelled because the SQL query execution was
blocking the thread. Then the thread could not treat the interruption though
it was flagged as interrupted.
  b/ The function UWSJob.isStopped() considered the job as stopped because
the interrupted flag was set, even though the thread was still processing
(and the database too). Because of that it returned true and the job phase
was ABORTED though the thread was still running.
  NOW:
  a/ TAPJob calls the function Statement.cancel() (if supported) in order
to cancel the SQL query execution properly inside the database.
  b/ The function UWSJob.isStopped() does not test any more the interrupted flag
and returns true only if the thread is really stopped.
  IN BRIEF: It is now sure that a job in the phase ABORTED is really stopped
(that's to say: thread stopped AND DB query execution stopped).

2) [TAP] BUG FIX: When the writing of a result is abnormaly interrupted for any
reason, the file which was being written is deleted.

when the content-type was not exactly 'application/x-www-form-urlencoded'
for normal POST requests, no parameter was read by the UWS/TAP library.
This content-type test has now been modified from a strict equality to a
startsWith test.
(Note: This bug only concerned the form encoded requests,
not the multipart ones)

in the log output. For that the function UWSToolBox.getParamsMap(...)
had to be modified.

[UWS] Fix bug in UWSServlet: the destroyJob action in POST must be tested before the setJobParam action....otherwise the setJobParam action is always applied which leads to a Forbidden error when trying to destroy a job.

[UWS,TAP] Add the origin of the main exception after the exception class name in the log entries. This origin includes the class, the method, the file and the line where the exception has been thrown.

[UWS,TAP] Fix regression: the log message for the event REQUEST_RECEIVED was not displayed any more.