Class QueryByExamplePolicy
- All Implemented Interfaces:
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
forint
) 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. SeealwaysIncludeAttribute
. - Ignore attributes set to some other special value. See
excludeValue
. - Match a
null
attribute on the example object with domain objects that have eithernull
for that attribute also, or have set a meaningful (notNull
) value for that attribute. SeesetShouldUseEqualityForNulls(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, Aggregate (Embeddable), ObjectReference
(OneToOne) or Collection type OneToMany/ManyToMany are considered in a Query By Example object. The behaviour when an example object has attribute values for other mappings types is undefined.
- To ensure the example does not include any unsupported mappings the flag
setValidateExample(boolean)
should be set to true on the corresponding QueryByExamplePolicy to ensure no unsupported relationship types are used in the example. - For OneToMany and ManyToMany mappings the elements within the collections and the references attribute values will be added to the expression as disjuncts (OR)
- To ensure the example does not include any unsupported mappings the flag
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:
-
Field Summary
Modifier and TypeFieldDescriptionboolean
protected boolean
-
Constructor Summary
ConstructorDescriptionPUBLIC: Constructs a default policy equal to that used when no policy is specified. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addSpecialOperation
(Class<?> attributeValueClass, String operation) PUBLIC: Allows operations other thanExpression.equal
to be used for comparisons.void
alwaysIncludeAttribute
(Class<?> exampleClass, String attributeName) PUBLIC: Always considers the value for a particular attribute as meaningful in a query by example.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).completeExpressionForNull
(Expression expression) INTERNAL: This method is used when the attribute value is null, but it has to be included at all times.void
PUBLIC: Ignores attributes set to the default value for their primitive type.void
excludeValue
(boolean value) PUBLIC: An attribute in the example object set to an excluded value will be ignored in a Query By Example.void
excludeValue
(byte value) PUBLIC: An attribute in the example object set to an excluded value will be ignored in a Query By Example.void
excludeValue
(char value) PUBLIC: An attribute in the example object set to an excluded value will be ignored in a Query By Example.void
excludeValue
(double value) PUBLIC: An attribute in the example object set to an excluded value will be ignored in a Query By Example.void
excludeValue
(float value) PUBLIC: An attribute in the example object set to an excluded value will be ignored in a Query By Example.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.void
excludeValue
(long value) PUBLIC: An attribute in the example object set to an excluded value will be ignored in a Query By Example.void
excludeValue
(short value) PUBLIC: An attribute in the example object set to an excluded value will be ignored in a Query By Example.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: Attributes to always consider even if set tonull
or an excluded value like0
orfalse
.getOperation
(Class<?> aClass) INTERNAL: determines which operation to use for comparison.PUBLIC: The special operations to use in place ofequal
.PUBLIC: Decides which attributes to ignore based on the values they are set to.void
PUBLIC: Considers all mapped attributes in the example object as meaningful in a Query By Example.boolean
isAlwaysIncluded
(Class<?> theClass, String attributeName) INTERNAL: returns whether the attributeName is to be always included.boolean
isExcludedValue
(Object value) INTERNAL: returns if the value is in the values to be excluded automatically.void
removeFromValuesToExclude
(Object value) PUBLIC: Considers all attributes set to a previously excluded value on the example object.void
setAttributesToAlwaysInclude
(Map 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).void
setShouldUseEqualityForNulls
(boolean shouldUseEqualityForNulls) PUBLIC: Matches an includednull
attribute in the example object either to objects with that attribute also set tonull
or to any value other thannull
.void
setSpecialOperations
(Map newOperations) PUBLIC: The special operations to use in place ofequal
.void
setValidateExample
(boolean validate) PUBLIC: When set totrue
the example object will be validated for unsupported mapping types.void
setValuesToExclude
(Map newValuesToExclude) PUBLIC: Decides which attributes to ignore based on the values they are set to.boolean
shouldIncludeInQuery
(Class<?> aClass, String attributeName, Object attributeValue) INTERNAL: This method determines whether an attribute pair is be included in the query.boolean
PUBLIC: Matches an includednull
attribute in the example object either to objects with that attribute also set tonull
or to any value other thannull
.boolean
PUBLIC: Returns true if the example object used with this policy should be validated for attributes with unsupported mappings.
-
Field Details
-
valuesToExclude
-
attributesToAlwaysInclude
-
specialOperations
-
shouldUseEqualityForNulls
public boolean shouldUseEqualityForNulls -
validateExample
protected boolean validateExample
-
-
Constructor Details
-
QueryByExamplePolicy
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 anull
in a certain field.- See Also:
-
-
Method Details
-
addSpecialOperation
PUBLIC: Allows operations other thanExpression.equal
to be used for comparisons.For example if an attribute of type
int
is set tox
in the example object, normally the query will be on all objects whose attributes are also equal tox
. The query could however be all objects whose attributes are notx
, greater thanx
, or even less than or equal tox
.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 areisNull
(default) andnotNull
. SeesetShouldUseEqualityForNulls(boolean)
.- Parameters:
attributeValueClass
- Attribute values of which type, for instanceInteger
, to apply to. Note forint
attributes the class isInteger.class
notint.class
. This is not theClass
of the example object the attribute is an instance variable of.operation
- Name of method inExpression
used- See Also:
-
alwaysIncludeAttribute
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 like0
.Example: To find all projects without a budget set
budget
to 0 in the example object and callalwaysIncludeAttribute(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.
-
completeExpression
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). -
completeExpressionForNull
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. -
excludeDefaultPrimitiveValues
public void excludeDefaultPrimitiveValues()PUBLIC: Ignores attributes set to the default value for their primitive type.For instance
0
is used asnull
for deciding whichint
attributes of the example object can be ignored in a query by example.Called by the constructor.
-
excludeValue
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
is0
. -
excludeValue
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' '
. -
excludeValue
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
is0.0
. -
excludeValue
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
is0.0f
. -
excludeValue
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
is0
. -
excludeValue
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
is0
. -
excludeValue
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. -
excludeValue
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
is0
. -
excludeValue
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
isfalse
. -
getAttributesToAlwaysInclude
PUBLIC: Attributes to always consider even if set tonull
or an excluded value like0
orfalse
.- See Also:
-
getOperation
INTERNAL: determines which operation to use for comparison. -
getSpecialOperations
PUBLIC: The special operations to use in place ofequal
.- Returns:
- A hashtable where the keys are
Class
objects and the values are the names of operations to use for attributes of thatClass
. - See Also:
-
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:
- valuesToExclude The keys and values are values to exclude (key == value). Primitives are
wrapped, so
int 0
will be stored asInteger(0)
. - See Also:
-
includeAllValues
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()
. -
isAlwaysIncluded
INTERNAL: returns whether the attributeName is to be always included. -
isExcludedValue
INTERNAL: returns if the value is in the values to be excluded automatically. -
removeFromValuesToExclude
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
- No attributes set tovalue
will be excluded from a Query By Example.value.getClass()
is a key of the Hashtable returned bygetValuesToExclude()
.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:
-
setAttributesToAlwaysInclude
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). -
setShouldUseEqualityForNulls
public void setShouldUseEqualityForNulls(boolean shouldUseEqualityForNulls) PUBLIC: Matches an includednull
attribute in the example object either to objects with that attribute also set tonull
or to any value other thannull
.Set to
false
to only select objects where certain attributes have been set.Example: to find all Employees with an assigned
address
, set attributeaddress
tonull
in the example object, callalwaysIncludeAttribute(Employee.class, "address")
and then callsetShouldUseEqualityForNulls(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
- If true (by default) usesisNull
elsenotNull
.- See Also:
-
setSpecialOperations
PUBLIC: The special operations to use in place ofequal
.- Parameters:
newOperations
- A hashtable where the keys areClass
objects and the values are the names of operations to use for attributes of thatClass
.- See Also:
-
setValidateExample
public void setValidateExample(boolean validate) PUBLIC: When set totrue
the example object will be validated for unsupported mapping types. If you wish these mapping types to be ignored either set this flag tofalse
or add the attribute to the list of ignored attributes in this policy -
setValuesToExclude
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
- The keys and values are values to exclude (key == value). Primitives are wrapped, soint 0
will be stored asInteger(0)
.- See Also:
-
shouldIncludeInQuery
INTERNAL: This method determines whether an attribute pair is be included in the query. -
shouldUseEqualityForNulls
public boolean shouldUseEqualityForNulls()PUBLIC: Matches an includednull
attribute in the example object either to objects with that attribute also set tonull
or to any value other thannull
.Set to
false
to only select objects where certain attributes have been set.Example: to find all Employees with an assigned
address
, set attributeaddress
tonull
in the example object, callalwaysIncludeAttribute(Employee.class, "address")
and then callsetShouldUseEqualityForNulls(false)
.- Returns:
- If true (by default) uses
isNull
elsenotNull
. - See Also:
-
shouldValidateExample
public boolean shouldValidateExample()PUBLIC: Returns true if the example object used with this policy should be validated for attributes with unsupported mappings.
-