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 <additional-criteria> - overriden and ignored
eclipselink.xml defines <additional-criteria-group> - applied

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) Be default additional criteria is not enable 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 enable 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>