Class UserDefinedFunction
- All Implemented Interfaces:
ADQLObject
,ADQLOperand
,UnknownType
- Direct Known Subclasses:
DefaultUDF
Abstract to concrete class
Since ADQL-Lib v2.0, this class is no longer abstract. DefaultUDF
has been merged into UserDefinedFunction
which then became a
concrete class. Most of the 'final' functions in DefaultUDF
are no
longer 'final' in UserDefinedFunction
.
Warning:
DefaultUDF
is now deprecated and should not be used any more.
Language feature
As any optional feature of ADQL (since ADQL-2.1), an explicit ID and
description have to be provided in the capabilities of an ADQL service
(like TAP). This is represented here by a LanguageFeature
. In
UserDefinedFunction
it is automatically generated by
generateLanguageFeature()
at creation (by
UserDefinedFunction(String, ADQLOperand[])
) or when NO definition
is explicitly set (by setDefinition(FunctionDef)
). Otherwise,
when setting a non NULL definition, a Language Feature is created using this
definition (with LanguageFeature(FunctionDef)
).
Function definition
ADQL allows the usage of User Defined Function (UDF), but as such there is
no definition (mainly a name and signature) available. However, TAPRegExt
lets return a definition and human description of UDFs. In the ADQL tree,
a such definition is represented by a FunctionDef
. It is not
mandatory to set one, but recommended anyway. To do so, call
setDefinition(FunctionDef)
.
Custom extension
It is expected that this class may be extended in order to cover special custom User Defined Function. That's why most of the defined function are not 'final', as attributes are not too.
Recommendation: It is recommended, when possible, to update the protected attributes directly instead of their corresponding getter function.
The empty constructor is protected only for extension purpose. That way,
it is up to the developer to decide whether he/she wants to call the super
class's empty constructor or the default one
(UserDefinedFunction(String, ADQLOperand[])
). However, the
extension class SHOULD have at least one constructor with 2 arguments:
String for the UDF name, ADQLOperand
[] for its parameters.
Warning:
If this constructor does not exist or is not desired,
ADQLQueryFactory.createUserDefinedFunction(String, ADQLOperand[])
will have to be overwritten. Also be careful that the definition set to this
extension class has no custom UDF class
,
otherwise, there will be an attempt to replace it by an instance of this
UDF class ; and this will probably end with an error because of the missing
constructor.
-
Nested Class Summary
Nested classes/interfaces inherited from class adql.query.operand.function.ADQLFunction
ADQLFunction.ParameterIterator
-
Field Summary
FieldsModifier and TypeFieldDescriptionprotected FunctionDef
Define/Describe this user defined function.protected String
Parsed name of this UDF.protected LanguageFeature
Description of this ADQL Feature.protected ADQLList
<ADQLOperand> Its parsed parameters. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
Creates a UDF with no name and no parameter.Builds a UserFunction by copying the given one.UserDefinedFunction
(String name, ADQLOperand[] params) Creates a user function. -
Method Summary
Modifier and TypeMethodDescriptionprotected void
Generate and set a defaultLanguageFeature
for this ADQL function.getCopy()
Gets a (deep) copy of this ADQL object.final FunctionDef
Get the signature/definition/description of this user defined function.final char
Get the type expected by the syntactic parser according to the context.final LanguageFeature
Get the description of this ADQL's Language Feature.getName()
Gets the name of this object in ADQL.int
Gets the number of parameters this function has.getParameter
(int index) Gets the index-th parameter.Gets the list of all parameters of this function.boolean
Tell whether this operand is a geometrical region or not.boolean
Tell whether this operand is numeric or not.boolean
isString()
Tell whether this operand is a string or not.void
setDefinition
(FunctionDef def) Let set the signature/definition/description of this user defined function.final void
setExpectedType
(char c) Set the type expected for this operand.setParameter
(int index, ADQLOperand replacer) Function to override if you want to check the parameters of this user defined function.translate
(ADQLTranslator caller) Translate this User Defined Function into the language supported by the given translator.Methods inherited from class adql.query.operand.function.ADQLFunction
adqlIterator, getPosition, paramIterator, setPosition, toADQL
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface adql.query.ADQLObject
adqlIterator, getPosition, toADQL
-
Field Details
-
languageFeature
Description of this ADQL Feature.- Since:
- 2.0
-
definition
Define/Describe this user defined function. This object gives the return type and the number and type of all parameters.Note: NULL if the function name is invalid. See
FunctionDef.FunctionDef(..., ADQLVersion)
for more details.- Since:
- 2.0
-
parameters
Its parsed parameters.- Since:
- 2.0
-
functionName
Parsed name of this UDF.Important: This attribute should never be NULL.
- Since:
- 2.0
-
-
Constructor Details
-
UserDefinedFunction
protected UserDefinedFunction()Creates a UDF with no name and no parameter.Implementation note 1: By default
functionName
is not set to NULL, but to"<unnamed>"
in order to avoidNullPointerException
(especially when generating aLanguageFeature
).Implementation note 2: The purpose of this constructor is just allow more flexibility when extending this class. However, it is highly recommended to set at least a non-null function name. This can be done in at least 3 ways:
- calling the super constructor:
UserDefinedFunction(String, ADQLOperand[])
- setting the protected attribute
functionName
- overwriting the function
getName()
- calling the super constructor:
-
UserDefinedFunction
Creates a user function.- Parameters:
params
- Parameters of the function.- Throws:
NullPointerException
- Since:
- 2.0
-
UserDefinedFunction
Builds a UserFunction by copying the given one.- Parameters:
toCopy
- The UserFunction to copy.- Throws:
Exception
- If there is an error during the copy.- Since:
- 2.0
-
-
Method Details
-
getExpectedType
public final char getExpectedType()Description copied from interface:UnknownType
Get the type expected by the syntactic parser according to the context.- Specified by:
getExpectedType
in interfaceUnknownType
- Returns:
- Expected type: 'n' or 'N' for numeric, 's' or 'S' for string, 'g' or 'G' for geometry.
-
setExpectedType
public final void setExpectedType(char c) Description copied from interface:UnknownType
Set the type expected for this operand.- Specified by:
setExpectedType
in interfaceUnknownType
- Parameters:
c
- Expected type: 'n' or 'N' for numeric, 's' or 'S' for string, 'g' or 'G' for geometry.
-
getFeatureDescription
Description copied from interface:ADQLObject
Get the description of this ADQL's Language Feature.Note: Getting this description is generally only useful when discovery optional features so that determining if they are allowed to be used in ADQL queries.
- Specified by:
getFeatureDescription
in interfaceADQLObject
- Returns:
- Description of this ADQL object as an ADQL's feature.
-
getDefinition
Get the signature/definition/description of this user defined function. The returned object provides information on the return type and the number and type of parameters.- Returns:
- Definition of this function. (MAY be NULL)
- Since:
- 2.0
-
setDefinition
Let set the signature/definition/description of this user defined function.IMPORTANT: No particular checks are done here except on the function name which MUST be the same (case insensitive) as the name of the given definition. Advanced checks must have been done before calling this setter.
- Parameters:
def
- The definition applying to this parsed UDF, or NULL if none has been found.- Throws:
IllegalArgumentException
- If the name in the given definition does not match the name of this parsed function.- Since:
- 2.0
-
generateLanguageFeature
protected void generateLanguageFeature()Generate and set a defaultLanguageFeature
for this ADQL function.Note: Knowing neither the parameters name nor their type, the generated LanguageFeature will just set an unknown type and set a default parameter name (index prefixed with `$`).
- Since:
- 2.0
-
isNumeric
public boolean isNumeric()Description copied from interface:ADQLOperand
Tell whether this operand is numeric or not.- Specified by:
isNumeric
in interfaceADQLOperand
- Returns:
- true if this operand is numeric, false otherwise.
-
isString
public boolean isString()Description copied from interface:ADQLOperand
Tell whether this operand is a string or not.- Specified by:
isString
in interfaceADQLOperand
- Returns:
- true if this operand is a string, false otherwise.
-
isGeometry
public boolean isGeometry()Description copied from interface:ADQLOperand
Tell whether this operand is a geometrical region or not.- Specified by:
isGeometry
in interfaceADQLOperand
- Returns:
- true if this operand is a geometry, false otherwise.
-
getCopy
Description copied from interface:ADQLObject
Gets a (deep) copy of this ADQL object.- Specified by:
getCopy
in interfaceADQLObject
- Returns:
- The copy of this ADQL object.
- Throws:
Exception
- If there is any error during the copy.
-
getName
Description copied from interface:ADQLObject
Gets the name of this object in ADQL.- Specified by:
getName
in interfaceADQLObject
- Returns:
- The name of this ADQL object.
-
getParameters
Description copied from class:ADQLFunction
Gets the list of all parameters of this function.- Specified by:
getParameters
in classADQLFunction
- Returns:
- Its parameters list.
-
getNbParameters
public int getNbParameters()Description copied from class:ADQLFunction
Gets the number of parameters this function has.- Specified by:
getNbParameters
in classADQLFunction
- Returns:
- Number of parameters.
-
getParameter
Description copied from class:ADQLFunction
Gets the index-th parameter.- Specified by:
getParameter
in classADQLFunction
- Parameters:
index
- Parameter number.- Returns:
- The corresponding parameter.
- Throws:
ArrayIndexOutOfBoundsException
- If the index is incorrect (index invalid input: '<' 0 || index >= getNbParameters()).
-
setParameter
public ADQLOperand setParameter(int index, ADQLOperand replacer) throws ArrayIndexOutOfBoundsException, NullPointerException, Exception Function to override if you want to check the parameters of this user defined function.- Specified by:
setParameter
in classADQLFunction
- Parameters:
index
- Index of the parameter to replace.replacer
- The replacer.- Returns:
- The replaced parameter.
- Throws:
ArrayIndexOutOfBoundsException
- If the index is incorrect (index invalid input: '<' 0 || index >= getNbParameters()).NullPointerException
- If a required parameter must be replaced by a NULL object.Exception
- If another error occurs.- Since:
- 2.0
- See Also:
-
translate
Translate this User Defined Function into the language supported by the given translator.VERY IMPORTANT: This function MUST NOT use
ADQLTranslator.translate(UserDefinedFunction)
to translate itself. The givenADQLTranslator
must be used ONLY to translate UDF's operands.Implementation example:
public String translate(final ADQLTranslator caller) throws TranslationException{ StringBuilder sql = new StringBuilder(functionName); sql.append('('); for(int i = 0; i invalid input: '<' parameters.size(); i++){ if (i > 0) sql.append(',').append(' '); sql.append(caller.translate(parameters.get(i))); } sql.append(')'); return sql.toString(); }
- Parameters:
caller
- Translator to use in order to translate ONLY function parameters.- Returns:
- The translation of this UDF into the language supported by the given translator, or NULL to let the calling translator apply a default translation.
- Throws:
TranslationException
- If one of the parameters can not be translated.- Since:
- 1.3
-