Top Description Fields Constructors Methods
org.eclipse.persistence.queries

public Class QueryByExamplePolicy

extends Object
implements Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable
Imports
java.security.AccessController, .PrivilegedActionException, java.util.HashMap, .Map, .Vector, org.eclipse.persistence.exceptions.QueryException, org.eclipse.persistence.expressions.Expression, org.eclipse.persistence.internal.helper.ClassConstants, .Helper, org.eclipse.persistence.internal.security.PrivilegedAccessHelper, .PrivilegedMethodInvoker

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:

A policy can be set on the query to:

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:

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, ObjectLevelReadQuery#setQueryByExamplePolicy

Field Summary

Modifier and TypeField and Description
public Map<K, V>
attributesToAlwaysInclude

public boolean
shouldUseEqualityForNulls

public Map<K, V>
specialOperations

protected boolean
validateExample

public Map<K, V>
valuesToExclude

Constructor Summary

AccessConstructor and Description
public
QueryByExamplePolicy()

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

Method Summary

Modifier and TypeMethod and Description
public void
addSpecialOperation(Class<?>
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.
attributeValueClass, String
Name of method in Expression used
operation)

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

public void
alwaysIncludeAttribute(Class<?>
The class that the attribute belongs to, normally this is the example class unless using nested QBE.
exampleClass, String
The name of a mapped attribute.
attributeName)

PUBLIC: Always considers the value for a particular attribute as meaningful in a query by example.

public Expression
completeExpression(Expression expression, Object attributeValue, Class<?> attributeValueClass)

INTERNAL: This method is used to determine which operation to use for comparison (equal, or a special operation).

public Expression
completeExpressionForNull(Expression expression)

INTERNAL: This method is used when the attribute value is null, but it has to be included at all times.

public void
excludeDefaultPrimitiveValues()

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

public void
excludeValue(byte value)

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

public void
excludeValue(char value)

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

public void
excludeValue(double value)

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

public void
excludeValue(float value)

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

public void
excludeValue(int value)

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

public void
excludeValue(long value)

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

public void
excludeValue(Object value)

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

public void
excludeValue(short value)

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

public void
excludeValue(boolean value)

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

public Map<K, V>
getAttributesToAlwaysInclude()

PUBLIC: Attributes to always consider even if set to null or an excluded value like 0 or false.

public String
getOperation(Class<?> aClass)

INTERNAL: determines which operation to use for comparison.

public Map<K, V>

Returns:

A hashtable where the keys are Class objects and the values are the names of operations to use for attributes of that Class.
getSpecialOperations()

PUBLIC: The special operations to use in place of equal.

public Map<K, V>

Returns:

valuesToExclude The keys and values are values to exclude (key == value). Primitives are wrapped, so int 0 will be stored as Integer(0).
getValuesToExclude()

PUBLIC: Decides which attributes to ignore based on the values they are set to.

public void
includeAllValues()

PUBLIC: Considers all mapped attributes in the example object as meaningful in a Query By Example.

public boolean
isAlwaysIncluded(Class<?> theClass, String attributeName)

INTERNAL: returns whether the attributeName is to be always included.

public boolean
isExcludedValue(Object value)

INTERNAL: returns if the value is in the values to be excluded automatically.

public void
removeFromValuesToExclude(Object
No attributes set to value will be excluded from a Query By Example. value.getClass() is a key of the Hashtable returned by getValuesToExclude.

Note

There is a distinction between an attribute and the value it is set to. An attribute can be included independently of its value with alwaysIncludeAttribute (recommended). It can also be included by making the value it is set to no longer excluded.

Note

null values are special and will always be excluded.

value)

PUBLIC: Considers all attributes set to a previously excluded value on the example object.

public void
setAttributesToAlwaysInclude(Map<K, V> newAttributesToAlwaysInclude)

INTERNAL: It is possible to generate a Hashtable (keys are the Class, and values the attribute names) of the attributes to be included at all times (even if the value is null, or the value belongs to the values to be excluced automatically).

public void
setShouldUseEqualityForNulls(boolean
If true (by default) uses isNull else notNull.
shouldUseEqualityForNulls)

PUBLIC: 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.

public void
setSpecialOperations(Map<K, V>
A hashtable where the keys are Class objects and the values are the names of operations to use for attributes of that Class.
newOperations)

PUBLIC: The special operations to use in place of equal.

public void
setValidateExample(boolean validate)

