EclipseLink/Development/AdditionalCriteria

Additional Criteria Requirements and Design

Enhancement Request: bug 322008

Additional criteria can be overriden from the eclipselink-orm.xml. The eclipselink-orm.xml will override annotations and other xml mapping files). XML file merging will remain in place as well.

That is:

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

New elements to be added to the <entity> and <mapped-superclass> elements.

 <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

<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

<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

<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

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