com.celequest.api.function
Interface IUDFunctionWithVariableResultType

All Superinterfaces:

IUDFunction

public interface IUDFunctionWithVariableResultType

extends IUDFunction

User defined functions should implement this extension of IUDFunction if they need to have specific control over the precision and scale of ISQLDecimal result types, or over the maximum specified string length of an ISQLVarchar result type.

By default, the precision of a decimal result to a function is the max of the precisions of the decimal arguments to that function, and the scale of a decimal result to a function is the max of the scales of the decimal arguments to that function. If there are no decimal arguments to a function which returns a decimal type, the returned type has the default precision of 256 scale of 2.

By default, the maximum-specified-string-length of a varchar result to a function is the max of the maximum specified string length of the varchar arguments to that function. If there are no varchar arguments to a function that returns a varchar type, the returned type is a varchar with no specified maximum string length. That is, the maximum specified string length is ISQLVarchar.INFINITE_STRING.

A user defined function that can return a result of type ISQLDecimal or ISQLVarchar, and that needs to override this default behaviour, should implement IUDFunctionWithVariableResultType.

Since:

2.5.3

Nested Class Summary

static interface	IUDFunctionWithVariableResultType.IDecimalResultTypeSetter Helper interface for getVarcharResultType.
static interface	IUDFunctionWithVariableResultType.IVarcharResultTypeSetter Helper interface for getVarcharResultType.

Method Summary

void

getDecimalResultType(ISQLValue[] arguments, IUDFunctionWithVariableResultType.IDecimalResultTypeSetter decimalResultTypeSetter) Passed an array of UDF arguments, this method looks at the types of those arguments, including the precision and scale of any ISQLDecimal arguments, and calls the setPrecision and setScale methods on the passed-in IDecimalResultTypeSetter to specify the precision and scale of the ISQLDecimal type that should be returned by the UDF.

void

getVarcharResultType(ISQLValue[] arguments, IUDFunctionWithVariableResultType.IVarcharResultTypeSetter varcharResultTypeSetter) Passed an array of UDF arguments, this method looks at the types of those arguments, including the maximum specified string length of ISQLVarchar arguments, and calls the setSpecifiedMaxStrLength methods on the passed-in IVarcharResultTypeSetter to specify the maximum specified string length of the ISQLVarchar type that should be returned by the UDF.

Methods inherited from interface com.celequest.api.function.IUDFunction

setLogger

Method Detail

getDecimalResultType

public void getDecimalResultType(ISQLValue[] arguments,
                                 IUDFunctionWithVariableResultType.IDecimalResultTypeSetter decimalResultTypeSetter)

Passed an array of UDF arguments, this method looks at the types of those arguments, including the precision and scale of any ISQLDecimal arguments, and calls the setPrecision and setScale methods on the passed-in IDecimalResultTypeSetter to specify the precision and scale of the ISQLDecimal type that should be returned by the UDF.

Only UDF function signatures specified in the com.celequest.manifest.manifest.xml file to return a DECIMAL result will have their argument types passed to this function.

For example, the following might be used by a custom decimal multiplication UDF that is expected to be called only with two decimal arguments, and to return a decimal with precision equal to the sum of the precisions of the arguments, and scale equal to the sum of the scales of the arguments. public void getDecimalResultType(ISQLValue []arguments, IDecimalResultTypeSetter decimalResultTypeSetter) { // Expect ISQLDecimal arguments because that is all that was declared // in the com.celequest.manifest.manifest.xml file to return a DECIMAL. ISQLDecimal arg1 = (ISQLDecimal)arguments[0]; ISQLDecimal arg2 = (ISQLDecimal)arguments[1]; // Calculate the precision and scale int precision = arg1.getPrecision() + arg2.getPrecision(); int scale = arg1.getScale() + arg2.getScale(); // Don't exceed the maximum allowed precision or scale precision = Math.min(precision, 256); scale = Math.min(scale, 256); // Set the precision and scale decimalResultTypeSetter.setPrecision(precision); decimalResultTypeSetter.setScale(scale); return; }

Parameters:

arguments - an array of the arguments to the UDF. These will often contain ISQLDecimal arguments on which this method will call ISQLDecimal.getScale and ISQLDecimal.getPrecision.

decimalResultTypeSetter - this method should call IDecimalResultTypeSetter.setScale and IDecimalResultTypeSetter.setPrecision methods to set the scale and precision of its result.

getVarcharResultType

public void getVarcharResultType(ISQLValue[] arguments,
                                 IUDFunctionWithVariableResultType.IVarcharResultTypeSetter varcharResultTypeSetter)

Passed an array of UDF arguments, this method looks at the types of those arguments, including the maximum specified string length of ISQLVarchar arguments, and calls the setSpecifiedMaxStrLength methods on the passed-in IVarcharResultTypeSetter to specify the maximum specified string length of the ISQLVarchar type that should be returned by the UDF.

Only UDF function signatures specified in the com.celequest.manifest.manifest.xml file to return a VARCHAR result will have their argument types passed to this function.

For example, the following might be used by a custom concatination UDF that is expected to be called only with two varchar arguments, and to return a varchar with the cmaximum specified string length equal to the sum of the maximum specified string length of the arguments. public void getVarcharResultType(ISQLValue []arguments, IVarcharResultTypeSetter varcharResultTypeSetter) { // Expect ISQLVarchar arguments because that is all that was declared // in the com.celequest.manifest.manifest.xml file to return a VARCHAR. ISQLVarchar arg1 = (ISQLVarchar)arguments[0]; ISQLVarchar arg2 = (ISQLVarchar)arguments[1]; // Calculate the maximum-specified-string-length final int maxStrLength; if (arg1.getSpecifiedMaxStrLength() == ISQLVarchar.INFINITE_STRING) || arg2.getSpecifiedMaxStrLength() == ISQLVarchar.INFINITE_STRING)) { maxStrLength = ISQLVarchar.INFINITE_STRING; } else { maxStrLength = arg1.getSpecifiedMaxStrLength() + arg2.getSpecifiedMaxStrLength(); } // Set the maxStrLength for the result varcharResultTypeSetter.setSpecifiedMaxStrLength(maxStrLength); return; }

Parameters:

arguments - an array of the arguments to the UDF. These will often contain ISQLVarchar arguments on which this method will call ISQLVarchargetSpecifiedMaxStrLength.

varcharResultTypeSetter - this method should call IVarcharResultTypeSetter.setSpecifiedMaxStrLength to set the maximum string length of its result.