PUBLIC: When set to true the example object will be validated for unsupported mapping types.

public void
setValuesToExclude(Map<K, V>
The keys and values are values to exclude (key == value). Primitives are wrapped, so int 0 will be stored as Integer(0).
newValuesToExclude)

PUBLIC: Decides which attributes to ignore based on the values they are set to.

public boolean
shouldIncludeInQuery(Class<?> aClass, String attributeName, Object attributeValue)

INTERNAL: This method determines whether an attribute pair is be included in the query.

public boolean

Returns:

If true (by default) uses isNull else notNull.
shouldUseEqualityForNulls()

PUBLIC: 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.

public boolean
shouldValidateExample()

PUBLIC: Returns true if the example object used with this policy should be validated for attributes with unsupported mappings.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

attributesToAlwaysIncludeback to summary
public Map<K, V> attributesToAlwaysInclude
shouldUseEqualityForNullsback to summary
public boolean shouldUseEqualityForNulls
specialOperationsback to summary
public Map<K, V> specialOperations
validateExampleback to summary
protected boolean validateExample
valuesToExcludeback to summary
public Map<K, V> valuesToExclude

Constructor Detail

QueryByExamplePolicyback to summary
public QueryByExamplePolicy()

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

addSpecialOperationback to summary
public void addSpecialOperation(Class<?> attributeValueClass, String operation)

PUBLIC: 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.

Parameters
attributeValueClass:Class<?>

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

Name of method in Expression used

See Also
equal (default), notEqual, equalsIgnoreCase, lessThan, lessThanEqual, greaterThan, greaterThanEqual, like, likeIgnoreCase, containsAllKeyWords, containsAnyKeyWords, containsSubstring, containsSubstringIgnoringCase
alwaysIncludeAttributeback to summary
public void alwaysIncludeAttribute(Class<?> exampleClass, String attributeName)

PUBLIC: Always considers the value for a particular attribute as meaningful 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:Class<?>

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

attributeName:String

The name of a mapped attribute.

completeExpressionback to summary
public Expression completeExpression(Expression expression, Object attributeValue, Class<?> attributeValueClass)

INTERNAL: This method is used to determine which operation to use for comparison (equal, or a special operation).

completeExpressionForNullback to summary
public Expression completeExpressionForNull(Expression expression)

INTERNAL: This method is used when the attribute value is null, but it has to be included at all times. It determines whether to use isNull, or notNull.

excludeDefaultPrimitiveValuesback to summary
public void excludeDefaultPrimitiveValues()

PUBLIC: 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.

excludeValueback to summary
public void excludeValue(byte value)

PUBLIC: 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.

excludeValueback to summary
public void excludeValue(char value)

PUBLIC: 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 '\0'.

excludeValueback to summary
public void excludeValue(double value)

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

The default excluded value for double is 0.0.

excludeValueback to summary
public void excludeValue(float value)

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

The default excluded value for float is 0.0f.

excludeValueback to summary
public void excludeValue(int value)

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

The default excluded value for int is 0.

excludeValueback to summary
public void excludeValue(long value)

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

The default excluded value for long is 0.

excludeValueback to summary
public void excludeValue(Object value)

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

The default excluded value for String is "".

Note

null is special and always considered an excluded value.

excludeValueback to summary
public void excludeValue(short value)

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

The default excluded value for short is 0.

excludeValueback to summary
public void excludeValue(boolean value)

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

The default excluded value for boolean is false.

getAttributesToAlwaysIncludeback to summary
public Map<K, V> getAttributesToAlwaysInclude()

PUBLIC: Attributes to always consider even if set to null or an excluded value like 0 or false.

See Also
alwaysIncludeAttribute
getOperationback to summary
public String getOperation(Class<?> aClass)

INTERNAL: determines which operation to use for comparison.

getSpecialOperationsback to summary
public Map<K, V> getSpecialOperations()

PUBLIC: The special operations to use in place of equal.

Returns:Map<K, V>

A hashtable where the keys are Class objects and the values are the names of operations to use for attributes of that Class.

See Also
addSpecialOperation
getValuesToExcludeback to summary
public Map<K, V> getValuesToExclude()

PUBLIC: Decides which attributes to ignore based on the values they are set to.

If an attribute of the example domain object is set to one of these values it will be ignored, and not considered in the query.

Attributes set to excluded values are not always ignored. See alwaysIncludeAttribute.

Returns:Map<K, V>

