SelectQuery objects can be rather complex. They may contain long qualifiers and lots of tuning parameters. Parameterized Queries feature addresses reusability of complex queries. With this feature, for each group of queries that differ only in the values used in the qualifier, a developer may create a single shared "prototype" or "template" query, and use it later as a factory for other queries. All settings configured in the prototype object will be passed to the final queries. Qualifier of the prototype query may use named parameters that are substituted for real values when a final query is created from the prototype.
|"Prototype" queries are normally created in CayenneModeler and stored in the DataMap XML file. "Queries Stored in DataMap" chapter describes how to use such templates. This chapter shows how to create them on the spot using the API calls.|
Building a prototype query using Expression.fromString(..):
Same example but using ExpressionFactory:
Prototype built in the example above can be used to create other queries. Relevalnt API is:
- public SelectQuery SelectQuery.queryWithParameters(Map parameters, boolean pruneMissing)
Creates and returns a new SelectQuery using current query as a prototype. Map of parameters is used to substitute named parameters in the qualifier with the real values. Returned query is a separate instance and can be further customized without affecting the prototype. If pruneMissing is true and some of the named parameters are missing from the parameters map, Cayenne would prune expressions that can not be resolved. If pruneMissing is set to false, the method would throw an exception unless all the named parameters can be resolved.
- public SelectQuery SelectQuery.queryWithParameters(Map parameters)
A shortcut for public SelectQuery queryWithParameters(Map parameters, true).
Example of using queryWithParameters is shown below: