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
.
Modifier and Type | Class and Description |
---|---|
static class |
FunctionDef.FunctionParam
Definition of a function parameter.
|
Modifier and Type | Field and 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 and 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.
|
Modifier and Type | Method and Description |
---|---|
int |
compareTo(ADQLFunction fct)
Compare this function definition with the given ADQL function item.
|
int |
compareTo(FunctionDef def) |
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> |
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() |
protected static final java.lang.String regularIdentifierRegExp
protected static final java.lang.String typeRegExp
protected static final java.lang.String fctParamsRegExp
protected static final java.lang.String fctParamRegExp
regularIdentifierRegExp
) and a type (see typeRegExp
).protected static final java.lang.String fctDefRegExp
protected static final java.util.regex.Pattern fctPattern
fctDefRegExp
.protected static final java.util.regex.Pattern paramPattern
fctParamRegExp
.public final java.lang.String name
public java.lang.String description
public final DBType returnType
protected final boolean isString
protected final boolean isNumeric
protected final boolean isGeometry
protected final boolean isUnknown
Note:
If true
, isString
, isNumeric
and isGeometry
are false
. Otherwise,
at least one of these attributes is set to true
.
public final int nbParams
protected final FunctionDef.FunctionParam[] params
public FunctionDef(java.lang.String fctName)
Create a function definition.
The created function will have no return type and no parameter.
fctName
- Name of the function.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.
fctName
- Name of the function.returnType
- Return type of the function. If NULL, this function will have no return typepublic 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).
fctName
- Name of the function.params
- Parameters of this function. If NULL or empty, this function will have no parameter.public FunctionDef(java.lang.String fctName, DBType returnType, FunctionDef.FunctionParam[] params)
public final boolean isNumeric()
public final boolean isString()
public final boolean isGeometry()
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
.
public final int getNbParams()
public final FunctionDef.FunctionParam getParam(int indParam) throws java.lang.ArrayIndexOutOfBoundsException
indParam
- Index of the parameter whose the definition must be returned.java.lang.ArrayIndexOutOfBoundsException
- If the given index is negative or bigger than the number of parameters.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).
UserDefinedFunction
. MAY BE NULLpublic 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.
udfClass
- Class to use to represent in an ADQL tree the User Defined Function defined in this FunctionDef
.java.lang.IllegalArgumentException
- If the given class does not provide any constructor with a single parameter of type ADQLOperand[].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.
strDefinition
- Serialized function definition to parse.ParseException
- If the given string has a wrong syntax or uses unknown types.public java.lang.String toString()
toString
in class java.lang.Object
public int compareTo(FunctionDef def)
compareTo
in interface java.lang.Comparable<FunctionDef>
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:
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
.
fct
- ADQL function item to compare with this function definition.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
.