Package adql.db

## Class FunctionDef

- java.lang.Object
- - adql.db.FunctionDef

- All Implemented Interfaces:
    `java.lang.Comparable<FunctionDef>`

      public class FunctionDef
      extends java.lang.Object
      implements java.lang.Comparable<FunctionDef>

  Definition of any function that could be used in ADQL queries.

  A such definition can be built manually thanks to the different constructors of this class, or by parsing a string function definition form using the static function `parse(String)`.

  The syntax of the expression expected by `parse(String)` is the same as the one used to build the string returned by `toString()`. Here is this syntax:

      {fctName}([{param1Name} {param1Type}, ...])[ -> {returnType}]

  A description of this function may be set thanks to the public class attribute `description`.

  Since:
    1.3
  Version:
    1.4 (08/2015)
  Author:
    Grégory Mantelet (ARI)

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `FunctionDef.FunctionParam` | Definition of a function parameter.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `java.lang.String` | `description` | Description of this function.
    `protected static java.lang.String` | `fctDefRegExp` | Rough regular expression for a whole function definition.
    `protected static java.lang.String` | `fctParamRegExp` | Rough regular expression for a function parameter: a name (see `regularIdentifierRegExp`) and a type (see `typeRegExp`).
    `protected static java.lang.String` | `fctParamsRegExp` | Rough regular expression for a function parameters' list.
    `protected static java.util.regex.Pattern` | `fctPattern` | Pattern of a function definition.
    `protected boolean` | `isGeometry` | Indicate whether the return type is a geometry.
    `protected boolean` | `isNumeric` | Indicate whether the return type is a numeric.
    `protected boolean` | `isString` | Indicate whether the return type is a string.
    `protected boolean` | `isUnknown` | Indicate whether the return type is an unknown type.
    `java.lang.String` | `name` | Name of the function.
    `int` | `nbParams` | Total number of parameters.
    `protected static java.util.regex.Pattern` | `paramPattern` | Pattern of a single parameter definition.
    `protected FunctionDef.FunctionParam[]` | `params` | List of all the parameters of this function.
    `protected static java.lang.String` | `regularIdentifierRegExp` | Regular expression for what should be a function or parameter name - a regular identifier.
    `DBType` | `returnType` | Type of the result returned by this function.
    `protected static java.lang.String` | `typeRegExp` | Rough regular expression for a function return type or a parameter type.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `FunctionDef​(java.lang.String fctName)` | Create a function definition.
    `FunctionDef​(java.lang.String fctName, DBType returnType)` | Create a function definition.
    `FunctionDef​(java.lang.String fctName, DBType returnType, FunctionDef.FunctionParam[] params)` |
    `FunctionDef​(java.lang.String fctName, FunctionDef.FunctionParam[] params)` | Create a function definition.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `int` | `compareTo​(FunctionDef def)` |
    `int` | `compareTo​(ADQLFunction fct)` | Compare this function definition with the given ADQL function item.
    `int` | `getNbParams()` | Get the number of parameters required by this function.
    `FunctionDef.FunctionParam` | `getParam​(int indParam)` | Get the definition of the indParam-th parameter of this function.
    `java.lang.Class<? extends UserDefinedFunction>` | `getUDFClass()` | Get the class of the `UserDefinedFunction` able to represent the function defined here in an ADQL tree.
    `boolean` | `isGeometry()` | Tell whether this function returns a geometry.
    `boolean` | `isNumeric()` | Tell whether this function returns a numeric.
    `boolean` | `isString()` | Tell whether this function returns a string.
    `boolean` | `isUnknown()` | Tell whether this function returns an unknown type.
    `static FunctionDef` | `parse​(java.lang.String strDefinition)` | Let parsing the serialized form of a function definition.
    `<T extends UserDefinedFunction> void` | `setUDFClass​(java.lang.Class<T> udfClass)` | Set the class of the `UserDefinedFunction` able to represent the function defined here in an ADQL tree.
    `java.lang.String` | `toString()` |

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### regularIdentifierRegExp

          protected static final java.lang.String regularIdentifierRegExp

      Regular expression for what should be a function or parameter name - a regular identifier.
      See Also:
        Constant Field Values

    - #### typeRegExp

          protected static final java.lang.String typeRegExp

      Rough regular expression for a function return type or a parameter type. The exact type is not checked here ; just the type name syntax is tested, not its value. This regular expression allows a type to have exactly one parameter (which is generally the length of a character or binary string.
      See Also:
        Constant Field Values

    - #### fctParamsRegExp

          protected static final java.lang.String fctParamsRegExp

      Rough regular expression for a function parameters' list.
      See Also:
        Constant Field Values

    - #### fctParamRegExp

          protected static final java.lang.String fctParamRegExp

      Rough regular expression for a function parameter: a name (see `regularIdentifierRegExp`) and a type (see `typeRegExp`).
      See Also:
        Constant Field Values

    - #### fctDefRegExp

          protected static final java.lang.String fctDefRegExp

      Rough regular expression for a whole function definition.
      See Also:
        Constant Field Values

    - #### fctPattern

          protected static final java.util.regex.Pattern fctPattern

      Pattern of a function definition. This object has been compiled with `fctDefRegExp`.

    - #### paramPattern

          protected static final java.util.regex.Pattern paramPattern

      Pattern of a single parameter definition. This object has been compiled with `fctParamRegExp`.

    - #### name

          public final java.lang.String name

      Name of the function.

    - #### description

          public java.lang.String description

      Description of this function.

    - #### returnType

          public final DBType returnType

      Type of the result returned by this function.

    - #### isString

          protected final boolean isString

      Indicate whether the return type is a string.

    - #### isNumeric

          protected final boolean isNumeric

      Indicate whether the return type is a numeric.

    - #### isGeometry

          protected final boolean isGeometry

      Indicate whether the return type is a geometry.

    - #### isUnknown

          protected final boolean isUnknown

      Indicate whether the return type is an unknown type.

      Note: If `true`, `isString`, `isNumeric` and `isGeometry` are `false`. Otherwise, at least one of these attributes is set to `true`.

      Since:
        1.4

    - #### nbParams

          public final int nbParams

      Total number of parameters.

    - #### params

          protected final FunctionDef.FunctionParam[] params

      List of all the parameters of this function.

  - ### Constructor Detail

    - #### FunctionDef

          public FunctionDef​(java.lang.String fctName)

      Create a function definition.

      The created function will have no return type and no parameter.

      Parameters:
        `fctName` - Name of the function.

    - #### FunctionDef

          public FunctionDef​(java.lang.String fctName,
                             DBType returnType)

      Create a function definition.

      The created function will have a return type (if the provided one is not null) and no parameter.

      Parameters:
        `fctName` - Name of the function.
        `returnType` - Return type of the function. If NULL, this function will have no return type

    - #### FunctionDef

          public FunctionDef​(java.lang.String fctName,
                             FunctionDef.FunctionParam[] params)

      Create a function definition.

      The created function will have no return type and some parameters (except if the given array is NULL or empty).

      Parameters:
        `fctName` - Name of the function.
        `params` - Parameters of this function. If NULL or empty, this function will have no parameter.

    - #### FunctionDef

          public FunctionDef​(java.lang.String fctName,
                             DBType returnType,
                             FunctionDef.FunctionParam[] params)

  - ### Method Detail

    - #### isNumeric

          public final boolean isNumeric()

      Tell whether this function returns a numeric.
      Returns:
        true if this function returns a numeric, false otherwise.

    - #### isString

          public final boolean isString()

      Tell whether this function returns a string.
      Returns:
        true if this function returns a string, false otherwise.

    - #### isGeometry

          public final boolean isGeometry()

      Tell whether this function returns a geometry.
      Returns:
        true if this function returns a geometry, false otherwise.

    - #### isUnknown

          public final boolean isUnknown()

      Tell whether this function returns an unknown type.

      If this function returns `true`, `isNumeric()`, `isString()` and `isGeometry()` MUST ALL return `false`. Otherwise, one of these 3 last functions MUST return `true`.

      Returns:
        true if this function returns an unknown/unresolved/unsupported type, false otherwise.

    - #### getNbParams

          public final int getNbParams()

      Get the number of parameters required by this function.
      Returns:
        Number of required parameters.

    - #### getParam

          public final FunctionDef.FunctionParam getParam​(int indParam)
                                                   throws java.lang.ArrayIndexOutOfBoundsException

      Get the definition of the indParam-th parameter of this function.
      Parameters:
        `indParam` - Index of the parameter whose the definition must be returned.
      Returns:
        Definition of the specified parameter.
      Throws:
        `java.lang.ArrayIndexOutOfBoundsException` - If the given index is negative or bigger than the number of parameters.

    - #### getUDFClass

          public final java.lang.Class<? extends UserDefinedFunction> getUDFClass()

      Get the class of the `UserDefinedFunction` able to represent the function defined here in an ADQL tree.

      Note: This getter should return always NULL if the function defined here is not a user defined function.
      However, if this `FunctionDef` is defining a user defined function and this function returns NULL, the library will create on the fly a `DefaultUDF` corresponding to this definition when needed. Indeed this UDF class is useful only if the translation from ADQL (to SQL for instance) of the defined function has a different signature (e.g. a different name) in the target language (e.g. SQL).

      Returns:
        The corresponding `UserDefinedFunction`. MAY BE NULL

    - #### setUDFClass

          public final <T extends UserDefinedFunction> void setUDFClass​(java.lang.Class<T> udfClass)
                                                                 throws java.lang.IllegalArgumentException

      Set the class of the `UserDefinedFunction` able to represent the function defined here in an ADQL tree.

      Note: If this `FunctionDef` defines an ordinary ADQL function - and not a user defined function - no class should be set here.
      However, if it defines a user defined function, there is no obligation to set a UDF class. It is useful only if the translation from ADQL (to SQL for instance) of the function has a different signature (e.g. a different name) in the target language (e.g. SQL). If the signature is the same, there is no need to set a UDF class ; a `DefaultUDF` will be created on the fly by the library when needed if it turns out that no UDF class is set.

      Parameters:
        `udfClass` - Class to use to represent in an ADQL tree the User Defined Function defined in this `FunctionDef`.
      Throws:
        `java.lang.IllegalArgumentException` - If the given class does not provide any constructor with a single parameter of type ADQLOperand[].

    - #### parse

          public static FunctionDef parse​(java.lang.String strDefinition)
                                   throws ParseException

      Let parsing the serialized form of a function definition.

      The expected syntax is (items between brackets are optional):

          {fctName}([{param1Name} {param1Type}, ...])[ -> {returnType}]

      This function must be able to parse functions as defined by TAPRegExt (section 2.3). Hence, allowed parameter types and return types should be one of the types listed by the UPLOAD section of the TAP recommendation document. These types are listed in the enumeration object `DBType.DBDatatype`. However, other types should be accepted like the common database types...but it should be better to not rely on that since the conversion of those types to TAP types should not be exactly what is expected (because depending from the used DBMS); a default interpretation of database types is nevertheless processed by this parser.

      Parameters:
        `strDefinition` - Serialized function definition to parse.
      Returns:
        The object representation of the given string definition.
      Throws:
        `ParseException` - If the given string has a wrong syntax or uses unknown types.

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

    - #### compareTo

          public int compareTo​(FunctionDef def)

      Specified by:
        `compareTo` in interface `java.lang.Comparable<FunctionDef>`

    - #### compareTo

          public int compareTo​(ADQLFunction fct)

      Compare this function definition with the given ADQL function item.

      The comparison is done only on the function name and on rough type of the parameters. "Rough type" means here that just the kind of type is tested: numeric, string or geometry. Anyway, the return type is never tested by this function, since such information is usually not part of a function signature.

      The notions of "greater" and "less" are defined here according to the three following test steps:

      1. Name test: if the name of both function are equals, next steps are evaluated, otherwise the standard string comparison (case insensitive) result is returned.
      2. Parameters test: parameters are compared individually. Each time parameters (at the same position in both functions) are equals the next parameter can be tested, and so on until two parameters are different or the end of the parameters' list is reached. Just the kind of type is used for parameter comparison. Each kind of type is tested in the following order: numeric, string and geometry. When a kind of type is not equal for both parameters, the function exits with the appropriate value (1 if the parameter of this function definition is of the kind of type, -1 otherwise).
      3. Number of parameters test: in the case where this function definition has N parameters and the given ADQL function has M parameters, and that the L (= min(N,M)) first parameters have the same type in both functions, the value returns by this function will be N-M. Thus, if this function definition has more parameters than the given function, a positive value will be returned. Otherwise a negative value will be returned, or 0 if the number of parameters is the same.

      Note: If one of the tested types (i.e. parameters types) is unknown, the match should return 0 (i.e. equality). The notion of "unknown" is different in function of the tested item. A `DBType` is unknown if its function `DBType.isUnknown()` returns `true` ; thus, its other functions such as `DBType.isNumeric()` will return `false`. On the contrary, an `ADQLOperand` does not have any isUnknown() function. However, when the type of a such is unknown, all its functions isNumeric(), isString() and isGeometry() return `true`.

      Parameters:
        `fct` - ADQL function item to compare with this function definition.
      Returns:
        A positive value if this function definition is "greater" than the given `ADQLFunction`, 0 if they are perfectly matching or one of the tested types (i.e. parameters types) is unknown, or a negative value if this function definition is "less" than the given `ADQLFunction`.