public FetchPlan getFetchPlan ();

Before compiling and/or executing your query, you may want to use the query's FetchPlan to optimize which fields and relations of your result objects will be loaded, and to configure result scrolling. See Chapter 12, FetchPlan for details on the FetchPlan interface.

When you create a query with PersistenceManager.newQuery or PersistenceManager.newNamedQuery, the query's FetchPlan is initialized to the same values as the plan of its owning PersistenceManager. Subsequent changes to the query's FetchPlan, however, will not affect the PersistenceManager's plan.

public void compile ();

Compiling is a hint to the implementation to optimize an execution plan for the query. During compilation, the query validates all of its elements and reports any inconsistencies by throwing a JDOUserException. Queries automatically compile themselves before they execute, so you probably won't use this method often.

public Object execute ();
public Object execute (Object param1);
public Object execute (Object param1, Object param2);
public Object execute (Object param1, Object param2, Object param3);
public Object executeWithArray (Object[] params);
public Object executeWithMap (Map params);

As evident from the examples throughout this chapter, queries are executed with one of the many execute methods defined in the Query interface. If your query uses between 0 and 3 parameters, you can use the execute version that takes the proper number of Object arguments. For queries with more than 3 parameters, you can use the generic executeWithArray and executeWithMap methods. In the latter method, the map is keyed on the parameter name.

All execute methods declare a return type of Object because the return type depends on how you've configured the query. So far we've only seen queries that return Lists, but this will change in the next section.

public void close (Object result);
public void closeAll ();

Some query results may hold on to datastore resources. Therefore, you should close query results when you no longer need them. You can close an individual query result with the close method, or all open results at once with closeAll.

Note

By default, Kodo greedily fills each result list and immediately releases all database resources, making close unnecessary. You can, however, configure Kodo to use lazy element instantiation where appropriate. Under lazy instantiation, list elements that are never accessed are never created, and elements may be released after being traversed. Combined with Kodo's memory-sensitive data structures and smart eager fetching policies, lazy element instantiation also allows you to efficiently iterate over huge data sets - even when the entire data set could not possibly fit into memory at once. These lazy results consume database resources, so if you enable them you are strongly encouraged to close all query results after processing. If they are not closed explicitly, they are closed automatically when the JVM garbage collects them. See Section 4.11, “Large Result Sets” in the Reference Guide for details on configuring Kodo for lazy result instantiation.