|
Oracle Fusion Middleware Java API Reference for Oracle TopLink 11g Release 1 (11.1.1) B32476-03 |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object oracle.toplink.queryframework.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 meaningfull (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(oracle.toplink.queryframework.QueryByExamplePolicy)
,
Serialized FormField 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 |
---|
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 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 '