com.triactive.jdo
Interface Query

All Superinterfaces:

javax.jdo.Query, java.io.Serializable

All Known Implementing Classes:

Query

public interface Query

extends javax.jdo.Query

An extension to the standard query interface including methods specific to TriActive JDO.

This interface includes a few of the new JDO 2.0 features, in advance of full support for 2.0.

Author:

Mike Martin

Method Summary

void	addExtension(java.lang.String key, java.lang.Object value) Adds a vendor-specific extension to this query.
void	setExtensions(java.util.Map extensions) Sets multiple extensions, or use null to clear all extensions.
void	setGrouping(java.lang.String grouping) Set the grouping expressions, optionally including a "having" clause.
void	setResult(java.lang.String result) Specifies what type of data this query should return.
void	setResultClass(java.lang.Class resultClass) Specifies the type of object in which to return each element of the result of invoking Query.execute() or one of its siblings.
void	setUnique(boolean unique) Specify that only the first result of the query should be returned, rather than a collection.

Methods inherited from interface javax.jdo.Query

close, closeAll, compile, declareImports, declareParameters, declareVariables, execute, execute, execute, execute, executeWithArray, executeWithMap, getIgnoreCache, getPersistenceManager, setCandidates, setCandidates, setClass, setFilter, setIgnoreCache, setOrdering

Method Detail

addExtension

public void addExtension(java.lang.String key,
                         java.lang.Object value)

Adds a vendor-specific extension to this query. The key and value are not standard. An implementation must ignore keys that are not recognized.

The keys recognized in TriActive JDO all begin with "com.triactive.jdo.". The following keys are currently recognized:

Key	Value
com.triactive.jdo.FetchSize	The JDBC fetch size to use for the query. The value must be a numeric object (a subclass of java.lang.Number) whose integer value is the number of rows that should be fetched at a time. Zero means the driver is free to make its own best guess. A null means use the PersistenceManager's default value.
com.triactive.jdo.ResultSetType	The JDBC result set type to use for the query. The value must be a numeric object (a subclass of java.lang.Number) whose integer value is one of the ResultSet.TYPE_ constants. A null means use the PersistenceManager's default value.

Parameters:

key - the key of the extension

value - the value of the extension

setExtensions

public void setExtensions(java.util.Map extensions)

Sets multiple extensions, or use null to clear all extensions. Map keys and values are not standard. An implementation must ignore entries that are not recognized.

The keys recognized in TriActive JDO all begin with "com.triactive.jdo.". The keys currently recognized are as documented for addExtension().

Parameters:

extensions - the map of extensions

See Also:

addExtension(java.lang.String, java.lang.Object)

setResult

public void setResult(java.lang.String result)

Specifies what type of data this query should return. If this is unset or set to null, this query returns instances of the query's candidate class. If set, this query will return expressions, including field values (projections) and aggregate function results.

Parameters:

result - a comma-delimited list of expressions (fields, functions on fields, or aggregate functions) to return from this query.

setResultClass

public void setResultClass(java.lang.Class resultClass)

Specifies the type of object in which to return each element of the result of invoking Query.execute() or one of its siblings. If the result is not set or set to null, the result class defaults to the candidate class of the query. If the result consists of one expression, the result class defaults to the type of that expression. If the result consists of more than one expression, the result class defaults to Object[]. The result class may be specified to be one of the java.lang classes Character, Boolean, Byte, Short, Integer, Long, Float, Double, String, or Object[]; or one of the java.math classes BigInteger or BigDecimal; or the java.util class Date; or one of the java.sql classes Date, Time, or Timestamp; or a user-defined class.

If there are multiple result expressions, the result class must be able to hold all elements of the result specification or a JDOUserException is thrown.

If there is only one result expression, the result class must be assignable from the type of the result expression or must be able to hold all elements of the result specification. A single value must be able to be coerced into the specified result class (treating wrapper classes as equivalent to their unwrapped primitive types) or by matching. If the result class does not satisfy these conditions, a JDOUserException is thrown.

A constructor of a result class specified in the setResult method will be used if the results specification matches the parameters of the constructor by position and type. If more than one constructor satisfies the requirements, the JDO implementation chooses one of them. If no constructor satisfies the results requirements, or if the result class is specified via the setResultClass method, the following requirements apply:

• A user-defined result class must have a no-args constructor and one or more public set or put methods or fields.
• Each result expression must match one of:
  • a public field that matches the name of the result expression and is of the type (treating wrapper types equivalent to primitive types) of the result expression;
  • or if no public field matches the name and type, a public set or if neither of the above applies, a public method must be found with the signature void put(Object, Object). During processing of the results, the first argument is the name of the result expression and the second argument is the value from the query result.

Portable result classes do not invoke any persistence behavior during their no-args constructor or set.

Parameters:

resultClass - the result class

setGrouping

public void setGrouping(java.lang.String grouping)

Set the grouping expressions, optionally including a "having" clause. When grouping is specified, each result expression must either be an expression contained in the grouping, or an aggregate evaluated once per group.

Parameters:

grouping - a comma-delimited list of expressions, optionally followed by the "having" keyword and a boolean expression.

setUnique

public void setUnique(boolean unique)

Specify that only the first result of the query should be returned, rather than a collection. The execute method will return null if the query result size is 0.

Parameters:

unique - if true, only one element is returned.