Factory Methods That Produce Query Objects

The newQuery methods in the PersistenceManager interface are the factory methods that produce Query objects. Although the PersistenceManager interface is described in Chapter 3, this is the appropriate place to describe its newQuery methods.

 public Query newQuery(Class candidateClass) public Query newQuery(Extent candidates) public Query newQuery(Class candidateClass, Collection candidates) public Query newQuery(Class candidateClass, String filter) public Query newQuery(Extent candidates, String filter) public Query newQuery(Class candidateClass, Collection candidates, String filter) 

When the query executes, it must know or be able to determine three things: its query filter, its candidates, and its candidate class. Each of these factory methods is a convenience method that produces a query ready to use, as long as the filter does not use parameters or variables. If the filter is not defined when the query executes, the filter evaluates to true for every candidate instance. If the candidate class is not defined when the query executes, but an extent provides the candidates, then the query's candidate class defaults to the extent's candidate class. Likewise, if the candidates are not defined when the query executes, but the candidate class is defined, then the candidates default to the extent that is associated with the candidate class.

After obtaining a Query object, the application can perform any additional configuration required by using the operations and properties of the Query interface.

 public Query newQuery() 

This factory method produces a Query object that needs configuration before it can be used. You may find that your code is more self-documenting when you use this method and the Query configuration methods than when you use the convenience factory methods.

 public Query newQuery(Object query) 

This method returns a new Query object associated with the persistence manager. Its primary use is to create viable Query objects from deserialized Query objects. The returned Query object does not have its candidates set, and it is not compiled. Otherwise, it has the same settings as the Query object supplied to the method. The deserialized Query object and the persistence manager must come from the same JDO implementation.

 public Query newQuery(String altQueryLanguage, Object altQueryObject) 

JDO implementations must support JDO's Query Language, but they may also support another query language. With this method, the application can construct a Query object that uses a vendor-supported query language and a vendor-defined object.