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.

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)

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.

  - 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.

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.

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.

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)

[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.

[UWS,TAP] Errors and log management improvements. Particularly, now TAP and UWS are able to manage correctly HTTP request abortions (i.e. when the user stop the request before the response has been fully sent, or when there is a connection problem or a time-out). Such abortions are considered by UWS and TAP merely as job abortion/cancel. No error is logged any more. In addition of this correction, log entries concerning the execution of a TAP sync/async job have been modified so that having more coherents messages. And stack traces of exception that occurred when executing a job (sync or async, tap or uws) are displayed just once: at the JOB END log entry, and not by the HTTP RESPONSE_SENT entry. And finally, output flush and interruption detection are made more often when writing a query result (the flush is particularly important when combining with fetch-size > 0 in synchronous mode....the sync response is then a streaming output).

[UWS,TAP] Change the default log and backup files name. Before it was 'uws.*', but since the same FileManager is used for both services, this default name has been replaced by 'service.*'.

[UWS] Add a log message filter: only messages whose the level is greater or equal to a given one are displayed. This level is by default DEBUG (meaning all messages are always written).

[UWS,TAP] Set the user who submits the request in an HttpServletRequest attribute. Thus, every TAP and UWS resources can get it without extracting the information every time from the HttpServletRequest.

[UWS,TAP] Fix UPLOAD bug (the last line of the table to upload was ignored). Fix an improbable NullPointerException in the MultipartParser.

[UWS,TAP] Add clean release of all resources (e.g. Threads, Timers, DB connections) allocated in a UWS and a TAP service. Small changes of the UWS API...but only if ExecutionManager, DestructionManager and UWS have been implemented by library users rather than using the default implementation.

[UWS,TAP] Review some log messages (in the log file but also in the error summary of a job) ; particularly stack traces are added into the error summary, but are displayed just once in the logs.

[TAP,UWS] Addition to the last commit: the TAP resource /sync did not yet use the RequestParser to get its parameters, and so it did not worked as before the last commit.

[UWS,TAP] 3 MAJOR DEPENDENT FIX: improve significantly the parameters extraction from HTTP request in UWS (1) AND move the file-upload ability into the UWS library (2) AND the modification of parameters in UWS is now conform with the standard (3). (1) Only application/x-form-urlencoded content-type was supported. However a UWS must accept a request body containing only an XML document as a single byReference parameter. It is now done when the content-type is not known. (2) Besides multipart/form-data is now fully supported in UWS and so is still possible in TAP. (3) In the UWS standard, parameters can not be added after creation: they can just be modified. This rule is now respected in the UWS library.

[UWS,TAP] Review the standard parameters checking. Particularly, because before, the default value was never used while no value was specified by the user.

[ADQL,TAP] Add STC-S and UDFs support in the ADQL parser. Now, it is possible to provide a list of allowed UDFs, regions and coordinate systems. The ServiceConnection of TAP is now able to provide these lists and to propagate them to the ADQLExecutor. UDFs and allowed regions are now listed automatically in the /capabilities resource of TAP. The type 'geometry' is now fully supported in ADQL. That's why the new function 'isGeometry()' has been added to all ADQLOperand extensions. Now the DBChecker is also able to check roughly types of columns and UDFs (unknown when parsing syntactically a query). The syntax of STC-S regions (expressed in the REGION function) are now checked by DBChecker. However, for the moment, geometries are not serialized in STC-S in the output....but it should be possible in some way in the next commit(s).