Overview | Package | Class | Tree | Deprecated | Index | Help
| Oracle TopLink API Reference 10g Release 3 (10.1.3) B13698-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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.Hashtable` | `attributesToAlwaysInclude`
`boolean` | `shouldUseEqualityForNulls`
`java.util.Hashtable` | `specialOperations`
`java.util.Hashtable` | `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 meaningfull in a query by example.
`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.Hashtable` | `getAttributesToAlwaysInclude()` PUBLIC: Attributes to always consider even if set to `null` or an excluded value like `0` or `false`.
`java.util.Hashtable` | `getSpecialOperations()` PUBLIC: The special operations to use in place of `equal`.
`java.util.Hashtable` | `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 meaningfull in a Query By Example.
`void` | `removeFromValuesToExclude(java.lang.Object value)` PUBLIC: Considers all attributes set to a previously excluded value on the example object.
`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.Hashtable newOperations)` PUBLIC: The special operations to use in place of `equal`.
`void` | `setValuesToExclude(java.util.Hashtable newValuesToExclude)` PUBLIC: Decides which attributes to ignore based on the values they are set to.
`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
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### valuesToExclude

    public java.util.Hashtable valuesToExclude

### attributesToAlwaysInclude

    public java.util.Hashtable attributesToAlwaysInclude

### specialOperations

    public java.util.Hashtable specialOperations

### shouldUseEqualityForNulls

    public boolean shouldUseEqualityForNulls

Constructor Detail

### 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 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)

  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(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)

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

  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.

### 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` is `0`.

### 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` is `0.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` is `0.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` is `0`.

### 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` is `0`.

### excludeValue

    public 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.

  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` is `0`.

### 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` is `false`.

### getAttributesToAlwaysInclude

    public java.util.Hashtable getAttributesToAlwaysInclude()

  PUBLIC: Attributes to always consider even if set to `null` or an excluded value like `0` or `false`.
  See Also:
    `alwaysIncludeAttribute(java.lang.Class, java.lang.String)`

### getSpecialOperations

    public java.util.Hashtable getSpecialOperations()

  PUBLIC: The special operations to use in place of `equal`.
  Returns:
    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(java.lang.Class, java.lang.String)`

### getValuesToExclude

    public java.util.Hashtable 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 as `Integer(0)`.
  See Also:
    `excludeValue(byte)`, `excludeDefaultPrimitiveValues()`, `includeAllValues()`

### includeAllValues

    public void includeAllValues()

  PUBLIC: Considers all mapped attributes in the example object as meaningfull 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()`.

### removeFromValuesToExclude

    public void removeFromValuesToExclude(java.lang.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` - 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)`

### setShouldUseEqualityForNulls

    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` - If true (by default) uses `isNull` else `notNull`.
  See Also:
    `addSpecialOperation`, `alwaysIncludeAttribute`

### setSpecialOperations

    public void setSpecialOperations(java.util.Hashtable newOperations)

  PUBLIC: The special operations to use in place of `equal`.
  Parameters:
    `newOperations` - 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(java.lang.Class, java.lang.String)`

### setValuesToExclude

    public void setValuesToExclude(java.util.Hashtable 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` - 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(byte)`, `excludeDefaultPrimitiveValues()`, `includeAllValues()`

### shouldUseEqualityForNulls

    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:
    If true (by default) uses `isNull` else `notNull`.
  See Also:
    `addSpecialOperation`, `alwaysIncludeAttribute`

Overview | Package | Class | Tree | Deprecated | Index | Help
| Copyright © 1998, 2006, Oracle. All Rights Reserved.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD