|
EclipseLink 2.0.0, build 'v20091127-r5931' API Reference | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.eclipse.persistence.queries.QueryByExamplePolicy
public class QueryByExamplePolicy
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:
null
are ignored.
0
for int
) are ignored.
A policy can be set on the query to:
null
or the default value for its type. See alwaysIncludeAttribute
.
excludeValue
.
null
attribute on the example object with domain objects that have
either null
for that attribute also, or have set a meaningful (notNull
) value
for that attribute. See setShouldUseEqualityForNulls(boolean)
.
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:
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);
ObjectLevelReadQuery.setExampleObject(java.lang.Object)
,
ObjectLevelReadQuery.setQueryByExamplePolicy(org.eclipse.persistence.queries.QueryByExamplePolicy)
,
Serialized FormField Summary | |
---|---|
java.util.Map |
attributesToAlwaysInclude
|
boolean |
shouldUseEqualityForNulls
|
java.util.Map |
specialOperations
|
java.util.Map |
valuesToExclude
|
Constructor Summary | |
---|---|
QueryByExamplePolicy()
PUBLIC: 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)
PUBLIC: Allows operations other than Expression.equal to be used
for comparisons. |
void |
alwaysIncludeAttribute(java.lang.Class exampleClass,
java.lang.String attributeName)
PUBLIC: Always considers the value for a particular attribute as meaningful in a query by example. |
Expression |
completeExpression(Expression expression,
java.lang.Object attributeValue,
java.lang.Class attributeValueClass)
INTERNAL: This method is used to determine which operation to use for comparison (equal, or a special operation). |
Expression |
completeExpressionForNull(Expression expression)
INTERNAL: This method is used when the attribute value is null, but it has to be included at all times. |
void |
excludeDefaultPrimitiveValues()
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(java.lang.Object 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. |
java.util.Map |
getAttributesToAlwaysInclude()
PUBLIC: Attributes to always consider even if set to null or an excluded
value like 0 or false . |
java.lang.String |
getOperation(java.lang.Class aClass)
INTERNAL: determines which operation to use for comparison. |
java.util.Map |
getSpecialOperations()
PUBLIC: The special operations to use in place of equal . |
java.util.Map |
getValuesToExclude()
PUBLIC: Decides which attributes to ignore based on the values they are set to. |
void |
includeAllValues()
PUBLIC: Considers all mapped attributes in the example object as meaningful in a Query By Example. |
boolean |
isAlwaysIncluded(java.lang.Class theClass,
java.lang.String attributeName)
INTERNAL: returns whether the attributeName is to be always included. |
boolean |
isExcludedValue(java.lang.Object value)
INTERNAL: returns if the value is in the values to be excluded automatically. |
void |
removeFromValuesToExclude(java.lang.Object value)
PUBLIC: Considers all attributes set to a previously excluded value on the example object. |
void |
setAttributesToAlwaysInclude(java.util.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 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)
PUBLIC: The special operations to use in place of equal . |
void |
setValuesToExclude(java.util.Map newValuesToExclude)
PUBLIC: Decides which attributes to ignore based on the values they are set to. |
boolean |
shouldIncludeInQuery(java.lang.Class aClass,
java.lang.String attributeName,
java.lang.Object attributeValue)
INTERNAL: This method determines whether an attribute pair is be included in the query. |
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 . |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public java.util.Map valuesToExclude
public java.util.Map attributesToAlwaysInclude
public java.util.Map specialOperations
public boolean shouldUseEqualityForNulls
Constructor Detail |
---|
public QueryByExamplePolicy()
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.
excludeDefaultPrimitiveValues()
,
setShouldUseEqualityForNulls(true)
Method Detail |
---|
public void addSpecialOperation(java.lang.Class attributeValueClass, java.lang.String operation)
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)
.
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
usedequal (default)
,
notEqual
,
equalsIgnoreCase
,
lessThan
,
lessThanEqual
,
greaterThan
,
greaterThanEqual
,
like
,
likeIgnoreCase
,
containsAllKeyWords
,
containsAnyKeyWords
,
containsSubstring
,
containsSubstringIgnoringCase
public void alwaysIncludeAttribute(java.lang.Class exampleClass, java.lang.String attributeName)
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.
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.public Expression completeExpression(Expression expression, java.lang.Object attributeValue, java.lang.Class attributeValueClass)
public Expression completeExpressionForNull(Expression expression)
public void excludeDefaultPrimitiveValues()
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.
public void excludeValue(byte value)
The default excluded value for byte
is 0
.
public void excludeValue(char value)
The default excluded value for char
is ' '
.
public void excludeValue(double value)
The default excluded value for double
is 0.0
.
public void excludeValue(float value)
The default excluded value for float
is 0.0f
.
public void excludeValue(int value)
The default excluded value for int
is 0
.
public void excludeValue(long value)
The default excluded value for long
is 0
.
public void excludeValue(java.lang.Object value)
The default excluded value for String
is ""
.
Note: null
is special and always considered an excluded value.
public void excludeValue(short value)
The default excluded value for short
is 0
.
public void excludeValue(boolean value)
The default excluded value for boolean
is false
.
public java.util.Map getAttributesToAlwaysInclude()
null
or an excluded
value like 0
or false
.
alwaysIncludeAttribute(java.lang.Class, java.lang.String)
public java.lang.String getOperation(java.lang.Class aClass)
public java.util.Map getSpecialOperations()
equal
.
Class
objects and the values
are the names of operations to use for attributes of that Class
.addSpecialOperation(java.lang.Class, java.lang.String)
public java.util.Map getValuesToExclude()
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
.
int 0
will be stored as Integer(0)
.excludeValue(byte)
,
excludeDefaultPrimitiveValues()
,
includeAllValues()
public void includeAllValues()
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()
.
public boolean isAlwaysIncluded(java.lang.Class theClass, java.lang.String attributeName)
public boolean isExcludedValue(java.lang.Object value)
public void removeFromValuesToExclude(java.lang.Object value)
Primitive values to be removed must first be wrapped inside an Object.
value
- 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.
excludeDefaultPrimitiveValues()
,
includeAllValues()
,
excludeValue(Object)
public void setAttributesToAlwaysInclude(java.util.Map newAttributesToAlwaysInclude)
public void setShouldUseEqualityForNulls(boolean shouldUseEqualityForNulls)
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.
shouldUseEqualityForNulls
- If true (by default) uses isNull
else notNull
.addSpecialOperation
,
alwaysIncludeAttribute
public void setSpecialOperations(java.util.Map newOperations)
equal
.
newOperations
- A hashtable where the keys are Class
objects and the values
are the names of operations to use for attributes of that Class
.addSpecialOperation(java.lang.Class, java.lang.String)
public void setValuesToExclude(java.util.Map newValuesToExclude)
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
.
newValuesToExclude
- The keys and values are values to exclude (key == value). Primitives are
wrapped, so int 0
will be stored as Integer(0)
.excludeValue(byte)
,
excludeDefaultPrimitiveValues()
,
includeAllValues()
public boolean shouldIncludeInQuery(java.lang.Class aClass, java.lang.String attributeName, java.lang.Object attributeValue)
public boolean shouldUseEqualityForNulls()
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)
.
isNull
else notNull
.addSpecialOperation
,
alwaysIncludeAttribute
|
EclipseLink 2.0.0, build 'v20091127-r5931' API Reference | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |