EclipseLink/Development/AdditionalCriteria

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 for the user to enable and disable the filter (or portions of it) as needed at runtime.

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:

• 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 users the option to enable and disable additional criteria.
• 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.

@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. 
 * 
 * Additional criteria can be specified as a single item or as multiples using
 * the plural AdditionalCriterias annotation.
 *
 * @author Guy Pelletier
 * @since EclipseLink 2.2
 */
@Target({TYPE})
@Retention(RUNTIME)
public @interface AdditionalCriteria {
    /**
     * (Optional) The name of the additional criteria. Naming allows the 
     * capability of turning off individual criteria based on name. 
     */
    String name() default "default";
    
    /**
     * (Optional) By default, the additional criteria is not enabled and applied.
     */
    boolean enabled() default false;
    
    /**
     * (Required) The JPQL fragment to use as the additional criteria.
     */
    String value();
}

@AdditionalCriterias

/** 
 * An AdditionalCriterias annotation allows the definition of multiple
 * AdditionalCriteria.
 * 
 * @see org.eclipse.persistence.annotations.AdditionalCriteria
 * @author Guy Pelletier
 * @since EclipseLink 2.2 
 */ 
@Target({TYPE})
@Retention(RUNTIME)
public @interface AdditionalCriterias {
    /**
     * (Required) An array of additional criteria.
     */
    AdditionalCriteria[] value();
}

<additional-criteria>

<xsd:complexType name="additional-criteria">
  <xsd:annotation>
    <xsd:documentation>
     ...
    </xsd:documentation>
  </xsd:annotation>
  <xsd:sequence>
      <xsd:element name="criteria" type="xsd:string"/>
  </xsd:sequence>
  <xsd:attribute name="name" type="xsd:string"/>
  <xsd:attribute name="enabled" type="xsd:boolean"/>
</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" maxOccurs="unbounded"/>
      ...
    </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" maxOccurs="unbounded"/>
      ...
    </xsd:sequence>
    ...
</xsd:complexType>

Example

  @AdditionalCriteria(
    name="CitySpecified",
    enabled=true,
    value="address.city IS NOT NULL"
  )

  <additional-criteria name="CitySpecified" enabled="true">
    <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.

An example of the XML override is as follows:

• mapping.xml defines:
  • additional-criteria named - A
  • additional-criteria named - B
• eclipselink.xml defines:
  • additional-criteria named - A
  • additional-criteria named - C

The outcome of additional criteria added to the descriptor's query event manager:

• A - from eclipselink-orm.xml
• B - from mapping.xml
• C - from eclipselink-orm.xml

If we add the following to the model:

• Entity class defines:
  • AdditionalCriteria - A
  • AdditionalCriteria - D
• MappedSuperclass defines:
  • AdditionalCriteria - B
  • AdditionalCriteria - D
  • AdditionalCriteria - E

The final outcome of additional criteria added to the descriptor's query event manager:

• A - from eclipselink-orm.xml
• B - from mapping.xml
• C - from eclipselink-orm.xml
• D - from Entity class
• E - from MappedSuperclass

Internal mapping

The additional criteria will be used to form the additionalJoinExpression from the descriptor's query manager. The core sections below will discuss the internal handling of this additional criteria metadata.

Core

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

DescriptorQueryManager

Will be responsible for storing and controlling the additional criteria to be applied to queries taking into consideration those additional criterias that are enabled/disabled.

The additional criterias will be stored on the query manager, keyed on name and can be enabled/disabled using properties set on the EntityManager.

New API

public void addAdditionalCriteria(String jpqlFragment, String name, boolean enabled)
public void disableAdditionalCriteria(String name)
public void enableAdditionalCriteria(String name)
public void setAdditionalCriteriaParameterValue(String name, Object value)

Exceptions

1. JPQL parse exception
2. Invalid additional criteria name

JPQL fragment

The current notion will be to 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, e.g. "Select this from <class> this where" and harness the selection criteria from that resulting query and appended to the executing query.

For an additional criteria group, each selection criteria harnessed from each additional criteria within the group will be joined with an 'AND'

Items that will not be supported in the JPQL fragment are:

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

Application

New properties will be added to control the enabling/disabling of properties and to provide the parameter values. These properties can be set at both the EntityManagerFactory and EntityManager level. At the EntityManager level, however, the user must be using an isolated session.

Modifying the additional criteria properties at the EntityManager level through the following API will not be allowed and an exception will be thrown.

1. setProperties
2. setProperty
3. find
4. refresh
5. remove

QUESTION: We may want to relax this restriction and allow them to make this modifications. Under this case though, we would clear the cache for them once 'any' additional criteria property was changed, added or removed.

Enabling/Disabling additional criteria

The additional criteria will be enabled and disabled using the following EntityManagerFactory properties (added to org.eclipse.persistence.config.PersistenceUnitProperties):

• eclipselink.enable-additional-criteria
• eclipselink.disable-additional-criteria

Both properties accept the entity name (or qualified name) appended to the property name to determine the additional criteria that is to be enabled/disabled.

Example:

eclipselink.enable-additional-criteria.Employee = CompanyFilter

This would then enable the additional criteria named 'CompanyFilter' on the model.Employee's DescriptorQueryManager.

Bulk Enabling/Disabling additional criteria

There is currently no bulk enabling/disable of additional criteria across all descriptors. They must all be enabled/disabled separately.

Passing parameters to the additional criteria

The additional criteria parameters will also be set using EntityManagerFactory properties:

The following properties will be added to org.eclipse.persistence.config.PersistenceUnitProperties

• eclipselink-additional-criteria-parameter

This property accept the entity name and parameter appended to the property name. The entity name and parameter should be separated by a semi-colon.

Note: Specifying a parameter to a disabled additional criteria will have no effect until the additional criteria containing the parameter is enabled.

Example:

eclipselink.additional-criteria-parameter.model.Employee:COMPANY = ORACLE

Example

With the given additional additional criterias

package model;

@AdditionalCriterias({
  @AdditionalCriteria(
    name="Company",
    enabled=true,
    value="company=:COMPANY"),
  @AdditionalCriteria(
    name="MaleEmps",
    enabled=true,
    value="gender = 'M'"),
  @AdditionalCriteria(
    name="FemaleEmps",
    enabled=false,
    value="gender = 'F'")
)
public class Employee {
  ...
}

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

eclipselink.additional-criteria-parameter.model.Employee:COMPANY = ORACLE

Passing the following properties would return all female employees at Oracle.

eclipselink.enable-additional-criteria.Employee = FemaleEmps
eclipselink.disable-additional-criteria.Employee = MaleEmps
eclipselink.additional-criteria-parameter.Employee:COMPANY = ORACLE

Bulk Parameter passing

There is currently no bulk parameter passing to all additional criteria across all descriptors. They must all be set for each descriptor separately.