Package adql.parser.feature

Class LanguageFeature

java.lang.Object
adql.parser.feature.LanguageFeature
public final class LanguageFeature extends Object
Description of an ADQL's language feature.

All ADQLObjects MUST provide an instance of this class, even if not optional.

A LanguageFeature is indeed particularly useful to identify optional ADQL features (e.g. LOWER, WITH). This is the role of the ADQLParser to generate an error if an optional feature is used in a query while declared as unsupported.

Note: Most of ADQL objects are not associated with any IVOA standard (e.g. TAPRegExt) apart from ADQL. In such case, the attribute type is set to NULL.

IMPORTANT note about UDF: To create a UDF feature (i.e. a LanguageFeature with the type TYPE_UDF), ONLY ONE constructor can be used: LanguageFeature(FunctionDef, String). Any attempt with another public constructor will fail.

Since:
2.0
See Also:

  • Field Details

    • id

      public final String id
      Unique identifier of this language feature.

      MANDATORY

      This identifier should follow this syntax:

              TYPE'!'FORM

      Examples:

      • !SELECT (no type specified for this in the ADQL standard, so TYPE='')
      • ivo://ivoa.net/std/TAPRegExt#features-adql-string!LOWER
      • ivo://ivoa.net/std/TAPRegExt#features-udf!MINE(VARCHAR) -> DOUBLE

    • type

      public final String type
      Type of this language feature.

      OPTIONAL

      All types mentioned in the ADQL standard are listed as public static final attributes of this class ; they all start with TYPE_ (ex: TYPE_ADQL_STRING).

      If no type is specified for this language feature in the ADQL standard, set this field to null.

      Examples:

      • null for SELECT (no type specified for this in the ADQL standard)
      • ivo://ivoa.net/std/TAPRegExt#features-adql-string for LOWER
      • ivo://ivoa.net/std/TAPRegExt#features-udf for the UDF MINE(VARCHAR) -> DOUBLE

    • form

      public final String form
      Name (or function signature).

      MANDATORY

      Examples:

      • SELECT
      • LOWER
      • MINE(VARCHAR) -> DOUBLE

    • udfDefinition

      public final FunctionDef udfDefinition
      Definition of the UDF represented by this LanguageFeature.

      OPTIONAL

    • optional

      public final boolean optional
      Is this feature optional in the ADQL grammar?

      MANDATORY

      An optional language feature can be used in an ADQL query only if it is declared as supported by the ADQL client (i.e. TAP service). To do, one should use FeatureSet to declare how supported is an optional feature.

      Examples:

      • false for SELECT
      • true for LOWER
      • true for MINE(VARCHAR) -> DOUBLE

    • description

      public String description
      Description of this feature.

      OPTIONAL

    • IVOID_TAP_REGEXT

      public static final String IVOID_TAP_REGEXT
      Root IVOID for all the TAPRegExt's language features.
      See Also:

    • TYPE_UDF

      public static final String TYPE_UDF
      User Defined Functions.
      See Also:

    • TYPE_ADQL_GEO

      public static final String TYPE_ADQL_GEO
      Geometric functions/regions.
      See Also:

    • TYPE_ADQL_STRING

      public static final String TYPE_ADQL_STRING
      String manipulation functions
      See Also:

    • TYPE_ADQL_SETS

      public static final String TYPE_ADQL_SETS
      Row-set manipulation functions.
      See Also:

    • TYPE_ADQL_COMMON_TABLE

      public static final String TYPE_ADQL_COMMON_TABLE
      Sub-query "alias" (i.e. WITH).
      See Also:

    • TYPE_ADQL_TYPE

      public static final String TYPE_ADQL_TYPE
      Datatype manipulation functions (e.g. CAST).
      See Also:

    • TYPE_ADQL_CONDITIONAL

      public static final String TYPE_ADQL_CONDITIONAL
      Conditional functions (e.g. COALESCE).
      See Also:

    • TYPE_ADQL_UNIT

      public static final String TYPE_ADQL_UNIT
      Unit manipulation functions (e.g. IN_UNIT).
      See Also:

    • TYPE_ADQL_BITWISE

      public static final String TYPE_ADQL_BITWISE
      Bit manipulation functions.
      See Also:

    • TYPE_ADQL_OFFSET

      public static final String TYPE_ADQL_OFFSET
      Query result offset.
      See Also:

  • Constructor Details

    • LanguageFeature

      public LanguageFeature(String type, String form) throws NullPointerException
      Create a de-facto supported (i.e. non-optional) language feature.

      IMPORTANT note: To create a UDF feature, DO NOT use this constructor. You MUST use instead LanguageFeature(FunctionDef, String).

      Parameters:
      type - [OPTIONAL] Category of the language feature. (see all static attributes starting with TYPE_)
      form - [REQUIRED] Name (or function signature) of the language feature.
      Throws:
      NullPointerException - If the given form is missing.

    • LanguageFeature

      public LanguageFeature(String type, String form, boolean optional) throws NullPointerException
      Create a language feature.

      IMPORTANT note: To create a UDF feature, DO NOT use this constructor. You MUST use instead LanguageFeature(FunctionDef, String).

      Parameters:
      type - [OPTIONAL] Category of the language feature. (see all static attributes starting with TYPE_)
      form - [REQUIRED] Name (or function signature) of the language feature.
      optional - [REQUIRED] true if the feature is by default supported in the ADQL standard, false if the ADQL client must declare it as supported in order to use it.
      Throws:
      NullPointerException - If the given form is missing.

    • LanguageFeature

      public LanguageFeature(String type, String form, boolean optional, String description) throws NullPointerException
      Create a language feature.

      IMPORTANT note: To create a UDF feature, DO NOT use this constructor. You MUST use instead LanguageFeature(FunctionDef, String).

      Parameters:
      type - [OPTIONAL] Category of the language feature. (see all static attributes starting with TYPE_)
      form - [REQUIRED] Name (or function signature) of the language feature.
      optional - [REQUIRED] true if the feature is by default supported in the ADQL standard, false if the ADQL client must declare it as supported in order to use it.
      description - [OPTIONAL] Description of this feature.
      Throws:
      NullPointerException - If given form is missing.

    • LanguageFeature

      public LanguageFeature(FunctionDef udfDef) throws NullPointerException
      Create a UDF feature.
      Parameters:
      udfDef - [REQUIRED] Detailed definition of the UDF feature.
      Throws:
      NullPointerException - If given FunctionDef is missing.

    • LanguageFeature

      public LanguageFeature(FunctionDef udfDef, String description) throws NullPointerException
      Create a UDF feature.
      Parameters:
      udfDef - [REQUIRED] Detailed definition of the UDF feature.
      description - [OPTIONAL] Description overwriting the description provided in the given FunctionDef. If NULL, the description of the FunctionDef will be used. If empty string, no description will be set.
      Throws:
      NullPointerException - If given FunctionDef is missing.

  • Method Details