Difference between revisions of "EclipseLink/Development/AdditionalCriteria"

Revision as of 12:41, 17 February 2011

Additional Criteria Requirements and Design

Enhancement Request: bug 322008

This work will introduce an additional criteria EclipseLink users can apply to a descriptors default queries in turn providing them with a filtering option. This filtering option will allow users to leverage the existing additional join expression from a descriptor query manager and allow parameters to be passed to it.

See the following blog from Doug discussing filters and their current usage though a descriptor customizer.

http://java-persistence.blogspot.com/2010/08/eclipselink-filters-how-to.html

A point form list of requirements are then as follows:

• Provide a mechanism for users to achieve:
  • Multi-tenancy
  • Soft deletes
  • Temporal filtering
• Simplify the definition and usage of EclipseLink's additional join expressions using Eclipselink metadata.
• Allow additional criteria to be specified through the use of annotations and xml.
• Allow for xml mapping file merging and overridding using the eclipselink-orm.xml
• Allow for JPQL fragments to specify the details of the additional criteria.
• Allow for a mechanism to pass parameters to the additional criteria.
• Easy to use and forward compatible.
• Respect the general JPA look and feel.

Metadata

The following sections will detail the metadata changes and modifications that are required. The additional criteria will be available in the form of annotations and xml and will be used to form the descritor query manager's additionalJoinExpression that is applied to all queries for that descriptor.

@AdditionalCriteria

/**
 * An additional criteria can be specified at the Entity or MappedSuperclass 
 * level. When specified at the mapped superclass level, it applies to all 
 * inheriting entities unless those entities define their own additional 
 * criteria, at which point the additional criteria from the mapped superclass 
 * is ignored.
 * 
 * The additional criteria supports any valid JPQL string and must use 'this' 
 * as an alias to form your additional criteria. E.G.,
 * 
 * @Entity
 * @AdditionalCriteria("this.nut.size = :NUT_SIZE and this.nut.color = :NUT_COLOR")
 * public class Bolt {...}
 *   
 * Additional criteria parameters are also accepted and are set through 
 * properties on the entity manager factory, or on an entity manager. When set 
 * on the entity manager, the properties must be set before any query execution
 * and should not be changed for the life span of that entity manager.
 * 
 * Properties set on the entity manager will override those similarly named 
 * properties set on the entity manager factory.
 * 
 * Additional criteria is not supported with any native queries.
 * 
 * @author Guy Pelletier
 * @since EclipseLink 2.2
 */
@Target({TYPE})
@Retention(RUNTIME)
public @interface AdditionalCriteria {
    /**
     * (Required) The JPQL fragment to use as the additional criteria.
     */
    String value();
}

<additional-criteria>

An additional criteria complex element will be created to allow future expansion.

<xsd:complexType name="additional-criteria">
  <xsd:annotation>
    <xsd:documentation>
     /**
      * An additional criteria can be specified at the Entity or MappedSuperclass 
      * level. When specified at the mapped superclass level, it applies to all 
      * inheriting entities unless those entities define their own additional 
      * criteria, at which point the additional criteria from the mapped superclass 
      * is ignored.
      * 
      * The additional criteria supports any valid JPQL string and must use 'this' 
      * as an alias to form your additional criteria. E.G.,
      * 
      * @Entity
      * @AdditionalCriteria("this.nut.size = :NUT_SIZE and this.nut.color = :NUT_COLOR")
      * public class Bolt {...}
      *   
      * Additional criteria parameters are also accepted and are set through 
      * properties on the entity manager factory, or on an entity manager. When set 
      * on the entity manager, the properties must be set before any query execution
      * and should not be changed for the life span of that entity manager.
      * 
      * Properties set on the entity manager will override those similarly named 
      * properties set on the entity manager factory.
      * 
      * Additional criteria is not supported with any native queries.
      * 
      * @author Guy Pelletier
      * @since EclipseLink 2.2
      */
     @Target({TYPE})
     @Retention(RUNTIME)
     public @interface AdditionalCriteria {
         /**
          * (Required) The JPQL fragment to use as the additional criteria.
          */
         String value();
      }

    </xsd:documentation>
  </xsd:annotation>
  <xsd:sequence>
      <xsd:element name="criteria" type="xsd:string"/>
  </xsd:sequence>
</xsd:complexType>

The additional-criteria element will be added to entity and mapped-superclass complex elements as follows

