Fixes #121

This aims to prevent extending UserDefinedFunction for UDFs whose translation
is very simple (e.g. different name in SQL, different argument order, etc).

Fixes #115

This commit reverts commit 89418d13.

The reverted commit will be applied in another branch (probably 'adql-2.1') as
it is part of the next release of ADQL-Lib.

- Now, `ADQLParserFactory.createParser(...)` should be used to create a parser
- Only the new function `LOWER` is supported for the moment
- Not yet possible to manage the optional features _(next dev to come)_
=> 1st step for ADQL-Lib v2.0

- TAP adapted so that using the last stable version of the ADQL language
  (i.e. 2.0 for the moment)
  - but not yet possible to set the ADQL version to use in the configuration
    file

`fix_on_fail` in the configuration file. By default, this feature is disabled.

_With 15cd5944, this commit finishes the resolution of the GitHub issue #104 ._

This new function - ADQLParser.tryQuickFix(...) - fixes the most common issues
with ADQL queries:

- replace Unicode confusable characters by their ASCII/UTF-8 version,
- double-quote SQL reserved words/terms (e.g. `public`, `year`, `date`),
- double-quote ADQL function names used a column name/alias (e.g. `distance`,
  `min`, `avg`),
- double-quote invalid regular identifiers (e.g. `_RAJ2000`, `2mass`).

The last point is far from being perfect but should work at least for
identifiers starting with a digit or an underscore, or an identifier including
one of the following character: `?`, `!`, `$`, `@`, `#`, `{`, `}`, `[`, `]`,
`~`, `^` and '`'.

It should also been noted that double-quoting a column/table name will make it
case-sensitive. Then, it is possible that the query does not pass even after the
double-quote operation ; the case would have to be checked by the user.

Finally, there is no attempt to fix column and table names (i.e. case
sensitivity and/or typos) using tables/columns list/metadata. That could be a
possible evolution of this function or an additional feature to implement in the
parser.

As @vforchi said:

> The ANSI standard `||` is supported only by Oracle and Postgres: MySQL uses
> `CONCAT` and SQLServer uses `+`.

_This commit resolves the issue #70 ._

UWSToolBox).

_ See GitHub Issue #100 _

The previous text formatting process was storing the entire table in memory....
hence OutOfMemoryError when dealing with large table.

Now, this process is done entirely in memory only for a table having less than
1000 lines. For a larger table, its content is stored in a temporary file. This
file is deleted after usage or in case of error.

This formatting process has been tested under JVM monitoring (both JConsole and
VisualVM) and tables larger than 3,000,000 rows, with success.

This commit fixes the GitHub issue #40

The property `upload_default_db_limit` has been deprecated. Indeed, in the
current state of the TAP protocol, this makes no sense: the user can not change
the limit size (in bytes or rows) for uploaded tables.

The property `upload_max_file_size` has been deprecated. It is actually
duplicated: `upload_max_db_limit`, if expressed in bytes already lets put a
limit on the maximum size of an uploaded table/file.

The property `upload_max_request_size` has been added. It lets set a maximum
size for a whole HTTP Multipart Request. By default it is set to 250MB.

The default value of `upload_max_db_size` is now 1 million rows.

The UPLOAD feature is still disabled by default (i.e. `upload_enabled=false`).

When enabled, it was generating a file each minute on the day before the
specified day of week.

For instance: if the log rotation frequency was `W 1 0 0` (so, weekly on Sunday
at 00:00). The rotation was performed on Saturday midnight. But, because of a
bad index correction, the rotation kept going on the whole day of Saturday.
Since the rotated file is suffixed by the timestamp with hours and minutes
(no seconds), it actually generated a new log file for each minute of the
saturday. Of course, each time the file contained only one line (or 2 with some
luck)...which is pretty useless.

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.

Follow up to the commits 33a790a4
and 5e0f82de

In TestPgSphereTranslator, two strings are compared
containing (double) floating point numbers. These numbers are slightly
different with different Java versions. To overcome this, only the
first eight fractional digits are compared.

The end of the description of a UDF was not detected when this UDF was followed
by another UDF definition. This was due to an incorrect double quote escape in
the regular expression of a UDF's definition.

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.

Although the Java code allowed the specification of a description of a User
Defined Function, it was not possible to set one in the UDFs listed in the
configuration file.

* The parsing did not allow unsigned numerics and SQL SET functions as
  specified in the ADQL 2.0 grammar

