Basic Topics Release Notes Installation Important Info Sample Applications Data Types	Advanced Topics Networking Tuning Transactions Readonly Mode Import & Export JDBC™ Triggers Encryption User-Defined Functions	Reference Topics Syntax Database Properties Javadoc Debugging Known Bugs
Documentation Home Page

User Defined Functions

How InstantDB Finds Functions
Writing Your Own Functions

InstantDB comes with a small number of built in functions. However users are not limited to the functions that we choose to provide. InstantDB allows you to add your own functions as well. These look and behave exactly like built in functions. In fact, the built in functions use exactly the same loading mechanism. If you want to change the built in functions, then you are perfectly free to do so. The idbf.jar is simply a compiled version of the functions directory.

The source code for the built in functions can be found in the functions sub-directory. All functions written by us will be made freely available as part of this software. We strongly encourage developers to make functions they have written available to others under the EPL open-source model. We will publish all of the functions that we receive. Send to: webmaster@enhydra.org

How InstantDB Finds Functions

Whenever InstantDB comes across a function in a SQL expression, it takes the function name, converts it to all lower case, and prepends the package name "org.enhydra.instantdb.db.". For example, in the case of: SELECT UPPER(col1) FROM mytable, InstantDB would look for a class with the name org.enhydra.instantdb.db.upper. It then creates an instance of this class and invokes the following methods:

1. int checkParameters (int[] parameterTypes)
   This is called when InstantDB has parsed the expressions being supplied as the function's parameters. It allows the function to determine the number and types of parameters it will receive and, if necessary, to throw an exception if the parameters types are unacceptable.
2. public void setSpecialValue (int type, Object value)
   Called when InstantDB wishes to pass database information, such as configuration parameters, to a function.
3. public Object getSpecialValue (int type)
   Called when InstantDB needs additional information from a function, such as how it would like its results to be formatted.
4. public Object evaluate(Object[] parameters)
   Called when InstantDB is actually evaluating a function. This is always called last.

You should not rely on the first three methods above being invoked in any particular order. The only thing guaranteed is the evaluate will be the last method to be invoked.

Writing Your Own Functions

All user defined functions must be in the package "org.enhydra.instantdb.db" and must implement the InstantDB interface org.enhydra.instantdb.db.SqlFunction. It is then simply a matter of placing your compiled function anywhere in your CLASSPATH or in the Java™ extensions directory (don't forget to put it in a "org.enhydra.instantdb.db" subdirectory though).

Feel free to use any of the existing functions as templates for your own. In addition to these, an example function is included in the examples directory. This shows you how to use all of the available InstantDB data types.

You can even add functions while InstantDB is still running, although you will not necessarily be able to release new version of existing functions without restarting the Java Virtual Machine™.