oracle.toplink.queryframework
Class QueryByExamplePolicy

java.lang.Object
  oracle.toplink.queryframework.QueryByExamplePolicy

All Implemented Interfaces:

java.io.Serializable

public class QueryByExamplePolicy
extends java.lang.Object
implements java.io.Serializable

Purpose: This policy defines the configuration options for a Query By Example query.

Description: A Query By Example query is an ObjectLevelReadQuery where the selection criteria is built from an example domain object passed in via setExampleObject.

If no policy is specified the selection criteria is built from the example object in the following way:

• Attributes of the example object set to null are ignored.
• Attributes set to the default value for their primitive type (such as 0 for int) are ignored.
• Unmapped attributes are ignored.
• A domain object is returned by the query only if its values for all the included attributes equal those set in the example object.

A policy can be set on the query to:

• Always consider an attribute even if set to null or the default value for its type. See alwaysIncludeAttribute.
• Ignore attributes set to some other special value. See excludeValue.
• Match a null attribute on the example object with domain objects that have either null for that attribute also, or have set a meaningfull (notNull) value for that attribute. See setShouldUseEqualityForNulls(boolean).
• Use specialized operations when comparing attributes set in the example object with those set in the domain objects. Matching attributes can be those with values greater than, less than, like, or not equal to that set in the example object. See addSpecialOperation(java.lang.Class, java.lang.String).

Note: When setting an attribute on the example object which is itself a java object with an ObjectReferenceMapping, the mapped components of that attribute will be considered, not the entire object. There is no limit to how many mapped objects can be nested inside the example object.

Note: setExampleObject is different from setSelectionObject in ReadObjectQuery which reads a single object by first extracting the primary key from the selection object.

Restrictions:

• Only attributes whose mappings are DirectToField or ObjectReference (OneToOne) are considered in a Query By Example.

Example:

 // This example uses like for Strings and the salary must be greater
 // than zero.
 ReadAllQuery query = new ReadAllQuery();
 Employee employee = new Employee();
 employee.setFirstName("B%");
 employee.setLastName("S%");
 employee.setSalary(0);
 query.setExampleObject(employee);
 QueryByExamplePolicy policy = new QueryByExamplePolicy();
 policy.addSpecialOperation(String.class, "like");
 policy.addSpecialOperation(Integer.class, "greaterThan");
 policy.alwaysIncludeAttribute(Employee.class, "salary");
 query.setQueryByExamplePolicy(policy);
 Vector results = (Vector) session.executeQuery(query);
 

Since:

TOPLink/Java 3.0

See Also:

ObjectLevelReadQuery.setExampleObject(java.lang.Object), ObjectLevelReadQuery.setQueryByExamplePolicy(oracle.toplink.queryframework.QueryByExamplePolicy), Serialized Form

Field Summary

java.util.Map	attributesToAlwaysInclude
boolean	shouldUseEqualityForNulls
java.util.Map	specialOperations
java.util.Map	valuesToExclude

Constructor Summary

QueryByExamplePolicy()
Constructs a default policy equal to that used when no policy is specified.

Method Summary

