ModSQL
Interface Function

All Known Subinterfaces:

Aggregate, RowConstructor

All Known Implementing Classes:

AbstractFunction, ColumnValue, IndirectFunction, Literal

public interface Function

This interface is at the root of all single-valued SQL expressions (including row constructors). The interface provides methods for manipulating function and operator parameters, and for evaluating the function/operator/variable/literal and obtaining a specific value.

Many of the method specified by this interface may only be used either before optimize() has been called, or after. This documentation for these methods will specify if this is case.

Author:

chris.studholme@utoronto.ca

Field Summary

static int	MATCH_BEGINS Match operator (begins with).
static int	MATCH_EQU Match operator (equal).
static int	MATCH_GT Match operator (greater than).
static int	MATCH_GTE Match operator (greater or equal).
static int	MATCH_LT Match operator (less than).
static int	MATCH_LTE Match operator (less or equal).
static int	MATCH_NE Match operator (not equal).

Method Summary

void	addParameter(Function item) Adds a value (function) to the list of parameters required by this function.
Object	evaluate(boolean aggregate) Evaluate parameters and compute the function.
Object	evaluate(int match_operator, Object match_value) Same as evaluate(), except that a specific result is desired.
void	evaluateOrder(int index, int order) Specify the order in which the parameters should be evaluated.
int	getMaxResultSize() Return the maximum number of characters that this function expects to return in a String object.
Function	getParameter(int index) Get a particular parameter.
int	getParameterCount() Get the number of parameters currently supplied to this function.
int	getSQLType() Return the SQL type of the value that this function expects to return.
boolean	isAggregate() Determine if this function will return a value that is an aggregate of many database rows.
boolean	isConstant() Determine if this function returns a constant value.
void	optimize() Prepare the function for use.
void	registerWith(Object o) Some functions (most notably IndirectValue) need to register themselves before optimize() can be called.
void	reset() In the case of aggregate functions, this method resets the state of the function to the state it was in before the first call to evaluate().

Field Detail

MATCH_BEGINS

public static final int MATCH_BEGINS

Match operator (begins with).

MATCH_EQU

public static final int MATCH_EQU

Match operator (equal).

MATCH_GT

public static final int MATCH_GT

Match operator (greater than).

MATCH_GTE

public static final int MATCH_GTE

Match operator (greater or equal).

MATCH_LT

public static final int MATCH_LT

Match operator (less than).

MATCH_LTE

public static final int MATCH_LTE

Match operator (less or equal).

MATCH_NE

public static final int MATCH_NE

Match operator (not equal).

Method Detail

getParameterCount

public int getParameterCount()

Get the number of parameters currently supplied to this function. If the function does not support/require parameters, this method should return 0.

Returns:

number of parameters

getParameter

public Function getParameter(int index)

Get a particular parameter. If the function does not support/require parameters, this method should throw an IndexOutOfBoundsException regardless of the index supplied.

Parameters:

index - index of parameter to get

Returns:

parameter (function)

Throws:

IndexOutOfBoundsException - if the index if out of range

addParameter

public void addParameter(Function item)
                  throws SQLException

Adds a value (function) to the list of parameters required by this function. If the function does not support/require parameters, an SQLException should be thrown.

This method can only be used before optimize() has been called.

Parameters:

item - function to add

Throws:

SQLException - if the parameter is inappropriate in some way

evaluateOrder

public void evaluateOrder(int index,
                          int order)
                   throws SQLException

Specify the order in which the parameters should be evaluated. ModSQL will determine the optimal order in which parameters should be evaluated and use this function to indicate this order. The order argument will be a number between 0 and num_parameters-1, and be a permutation of those numbers. The function is free to ignore this suggested ordering, but it should attempt to follow the ordering for optimal efficiency. If the function does not support/require parameters, an IndexOutOfBoundsException should be thrown regardless of the index.

This method can only be used before optimize() has been called.

Parameters:

index - index of parameter

order - number indicating the order in which the parameter should be evaluated

Throws:

IndexOutOfBoundsException - if the index if out of range

SQLException - if optimize has already been called

registerWith

public void registerWith(Object o)
                  throws SQLException

Some functions (most notably IndirectValue) need to register themselves before optimize() can be called. This method must call the registerWith() method on all Function objects contained within (including, but not limited to, all parameters). Most implementations will simply pass this call on to all contained parameters.

This method can only be used before optimize() has been called.

Parameters:

o - object to register with

Throws:

SQLException - if an error occurs