valuesToExclude The keys and values are values to exclude (key == value). Primitives are wrapped, so int 0 will be stored as Integer(0).

See Also
excludeValue, excludeDefaultPrimitiveValues, includeAllValues
includeAllValuesback to summary
public void includeAllValues()

PUBLIC: Considers all mapped attributes in the example object as meaningful in a Query By Example.

Note

Even attributes of the example object that are not set, and therefore zero or empty by default, will be included.

Reverses a previous call to excludeDefaultPrimitiveValues.

isAlwaysIncludedback to summary
public boolean isAlwaysIncluded(Class<?> theClass, String attributeName)

INTERNAL: returns whether the attributeName is to be always included.

isExcludedValueback to summary
public boolean isExcludedValue(Object value)

INTERNAL: returns if the value is in the values to be excluded automatically.

removeFromValuesToExcludeback to summary
public void removeFromValuesToExclude(Object value)

PUBLIC: Considers all attributes set to a previously excluded value on the example object.

Primitive values to be removed must first be wrapped inside an Object.

Parameters
value:Object

No attributes set to value will be excluded from a Query By Example. value.getClass() is a key of the Hashtable returned by getValuesToExclude.

Note

There is a distinction between an attribute and the value it is set to. An attribute can be included independently of its value with alwaysIncludeAttribute (recommended). It can also be included by making the value it is set to no longer excluded.

Note

null values are special and will always be excluded.

See Also
excludeDefaultPrimitiveValues, includeAllValues, excludeValue(Object)
setAttributesToAlwaysIncludeback to summary
public void setAttributesToAlwaysInclude(Map<K, V> newAttributesToAlwaysInclude)

INTERNAL: It is possible to generate a Hashtable (keys are the Class, and values the attribute names) of the attributes to be included at all times (even if the value is null, or the value belongs to the values to be excluced automatically).

setShouldUseEqualityForNullsback to summary
public void setShouldUseEqualityForNulls(boolean shouldUseEqualityForNulls)

PUBLIC: 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.

Set to false to only select objects where certain attributes have been set.

Example: to find all Employees with an assigned address, set attribute address to null in the example object, call alwaysIncludeAttribute(Employee.class, "address") and then call setShouldUseEqualityForNulls(false).

Note

Unless an attribute set to null is specifically included, it will not be considered at all in the Query By Example.

Parameters
shouldUseEqualityForNulls:boolean

If true (by default) uses isNull else notNull.

See Also
addSpecialOperation, alwaysIncludeAttribute
setSpecialOperationsback to summary
public void setSpecialOperations(Map<K, V> newOperations)

PUBLIC: The special operations to use in place of equal.

Parameters
newOperations:Map<K, V>

A hashtable where the keys are Class objects and the values are the names of operations to use for attributes of that Class.

See Also
addSpecialOperation
setValidateExampleback to summary
public void setValidateExample(boolean validate)

PUBLIC: When set to true the example object will be validated for unsupported mapping types. If you wish these mapping types to be ignored either set this flag to false or add the attribute to the list of ignored attributes in this policy

setValuesToExcludeback to summary
public void setValuesToExclude(Map<K, V> newValuesToExclude)

PUBLIC: Decides which attributes to ignore based on the values they are set to.

An attribute of the example domain object set to one of these values will be ignored, and not considered in the query.

Attributes set to excluded values are not always ignored. See alwaysIncludeAttribute.

Parameters
newValuesToExclude:Map<K, V>

The keys and values are values to exclude (key == value). Primitives are wrapped, so int 0 will be stored as Integer(0).

See Also
excludeValue, excludeDefaultPrimitiveValues, includeAllValues
shouldIncludeInQueryback to summary
public boolean shouldIncludeInQuery(Class<?> aClass, String attributeName, Object attributeValue)

INTERNAL: This method determines whether an attribute pair is be included in the query.

shouldUseEqualityForNullsback to summary
public boolean shouldUseEqualityForNulls()

PUBLIC: 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.

Set to false to only select objects where certain attributes have been set.

Example: to find all Employees with an assigned address, set attribute address to null in the example object, call alwaysIncludeAttribute(Employee.class, "address") and then call setShouldUseEqualityForNulls(false).

Returns:boolean

If true (by default) uses isNull else notNull.

See Also
addSpecialOperation, alwaysIncludeAttribute
shouldValidateExampleback to summary
public boolean shouldValidateExample()

PUBLIC: Returns true if the example object used with this policy should be validated for attributes with unsupported mappings.