void	addSpecialOperation(java.lang.Class attributeValueClass, java.lang.String operation) Allows operations other than Expression.equal to be used for comparisons.
void	alwaysIncludeAttribute(java.lang.Class exampleClass, java.lang.String attributeName) Always considers the value for a particular attribute as meaningfull in a query by example.
void	excludeDefaultPrimitiveValues() Ignores attributes set to the default value for their primitive type.
void	excludeValue(boolean value) An attribute in the example object set to an excluded value will be ignored in a Query By Example.
void	excludeValue(byte value) An attribute in the example object set to an excluded value will be ignored in a Query By Example.
void	excludeValue(char value) An attribute in the example object set to an excluded value will be ignored in a Query By Example.
void	excludeValue(double value) An attribute in the example object set to an excluded value will be ignored in a Query By Example.
void	excludeValue(float value) An attribute in the example object set to an excluded value will be ignored in a Query By Example.
void	excludeValue(int value) An attribute in the example object set to be an excluded value will be ignored in a Query By Example.
void	excludeValue(long value) An attribute in the example object set to an excluded value will be ignored in a Query By Example.
void	excludeValue(java.lang.Object value) An attribute in the example object set to an excluded value will be ignored in a Query By Example.
void	excludeValue(short value) An attribute in the example object set to an excluded value will be ignored in a Query By Example.
java.util.Map	getAttributesToAlwaysInclude() Attributes to always consider even if set to null or an excluded value like 0 or false.
java.util.Map	getSpecialOperations() The special operations to use in place of equal.
java.util.Map	getValuesToExclude() Decides which attributes to ignore based on the values they are set to.
void	includeAllValues() Considers all mapped attributes in the example object as meaningfull in a Query By Example.
void	removeFromValuesToExclude(java.lang.Object value) Considers all attributes set to a previously excluded value on the example object.
void	setShouldUseEqualityForNulls(boolean shouldUseEqualityForNulls) Matches an included null attribute in the example object either to objects with that attribute also set to null or to any value other than null.
void	setSpecialOperations(java.util.Map newOperations) The special operations to use in place of equal.
void	setValuesToExclude(java.util.Map newValuesToExclude) Decides which attributes to ignore based on the values they are set to.
boolean	shouldUseEqualityForNulls() Matches an included null attribute in the example object either to objects with that attribute also set to null or to any value other than null.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

valuesToExclude

public java.util.Map valuesToExclude

attributesToAlwaysInclude

public java.util.Map attributesToAlwaysInclude

specialOperations

public java.util.Map specialOperations

shouldUseEqualityForNulls

public boolean shouldUseEqualityForNulls

Constructor Detail

QueryByExamplePolicy

public QueryByExamplePolicy()

Constructs a default policy equal to that used when no policy is specified.

Sets the default values to be excluded, (that includes 0, false, empty String, etc).

By default if an attribute is null, and yet has to be included at all times, equality (isNull) is used for the comparison. This is used for searching for an object with a null in a certain field.

See Also:

excludeDefaultPrimitiveValues(), setShouldUseEqualityForNulls(true)

Method Detail

addSpecialOperation

public void addSpecialOperation(java.lang.Class attributeValueClass,
                                java.lang.String operation)

Allows operations other than Expression.equal to be used for comparisons.

For example if an attribute of type int is set to x in the example object, normally the query will be on all objects whose attributes are also equal to x. The query could however be all objects whose attributes are not x, greater than x, or even less than or equal to x.

Any comparison operation in Expression which takes the example attribute as a parameter can be used. A list of supported operations is provided below.

Note: A special operation can not be used for attributes set to null. The only options are isNull (default) and notNull. See setShouldUseEqualityForNulls(boolean).

Parameters:

attributeValueClass - Attribute values of which type, for instance Integer, to apply to. Note for int attributes the class is Integer.class not int.class. This is not the Class of the example object the attribute is an instance variable of.

operation - Name of method in Expression used

See Also:

equal (default), notEqual, equalsIgnoreCase, lessThan, lessThanEqual, greaterThan, greaterThanEqual, like, likeIgnoreCase, containsAllKeyWords, containsAnyKeyWords, containsSubstring, containsSubstringIgnoringCase

alwaysIncludeAttribute

public void alwaysIncludeAttribute(java.lang.Class exampleClass,
                                   java.lang.String attributeName)

Always considers the value for a particular attribute as meaningfull in a query by example.

Required to override the normal behavior which is to ignore an attribute of the example object if set to null, or an excluded value like 0.

Example: To find all projects without a budget set budget to 0 in the example object and call alwaysIncludeAttribute(Project.class, "budget") on the policy.

Parameters:

exampleClass - The class that the attribute belongs to, normally this is the example class unless using nested QBE.

attributeName - The name of a mapped attribute.

excludeDefaultPrimitiveValues

public void excludeDefaultPrimitiveValues()

Ignores attributes set to the default value for their primitive type.

For instance 0 is used as null for deciding which int attributes of the example object can be ignored in a query by example.

Called by the constructor.

excludeValue

public void excludeValue(byte value)

An attribute in the example object set to an excluded value will be ignored in a Query By Example.

The default excluded value for byte is 0.

excludeValue

public void excludeValue(char value)

An attribute in the example object set to an excluded value will be ignored in a Query By Example.

The default excluded value for char is '