Interface ADQLGrammar
- All Known Implementing Classes:
ADQLGrammarBase
A concrete implementation of this interface lets parsing a full or partial ADQL query. It MUST follow ONLY ONE VERSION of an ADQL standard grammar.
Usage
Here is how to proceed in order to parse an ADQL expression:
- (Re-)Set the parser with the expression to parse,
- Call the appropriate parsing in function of what should be parsed
(e.g.
Query()
for a full ADQL query,Where()
for a WHERE clause), - The corresponding class representation is returned.
Example 1: Parse a full ADQL query
// 1. (Re-)Set the parser with the expression to parse: grammarParser.reset(new ByteArrayInputStream("SELECT foo FROM bar WHERE stuff = 1 ORDER BY 1 DESC LIMIT 10".getBytes())); // 2. Call the appropriate parsing: grammarParser.Query(); // 3. Get the result: System.out.println("RESULT: `" + grammarParser.getQuery().toADQL() + "`")
Example 2: Parse just a WHERE clause
// 1. (Re-)Set the parser with the expression to parse: grammarParser.reset(new ByteArrayInputStream("WHERE foo = 'bar' AND stuff = 1".getBytes())); // 2. Call the appropriate parsing: grammarParser.Where(); // 3. Get the result: System.out.println("RESULT: `" + grammarParser.getQuery().getWhere().toADQL() + "`")
ADQLGrammar
VS ADQLParser
Implementations of ADQLGrammar
should not be used directly. These
classes are generally generated by another tool from a grammar (e.g. JavaCC,
PEG) which makes them quite difficult to use without knowledges on the used
tool. Thus, this interface aims to simplify use of these grammar parsers.
ADQL-Lib users should use ADQLParser
instead of direct use of
ADQLGrammar
implementations. ADQLParser
wraps the
appropriate ADQLGrammar
implementation in function of the specified
ADQL Grammar version. It also includes additional tests (e.g. optional
language features, UDFs, types) as well as some useful tool functions
(e.g. tokenization, quick fix).
- Since:
- 2.0
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeInterfaceDescriptionstatic interface
API helping to iterate over a set ofToken
s. -
Method Summary
Modifier and TypeMethodDescriptionvoid
Disable the deep tracing of the Grammar Parser.void
Enable the deep tracing of the Grammar Parser.From()
Parse the ADQL expression as a singleFROM
clause.Generate aParseException
instance representing the givenException
.Get theADQLQueryFactory
used by this Grammar Parser to create ADQL object representations (e.g.getTokenizer
(String expr) Get an API giving access to the result of the tokenization of the given ADQL expression.Get the version of the ADQL Grammar implemented by this parser.GroupBy()
Parse the ADQL expression as a singleGROUP BY
clause.boolean
Tell whether the given token represents the end of an ADQL query.boolean
boolean
boolean
boolean
isRegularIdentifier
(String idCandidate) Tell whether the given string is a valid ADQL regular identifier.boolean
boolean
isSQLReservedWord
(Token token) OrderBy()
Parse the ADQL expression as a singleORDER BY
clause.Query()
Parse the ADQL expression as a single full ADQL query.void
reset
(InputStream inputADQLExpression) (Re-)Set the ADQL expression to parse.Select()
Parse the ADQL expression as a singleSELECT
clause.void
setQueryFactory
(ADQLQueryFactory factory) Set theADQLQueryFactory
to use in order to create ADQL object representations (e.g.Parse the ADQL expression as a single string constant.void
testRegularIdentifier
(Token token) Test the given token as an ADQL's regular identifier.Where()
Parse the ADQL expression as a singleWHERE
clause.
-
Method Details
-
getVersion
ADQLParser.ADQLVersion getVersion()Get the version of the ADQL Grammar implemented by this parser.- Returns:
- Implemented ADQL Grammar version. Never NULL
-
getQueryFactory
ADQLQueryFactory getQueryFactory()Get theADQLQueryFactory
used by this Grammar Parser to create ADQL object representations (e.g. SELECT, column, string, constraint) while building the ADQL query tree- Returns:
- The used
ADQLQueryFactory
. Never NULL
-
setQueryFactory
Set theADQLQueryFactory
to use in order to create ADQL object representations (e.g. SELECT, column, string, constraint) while building the ADQL query tree.- Parameters:
factory
- TheADQLQueryFactory
to use.- Throws:
NullPointerException
- If the given factory is NULL.
-
reset
(Re-)Set the ADQL expression to parse.Important note: This function MUST always be called BEFORE calling any parsing function.
- Parameters:
inputADQLExpression
- ADQL expression to parse.- Throws:
NullPointerException
- If the given stream is NULL.Exception
- If any error occurs while initializing the parser.
-
Query
Parse the ADQL expression as a single full ADQL query.Important note: This function MUST always be called AFTER
reset(InputStream)
with the ADQL expression to parse.- Returns:
- The corresponding ADQL tree.
- Throws:
ParseException
- If the parsing failed.
-
Select
Parse the ADQL expression as a singleSELECT
clause.Important note: This function MUST always be called AFTER
reset(InputStream)
with the ADQL expression to parse.- Throws:
ParseException
- If the parsing failed.
-
From
Parse the ADQL expression as a singleFROM
clause.Important note: This function MUST always be called AFTER
reset(InputStream)
with the ADQL expression to parse.- Throws:
ParseException
- If the parsing failed.
-
Where
Parse the ADQL expression as a singleWHERE
clause.Important note: This function MUST always be called AFTER
reset(InputStream)
with the ADQL expression to parse.- Throws:
ParseException
- If the parsing failed.
-
OrderBy
Parse the ADQL expression as a singleORDER BY
clause.Important note: This function MUST always be called AFTER
reset(InputStream)
with the ADQL expression to parse.- Throws:
ParseException
- If the parsing failed.
-
GroupBy
Parse the ADQL expression as a singleGROUP BY
clause.Important note: This function MUST always be called AFTER
reset(InputStream)
with the ADQL expression to parse.- Throws:
ParseException
- If the parsing failed.
-
StringExpression
Parse the ADQL expression as a single string constant.Important note: This function MUST always be called AFTER
reset(InputStream)
with the ADQL expression to parse.Implementation note: This function is available here just for Unitary Test purpose.
- Returns:
- The parsed
StringConstant
. - Throws:
ParseException
- If the parsing failed.
-
isEOF
-
isEOQ
-
isRegularIdentifierCandidate
-
isSQLReservedWord
-
isLeftPar
-
isEnd
Tell whether the given token represents the end of an ADQL query.Implementation note: NULL is considered as a last token of a set. So, by extension it should also be considered as the end of an ADQL query. But this method should rely on the ADQL grammar. Consequently, at least the token for the semi-colon (;) and the token for the End-Of-File (EOF) should be considered as the correct one to use to indicate the end of an ADQL query.
- Parameters:
token
- Token to analyze. Might be NULL.- Returns:
true
if the given token represents a query end,false
otherwise.
-
getTokenizer
Get an API giving access to the result of the tokenization of the given ADQL expression.- Parameters:
expr
- The ADQL expression to tokenize.- Returns:
- A
ADQLGrammar.Tokenizer
object helping to iterate over the tokens of the given ADQL expression. - Throws:
NullPointerException
- If the given ADQL expression is NULL.
-
isRegularIdentifier
Tell whether the given string is a valid ADQL regular identifier.According to the ADQL-2.0's BNF, a regular identifier (i.e. not delimited ; not between double quotes) must be a letter followed by a letter, digit or underscore. So, the following regular expression:
[a-zA-Z]+[a-zA-Z0-9_]*
This is what this function tests on the given string.
Warning: This function may return a different result for different versions of the ADQL grammar.
- Parameters:
idCandidate
- The string to test.- Returns:
true
if the given string is a valid regular identifier,false
otherwise.- See Also:
-
testRegularIdentifier
Test the given token as an ADQL's regular identifier.Implementation note: This function uses
isRegularIdentifier(String)
to test the given token's image. If the test fails, aParseException
is thrown.- Parameters:
token
- The token to test.- Throws:
ParseException
- If the given token is not a valid ADQL regular identifier.- See Also:
-
generateParseException
Generate aParseException
instance representing the givenException
.Implementation note: If the given
Exception
is already aParseException
this function should do nothing else than returning it as such.- Parameters:
ex
- The exception to represent as aParseException
.- Returns:
- The corresponding ParseException.
-
enable_tracing
void enable_tracing()Enable the deep tracing of the Grammar Parser. -
disable_tracing
void disable_tracing()Disable the deep tracing of the Grammar Parser.
-