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>

Sample Usage

The following is an initial proposal to generate discussion.

@Entity
 
// This annotation is needed and very useful when defining comparison against 
// columns that are not mapped
@BasicQueryAttribute(name = "isDeleted", column = @Column(name = "IS_DEL"))
 
/**
 *  Simple fixed criteria for virtual delete scenario
 */
@FixedCriteria(attribute = "isDeleted", operator = EQUAL, value = "Y")
 
/**
 *  Simple Property usage. The property will be looked up in the active session
 *  
 *  Note: Currently this is only the UOW/CS when the cache.shared=false. When cache.shared=true only the server session's properties are visible.
 */
@PropertyCriteria(attribute = "company", operator = LIKE, property = "COMPANY_PATTERN")
 
/**
 * Call-back criteria where expressions can be added dynamically. This class
 * could either implement an interface for call-backs or an additional set of
 * annotations could be defined that allows you to define which methods are
 * called for which query types.
 */
@CallbackCriteria(CustomerUserCriteria.class)
 
/**
 * More complex additional criteria that supports composition, named access, and 
 * enable/disable. Any of the above could be specified within @AdditionalCriteria to 
 * allow enable/disable through named access.
 * 
 * When specified without @AdditionalCriteria all of the provided criteria are combined 
 * into a AdditionalCriteria named 'default' on the descriptor and enabled.
 */
@AdditionalCriteria(name = "example", enabled = false, 
        fixed = { @FixedCriteria(attribute = "name", operator = NOT_NULL) }, 
        properties = { @PropertyCriteria(attribute = "company", operator = EQUAL, property = "COMPANY_NAME") }, 
        callbacks = { @CallbackCriteria(CustomerTemporalCriteria.class) })
public class Customer {
 
    @Id
    private int id;
 
    private String name;
 
    private String company;