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:

KeyValue
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:

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.


Copyright 2001-2007 The TJDO Project All Rights Reserved.