<xsd:complexType name="entity">
    <xsd:annotation>
      <xsd:documentation>
       ...
      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      ...
      <xsd:element name="additional-criteria" type="orm:additional-criteria" minOccurs="0"/>
      ...
    </xsd:sequence>
    ...
</xsd:complexType>

<xsd:complexType name="mapped-superclass">
    <xsd:annotation>
      <xsd:documentation>
       ...
      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      ...
      <xsd:element name="additional-criteria" type="orm:additional-criteria" minOccurs="0"/>
      ...
    </xsd:sequence>
    ...
</xsd:complexType>

Example

@AdditionalCriteria("this.address.city IS NOT NULL")

<additional-criteria>
  <criteria>this.address.city IS NOT NULL</criteria>
</additional-criteria>

Metadata overriding and merging

The additional criteria can be overridden from the eclipselink-orm.xml. XML file merging will be available as well in its current form, simply expanded to include the additional criteria. The following will be the order of precedence used to determine the which additional-criteria is applied to the descriptor.

1. eclipselink-orm.xml
2. mapping file
3. on the entity class
4. on a mapped superclass (first one to define one)

Internal mapping

The additional criteria will be used to form the additionalJoinExpression from the descriptor's query manager.

Core

The following sections will detail the core changes and modifications that are required.

DescriptorQueryManager

The additional criteria will be used to form the existing additional join expression stored on the descriptor query manager. Care must be taken by those users who currently set the additional join expression directly through a customizer. Adding additional criteria will be AND'ed to this expression.

The metadata will set the additional criteria through the following new API on the DescriptorQueryManager.

public void setAdditionalCriteria(String jpqlFragment)

The jpql fragment will be parsed into the additional join expression at post-initialization time. Any parsing exceptions will be thrown at that time.

Other new API added to DescriptorQueryManager:

HashMap<String, Class> getAdditionalCriteriaArguments() // key = name and value = type
boolean hasAdditionalCriteria()
boolean hasAdditionalCriteriaArguments()

JPQL fragment parsing

We will tie into the existing JPQL parser to parse the additional criteria where the only alias allowed will be 'this'. We will prepend the following select statement with the additional criteria JPQL fragment and harness the selection criteria from that resulting query and set it to be the additional join expression.

Select this from <class> this where

The JPQL will be parsed at descriptor postInitialization time. Multiple selects will not be supported in the JPQL fragment.

Parameters

At runtime, users will provide parameters to their additional criteria during EntityManager create or through a set property call before any query execution. Changing the parameters during the lifespan of the EntityManager is not defined and could lead to a 'corrupted' cache and unpredictable results.

Parameters are global in scope and are added to the active JPA context (server session) and will be applied all additional criteria that accept the same parameter name at query execution time.

NOTE: Users must be careful when selecting their parameter names so as to not conflict with existing JPA and Eclipselink properties.

Query parameters and their types will be available from the DescriptorQueryManager after postInitialization through the following API:

HashMap<String, Class> getAdditionalCriteriaArguments()

These parameters are added to each executing query during its prepare. More specifically in the call to buildArgumentFields(). Following that, the parameter values are added to each executing query before its execution in the call to rowFromArguments(List, AbstractSession). The properties are extracted from the session given. If an additional criteria parameter value is not found, a new exception QueryException.argumentFromAdditionalCriteriaMissing is thrown. To ease the checking if a parameter is an additional criteria parameter, the following API had been added to DatabaseQuery:

boolean isAdditionalCriteriaArgument(String argument)

Beyond that, existing checking remains in place for an incorrect number of arguments vs. number of values provided, that is, QueryException.argumentSizeMismatchInQueryAndQueryDefinition

Example

With the given additional additional criteria

package model;

@AdditionalCriteria("this.company=:COMPANY")
public class Employee {
  ...
}

Setting the following property on the EntityManager would return all employees of Oracle.

entityManager.setProperty("COMPANY", "Oracle");

A more complex example

@Entity
@AdditionalCriteria("this.nut.size = :NUT_SIZE and this.nut.color = :NUT_COLOR order by this.id")
public class Bolt {
...
}

This additional criteria accespts two parameters across a 1-1 relation and is order by id.

Exceptions/Open Issues/Future

• Exception: Additional criteria specified on a descriptor within an inheritance hierarchy using views is not supported.
• Future: Allow additional criteria to be specified at the mapping level.
• Future: Allow multiple additional criteria with option to enable/disable individual additonal criteria