DataNucleus - Plugins : RDBMS SQL Operations

DataNucleus is developed as a plugin-driven framework and one of the components that is pluggable is the support for JDOQL/JPQL operations in the "new" query mechanism. DataNucleus provides support for all major operations typically handling them internally but occasionally handing off to an SQL function where one is more appropriate. However the codebase is structured so that you could add on support for your own easily enough

The following sections describe how to create your own SQL Operation plugin for DataNucleus.

Interface

Any SQL operation plugin will need to implement org.datanucleus.store.rdbms.sql.operation.SQLOperation So you need to implement the following interface

import org.datanucleus.store.rdbms.sql.method;

public interface SQLOperation
{
    /**
     * Return the expression for this SQL function.
     * @param expr Left hand expression
     * @param expr2 Right hand expression
     * @return The SQL expression for the operation
     */
    public SQLExpression getExpression(SQLExpression expr, SQLExpression expr2);
}

Implementation

So there is only one method to provide in your implementation. The arguments to this are

The expression on the left hand side of the operation. So if you have {expr1} {operation} {expr2} then the first argument will be {expr1}
The expression on the right hand side of the operation. So if you have {expr1} {operation} {expr2} then the first argument will be {expr2}

So if we wanted to support modulus (%) (so something like expr1 % expr2 ) and wanted to use the SQL function "MOD" to provide this then we define our class as

package mydomain;

import java.util.ArrayList;

import org.datanucleus.exceptions.NucleusException;
import org.datanucleus.store.rdbms.sql.operation.SQLOperation;
import org.datanucleus.store.rdbms.sql.expression.SQLExpression;
import org.datanucleus.store.rdbms.sql.expression.NumericExpression;

public class MyModOperation implements SQLOperation
{
    public SQLExpression getExpression(SQLExpression expr, SQLExpression expr2)
    {
        ArrayList args = new ArrayList();
        args.add(expr);
        args.add(expr2);
        return new NumericExpression("MOD", args);
    }
}

So in this implementation when the user includes {expr1} % {expr2} this is translated into the SQL MOD({expr1}, {expr2}) which will certainly work on some RDBMS. Obviously you could use this extension mechanism to support a different underlying SQL function.

Plugin Specification

So we now have our custom SQL method and we just need to make this into a DataNucleus plugin. To do this you simply add a file plugin.xml to your JAR at the root. The file plugin.xml should look like this

<?xml version="1.0"?>
<plugin id="mydomain" name="DataNucleus plug-ins" provider-name="My Company">
    <extension point="org.datanucleus.store.rdbms.sql_operation">
        <sql-operation name="mod" datastore="hsql"
            evaluator="mydomain.MyModOperation"/>
    </extension>
</plugin>

Note that you also require a MANIFEST.MF file as per the Plugins Guide.

So we defined calls to an operation mod for the datastore "hsql" to use our evaluator. Simple! Whenever this operation is encountered in a query from then on for the HSQL database it will use our operation evaluator.