13.5. MethodQL

If JDOQL and direct SQL execution do not match your needs, Kodo JDO Enterprise Edition also allows you to name a Java method to use to load a set of objects. Kodo uses JDO's built-in alternate query language capabilities to create method-based queries. In a MethodQL query, the filter string names a static method to invoke to determine the matching objects:

// the method query language is 'kodo.MethodQL'
Query q = pm.newQuery ("kodo.MethodQL", null);

// set the type of objects that the method returns
q.setClass (Person.class);

// set the filter to the method to execute, including full class name; if
// the class is in the candidate class' package or in the query imports, you
// can omit the package; if the method is in the candidate class, you can omit
// the class name and just specify the method name
q.setFilter ("com.xyz.Finder.getByName");

// parameters are declared and passed the same way as in standard queries
q.declareParameters ("String firstName, String lastName");

// this executes your method to get the results
Collection results = (Collection) q.execute ("Fred", "Lucas");

For datastore queries, the method must have the following signature:

public static ResultObjectProvider xxx(KodoPersistenceManager pm, 
    ClassMetaData meta, boolean subclasses, Map params, FetchConfiguration fetch)

The returned result object provider should produce objects of the candidate class that match the method's search criteria. If the returned objects do not have all fields in the given fetch configuration loaded, Kodo will make additional trips to the datastore as necessary to fill in the data for the missing fields.

In-memory execution is slightly different, taking in one object at a time and returning a boolean on whether the object matches the query:

public static boolean xxx(KodoPersistenceManager pm, ClassMetaData meta, 
    boolean subclasses, Object obj, Map params, FetchConfiguration fetch)

In both method versions, the given params map contains the names and values of all the parameters declared in the JDO query object and passed to the execute method.

The StoredProcQueries class and StoredProcMain driver program in the samples/ormapping directory of your Kodo distribution demonstrate how you might implement your own custom query method, and how to execute it through the JDO query interface.