Package org.eclipse.persistence.queries

Class 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 meaningful (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, 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)

    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);
    See Also:
    ObjectLevelReadQuery.setExampleObject(java.lang.Object), ObjectLevelReadQuery.setQueryByExamplePolicy(org.eclipse.persistence.queries.QueryByExamplePolicy), Serialized Form
    Since:
    TOPLink/Java 3.0

    • Constructor Summary

      Constructors 
      Constructor Description
      QueryByExamplePolicy()
      PUBLIC: Constructs a default policy equal to that used when no policy is specified.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      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​(short 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.
      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 setValidateExample​(boolean validate)
      PUBLIC: When set to true the example object will be validated for unsupported mapping types.
      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.
      boolean shouldValidateExample()
      PUBLIC: Returns true if the example object used with this policy should be validated for attributes with unsupported mappings.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • valuesToExclude

        public java.util.Map valuesToExclude

      • attributesToAlwaysInclude

        public java.util.Map attributesToAlwaysInclude

      • specialOperations

        public java.util.Map specialOperations

      • shouldUseEqualityForNulls

        public boolean shouldUseEqualityForNulls

      • validateExample

        protected boolean validateExample

    • 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 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 - 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,
                                     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).

      • completeExpressionForNull

        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.

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

      • getOperation

        public java.lang.String getOperation​(java.lang.Class aClass)
        INTERNAL: determines which operation to use for comparison.

      • getSpecialOperations

        public java.util.Map 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.Map 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 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

        public boolean isAlwaysIncluded​(java.lang.Class theClass,
                                java.lang.String attributeName)
        INTERNAL: returns whether the attributeName is to be always included.

      • isExcludedValue

        public boolean isExcludedValue​(java.lang.Object value)
        INTERNAL: returns if the value is in the values to be excluded automatically.

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

      • setAttributesToAlwaysInclude

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

      • 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.Map 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)

      • setValidateExample

        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

      • setValuesToExclude

        public void setValuesToExclude​(java.util.Map 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()

      • shouldIncludeInQuery

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

      • 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

      • shouldValidateExample

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