optimize

public void optimize()
              throws SQLException

Prepare the function for use. This method must call optimize() for each parameter or other contained Function and then prepare itself for use.

After this method has been called, the number and types of parameters will not change. If the number or type of parameters is incorrect, an SQLException should be thrown.

This method may only be called once per object instance.

Throws:

SQLException - if an error occurs

isConstant

public boolean isConstant()
                   throws SQLException

Determine if this function returns a constant value. If all of the functions parameters are constant, then the function is considered constant as well.

This method can only be used after optimize() has been called.

Returns:

true if the value returned is constant

Throws:

SQLException - if an error occurs

isAggregate

public boolean isAggregate()
                    throws SQLException

Determine if this function will return a value that is an aggregate of many database rows. If the function does not aggregate data itself, it is still considered an aggregate function if all of its parameters are either aggregate or constant. Columns that appear in the GROUP BY clause will be marked as aggregate.

This method is expected to throw an exception if it aggregates data but contains parameters that also aggregate data, or if it does not aggregate data but contains both aggregate parameters and non-aggregate, non-constant parameters.

This method can only be used after optimize() has been called.

Returns:

true if the function aggregates several rows of data

Throws:

SQLException - if an error occurs

getSQLType

public int getSQLType()
               throws SQLException

Return the SQL type of the value that this function expects to return. The data returned by the function must either be of this type, or null.

This method can only be used after optimize() has been called.

Returns:

SQL type of data to be returned

Throws:

SQLException - if an error occurs

getMaxResultSize

public int getMaxResultSize()
                     throws SQLException

Return the maximum number of characters that this function expects to return in a String object. If the function does not expect to return a String object or if it cannot guess a maximum value, -1 should be returned.

This method can only be used after optimize() has been called.

Returns:

maximum size of String returned or -1 if unknown

Throws:

SQLException - if an error occurs

reset

public void reset()
           throws SQLException

In the case of aggregate functions, this method resets the state of the function to the state it was in before the first call to evaluate().

This method is expected to call reset() for all of the function's parameters and other contained Function objects.

This method can only be used after optimize() has been called. The function should be in a reset state immediately after optimize() has been called.

Throws:

SQLException - if an error occurs

evaluate

public Object evaluate(boolean aggregate)
                throws SQLException,
                       EndOfTable

Evaluate parameters and compute the function. The parameters should be evaluated in the order indicated with evaluateOrder() for optimal query efficiency.

If the function is an aggregate, this method may return null to indicate that the aggregate is not yet available. The method will be called later with the aggregate parameter set to true to indicate that the final aggregate value is required. If the function is non-constant and non-aggregate, it may throw an exception if the aggregate parameter is true. Functions that read data from the database should not advance to a new row if aggregate is true.

This method can only be used after optimize() has been called.

Parameters:

aggregate - true to return final aggregate value

Returns:

result object

Throws:

SQLException - if an error occurs

EndOfTable - if a database was advanced beyond the end of the table

evaluate

public Object evaluate(int match_operator,
                       Object match_value)
                throws SQLException,
                       EndOfTable

Same as evaluate(), except that a specific result is desired. If the desired result can only be obtained when a particular parameter evaluates to a particular value, the evaulate() method for that parameter should be passed that particular value in the hopes that it will be returned. Otherwise, if knowledge of a desired result does not sufficiently constrain the parameters, this method can simply call the evaluate() method above and return what it returns.

This method is in no way obligated to return a value satisfying the constraint. If the constraint can be satisified, every effort should me made to satisfy it; however, if during the calculation it becomes obvious that the constraint cannot be satisfied, any non-satisfying value may be returned (even if it's an incorrect evaluation).

The match_operator parameter will be one of the MATCH_* constants. The match condition can be considered a relation of the form: desired_value match_operator match_value. For example, desired_value MATCH_LT match_value implies desired_value < match_value.

If match_value is null or a Boolean object, match_operator must be either MATCH_EQU or MATCH_NE. If match_value is non-null, it should be assumed that a non-null value is sought, except in the case where match_operator is MATCH_NE and match_value is a Boolean object. In this case, a value of either the null or !match_value is sought.

The type of the match_value object need not exactly match the return type of the function, but it must be a compatible type.

This method can only be used after optimize() has been called.

Parameters:

match_operator - how desired value is matched

match_value - value to match to

Returns:

result object

Throws:

SQLException - if an error occurs

EndOfTable - if a database was advanced beyond the end of the table