Package adql.parser.grammar

Interface ADQLGrammar

All Known Implementing Classes:
ADQLGrammarBase
public interface ADQLGrammar
API of a specific ADQL grammar's parser.

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:

  1. (Re-)Set the parser with the expression to parse,
  2. Call the appropriate parsing in function of what should be parsed (e.g. Query() for a full ADQL query, Where() for a WHERE clause),
  3. 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:

  • 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 the ADQLQueryFactory 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

      void setQueryFactory(ADQLQueryFactory factory) throws NullPointerException
      Set the ADQLQueryFactory to use in order to create ADQL object representations (e.g. SELECT, column, string, constraint) while building the ADQL query tree.
      Parameters:
      factory - The ADQLQueryFactory to use.
      Throws:
      NullPointerException - If the given factory is NULL.

    • reset

      void reset(InputStream inputADQLExpression) throws Exception
      (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

      ADQLSet Query() throws ParseException
      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

      ClauseSelect Select() throws ParseException
      Parse the ADQL expression as a single SELECT 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

      FromContent From() throws ParseException
      Parse the ADQL expression as a single FROM 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

      ClauseConstraints Where() throws ParseException
      Parse the ADQL expression as a single WHERE 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

      ClauseADQL<ADQLOrder> OrderBy() throws ParseException
      Parse the ADQL expression as a single ORDER 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

      ClauseADQL<ADQLOperand> GroupBy() throws ParseException
      Parse the ADQL expression as a single GROUP 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

      ADQLOperand StringExpression() throws ParseException
      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

      boolean isEOF(Token token)

    • isEOQ

      boolean isEOQ(Token token)

    • isRegularIdentifierCandidate

      boolean isRegularIdentifierCandidate(Token token)

    • isSQLReservedWord

      boolean isSQLReservedWord(Token token)

    • isLeftPar

      boolean isLeftPar(Token token)

    • isEnd

      boolean isEnd(Token token)
      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

      ADQLGrammar.Tokenizer getTokenizer(String expr) throws NullPointerException
      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

      boolean isRegularIdentifier(String idCandidate)
      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

      void testRegularIdentifier(Token token) throws ParseException
      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, a ParseException is thrown.

      Parameters:
      token - The token to test.
      Throws:
      ParseException - If the given token is not a valid ADQL regular identifier.
      See Also:

    • generateParseException

      ParseException generateParseException(Exception ex)
      Generate a ParseException instance representing the given Exception.

      Implementation note: If the given Exception is already a ParseException this function should do nothing else than returning it as such.

      Parameters:
      ex - The exception to represent as a ParseException.
      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.