: Interface Function

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD