Package org.sqlite

Class Function

java.lang.Object

org.sqlite.Function

Direct Known Subclasses:

Function.Aggregate

public abstract class Function
extends Object

Provides an interface for creating SQLite user-defined functions.

A subclass of org.sqlite.Function can be registered with Function.create() and called by the name it was given. All functions must implement xFunc(), which is called when SQLite runs the custom function. E.g.

      Class.forName("org.sqlite.JDBC");
      Connection conn = DriverManager.getConnection("jdbc:sqlite:");

      Function.create(conn, "myFunc", new Function() {
          protected void xFunc() {
              System.out.println("myFunc called!");
          }
      });

      conn.createStatement().execute("select myFunc();");
  

Arguments passed to a custom function can be accessed using the protected functions provided. args() returns the number of arguments passed, while value_<type>(int) returns the value of the specific argument. Similarly, a function can return a value using the result(<type>) function.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Function.Aggregate	Provides an interface for creating SQLite user-defined aggregate functions.
static class	Function.Window	Provides an interface for creating SQLite user-defined window functions.

Field Summary

Fields

Modifier and Type	Field	Description
static int	FLAG_DETERMINISTIC	Flag to provide to create(Connection, String, Function, int) that marks this Function as deterministic, making is usable in Indexes on Expressions.

Constructor Summary

Constructors

Constructor	Description
Function()

Method Summary

Modifier and Type	Method	Description
protected int	args()	Returns the number of arguments passed to the function.
static void	create(Connection conn, String name, Function f)	Registers a given function with the connection.
static void	create(Connection conn, String name, Function f, int flags)	Registers a given function with the connection.
static void	create(Connection conn, String name, Function f, int nArgs, int flags)	Registers a given function with the connection.
static void	destroy(Connection conn, String name)	Removes a named function from the given connection.
static void	destroy(Connection conn, String name, int nArgs)	Removes a named function from the given connection.
protected void	error(String err)	Called by xFunc to throw an error.
protected void	result()	Called by xFunc to return a value.
protected void	result(byte[] value)	Called by xFunc to return a value.
protected void	result(double value)	Called by xFunc to return a value.
protected void	result(int value)	Called by xFunc to return a value.
protected void	result(long value)	Called by xFunc to return a value.
protected void	result(String value)	Called by xFunc to return a value.
protected byte[]	value_blob(int arg)	Called by xFunc to access the value of an argument.
protected double	value_double(int arg)	Called by xFunc to access the value of an argument.
protected int	value_int(int arg)	Called by xFunc to access the value of an argument.
protected long	value_long(int arg)	Called by xFunc to access the value of an argument.
protected String	value_text(int arg)	Called by xFunc to access the value of an argument.
protected int	value_type(int arg)	Called by xFunc to access the value of an argument.
protected abstract void	xFunc()	Called by SQLite as a custom function.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FLAG_DETERMINISTIC

public static final int FLAG_DETERMINISTIC

Flag to provide to create(Connection, String, Function, int) that marks this Function as deterministic, making is usable in Indexes on Expressions.

See Also:

Constant Field Values

Constructor Detail

Function

public Function()

Method Detail

create

public static void create(Connection conn,
                          String name,
                          Function f)
                   throws SQLException

Registers a given function with the connection.

Parameters:

conn - The connection.

name - The name of the function.

f - The function to register.

Throws:

SQLException

create

public static void create(Connection conn,
                          String name,
                          Function f,
                          int flags)
                   throws SQLException

Registers a given function with the connection.

Parameters:

conn - The connection.

name - The name of the function.

f - The function to register.

flags - Extra flags to pass, such as FLAG_DETERMINISTIC

Throws:

SQLException

create

public static void create(Connection conn,
                          String name,
                          Function f,
                          int nArgs,
                          int flags)
                   throws SQLException

Registers a given function with the connection.

Parameters:

conn - The connection.

name - The name of the function.

f - The function to register.

nArgs - The number of arguments that the function takes.

flags - Extra flags to pass, such as FLAG_DETERMINISTIC

Throws:

SQLException

destroy

public static void destroy(Connection conn,
                           String name,
                           int nArgs)
                    throws SQLException

Removes a named function from the given connection.

Parameters:

conn - The connection to remove the function from.

name - The name of the function.

nArgs - Ignored.

Throws:

SQLException

destroy

public static void destroy(Connection conn,
                           String name)
                    throws SQLException

Removes a named function from the given connection.

Parameters:

conn - The connection to remove the function from.

name - The name of the function.

Throws:

SQLException

xFunc

protected abstract void xFunc()
                       throws SQLException

Called by SQLite as a custom function. Should access arguments through value_*(int), return results with result(*) and throw errors with error(String).

Throws:

SQLException

args

protected final int args()
                  throws SQLException

Returns the number of arguments passed to the function. Can only be called from xFunc().

Throws:

SQLException

result

protected final void result(byte[] value)
                     throws SQLException

Called by xFunc to return a value.

Parameters:

value -

Throws:

SQLException

result

protected final void result(double value)
                     throws SQLException

Called by xFunc to return a value.

Parameters:

value -

Throws:

SQLException

result

protected final void result(int value)
                     throws SQLException

Called by xFunc to return a value.

Parameters:

value -

Throws:

SQLException

result

protected final void result(long value)
                     throws SQLException

Called by xFunc to return a value.

Parameters:

value -

Throws:

SQLException

result

protected final void result()
                     throws SQLException

Called by xFunc to return a value.

Throws:

SQLException

result

protected final void result(String value)
                     throws SQLException

Called by xFunc to return a value.

Parameters:

value -

Throws:

SQLException

error

protected final void error(String err)
                    throws SQLException

Called by xFunc to throw an error.

Parameters:

err -

Throws:

SQLException

value_text

protected final String value_text(int arg)
                           throws SQLException

Called by xFunc to access the value of an argument.

Parameters:

arg -

Throws:

SQLException

value_blob

protected final byte[] value_blob(int arg)
                           throws SQLException

Called by xFunc to access the value of an argument.

Parameters:

arg -

Throws:

SQLException

value_double

protected final double value_double(int arg)
                             throws SQLException

Called by xFunc to access the value of an argument.

Parameters:

arg -

Throws:

SQLException

value_int

protected final int value_int(int arg)
                       throws SQLException

Called by xFunc to access the value of an argument.

Parameters:

arg -

Throws:

SQLException

value_long

protected final long value_long(int arg)
                         throws SQLException

Called by xFunc to access the value of an argument.

Parameters:

arg -

Throws:

SQLException

value_type

protected final int value_type(int arg)
                        throws SQLException

Called by xFunc to access the value of an argument.

Parameters:

arg -

Throws:

SQLException