Difference between revisions of "EclipseLink/Development/AdditionalCriteria"

Revision as of 11:04, 1 October 2010 (view source) Guy.pelletier.oracle.com (Talk | contribs) (→‎Parameters) ← Older edit		Revision as of 13:28, 8 October 2010 (view source) Guy.pelletier.oracle.com (Talk | contribs) (→‎DescriptorQueryManager) Newer edit →
Line 144:		Line 144:
	<pre>public void addAdditionalCriteria(String jpqlFragment)</pre>		<pre>public void addAdditionalCriteria(String jpqlFragment)</pre>
−	The jpql fragment will be parsed into the additional join expression at initialize time. Any parsing exceptions will be thrown then as well.	+	The jpql fragment will be parsed into the additional join expression at post-initialization time. Any parsing exceptions will be thrown then as well.
	=== JPQL fragment parsing ===		=== JPQL fragment parsing ===

---

Revision as of 13:28, 8 October 2010

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

/**
 * 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. 
 *
 * @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>
     /**
      * 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. 
      *
      * @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("address.city IS NOT NULL")

<additional-criteria>
  <criteria>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 addAdditionalCriteria(String jpqlFragment)

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

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 select statement

Select this from <class> this where

and harness the selection criteria from that resulting query and set it to be the additional join expression.

The JPQL will be parsed at descriptor postInitialization time. Items that will not be supported in the JPQL fragment are:

• multiple selects
• order by
• group by
• ... more to come ...

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, in that, they will be applied to all additional criteria that accept the same parameter name.

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

Session API

This session will be responsible for controlling the additional criteria parameters applied to queries through the following new API to ServerSession.

public void setAdditionalCriteriaParameterValue(String name, Object value)

These parameters will be applied to query clones at query execution time.

Example

With the given additional additional criteria

package model;

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

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

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