Difference between revisions of "EclipseLink/UserGuide/JPA/Basic JPA Development/Mapping/Additional Criteria"

From Eclipsepedia

Jump to: navigation, search
m
m
Line 16: Line 16:
  
 
Additional criteria can provide an additional filtering mechanism for queries. This filtering option, for example, allows you to use an existing additional JOIN expression defined for the entity or mapped superclass and allows you to pass parameters to it.  
 
Additional criteria can provide an additional filtering mechanism for queries. This filtering option, for example, allows you to use an existing additional JOIN expression defined for the entity or mapped superclass and allows you to pass parameters to it.  
 +
 +
 +
==Defining Additional Criteria==
  
 
Set additional criteria parameters through properties on the entity manager factory or on the entity manager. When set on the entity manager, you must set the properties before executing a query. Do not change the properties for the lifespan of that entity manager. Properties set on the entity manager override identically named properties set on the entity manager factory.
 
Set additional criteria parameters through properties on the entity manager factory or on the entity manager. When set on the entity manager, you must set the properties before executing a query. Do not change the properties for the lifespan of that entity manager. Properties set on the entity manager override identically named properties set on the entity manager factory.
  
 
Additional criteria are not supported with native queries.
 
Additional criteria are not supported with native queries.
 
 
The additional criteria definition supports any valid JPQL string and must use <tt>this</tt> as an alias to form the additional criteria. For example,
 
The additional criteria definition supports any valid JPQL string and must use <tt>this</tt> as an alias to form the additional criteria. For example,
  
Line 57: Line 59:
 
</source>
 
</source>
  
==Uses of AdditionalCriteria==
+
==Examples==
 +
Additional criteria are useful when working with multitenancy environments, soft deletes, history,
  
Use AdditionalCriteria is to define parameterized views on data.
+
Multitenancy Example
 
+
Uses include the following:
+
*[[#Multitenancy|Multitenancy]]
+
*[[#Soft Deletes|Soft Deletes]]
+
*[[#Multitenancy|Multitenancy]]
+
 
+
===Multitenancy===
+
  
 
In a multitenancy environment, tenants (users, clients, organizations, applications) can share database tables, but the views on the data must be restricted so that tenants have access only to their own data. You can use <tt>AdditionalCriteria</tt> to thus restrict views on the data.  For example,
 
In a multitenancy environment, tenants (users, clients, organizations, applications) can share database tables, but the views on the data must be restricted so that tenants have access only to their own data. You can use <tt>AdditionalCriteria</tt> to thus restrict views on the data.  For example,
Line 84: Line 80:
  
 
   
 
   
===Soft Deletes===
+
'''Soft Delete Example'''
  
 
A soft delete is when a user marks data as deleted but does not actually delete it from the database, for example to keep a record.
 
A soft delete is when a user marks data as deleted but does not actually delete it from the database, for example to keep a record.
Line 92: Line 88:
 
<tt>@AdditionalCriteria("this.isDeleted = false")</tt> filters any delete data from any query.  
 
<tt>@AdditionalCriteria("this.isDeleted = false")</tt> filters any delete data from any query.  
  
===History===
+
 
 +
'''History Example'''
 +
 
 
History is when data is never removed or updated. On an update, a new row is inserted with a new start/end time instead.  
 
History is when data is never removed or updated. On an update, a new row is inserted with a new start/end time instead.  
  
Line 103: Line 101:
 
<tt>@AdditionalCriteria("this.startDate <= :viewDate and this.endDate >= :viewDate")</tt>  
 
<tt>@AdditionalCriteria("this.startDate <= :viewDate and this.endDate >= :viewDate")</tt>  
  
===Shared Tables===
+
'''Shared Tables Example'''
 +
 
 
For a shared table, you could have inheritance in the table, but not in the object model.  
 
For a shared table, you could have inheritance in the table, but not in the object model.  
 
i.e. you have an SavingsAccount class and an ACCOUNT table but the ACCOUNT table also has checking account data that you want filtered.  
 
i.e. you have an SavingsAccount class and an ACCOUNT table but the ACCOUNT table also has checking account data that you want filtered.  

Revision as of 13:14, 18 May 2011

EclipseLink JPA


@AdditionalCriteria

Use @AdditionalCriteria to define parameterized views on data. You can define additional criteria on entities or mapped superclasses. When specified at the mapped superclass level, the additional criteria definition applies to all inheriting entities, unless those entities define their own additional criteria, in which case those defined for the mapped superclass are ignored.

Additional criteria can provide an additional filtering mechanism for queries. This filtering option, for example, allows you to use an existing additional JOIN expression defined for the entity or mapped superclass and allows you to pass parameters to it.


Defining Additional Criteria

Set additional criteria parameters through properties on the entity manager factory or on the entity manager. When set on the entity manager, you must set the properties before executing a query. Do not change the properties for the lifespan of that entity manager. Properties set on the entity manager override identically named properties set on the entity manager factory.

Additional criteria are not supported with native queries. The additional criteria definition supports any valid JPQL string and must use this as an alias to form the additional criteria. For example,

@AdditionalCriteria("this.address.city IS NOT NULL")

You can specify additional criteria using the @AdditionalCriteria annotation or the <additional-criteria> element, as shown in the following examples.

The following example shows additional criteria defined for the entity Employee and then shows the parameters for the additional criteria set on the entity manager.

Define additional criteria on Employee...

package model;
 
@AdditionalCriteria("this.company=:COMPANY")
public class Employee {
  ...
}

...then set the property on the EntityManager. This example returns all employees of MyCompany.

entityManager.setProperty("COMPANY", "MyCompany");


The following example shows the <additional-criteria> element used in the eclipselink-orm.xml descriptor:

<additional-criteria>
  <criteria>this.address.city IS NOT NULL</criteria>
</additional-criteria&>

Examples

Additional criteria are useful when working with multitenancy environments, soft deletes, history,

Multitenancy Example

In a multitenancy environment, tenants (users, clients, organizations, applications) can share database tables, but the views on the data must be restricted so that tenants have access only to their own data. You can use AdditionalCriteria to thus restrict views on the data. For example,

  • Use @AdditionalCriteria("TENANT = 'Billing'") to restrict the data for a “Billing” client, such as a billing application or billing organization.
  • You could use @AdditionalCriteria("this.tenant = :tenant") for an application that can be used by multiple different tenants at the same time. When the tenant acquires its EntityManagerFactory or EntityManager the persistence/entity manager property tenant is set to the name of the tenant acquring it.
         Map properties = new HashMap();
         properties.put("tenant", "ACME");
         EntityManagerFactory emf = Persistence.createEntityManagerFactory(properties);

or,

         Map properties = new HashMap();
         properties.put("tenant", "ACME");
         EntityManager em = factory.createEntityManager(properties);


Soft Delete Example

A soft delete is when a user marks data as deleted but does not actually delete it from the database, for example to keep a record.

For example,

@AdditionalCriteria("this.isDeleted = false") filters any delete data from any query.


History Example

History is when data is never removed or updated. On an update, a new row is inserted with a new start/end time instead.


@AdditionalCriteria("this.endDate is null") returns the current data from any query.

Or, you could create an EntityManager on a specific date, for example:

@AdditionalCriteria("this.startDate <= :viewDate and this.endDate >= :viewDate")

Shared Tables Example

For a shared table, you could have inheritance in the table, but not in the object model. i.e. you have an SavingsAccount class and an ACCOUNT table but the ACCOUNT table also has checking account data that you want filtered.


Eclipselink-logo.gif
Version: 2.2.0 DRAFT
Other versions...