* It was even forbidden to put a column whose the type is not String.

* The translation of a concatenation expression was always prefixed by the
  ADQLList's name: CONCAT_STR. Of course, no database likes that...

Regarding this last point, this commit fixes the GitHub issue #54

if the alias is not delimited in ADQL.

This commit fixes the GitHub issue #56

this table is declared with an alias. Instead, the table alias must be used.

Note: This problem occurred only when ADQLParser was used with a DBChecker.

This commit fixes the GitHub issue #53

A delimited identifier is any sequence of characters between a pair of
double quotes. For instance: "123 I am a delimited identifier!".

It is of course possible to have double quotes inside this kind of identifier,
but they have to be doubled in order to not be mistaken with the end of the
identifier. For instance: "Cool ""identifier""".

However, this escape option was not taken into account by the ADQL library,
though the same mechanism was already in place for string contants.

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.

reserved word is encountered instead of a column/table/schema name/alias.

On the contrary to the previous commit, this time a list of SQL reserved words
has been added into the ADQL grammar. In this way, the parser will ensure that
no word of this list is used in an ADQL query. The raised error is then enriched
of an HINT message stating that this word is part of SQL, is not supported
by ADQL and must be written between double quotes if used as an identifier.

The list of SQL reserved words comes from the ADQL-2.0 standard, after removal
of all potentially used ADQL words, in order to avoid a conflict with the
already existing tokens in the ADQL grammar.

reserved word is encountered instead of a column/table/schema name/alias.

No list of ADQL reserved words has been added into the ADQL grammar.

However, the ADQL grammar has been slightly changed in order to provide a more
precise location of the REAL wrong part of the query.

Before this commit, if an ADQL reserved word (e.g. 'point') was encountered
outside of its normal syntax (e.g. 'point' no followed by an opening
parenthesis), the next token was highlighted instead of this one. Hence a
confusing error message.

For instance, the following ADQL query:

```sql
SELECT point
FROM aTable
```

returned the following error message:

> Encountered "FROM". Was expecting: "("

Now, it will return the following one:

> Encountered "point". Was expecting one of: "*" <QUANTIFIER> "TOP" [...]
> (HINT: "point" is a reserved ADQL word. To use it as a column/table/schema name/alias, write it between double quotes.)

This error message highlights exactly the source of the problem and even provide
to the user a clear explanation of why the query did not parse and how it could
be solved.

with a different local charset, the error message will print differently the
incorrect character.

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

In the resulting SQL query, if there are an alias on the joined tables, these
aliases must be used in the ON clause (instead of the full table name).

For instance, the following ADQL query:

```sql
  SELECT *
  FROM tableA AS a NATURAL JOIN tableB AS b;
```

should be translated into the following SQL:

```sql
  SELECT *
  FROM tableA AS a
    INNER JOIN tableB AS b
      ON a.id = b.id
```

This commit complete the resolution of the Pull Request #16
(more details about the issue can be got in there)

when an incorrect character that can not be interpreted by
the JavaCC Token Manager is encountered.

Actually, the TokenMgrError thrown by JavaCC is caught by all
ADQLParser.parseQuery(...) functions, wrapped inside a ParseException
which is finally thrown instead of the TokenMgrError. In this way,
ADQL-Lib users just have to care about a single Throwable:
ParseException.

Besides the error message has been slightly modified from:

> Lexical error at line 1, column 10.  Encountered: "\u00e9" (233), after : \"\"

to:

> Incorrect character encountered at l.1, c.10: \"\\u00e9\" ('é'), after : \"\"

Thus, the error is more user-friendly, more easy to understand by users.
Additionally, the incorrect character is displayed, as before, in its unicode
expression, but also in its character form (instead of an integer value that
nobody can really understand).

This commit fixes the GitHub issue #17

The JUnit test should have been updated as well.

This infinite loop occured only when the replacement object is just
a wrapping of the matching object ; after replacement, the new object was
inspected for matching objects.

Example: infinite loop if we want to wrap all foo(...) functions with
         the function ROUND in the following query:
    SELECT foo(foo(123)) FROM myTable
	     Expected result:
    SELECT ROUND(foo(ROUND(foo(123)))) FROM myTable
	     But generated result was:
    SELECT ROUND(ROUND(ROUND(......foo(foo(123))))) FROM myTable

See the test case TestDBChecker.testClauseADQLWithNameNull() for more details.

since the commit 8e2fa9ff.