Class FunctionDef
- All Implemented Interfaces:
Comparable<FunctionDef>
Creating a function definition
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}]
Description
A description of this function may be set thanks to the public class
attribute description
.
Custom UDF
To specify a special UDF representation use setUDFClass(Class)
.
Then, to create an instance of this class, use
createUDF(ADQLOperand[])
. Specifying a UDF class is also one of the
two ways to describe how to translate the represented UDF into the target
language.
Translation
An alternative (and simpler) way to tell how to the translate the
represented UDF is through a FunctionTranslator
thanks to
setTranslatorClass(Class)
. Then, to create an instance of this class,
use createTranslator()
.
Warning:
It has to be noted that setUDFClass(Class)
and
setTranslatorClass(Class)
are mutually exclusive. Setting a UDF class
reset to NULL any previously set translator, and setting a translator class,
reset to NULL any previously set UDF class.
- Since:
- 1.3
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final class
Definition of a function parameter. -
Field Summary
FieldsModifier and TypeFieldDescriptionDescription of this function.protected static final String
Rough regular expression for a whole function definition.protected static final String
Rough regular expression for a function parameter: a name (seeregularIdentifierRegExp
) and a type (seetypeRegExp
).protected static final String
Rough regular expression for a function parameters' list.protected static final Pattern
Pattern of a function definition.protected final boolean
Indicate whether the return type is a geometry.protected final boolean
Indicate whether the return type is a numeric.protected final boolean
Indicate whether the return type is a string.protected final boolean
Indicate whether the return type is an unknown type.final String
Name of the function.final int
Total number of parameters.protected static final Pattern
Pattern of a single parameter definition.protected final FunctionDef.FunctionParam[]
List of all the parameters of this function.protected static final String
Regular expression for what should be a function or parameter name - a regular identifier.final DBType
Type of the result returned by this function.protected static final String
Rough regular expression for a function return type or a parameter type. -
Constructor Summary
ConstructorsConstructorDescriptionFunctionDef
(String fctName) Create a function definition.FunctionDef
(String fctName, DBType returnType) Create a function definition.FunctionDef
(String fctName, DBType returnType, FunctionDef.FunctionParam[] params) Create a function definition.FunctionDef
(String fctName, DBType returnType, FunctionDef.FunctionParam[] params, ADQLParser.ADQLVersion targetADQL) Create a function definition.FunctionDef
(String fctName, FunctionDef.FunctionParam[] params) Create a function definition. -
Method Summary
Modifier and TypeMethodDescriptionprotected static void
checkUDFName
(String fctName, ADQLParser.ADQLVersion adqlVersion) Check that the given UDF name is valid according to the ADQL grammar.int
compareTo
(FunctionDef def) int
compareTo
(ADQLFunction fct) Compare this function definition with the given ADQL function item.final FunctionTranslator
Create an instance of the specifiedFunctionTranslator
interface (getTranslatorClass()
) or of aFunctionTranslatorWithPattern
with the specified translation pattern (getTranslationPattern()
).final UserDefinedFunction
createUDF
(ADQLOperand[] parameters) Create an instance of theUserDefinedFunction
class specified bygetUDFClass()
.final int
Get the number of parameters required by this function.getParam
(int indParam) Get the definition of the indParam-th parameter of this function.final String
Get the translation pattern to use for any ADQL function implementing this UDF definition.final Class
<? extends FunctionTranslator> Get the class of the translator to use for any ADQL function implementing this UDF definition.final Class
<? extends UserDefinedFunction> Get the class of theUserDefinedFunction
able to represent the function defined here in an ADQL tree.final boolean
Tell whether this function returns a geometry.final boolean
Tell whether this function returns a numeric.final boolean
isString()
Tell whether this function returns a string.final boolean
Tell whether this function returns an unknown type.static FunctionDef
Let parsing the serialized form of a function definition.static FunctionDef
parse
(String strDefinition, ADQLParser.ADQLVersion targetADQL) Let parsing the serialized form of a function definition.final void
setTranslationPattern
(String pattern) Set the translation pattern to use for any ADQL function implementing this UDF definition.final <T extends FunctionTranslator>
voidsetTranslatorClass
(Class<T> translatorClass) Set theFunctionTranslator
class to use for any ADQL function implementing this UDF definition.final <T extends UserDefinedFunction>
voidsetUDFClass
(Class<T> udfClass) Set the class of theUserDefinedFunction
able to represent the function defined here in an ADQL tree.final LanguageFeature
Create aLanguageFeature
corresponding and linked to thisFunctionDef
.toString()
final boolean
Tell whether either a translation pattern or aFunctionTranslator
class is specified in this function definition.
-
Field Details
-
regularIdentifierRegExp
Regular expression for what should be a function or parameter name - a regular identifier.- See Also:
-
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:
-
fctParamsRegExp
Rough regular expression for a function parameters' list.- See Also:
-
fctParamRegExp
Rough regular expression for a function parameter: a name (seeregularIdentifierRegExp
) and a type (seetypeRegExp
).- See Also:
-
fctDefRegExp
Rough regular expression for a whole function definition.- See Also:
-
fctPattern
Pattern of a function definition. This object has been compiled withfctDefRegExp
. -
paramPattern
Pattern of a single parameter definition. This object has been compiled withfctParamRegExp
. -
name
Name of the function. -
description
Description of this function. -
returnType
Type of the result returned by this function. -
isString
protected final boolean isStringIndicate whether the return type is a string. -
isNumeric
protected final boolean isNumericIndicate whether the return type is a numeric. -
isGeometry
protected final boolean isGeometryIndicate whether the return type is a geometry. -
isUnknown
protected final boolean isUnknownIndicate whether the return type is an unknown type.Note: If
true
,isString
,isNumeric
andisGeometry
arefalse
. Otherwise, at least one of these attributes is set totrue
.- Since:
- 1.4
-
nbParams
public final int nbParamsTotal number of parameters. -
params
List of all the parameters of this function.
-
-
Constructor Details
-
FunctionDef
Create a function definition.The created function will have no return type and no parameter.
- Parameters:
fctName
- Name of the function.- Throws:
ParseException
- If the given UDF name is invalid according to theinvalid reference
default version
-
FunctionDef
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.- Throws:
ParseException
- If the given UDF name is invalid according to theinvalid reference
default version
-
FunctionDef
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.- Throws:
ParseException
- If the given UDF name is invalid according to theinvalid reference
default version
-
FunctionDef
public FunctionDef(String fctName, DBType returnType, FunctionDef.FunctionParam[] params) throws ParseException Create a function definition.- Parameters:
fctName
- Name of the function.returnType
- Return type of the function. If NULL, this function will have no return typeparams
- Parameters of this function. If NULL or empty, this function will have no parameter.- Throws:
ParseException
- If the given UDF name is invalid according to theinvalid reference
default version
-
FunctionDef
public FunctionDef(String fctName, DBType returnType, FunctionDef.FunctionParam[] params, ADQLParser.ADQLVersion targetADQL) throws ParseException Create a function definition.- Parameters:
fctName
- Name of the function.returnType
- Return type of the function. If NULL, this function will have no return typeparams
- Parameters of this function. If NULL or empty, this function will have no parameter.targetADQL
- Targeted ADQL grammar's version. If NULL, theinvalid reference
default version
- Throws:
ParseException
- If the given UDF name is invalid according to theinvalid reference
default version
- Since:
- 2.0
-
-
Method Details
-
checkUDFName
protected static void checkUDFName(String fctName, ADQLParser.ADQLVersion adqlVersion) throws ParseException Check that the given UDF name is valid according to the ADQL grammar.- Parameters:
fctName
- Name of the UDF to check.adqlVersion
- Version of the targeted ADQL grammar. If NULL, theinvalid reference
default version
- Throws:
ParseException
- If the given name is invalid.- Since:
- 2.0
-
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()
andisGeometry()
MUST ALL returnfalse
. Otherwise, one of these 3 last functions MUST returntrue
.- 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
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:
ArrayIndexOutOfBoundsException
- If the given index is negative or bigger than the number of parameters.
-
getUDFClass
Get the class of theUserDefinedFunction
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 thisFunctionDef
is defining a user defined function and this function returns NULL, the library will create on the fly aUserDefinedFunction
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(Class<T> udfClass) throws IllegalArgumentException Set the class of theUserDefinedFunction
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 ; aUserDefinedFunction
will be created on the fly by the library when needed if it turns out that no UDF class is set.WARNING: If successful, this operation will reset to NULL any translation pattern already set with
setTranslationPattern(String)
as well as any translator function set withsetTranslatorClass(Class)
.- Parameters:
udfClass
- Class to use to represent in an ADQL tree the User Defined Function defined in thisFunctionDef
. NULL to set no UDF class (and no translator and translation pattern as well).- Throws:
IllegalArgumentException
- If the given class does not provide any constructor with a single parameter of type ADQLOperand[].
-
createUDF
public final UserDefinedFunction createUDF(ADQLOperand[] parameters) throws NoSuchMethodException, SecurityException, InstantiationException, IllegalAccessException, IllegalArgumentException, InvocationTargetException Create an instance of theUserDefinedFunction
class specified bygetUDFClass()
.- Parameters:
parameters
- TheUserDefinedFunction
parameters. May be NULL.- Returns:
- The created instance.
- Throws:
NoSuchMethodException
- IfgetUDFClass()
does not provide a constructor with a single argument of typeADQLOperand
[].SecurityException
- If a security manager, s, is present and the caller's class loader is not the same as or an ancestor of the class loader for the current class and invocation of s.checkPackageAccess() denies access to the package of this class.InstantiationException
- If the class returned bygetUDFClass()
represents an abstract class.IllegalAccessException
- IfgetUDFClass()
is NULL or if this Constructor object is enforcing Java language access control and the underlying constructor is inaccessible.IllegalArgumentException
- If the given array is unexpected, or contains incorrect items.InvocationTargetException
- If the underlying constructor throws an exception (useInvocationTargetException.getCause()
to get it).- Since:
- 2.0
-
getTranslatorClass
Get the class of the translator to use for any ADQL function implementing this UDF definition.- Returns:
- The
FunctionTranslator
to use. NULL if no custom translator is defined. - Since:
- 2.0
-
setTranslatorClass
public final <T extends FunctionTranslator> void setTranslatorClass(Class<T> translatorClass) throws IllegalArgumentException Set theFunctionTranslator
class to use for any ADQL function implementing this UDF definition.WARNING: If successful, this operation will reset to NULL any UDF class already set with
setUDFClass(Class)
as well any translation pattern set withsetTranslationPattern(String)
.- Parameters:
translatorClass
- Class of the translator to use. NULL to set no translator (and no translation pattern and UDF class as well).- Throws:
IllegalArgumentException
- If the given class does not provide an empty constructor.- Since:
- 2.0
-
getTranslationPattern
Get the translation pattern to use for any ADQL function implementing this UDF definition.- Returns:
- The translation pattern to use. NULL if no translation pattern is defined.
- Since:
- 2.0
-
setTranslationPattern
Set the translation pattern to use for any ADQL function implementing this UDF definition.WARNING: If successful, this operation will reset to NULL any UDF class already set with
setUDFClass(Class)
and any translator already set withsetTranslatorClass(Class)
.- Parameters:
translationPattern
- Pattern to follow at translation time. NULL to set no translation pattern (and no translator and UDF class as well).- Throws:
IllegalArgumentException
- If the given translation pattern is incorrect (e.g. a referenced argument does not exist according to thisFunctionDef
).- Since:
- 2.0
-
withCustomTranslation
public final boolean withCustomTranslation()Tell whether either a translation pattern or aFunctionTranslator
class is specified in this function definition.Note: It is recommended to use this function before using
createTranslator()
. Ittrue
is returned, this latter can be safely used, otherwise an error will be thrown.Implementation note: This function is similar to check that either
getTranslationPattern()
orgetTranslatorClass()
return a non NULL value.- Returns:
true
if either a translation pattern or translator class is specified,false
otherwise (but maybe a custom UDF class is specified).- Since:
- 2.0
-
createTranslator
public final FunctionTranslator createTranslator() throws NoSuchMethodException, SecurityException, InstantiationException, IllegalAccessException, IllegalArgumentException, InvocationTargetExceptionCreate an instance of the specifiedFunctionTranslator
interface (getTranslatorClass()
) or of aFunctionTranslatorWithPattern
with the specified translation pattern (getTranslationPattern()
).Hint: This function will throw an error if no translation pattern or translator class is defined. To avoid this undesired behavior, you should use
withCustomTranslation()
. Iftrue
is returned,createTranslator()
can be safely used.- Returns:
- The created instance.
- Throws:
NoSuchMethodException
- Ifinvalid @link
{@link #getTranslatorClass()()
SecurityException
- If a security manager, s, is present and the caller's class loader is not the same as or an ancestor of the class loader for the current class and invocation of s.checkPackageAccess() denies access to the package of this class.InstantiationException
- If the class returned bygetTranslatorClass()
represents an abstract class.IllegalAccessException
- If bothgetTranslatorClass()
andgetTranslationPattern()
return NULL or if this Constructor object is enforcing Java language access control and the underlying constructor is inaccessible.IllegalArgumentException
- If the given array is unexpected, or contains incorrect items.InvocationTargetException
- If the underlying constructor throws an exception (useInvocationTargetException.getCause()
to get it).- Since:
- 2.0
-
parse
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, or if the function name is invalid according to the ADQL grammar.
-
parse
public static FunctionDef parse(String strDefinition, ADQLParser.ADQLVersion targetADQL) 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.targetADQL
- Targeted ADQL grammar's version. If NULL, theinvalid reference
default version
- Returns:
- The object representation of the given string definition.
- Throws:
ParseException
- If the given string has a wrong syntax or uses unknown types, or if the function name is invalid according to the ADQL grammar.- Since:
- 2.0
-
toLanguageFeature
Create aLanguageFeature
corresponding and linked to thisFunctionDef
.- Returns:
- The corresponding LanguageFeature.
- Since:
- 2.0
-
toString
-
compareTo
- Specified by:
compareTo
in interfaceComparable<FunctionDef>
-
compareTo
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:
- Name test: if the name of both function are equals, next steps are evaluated, otherwise the standard string comparison (case insensitive) result is returned.
- 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).
- 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 functionDBType.isUnknown()
returnstrue
; thus, its other functions such asDBType.isNumeric()
will returnfalse
. On the contrary, anADQLOperand
does not have any isUnknown() function. However, when the type of a such is unknown, all its functions isNumeric(), isString() and isGeometry() returntrue
.- 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 givenADQLFunction
.
-