Difference between revisions of "EclipseLink/Development/AdditionalCriteria"

Revision as of 14:51, 23 September 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 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 additional criteria will be available in the form of annotations and/or xml where additional criteria can be overriden from the eclipselink-orm.xml. XML file merging will be available as well in its current form, simply expanded to include the additional criteria and additional criteria callback methods.

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 if the following additional criteria list appended to the descriptors query event manager:

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

The following new element will be added to <entity> and <mapped-superclass> complex elements to facilitate the additional criteria support.

<xsd:element name="additional-criteria" type="orm:additional-criteria" maxOccurs="unbounded"/>

The additional-criteria will be applied to all queries.

Additional Criteria

The additional criteria(s) will be used to form the existing additionalJoinExpression from the descriptor's query manager. See the JPQL fragment section below that will discuss how this value will be populated. The additional criterias will be stored on the query manager, keyed by name and can be enabled/disabled using properties set on the EntityManager.

<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. 
       * 
       * 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();
      }

    </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>

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>

Enabling/Disabling additional criteria

The additional criteria will be enable and disabled using EntityManager properties:

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

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

Both properties accept the 'entity-name:additional-criteria-name' format to specify which additional criteria to enable/disable.

Example:

eclipselink-enable-additional-criteria = model.Employee:CompanyFilter

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

These properties are passed to the EntityManager through the following API:

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

Passing parameters to the additional criteria

... work in progress ...

Core

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

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.

New API

public void addAdditionalCriteria(String jpql, String name, boolean enabled)
public void disableAdditionalCriteria(String name)
public void enableAdditionalCriteria(String name)

Exceptions

1. JPQL parse exception
2. Invalid additional criteria name