com.pervasive.datarush.functions

Interface ScalarValuedFunction

All Known Implementing Classes:

ConstantReference, FieldReference

public interface ScalarValuedFunction

The description of a function taking record data and producing a scalar result. It provides the ability to enquire about the expected output type and required field arguments.

Implementors of new functions should generally not implement this interface, but instead implement FunctionEvaluator in conjunction with using ScalarFunctionDescriptor.

Method Summary

Modifier and Type	Method and Description
boolean	equals(Object o)
FunctionEvaluator	getEvaluator(RecordValued input, ScalarSettable result) Constructs an instance of an evaluator for the function.
Collection<String>	getRequiredFields() Get the input fields required in the function input.
ScalarValued	getSubexpressionEvaluation(EvaluationContext ctx) Constructs an instance of an evaluation of the function in the context of a larger expression.
ScalarTokenType	getUpperBound() Gets the upper bound on the output type of the function.
int	hashCode()
ScalarValuedFunction	mapFieldsToFunctions(Map<String,ScalarValuedFunction> mapping) Creates a new function, equivalent to the given function, but with specified field references mapped to functions.
ScalarValuedFunction	remapFieldReferences(Map<String,String> oldToNewMapping) Creates a new function, equivalent to the given function, but with all field references renamed according to the given mapping.
ScalarTokenType	validateInputType(RecordTokenType inputType) Calculates the actual output type of the function given the specified input type.

Method Detail

getUpperBound

ScalarTokenType getUpperBound()

Gets the upper bound on the output type of the function. This need not be the exact type of the output, but is expected to be a type to which the actual output type is assignable, as according to TokenType#isAssignableFrom(TokenType).

This value is used to detect type consistency issues as early as possible. It is always valid to return TokenTypeConstant#SCALAR, in which case no type consistency issues can be caught early.

Returns:

the most specific type to which any possible return type is assignable.

getRequiredFields

Collection<String> getRequiredFields()

Get the input fields required in the function input. An empty collection implies no specific fields are required.

Returns:

the names of fields which must be present in the record input schema

validateInputType

ScalarTokenType validateInputType(RecordTokenType inputType)

Calculates the actual output type of the function given the specified input type.

The type returned must be assignable to the type returned by getUpperBound(). If this is not the case, runtime type errors may arise.

Parameters:

inputType - the type of the record used as input to the function

Returns:

the return type of the function for the given input record schema

Throws:

InvalidFieldException - if the function requires a field not present in the input type

InvalidOperandTypeException - if a subexpression evaluates to a type incompatible with the function

getEvaluator

FunctionEvaluator getEvaluator(RecordValued input,
                               ScalarSettable result)

Constructs an instance of an evaluator for the function. The evaluator returns the result of the the function applied to the specified input into the given output target.

Implementations may assume that the input and output are known to be compatible with the function. Normally, this method is only invoked by the DataRush framework, which guarantees this is the case. In general, to satisfy this requirement, callers are expected to:

• verify that validateInputType(input.getType()) does not throw an exception
• verify the output type returned is assignable to result.getType()

Failure to meet this contract may result in runtime exceptions.

Parameters:

input - the record source to use as context for evaluating the function

result - the buffer into which evaluation results are to be stored

Returns:

an evaluator bound to the provided input and output

getSubexpressionEvaluation

ScalarValued getSubexpressionEvaluation(EvaluationContext ctx)

Constructs an instance of an evaluation of the function in the context of a larger expression.

Parameters:

ctx - the expression context in which the function is being evaluated as a subexpression

Returns:

an object representing the subexpression's current value

equals

boolean equals(Object o)

ScalarValuedFunctions should override this method to indicate whether they are equal to another ScalarValuedFunction.

Overrides:

equals in class Object

hashCode

int hashCode()

ScalarValuedFunctions should override this method in a manner consistent with equals(Object).

Overrides:

hashCode in class Object

remapFieldReferences

ScalarValuedFunction remapFieldReferences(Map<String,String> oldToNewMapping)

Creates a new function, equivalent to the given function, but with all field references renamed according to the given mapping.

Parameters:

oldToNewMapping - a mapping from old names to new names. If a name is not present in the given mapping, it will remain as-is.

Returns:

a new function with all field reference renamed appropriately

mapFieldsToFunctions

ScalarValuedFunction mapFieldsToFunctions(Map<String,ScalarValuedFunction> mapping)

Creates a new function, equivalent to the given function, but with specified field references mapped to functions.

Parameters:

mapping - a mapping from field names to functions. If a name is not present in the given mapping, it will remain as-is.

Returns:

a new function with all field reference mapped appropriately