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"
(→Meeting September 29th - Discussion points) |
(→Meeting September 29th - Discussion points) |
||
Line 5: | Line 5: | ||
* Allow additional criteria at the EMF/session level only which will tie into the existing additional join expression framework directly and also add the option to pass paramaters to it. | * Allow additional criteria at the EMF/session level only which will tie into the existing additional join expression framework directly and also add the option to pass paramaters to it. | ||
− | Going further, opens the following discussion points | + | Going further than that, opens the following discussion points: |
* Need a list of requirements and the use cases we expect to solve and examples of those. Specifically where the requirement for multiple criteria and being able to enable/disable comes from and how this is expected to be used. | * Need a list of requirements and the use cases we expect to solve and examples of those. Specifically where the requirement for multiple criteria and being able to enable/disable comes from and how this is expected to be used. |
Revision as of 11:51, 29 September 2010
Contents
Meeting September 29th - Discussion points
Here is a current proprosal for this feature:
- Allow additional criteria at the EMF/session level only which will tie into the existing additional join expression framework directly and also add the option to pass paramaters to it.
Going further than that, opens the following discussion points:
- Need a list of requirements and the use cases we expect to solve and examples of those. Specifically where the requirement for multiple criteria and being able to enable/disable comes from and how this is expected to be used.
- Additional criteria at the Session or EntityManager level
- Enable/Disable, do we allow it, to which extend
- At create entity manager factory level
- Used through properties
- What are the expectations then with respect to:
- Caching
- Query preparation
- Performance
- At create entity manager level
- Used through properties or new EM API
- At any point during em operations (find, refresh) etc.
- At create entity manager factory level
- Should they be enabled by default
- Removing enable/disable renders multiple additional criteria obsolete
- Should additional criteria be global in scope
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. This filtering option will allow for the user to enable and disable the filter (or portions of it) as needed at runtime.
See the following blog from Doug discussing filters and their current usage though a descriptor customizer.
http://java-persistence.blogspot.com/2010/08/eclipselink-filters-how-to.html
A point form list of requirements are then as follows:
- Simplify the definition and usage of EclipseLink's additional join expressions using Eclipselink metadata.
- Allow additional criteria to be specified through the use of annotations and xml.
- Allow users the option to enable and disable additional criteria.
- Allow for xml mapping file merging and overridding using the eclipselink-orm.xml
- Allow for JPQL fragments to specify the details of the additional criteria.
- Allow for a mechanism to pass parameters to the additional criteria.
- Easy to use and forward compatible.
- Respect the general JPA look and feel.
Metadata
The following sections will detail the metadata changes and modifications that are required. The additional criteria will be available in the form of annotations and xml and will be used to form the descritor query manager's additionalJoinExpression that is applied to all queries.
@AdditionalCriteria
/** * 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 as multiples using * the plural AdditionalCriterias annotation. * * @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(); }
@AdditionalCriterias
/** * An AdditionalCriterias annotation allows the definition of multiple * AdditionalCriteria. * * @see org.eclipse.persistence.annotations.AdditionalCriteria * @author Guy Pelletier * @since EclipseLink 2.2 */ @Target({TYPE}) @Retention(RUNTIME) public @interface AdditionalCriterias { /** * (Required) An array of additional criteria. */ AdditionalCriteria[] value(); }
<additional-criteria>
<xsd:complexType name="additional-criteria"> <xsd:annotation> <xsd:documentation> ... </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>
The additional-criteria element will be added to entity and mapped-superclass complex elements as follows
<xsd:complexType name="entity"> <xsd:annotation> <xsd:documentation> ... </xsd:documentation> </xsd:annotation> <xsd:sequence> ... <xsd:element name="additional-criteria" type="orm:additional-criteria" maxOccurs="unbounded"/> ... </xsd:sequence> ... </xsd:complexType> <xsd:complexType name="mapped-superclass"> <xsd:annotation> <xsd:documentation> ... </xsd:documentation> </xsd:annotation> <xsd:sequence> ... <xsd:element name="additional-criteria" type="orm:additional-criteria" maxOccurs="unbounded"/> ... </xsd:sequence> ... </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>
Metadata overriding and merging
The additional criteria can be overridden 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:
- additional-criteria named - A
- additional-criteria named - B
- eclipselink.xml defines:
- additional-criteria named - A
- additional-criteria named - C
The outcome of additional criteria added to the descriptor's query event manager:
- A - from eclipselink-orm.xml
- B - from mapping.xml
- C - from eclipselink-orm.xml
The additional criteria that is applied then is as follows:
- From XML
- From the entity class
- From a mapped superclass (first one to define additional criteria)
Meaning, where ever the additional criteria is found, it must be the complete set of additional criteria that should be added to the descriptor's query event manager.
Internal mapping
The additional criteria will be used to form the additionalJoinExpression from the descriptor's query manager. The core sections below will discuss the internal handling of this additional criteria metadata.
Core
The following sections will detail the core changes and modifications that are required.
DescriptorQueryManager
The additional criterias will be stored on the query manager, keyed on name and can be enabled/disabled using properties set on the EntityManager (see IsolatedSession API below). Additional criteria should not be used in conjunction with setting the additional join expression directly. Setting additional criteria will set and control the additional join expression.
New API
public void addAdditionalCriteria(String jpqlFragment, String name, boolean enabled)
Exceptions
- JPQL parse exception
- Invalid additional criteria name (DescriptorException)
IsolatedSession API
To leverage the enable/disable users will need to use an isolated session. This session will be responsible for controlling the additional criteria to be applied to queries.
public void disableAdditionalCriteria(String name) public void enableAdditionalCriteria(String name) public void setAdditionalCriteriaParameterValue(String name, Object value)
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 ...
Application
New properties will be added to control the enabling/disabling of properties and to provide the parameter values. These properties can be set at both the EntityManagerFactory and EntityManager level. At the EntityManager level, however, the user must be using an isolated session.
Modifying the additional criteria properties at the EntityManager level through the following API will not be allowed and an exception will be thrown. AdditionalCriteria properties should only be supported at create entity manager time.
- setProperties
- setProperty
- find
- refresh
- remove
Enabling/Disabling additional criteria
The additional criteria will be enabled and disabled using the following EntityManagerFactory properties (added to org.eclipse.persistence.config.PersistenceUnitProperties):
- eclipselink.enable-additional-criteria
- eclipselink.disable-additional-criteria
Both properties accept the entity name (or qualified name) appended to the property name to determine the additional criteria that is to be enabled/disabled.
Example:
eclipselink.enable-additional-criteria.Employee = CompanyFilter
This would then enable the additional criteria named 'CompanyFilter' on the model.Employee's DescriptorQueryManager.
Bulk Enabling/Disabling additional criteria
There is currently no bulk enabling/disable of additional criteria across all descriptors. They must all be enabled/disabled separately.
Passing parameters to the additional criteria
The additional criteria parameters will also be set using EntityManagerFactory properties:
The following properties will be added to org.eclipse.persistence.config.PersistenceUnitProperties
- eclipselink-additional-criteria-parameter
This property accept the entity name and parameter appended to the property name. The entity name and parameter should be separated by a semi-colon.
Note: Specifying a parameter to a disabled additional criteria will have no effect until the additional criteria containing the parameter is enabled.
Example:
eclipselink.additional-criteria-parameter.model.Employee:COMPANY = ORACLE
Example
With the given additional additional criterias
package model; @AdditionalCriterias({ @AdditionalCriteria( name="Company", enabled=true, value="company=:COMPANY"), @AdditionalCriteria( name="MaleEmps", enabled=true, value="gender = 'M'"), @AdditionalCriteria( name="FemaleEmps", enabled=false, value="gender = 'F'") ) public class Employee { ... }
Setting the following property on the EntityManager would return all male employees at Oracle.
eclipselink.additional-criteria-parameter.model.Employee:COMPANY = ORACLE
Passing the following properties would return all female employees at Oracle.
eclipselink.enable-additional-criteria.Employee = FemaleEmps eclipselink.disable-additional-criteria.Employee = MaleEmps eclipselink.additional-criteria-parameter.Employee:COMPANY = ORACLE
Bulk Parameter passing
There is currently no bulk parameter passing to all additional criteria across all descriptors. They must all be set for each descriptor separately.