|
|
| (8 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| − | {{EclipseLink_TLJPA
| + | #REDIRECT [[EclipseLink/UserGuide/JPA/2.4/toc]] |
| − | |info=n
| + | |
| − | |toc=n
| + | |
| − | |category=JPA
| + | |
| − | |release=2.4.x
| + | |
| − | |title=Java Persistence API (JPA) Extensions Reference for EclipseLink}}
| + | |
| − | <span class="metaname"> </span>
| + | |
| − | | + | |
| − | {| class="simple oac_no_warn" width="100%"
| + | |
| − | | align="left" valign="top" |
| + | |
| − | | width="165" align="right" valign="bottom" |
| + | |
| − | {| class="simple oac_no_warn" width="100%"
| + | |
| − | |
| + | |
| − | | align="center" valign="top" |
| + | |
| − | [[Image:Elug_Magnifier.png|Search]][http://www.google.com/cse/home?cx=016171230611334810008:y5kxq4rqd8s&hl=en Search]
| + | |
| − | | align="center" valign="top" |
| + | |
| − | [[EclipseLink/UserGuide/JPA/2.4/toc| Contents]]
| + | |
| − | |}
| + | |
| − | |}
| + | |
| − | | + | |
| − | ----
| + | |
| − | | + | |
| − | {| width="165"
| + | |
| − | | align="center" |
| + | |
| − | [[EclipseLink/UserGuide/JPA/2.4/annotations_ref002| Previous ]]<span class="previouslink">[[Image:Elug_previous_icon.png|Previous]]</span>
| + | |
| − | | align="center" |
| + | |
| − | [[EclipseLink/UserGuide/JPA/2.4/a_array| Next ]][[Image:Elug_next_icon.png|Next]]
| + | |
| − | |
| + | |
| − | |}
| + | |
| − | | + | |
| − | <span id="additionalcriteria"></span>
| + | |
| − | | + | |
| − | ----
| + | |
| − | | + | |
| − | ==@AdditionalCriteria==
| + | |
| − | | + | |
| − | Use <code>@AdditionalCriteria</code> to define parameterized views on data. You can define additional criteria on entities or mapped superclass. 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.
| + | |
| − | | + | |
| − | <span id="sthref15"></span>
| + | |
| − | | + | |
| − | ''' '''
| + | |
| − | | + | |
| − | ===Annotation Elements===
| + | |
| − | | + | |
| − | [[#CHDGJGDCxx|Table 2-1]] describes this annotation's elements.
| + | |
| − | | + | |
| − | <span id="sthref16"></span><span id="CHDGJGDCxx"></span>
| + | |
| − | | + | |
| − | '''''Table 2-1 @AdditionalCriteria Annotation Elements'''''
| + | |
| − | | + | |
| − | {| class="HRuleFormalWide" dir="ltr" title="@AdditionalCriteria Annotation Elements" summary="This table describes the list of attributes for this annotation." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
| + | |
| − | |- align="left" valign="top"
| + | |
| − | ! id="r1c1-t2" align="left" valign="bottom" | '''Attribute'''
| + | |
| − | ! id="r1c2-t2" align="left" valign="bottom" | '''Description'''
| + | |
| − | ! id="r1c3-t2" align="left" valign="bottom" | '''Default'''
| + | |
| − | |- align="left" valign="top"
| + | |
| − | | id="r2c1-t2" headers="r1c1-t2" align="left" |
| + | |
| − | <code>value</code>
| + | |
| − | | headers="r2c1-t2 r1c2-t2" align="left" |
| + | |
| − | (Required) The JPQL fragment to use as the additional criteria.
| + | |
| − | | headers="r2c1-t2 r1c3-t2" align="left" | <br />
| + | |
| − | |}
| + | |
| − | | + | |
| − | <br />
| + | |
| − | | + | |
| − | <span id="sthref17"></span>
| + | |
| − | | + | |
| − | ''' '''
| + | |
| − | | + | |
| − | ===Usage===
| + | |
| − | | + | |
| − | Additional criteria can provide an additional filtering mechanism for queries. This filtering option, for example, allows you to use an existing additional <code>JOIN</code> expression defined for the entity or mapped superclass and allows you to pass parameters to it.
| + | |
| − | | + | |
| − | 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.
| + | |
| − | | + | |
| − | <br />
| + | |
| − | | + | |
| − | {| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
| + | |
| − | | align="left" |
| + | |
| − | [[Image:Elug_note_icon.png|Note]] '''Note:'''
| + | |
| − | | + | |
| − | Additional criteria are not supported with native queries.
| + | |
| − | |}
| + | |
| − | | + | |
| − | <br />
| + | |
| − | | + | |
| − | <span id="sthref18"></span>
| + | |
| − | | + | |
| − | ''' '''
| + | |
| − | | + | |
| − | ===Examples===
| + | |
| − | | + | |
| − | Specify additional criteria using the <code>@AdditionalCriteria</code> annotation or the <code><additional-criteria></code> element. The additional criteria definition supports any valid JPQL string and must use <code>this</code> as an alias to form the additional criteria. For example:
| + | |
| − | | + | |
| − |
| + | |
| − | @AdditionalCriteria("this.address.city IS NOT NULL")
| + | |
| − | | + | |
| − | [[#CFHFACAI|Example 2-1]] shows additional criteria defined for the entity <code>Employee</code> and then shows the parameters for the additional criteria set on the entity manager.
| + | |
| − | | + | |
| − | <span id="CFHFACAI"></span>
| + | |
| − | | + | |
| − | '''''Example 2-1 Using @AdditionalCriteria Annotation'''''
| + | |
| − | | + | |
| − | Define additional criteria on <code>Employee</code>, as follows:
| + | |
| − | | + | |
| − |
| + | |
| − | package model;
| + | |
| − |
| + | |
| − | @AdditionalCriteria("this.company=:COMPANY")
| + | |
| − | public class Employee {
| + | |
| − |
| + | |
| − | ...
| + | |
| − | }
| + | |
| − | | + | |
| − | Set the property on the <code>EntityManager</code>. This example returns all employees of <code>MyCompany</code>.
| + | |
| − | | + | |
| − |
| + | |
| − | entityManager.setProperty("COMPANY", "MyCompany");
| + | |
| − | | + | |
| − | [[#CFHHBDFE|Example 2-2]] illustrates the same example as before, but uses the <code><additional-criteria></code> element in the <code>eclipselink-orm.xml</code> mapping file.
| + | |
| − | | + | |
| − | <span id="CFHHBDFE"></span>
| + | |
| − | | + | |
| − | '''''Example 2-2 Using <additional-criteria> XML'''''
| + | |
| − | | + | |
| − |
| + | |
| − | <additional-criteria>
| + | |
| − | <criteria>this.address.city IS NOT NULL</criteria>
| + | |
| − | </additional-criteria>
| + | |
| − | | + | |
| − | <span id="sthref19"></span>
| + | |
| − | | + | |
| − | '''Uses for Additional Criteria'''
| + | |
| − | | + | |
| − | Uses for additional criteria include:
| + | |
| − | | + | |
| − | <span id="sthref20"></span>
| + | |
| − | | + | |
| − | '''Multitenancy'''
| + | |
| − | | + | |
| − | 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.
| + | |
| − | | + | |
| − | <span id="sthref21"></span>
| + | |
| − | | + | |
| − | '''''Example 2-3 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'")
| + | |
| − | | + | |
| − | <span id="sthref22"></span>
| + | |
| − | | + | |
| − | '''''Example 2-4 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 <code>EntityManagerFactory</code> or <code>EntityManager</code>, 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);
| + | |
| − | | + | |
| − | <span id="sthref23"></span>
| + | |
| − | | + | |
| − | '''Soft Delete'''
| + | |
| − | | + | |
| − | The following example filters data that is marked as deleted (but which still exists in the table) from a query:
| + | |
| − | | + | |
| − |
| + | |
| − | @AdditionalCriteria("this.isDeleted = false")
| + | |
| − | | + | |
| − | <span id="sthref24"></span>
| + | |
| − | | + | |
| − | '''Data History'''
| + | |
| − | | + | |
| − | 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")
| + | |
| − | | + | |
| − | <br />
| + | |
| − | | + | |
| − | {| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
| + | |
| − | | align="left" |
| + | |
| − | [[Image:Elug_note_icon.png|Note]] '''Note:'''
| + | |
| − | | + | |
| − | EclipseLink also provides specific history support, via <code>HistoryPolicy</code> . See Tracking Changes Using History Policy at <code>http://wiki.eclipse.org/EclipseLink/Examples/JPA/History</code>.
| + | |
| − | |}
| + | |
| − | | + | |
| − | <br />
| + | |
| − | | + | |
| − | <span id="sthref25"></span>
| + | |
| − | | + | |
| − | '''Temporal Filtering'''
| + | |
| − | | + | |
| − | The following example filters on a specific date:
| + | |
| − | | + | |
| − |
| + | |
| − | @AdditionalCriteria("this.startDate <= :viewDate and this.endDate >= :viewDate")
| + | |
| − | | + | |
| − | <span id="sthref26"></span>
| + | |
| − | | + | |
| − | '''Shared Table'''
| + | |
| − | | + | |
| − | For a shared table, there may be inheritance in the table but not in the object model. For example, a <code>SavingsAccount</code> class may be mapped to an <code>ACCOUNT</code> table, but the <code>ACCOUNT</code> table contains both savings account data (<code>SAVINGS</code>) and checking account (<code>CHECKING</code>) data. You can use additional criteria to filter out the checking account data.
| + | |
| − | | + | |
| − | <span id="sthref27"></span>
| + | |
| − | | + | |
| − | ''' '''
| + | |
| − | | + | |
| − | ===See Also===
| + | |
| − | | + | |
| − | For more information, see:
| + | |
| − | | + | |
| − | * [[EclipseLink/UserGuide/JPA/2.4/j_column|"COLUMN"]]
| + | |
| − | | + | |
| − | <span id="footerspace"> </span>
| + | |
| − | | + | |
| − | ----
| + | |
| − | | + | |
| − | {| class="simple oac_no_warn" width="100%"
| + | |
| − | |-
| + | |
| − | | valign="bottom" |
| + | |
| − | {| width="165"
| + | |
| − | |-
| + | |
| − | |
| + | |
| − | | align="center" |
| + | |
| − | [[EclipseLink/UserGuide/JPA/2.4/annotations_ref002| Previous ]]<span class="previouslink">[[Image:Elug_previous_icon.png|Previous]]</span>
| + | |
| − | | align="center" |
| + | |
| − | [[EclipseLink/UserGuide/JPA/2.4/a_array| Next ]][[Image:Elug_next_icon.png|Next]]
| + | |
| − | |}
| + | |
| − | | width="34%" align="center" |
| + | |
| − | [[Image:Eclipselink-logo.gif|150px|EclispeLink]]<br />[[Image:Elug_home_icon.png|EclipseLink logo]][http://www.eclipse.org/eclipselink/ EclipseLink Home][[Image:Elug_pdf.png|PDF]]PDF (coming soon)<br />
| + | |
| − | | align="right" valign="bottom" |
| + | |
| − | {| class="simple oac_no_warn" width="225"
| + | |
| − | |
| + | |
| − | | align="center" valign="top" |
| + | |
| − | [[Image:Elug_Magnifier.png|Search]][http://www.google.com/cse/home?cx=016171230611334810008:y5kxq4rqd8s&hl=en Search]
| + | |
| − | | align="center" valign="top" |
| + | |
| − | [[EclipseLink/UserGuide/JPA/2.4/toc| Contents]] | + | |
| − | |}
| + | |
| − | |}
| + | |
