Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "EclipseLink/Development/AdditionalCriteria"
< EclipseLink | Development
(→Notes) |
(→Notes) |
||
Line 207: | Line 207: | ||
=== Notes === | === Notes === | ||
* The package element will apply to the additional criteria callback class when specified in XML. | * The package element will apply to the additional criteria callback class when specified in XML. | ||
+ | |||
+ | == Additional Criteria Callback Method == | ||
+ | |||
+ | <pre> | ||
+ | <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> | ||
+ | </pre> | ||
+ | |||
+ | === Example === | ||
+ | |||
+ | <pre> | ||
+ | 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> | ||
+ | </pre> |
Revision as of 11:41, 20 September 2010
Contents
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>