Difference between revisions of "EclipseLink/Development/AdditionalCriteria"

Revision as of 11:52, 29 September 2010

Meeting September 29th - Discussion points

Here is a current proposal for this feature:

• Allow additional criteria at the EMF/session level only which will tie into the existing additional join expression framework directly and also add the option to pass paramaters to it.

Going further than that, opens the following discussion points:

• Need a list of requirements and the use cases we expect to solve and examples of those. Specifically where the requirement for multiple criteria and being able to enable/disable comes from and how this is expected to be used.
• Additional criteria at the Session or EntityManager level
• Enable/Disable, do we allow it, to which extend
  • At create entity manager factory level
    • Used through properties
    • What are the expectations then with respect to:
      • Caching
      • Query preparation
      • Performance
  • At create entity manager level
    • Used through properties or new EM API
  • At any point during em operations (find, refresh) etc.
• Should they be enabled by default
• Removing enable/disable renders multiple additional criteria obsolete
• Should additional criteria be global in scope

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

The additional criteria that is applied then is as follows:

1. From XML
2. From the entity class
3. From a mapped superclass (first one to define additional criteria)

Meaning, where ever the additional criteria is found, it must be the complete set of additional criteria that should be added to the descriptor's query event manager.

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

The additional criterias will be stored on the query manager, keyed on name and can be enabled/disabled using properties set on the EntityManager (see IsolatedSession API below). Additional criteria should not be used in conjunction with setting the additional join expression directly. Setting additional criteria will set and control the additional join expression.

New API

public void addAdditionalCriteria(String jpqlFragment, String name, boolean enabled)

Exceptions

1. JPQL parse exception
2. Invalid additional criteria name (DescriptorException)

IsolatedSession API

To leverage the enable/disable users will need to use an isolated session. This session will be responsible for controlling the additional criteria to be applied to queries.

public void disableAdditionalCriteria(String name)
public void enableAdditionalCriteria(String name)
public void setAdditionalCriteriaParameterValue(String name, Object value)

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. AdditionalCriteria properties should only be supported at create entity manager time.

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

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.