/* * Copyright (c) 2007 David Crawshaw * * Permission to use, copy, modify, and/or distribute this software for any * purpose with or without fee is hereby granted, provided that the above * copyright notice and this permission notice appear in all copies. * * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ package org.sqlite; import java.sql.*; /** 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.

* * Eg. * * 
 *      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.

* *

Aggregate functions are not yet supported, but coming soon.

* */ public abstract class Function { private Conn conn; private DB db; long context = 0; // pointer sqlite3_context* long value = 0; // pointer sqlite3_value** int args = 0; /** Registers the given function with the Connection using the * provided name. */ public static final void create(Connection conn, String name, Function f) throws SQLException { if (conn == null || !(conn instanceof Conn)) throw new SQLException("connection must be to an SQLite db"); if (conn.isClosed()) throw new SQLException("connection closed"); f.conn = (Conn)conn; f.db = f.conn.db(); if (name == null || name.length() > 255) throw new SQLException("invalid function name: '"+name+"'"); if (f.db.create_function(name, f) != Codes.SQLITE_OK) throw new SQLException("error creating function"); } /** Removes the named function form the Connection. */ public static final void destroy(Connection conn, String name) throws SQLException { if (conn == null || !(conn instanceof Conn)) throw new SQLException("connection must be to an SQLite db"); ((Conn)conn).db().destroy_function(name); } /** Called by SQLite as a custom function. Should access arguments * through value_*(int), return results with * result(*) and throw errors with error(String). */ protected abstract void xFunc() throws SQLException; /** Returns the number of arguments passed to the function. * Can only be called from xFunc(). */ protected synchronized final int args() throws SQLException { checkContext(); return args; } /** Called by xFunc to return a value. */ protected synchronized final void result(byte[] value) throws SQLException { checkContext(); db.result_blob(context, value); } /** Called by xFunc to return a value. */ protected synchronized final void result(double value) throws SQLException { checkContext(); db.result_double(context,value);} /** Called by xFunc to return a value. */ protected synchronized final void result(int value) throws SQLException { checkContext(); db.result_int(context, value); } /** Called by xFunc to return a value. */ protected synchronized final void result(long value) throws SQLException { checkContext(); db.result_long(context, value); } /** Called by xFunc to return a value. */ protected synchronized final void result() throws SQLException { checkContext(); db.result_null(context); } /** Called by xFunc to return a value. */ protected synchronized final void result(String value) throws SQLException { checkContext(); db.result_text(context, value); } /** Called by xFunc to throw an error. */ protected synchronized final void error(String err) throws SQLException { checkContext(); db.result_error(context, err); } /** Called by xFunc to access the value of an argument. */ protected synchronized final int value_bytes(int arg) throws SQLException {checkValue(arg); return db.value_bytes(this,arg);} /** Called by xFunc to access the value of an argument. */ protected synchronized final String value_text(int arg) throws SQLException {checkValue(arg); return db.value_text(this,arg);} /** Called by xFunc to access the value of an argument. */ protected synchronized final byte[] value_blob(int arg) throws SQLException {checkValue(arg); return db.value_blob(this,arg); } /** Called by xFunc to access the value of an argument. */ protected synchronized final double value_double(int arg) throws SQLException {checkValue(arg); return db.value_double(this,arg);} /** Called by xFunc to access the value of an argument. */ protected synchronized final int value_int(int arg) throws SQLException {checkValue(arg); return db.value_int(this, arg); } /** Called by xFunc to access the value of an argument. */ protected synchronized final long value_long(int arg) throws SQLException { checkValue(arg); return db.value_long(this,arg); } /** Called by xFunc to access the value of an argument. */ protected synchronized final int value_type(int arg) throws SQLException {checkValue(arg); return db.value_type(this,arg); } private void checkContext() throws SQLException { if (conn == null || conn.db() == null || context == 0) throw new SQLException("no context, not allowed to read value"); } private void checkValue(int arg) throws SQLException { if (conn == null || conn.db() == null || value == 0) throw new SQLException("not in value access state"); if (arg >= args) throw new SQLException("arg "+arg+" out bounds [0,"+args+")"); } public static abstract class Aggregate extends Function implements Cloneable { protected final void xFunc() {} protected abstract void xStep() throws SQLException; protected abstract void xFinal() throws SQLException; public Object clone() throws CloneNotSupportedException { return super.clone(); } } }