Difference between revisions of "EclipseLink/Development/AdditionalCriteria"

Revision as of 08:36, 22 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.

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)

An example of the XML override is as follows:

• mapping.xml defines an additional-criteria
• eclipselink.xml defines an additional-criteria-group

The outcome is that the additional-criteria-group from the eclipselink-orm.xml is applied and overrides the additional-criteria from the mapping.xml.

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

 <xsd:choice minOccurs="0">
   <xsd:element name="additional-criteria" type="orm:additional-criteria"/>
   <xsd:element name="additional-criteria-group" type="orm:additional-criteria-group"/>
   <xsd:element name="additional-criteria-callback" type="orm:additional-criteria-callback"/>
 </xsd:choice>

Additional Criteria

The additional criteria will tie into the existing additionalJoinExpression from the descriptor's query manager. See the JPQL fragment section below that will discuss how this value will be populated.

<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 within an additional 
       * criteria group. A single additional criteria or an additional criteria group 
       * can not be specified in conjunction with an additional criteria callback. 
       * 
       * @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>

Additional Criteria Group

An additional criteria group allows for a more complex expression to be set as the additionalJoinExpression from the descriptor's query manager. See the JPQL fragment section below that will discuss how this value will be populated.

<xsd:complexType name="additional-criteria-group">
  <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 group from the mapped superclass is ignored. 
       * 
       * An additional criteria group can not be specified in conjunction with an 
       * additional criteria callback or additional criteria.
       * 
       * @author Guy Pelletier
       * @since EclipseLink 2.2
       */
      @Target({TYPE})
      @Retention(RUNTIME)
      public @interface AdditionalCriteriaGroup {
          /**
           * (Optional) The name of the additional criteria group. 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) Specifying an additional criteria group requires at least one
           * additional criteria.
           */
          AdditionalCriteria[] value();
      }
        
    </xsd:documentation>
  </xsd:annotation>
  <xsd:sequence>
    <xsd:element name="additional-criteria" type="orm:additional-criteria" minOccurs="1" maxOccurs="unbounded"/>
  </xsd:sequence>
  <xsd:attribute name="name" type="xsd:string"/>
  <xsd:attribute name="enabled" type="xsd:boolean"/>
</xsd:complexType>

Example

@AdditionalCriteriaGroup(
     name="MaleEmployees", 
     value={ 
       @AdditionalCriteria(gender='M'"), 
       @AdditionalCriteria("company=:COMPANY")})

<additional-criteria-group name="MaleEmployees">
  <additional-criteria>
    <criteria>gender='M'</criteria>
  </additional-criteria>
  <additional-criteria>
    <criteria>company=:CONPANY</criteria>
  </additional-criteria>
</additional-criteria-group>

Notes

• The enabled flag on individual additiona criteria are ignored at this point and only the group flag applies. In this case, it defaults to false.

Additional Criteria Callback

The additional criteria callback allows the user to control how the additionalJoinExpression is expressed and allows the user to decorate a separate class without having to implement an internal interface. The use case here is similar to an entity listener class.

The callback class will be stored on the descriptor's query manager and will invoked/tied in through the getAdditionalCriteria method.

Using a callback class, users can further control which additional criteria is used for individual query classes. See the AdditionalCriteriaCallbackMethod below.

<xsd:complexType name="additional-criteria-callback">
  <xsd:annotation>
    <xsd:documentation>
 
      /**
       * An additional criteria callback 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 callback from the 
       * mapped superclass is ignored.
       * 
       * An additional criteria callback can not be specified in conjunction with a 
       * single additional criteria or an additional criteria group.
       * 
       * @author Guy Pelletier
       * @since EclipseLink 2.2
       */
      @Target({TYPE})
      @Retention(RUNTIME)
      public @interface AdditionalCriteriaCallback {    
          /**
           * (Required) Defines the name of the additional criteria callback class 
           * that should be applied to this entity's descriptor.
           */
          Class value();
      }
        
    </xsd:documentation>
  </xsd:annotation>
  <xsd:sequence>
      <xsd:element name="callback-method" type="orm:additional-criteria-callback-method" maxOccurs="unbounded"/>
  </xsd:sequence>
  <xsd:attribute name="class" type="xsd:string" use="required"/>
</xsd:complexType>

Example

  @AdditionalCriteriaCallback(CustomerUserCriteria.class)

  <additional-criteria-callback class="CustomerUserCriteria"/>

Notes

• The package element will apply to the additional criteria callback class when specified in XML.

Additional Criteria Callback Method

The additional criteria callback method(s) control which methods from the callback class are used to control the additional criteria and to which queries they apply.

<xsd:complexType name="additional-criteria-callback-method">
  <xsd:annotation>
    <xsd:documentation>
 
      /**
       * An additional criteria callback method(s) is specified on an additional
       * criteria callback class. It also defines the EclipseLink queries that should
       * call the method on execution.
       * 
       * @author Guy Pelletier
       * @since EclipseLink 2.2
       */
      @Target({METHOD})
      @Retention(RUNTIME)
      public @interface AdditionalCriteriaCallbackMethod {    
          /**
           * (Optional) The list of EclipseLink query classes that will accept the
           * additional criteria. E.g. ReadAllQuery.class, DeleteObjectQuery.class.
           * By defaul the callback method is applied to all queries.
           * 
           * There can be multiple AdditionalCriteriaCallbackMethod on a callback
           * class.
           */
          Class[] value() default {};
      }
  
    </xsd:documentation>
  </xsd:annotation>
  <xsd:sequence>
      <xsd:element name="query-class" type="xsd:string" maxOccurs="unbounded"/>
  </xsd:sequence>
  <xsd:attribute name="name" type="xsd:string" use="required"/>
</xsd:complexType>

Example

public class CustomerUserCriteria {
  @AdditionalCriteriaCallbackMethod 
  public void handleAll(DatabaseQuery query) {}

  @AdditionalCriteriaCallbackMethod({ReadAllQuery.class, ReadObject.class}) 
  public void handleRead(DatabaseQuery query) {}

  @AdditionalCriteriaCallbackMethod({DeleteObjectQuery.class, DeleteAllQuery.class}) 
  public void handleDelete(DatabaseQuery query) {}
}

<additional-criteria-callback class="CustomerUserCriteria">
  <callback-method name="handleAll"/>
  <callback-method name="handleRead">
    <query-class>ReadAllQuery</query-class>
    <query-class>ReadObjectQuery</query-class>
  </callback-method>
  <callback-method name="handleDelete">
    <query-class>org.eclipse.persistence.queries.DeleteAllQuery</query-class>
    <query-class>org.eclipse.persistence.queries.DeleteObjectQuery</query-class>
  </callback-method>
</additional-criteria-callback>

Notes:

• The org.eclipse.persistence.queries package will be appended by default.
• An additional criteria callback class is parsed similarly as an entity listener class. That is, it is pased for more additional criteria callback methods, however XML will override any similarly named criteria callback method in annotations.

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

Query manager

Will be responsible for controlling the additional criteria that is applied to the queries. That is, it will take into consideration the additional criteria that is enabled (only a single criteria or group or callback can be enabled at one time). The query manager is responsible for directing the executing query to the related callback method(s).