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

From Eclipsepedia

Jump to: navigation, search
m
 
(26 intermediate revisions by 2 users not shown)
Line 7: Line 7:
 
|apis=
 
|apis=
 
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/annotations/AdditionalCriteria.html @AdditionalCriteria]
 
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/annotations/AdditionalCriteria.html @AdditionalCriteria]
 +
|nativeapi=y
 +
|nativeapis=
 
*[http://www.eclipse.org/eclipselink/api/latest//org/eclipse/persistence/descriptors/DescriptorQueryManager.html DescriptorQueryManager]
 
*[http://www.eclipse.org/eclipselink/api/latest//org/eclipse/persistence/descriptors/DescriptorQueryManager.html DescriptorQueryManager]
 
*[http://www.eclipse.org/eclipselink/api/latest///org/eclipse/persistence/expressions/Expression.html Expression]
 
*[http://www.eclipse.org/eclipselink/api/latest///org/eclipse/persistence/expressions/Expression.html Expression]
Line 13: Line 15:
 
=@AdditionalCriteria=
 
=@AdditionalCriteria=
  
Use <tt>@AdditionalCriteria</tt> to define parameterized views on data. You can define additional criteria on entities or mapped superclasses.  
+
Use <tt>@AdditionalCriteria</tt> 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.  
 
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.  
  
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.
+
{{EclipseLink_AttributeTable
 +
|caption=@AdditionalCriteria Attributes
 +
|content=<tr>
 +
<td>'''<tt>value</tt>'''</td>
 +
<td>The JPQL fragment to use as the additional criteria.</td>
 +
<td></td>
 +
<td>Yes</td>
 +
</tr>
 +
}}
 +
 
 +
 
 +
==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. Properties set on the entity manager override identically named properties set on the entity manager factory. Properties must be set on an entity manager before executing a query. Do not change the properties for the lifespan of the entity manager.  
  
Additional criteria are not supported with ative 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,
+
Specify additional criteria using the <tt>@AdditionalCriteria</tt> annotation or the <tt>&lt;additional-criteria&gt;</tt> element. 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,
  
 
<source lang="java">
 
<source lang="java">
 
@AdditionalCriteria("this.address.city IS NOT NULL")
 
@AdditionalCriteria("this.address.city IS NOT NULL")
 
</source>
 
</source>
 
You can specify additional criteria using the <tt>@AdditionalCriteria</tt> annotation or the <tt>&lt;additional-criteria&gt;</tt> element, as shown in the following examples.
 
  
 
The following example shows additional criteria defined for the entity <tt>Employee</tt> and then shows the parameters for the additional criteria set on the entity manager.
 
The following example shows additional criteria defined for the entity <tt>Employee</tt> and then shows the parameters for the additional criteria set on the entity manager.
  
Define additional criteria on <tt>Employee</tt>...
+
Define additional criteria on <tt>Employee</tt>, as follows,...
  
 
<source lang="java">
 
<source lang="java">
Line 53: Line 64:
 
The following example shows the <tt><additional-criteria></tt> element used in the <tt>eclipselink-orm.xml</tt> descriptor:
 
The following example shows the <tt><additional-criteria></tt> element used in the <tt>eclipselink-orm.xml</tt> descriptor:
  
 +
======'' Example: additional-criteria Element''======
 
<source lang="xml">
 
<source lang="xml">
 
<additional-criteria>
 
<additional-criteria>
 
   <criteria>this.address.city IS NOT NULL</criteria>
 
   <criteria>this.address.city IS NOT NULL</criteria>
</additional-criteria&>
+
</additional-criteria>
 
</source>
 
</source>
  
==Uses of AdditionalCriteria==
+
==Uses for Additional Criteria==
 +
Uses for additional criteria include:
 +
*[[#Multitenancy Example|Multitenancy]]
 +
*[[#Soft Delete Example|Soft deletes]]
 +
*[[#History Example|Data history]]
 +
*[[#Temporal Filtering Example|Temporal filtering]]
 +
*[[#Shared Table Example|Shared tables]]
  
Use AdditionalCriteria is to define parameterized views on data.
+
====Multitenancy Example====
  
Uses include the following:
+
In a multitenancy environment, tenants (users, clients, organizations, applications) can share database tables, but the views on the data are restricted so that tenants have access only to their own data. You can use additional criteria to configure such restrictions. 
*[[#Multitenancy|Multitenancy]]
+
*[[#Soft Deletes|Soft Deletes]]
+
*[[#Multitenancy|Multitenancy]]
+
  
===Multitenancy===
+
=====Multitenancy Example 1 =====
  
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,
+
The following example restricts the data for a “Billing” client, such as a billing application or billing organization:
 +
<source lang="java">
 +
@AdditionalCriteria("this.tenant = 'Billing'")
 +
</source>
  
* Use <tt>@AdditionalCriteria("TENANT = 'Billing'")</tt> to restrict the data for a “Billing” client, such as a billing application or billing organization.
+
=====Multitenancy Example 2 =====
  
* You could use <tt>@AdditionalCriteria("this.tenant = :tenant")</tt> for an application that can be used by multiple different tenants at the same time. When the tenant acquires its <tt>EntityManagerFactory</tt> or <tt>EntityManager</tt> the persistence/entity manager property <tt>tenant</tt> is set to the name of the tenant acquring it.
+
The following example could be used in an application used by multiple tenants at the same time. The additional criteria is defined as:
  
          Map properties = new HashMap();
+
<source lang="java">
          properties.put("tenant", "ACME");
+
@AdditionalCriteria("this.tenant = :tenant")
          EntityManagerFactory emf = Persistence.createEntityManagerFactory(properties);
+
</source>
  
or,  
+
When the tenant acquires its <tt>EntityManagerFactory</tt> or <tt>EntityManager</tt>, the persistence/entity manager property <tt>tenant</tt> is set to the name of the tenant acquiring it. For example,
          Map properties = new HashMap();
+
          properties.put("tenant", "ACME");
+
          EntityManager em = factory.createEntityManager(properties);
+
  
+
<source lang="java">
===Soft Deletes===
+
Map properties = new HashMap();
 +
properties.put("tenant", "ACME");
 +
EntityManagerFactory emf = Persistence.createEntityManagerFactory(properties);
 +
</source>
  
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.
+
or
  
For example,
+
<source lang="java">
+
Map properties = new HashMap();
<tt>@AdditionalCriteria("this.isDeleted = false")</tt> filters any delete data from any query.
+
properties.put("tenant", "ACME");
 +
EntityManager em = factory.createEntityManager(properties);
 +
</source>
  
===History===
+
====Soft Delete 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.
+
  
 +
The following example filters data that is marked as deleted (but which still exists in the table) from a query:
 +
 +
<source lang="java">
 +
@AdditionalCriteria("this.isDeleted = false")
 +
</source>
 +
 +
====Data History Example====
 
<!--We have specific history support, but if the user just wants something simpler or more generic they can use criteria. -->
 
<!--We have specific history support, but if the user just wants something simpler or more generic they can use criteria. -->
  
<tt>@AdditionalCriteria("this.endDate is null")</tt> returns the current data from any query.
+
The following example returns the current data from a query, thus filtering out any out-of-date data, for example data stored in a history table.
  
Or, you could create an <tt>EntityManager</tt> on a specific date, for example:
+
<source lang="java">
 +
@AdditionalCriteria("this.endDate is null")
 +
</source>  
  
<tt>@AdditionalCriteria("this.startDate <= :viewDate and this.endDate >= :viewDate")</tt>  
+
Note: EclipseLink also provides specific history support, via [http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/history/HistoryPolicy.html <tt>HistoryPolicy</tt> ]. See [http://wiki.eclipse.org/EclipseLink/Examples/JPA/History Tracking Changes Using History Policy].
  
===Shared Tables===
+
====Temporal Filtering 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.
+
  
 +
The following example filters on a specific date:
  
 +
<source lang="java">
 +
@AdditionalCriteria("this.startDate <= :viewDate and this.endDate >= :viewDate")
 +
</source>
 +
 +
====Shared Table Example====
 +
 +
For a shared table, there may be inheritance in the table but not in the object model.
 +
For example, a <tt>SavingsAccount</tt> class may be mapped to an ACCOUNT table, but the ACCOUNT table contains both savings account data (SAVINGS) and checking account (CHECKING) data. You can use additional criteria to filter out the checking account data.
 +
 +
<!--
 +
<source lang="java">
 +
@AdditionalCriteria("this.savings=:SAVINGS")
 +
</source>
 +
-->
  
 
{{EclipseLink_JPA
 
{{EclipseLink_JPA

Latest revision as of 13:51, 14 June 2011

EclipseLink JPA

link="http://wiki.eclipse.org/EclipseLink"
EclipseLink
Website
Download
Community
Mailing ListForumsIRC
Bugzilla
Open
Help Wanted
Bug Day
Contribute
Browse Source


[edit] @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.

@AdditionalCriteria Attributes
Attribute Description Default Required?
value The JPQL fragment to use as the additional criteria. Yes


[edit] Defining Additional Criteria

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

Additional criteria are not supported with native queries.

Specify additional criteria using the @AdditionalCriteria annotation or the <additional-criteria> element. 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")

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, as follows,...

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:

[edit] Example: additional-criteria Element
<additional-criteria>
  <criteria>this.address.city IS NOT NULL</criteria>
</additional-criteria>

[edit] Uses for Additional Criteria

Uses for additional criteria include:

[edit] Multitenancy Example

In a multitenancy environment, tenants (users, clients, organizations, applications) can share database tables, but the views on the data are restricted so that tenants have access only to their own data. You can use additional criteria to configure such restrictions.

[edit] Multitenancy Example 1

The following example restricts the data for a “Billing” client, such as a billing application or billing organization:

@AdditionalCriteria("this.tenant = 'Billing'")
[edit] Multitenancy Example 2

The following example could be used in an application used by multiple tenants at the same time. The additional criteria is defined as:

@AdditionalCriteria("this.tenant = :tenant")

When the tenant acquires its EntityManagerFactory or EntityManager, the persistence/entity manager property tenant is set to the name of the tenant acquiring it. For example,

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);

[edit] Soft Delete Example

The following example filters data that is marked as deleted (but which still exists in the table) from a query:

@AdditionalCriteria("this.isDeleted = false")

[edit] Data History Example

The following example returns the current data from a query, thus filtering out any out-of-date data, for example data stored in a history table.

@AdditionalCriteria("this.endDate is null")

Note: EclipseLink also provides specific history support, via HistoryPolicy . See Tracking Changes Using History Policy.

[edit] Temporal Filtering Example

The following example filters on a specific date:

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

[edit] Shared Table Example

For a shared table, there may be inheritance in the table but not in the object model. For example, a SavingsAccount class may be mapped to an ACCOUNT table, but the ACCOUNT table contains both savings account data (SAVINGS) and checking account (CHECKING) data. You can use additional criteria to filter out the checking account data.


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