blob: 1b9b0075dfa30e45a9331b775a6e413add5faddb [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<meta http-equiv="Content-Script-Type" content="text/javascript" />
<title>About the Criteria API | EclipseLink 3.0.x Understanding EclipseLink</title>
<meta name="generator" content="Oracle DARB XHTML Converter (Mode = document) - Version 1.0.22 Build 1" />
<meta name="date" content="2014-06-10T10:39:53Z" />
<meta name="robots" content="noarchive" />
<meta name="doctitle" content="About the Criteria API" />
<meta name="relnum" content="3.0" />
<link rel="stylesheet" type="text/css" href="../../dcommon/style.css" media="screen" />
<link rel="copyright" href="../../dcommon/html/cpyr.htm" title="Copyright" type="text/html" />
<link rel="start" href="../../index.htm" title="Home" type="text/html" />
<link rel="contents" href="toc.htm" title="Contents" type="text/html" />
<link rel="prev" href="queries003.htm" title="Previous" type="text/html" />
<link rel="next" href="queries005.htm" title="Next" type="text/html" />
<!-- START: Disqus --><script type="text/javascript"> var disqus_developer = 0; </script><!-- END: Disqus --><!-- START: Sharethis --><script type="text/javascript">var switchTo5x=true;</script><script type="text/javascript" src="http://w.sharethis.com/button/buttons.js"></script><script type="text/javascript" src="http://s.sharethis.com/loader.js"></script> <!-- END: Sharethis --></head>
<body bgcolor="#FFFFFF"><iframe id="docheader" frameborder="0" framemargin="0" scrolling="no" src="../../dcommon/header.html"></iframe><script src="http://www.google.com/jsapi" type="text/javascript"></script><script type="text/javascript"> google.load('search', '1', {language : 'en'}); google.setOnLoadCallback(function() { var customSearchOptions = {}; var googleAnalyticsOptions = {}; googleAnalyticsOptions['queryParameter'] = 'q'; googleAnalyticsOptions['categoryParameter'] = ''; customSearchOptions['googleAnalyticsOptions'] = googleAnalyticsOptions; var customSearchControl = new google.search.CustomSearchControl( '016171230611334810008:mdbgdwjv8zu', customSearchOptions); customSearchControl.setResultSetSize(google.search.Search.FILTERED_CSE_RESULTSET); var options = new google.search.DrawOptions(); options.setSearchFormRoot('cse-search-form'); customSearchControl.draw('cse', options); }, true);</script><link rel="stylesheet" href="http://www.google.com/cse/style/look/default.css" type="text/css" /><div id="cse" style="width:100%;"></div>
<div class="header"><a id="top" name="top"></a>
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%">
<tr>
<td align="left" valign="top"><div class="booktitle">Understanding EclipseLink,
<b>3.0</b><br /></font></td>
<td valign="bottom" align="right" width="144">
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%">
<tr>
<td>&nbsp;</td>
<td align="center" valign="top"><a href="toc.htm"><img src="../../dcommon/images/contents.png" alt="Go To Table Of Contents" border="0" height="16" width="16" /><br />
</td><td>&nbsp;</td><td align="center"><a href="../../" target="_top" class="external text" title="Search" rel="nofollow"><img src="../../dcommon/images/search.png" alt="Search" style="border:0;" /><br /><span class="mini"></span></a></td><td>&nbsp;</td><td align="center"><a href="../eclipselink_otlcg.pdf" title="PDF" target="_blank"><img src="../../dcommon/images/pdf_icon.png" style="padding-right:5px;border:0" alt="PDF"></a></td>
</tr>
</table>
</td>
</tr>
</table>
<hr />
<table class="navigation simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100" align="center">
<tr>
<td align="center"><a href="queries003.htm"><img src="../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
<td align="center"><a href="queries005.htm"><img src="../../dcommon/images/rarrow.png" alt="Next" border="0" height="16" width="16" /></a></td>
<td>&nbsp;</td>
</tr>
</table>
</div>
<!-- class="header" -->
<div class="ind"><!-- End Header --><a id="A7714964" name="A7714964"></a><a id="OTLCG94376" name="OTLCG94376"></a>
<div class="sect1"><!-- infolevel="all" infotype="General" -->
<h1 class="sect1"><font face="arial, helvetica, sans-serif" color="#330099">About the Criteria API</font></h1>
<p>The Java Persistence Criteria API is used to define dynamic queries through the construction of object-based query definition objects, rather than use of the string-based approach of JPQL. The Criteria API allows dynamic queries to be built programmatically offering better integration with the Java language than a string-based 4th GL approach.</p>
<p>The Criteria API has two modes, the type-restricted mode, and the non-typed mode. The type-restricted mode uses a set of JPA metamodel generated classes to define the query-able attributes of a class. The non-typed mode uses strings to reference attributes of a class.</p>
<p>The Criteria API is only for dynamic queries, and cannot be used in metadata or named queries. Criteria queries are dynamic queries and do not perform as well as static named queries, or even dynamic parametrized JPQL which benefit from EclipseLink's parse cache.</p>
<p>For more information, see Chapter 6 "Criteria API" in the JPA Specification.</p>
<p><code><a href="http://jcp.org/en/jsr/detail?id=338">http://jcp.org/en/jsr/detail?id=338</a></code></p>
<p><code>CriteriaBuilder</code> is the main interface into the Criteria API. A <code>CriteriaBuilder</code> is obtained from an <code>EntityManager</code> or an <code>EntityManagerFactory</code> using the <code>getCriteriaBuilder()</code> API. <code>CriteriaBuilder</code> is used to construct <code>CriteriaQuery</code> objects and their expressions. The Criteria API currently only supports select queries.</p>
<p><code>CriteriaQuery</code> defines a database select query. A <code>CriteriaQuery</code> models all of the clauses of a JPQL select query. Elements from one <code>CriteriaQuery</code> cannot be used in other <code>CriteriaQuerys</code>. A <code>CriteriaQuery</code> is used with the <code>EntityManager</code> <code>createQuery()</code> API to create a JPA Query.</p>
<p>The <code>where</code> clause is normally the main part of the query as it defines the conditions (predicates) that filter what is returned. The <code>where</code> clause is defined using the <code>where</code> API on <code>CriteriaQuery</code> with any <code>Predicate</code> objects. A <code>Predicate</code> is obtained using a comparison operation, or a logical operation on <code>CriteriaBuilder</code>. The <code>isNull</code>, <code>isNotNull</code>, and <code>in</code> operations can also be called on <code>Expression</code> objects. The <code>not</code> operation can also be called on <code>Predicate</code> objects.</p>
<p>Subqueries can be used in the Criteria API in the <code>select</code>, <code>where</code>, <code>order</code>, <code>group</code> <code>by</code>, or <code>having</code> clauses. A subquery is created from a <code>CriteriaQuery</code> using the <code>subquery</code> operation. Most <code>subquery</code> usage restricts the subquery to returning a single result and value, unless used with the <code>CriteriaBuilder</code> <code>exists</code>, <code>all</code>, <code>any</code>, or <code>some</code> operations, or with an <code>in</code> operation.</p>
<p>Parameters can be defined using the <code>parameter</code> API on <code>CriteriaBuilder</code>. JPA defines named parameters, and positional parameters. For named parameters the parameter type and name are specified. For positional parameters only the parameter type is specified. Positional parameters start at position <code>1</code> not <code>0</code>.</p>
<p>Several database functions are supported by the Criteria API. All supported functions are defined on <code>CriteriaBuilder</code>. Some functions may not be supported by some databases, if they are not SQL compliant, and offer no equivalent function.</p>
<p>The Criteria API defines several special operations that are not database functions, but have special meaning in JPA. Some of these operations are defined on <code>CriteriaBuilder</code> and some are on specific Expression interfaces.</p>
<p>JPA defines a meta-model that can be used at runtime to query information about the ORM mapping metadata. The meta-model includes the list of mapped attributes for a class, and their mapping types and cardinality. The meta-model can be used with the Criteria API in place of using strings to reference the class attributes.</p>
<p>JPA defines a set of "<code>_</code>" classes ("<code>_MyEntity.java</code>", for example) that are to be generated by the JPA provider, or IDE, that give compile time access to the meta-model. This allows typed static variables to be used in the Criteria API. This can reduce the occurrence of typos, or invalid queries in application code, by catching query issues at compile time, instead of during testing. It does however add complexity to the development process, as the meta-model static class needs to be generated, and be part of the development cycle.</p>
<p>A Tuple defines a multi-select query result. Normally an object array is returned by JPA multi-select queries, but an object array is not a very useful data structure. A Tuple is a map-like structure that allows the results to be retrieved by name or index.</p>
<a id="OTLCG94396" name="OTLCG94396"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" --><a id="sthref64" name="sthref64"></a>
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">EclipseLink Extensions to the Criteria API</font></h2>
<p>EclipseLink's Criteria API support has fewer restrictions than specified by JPA. In general, sub-queries and object path expressions are allowed in most places, including:</p>
<ul>
<li>
<p>Sub-queries in the select, group by, and order clauses;</p>
</li>
<li>
<p>Sub-query usage with functions;</p>
</li>
<li>
<p>in usage with object path expressions;</p>
</li>
<li>
<p>Order by usage with object path expressions.</p>
</li>
</ul>
<p>EclipseLink's Criteria API support is built on top of EclipseLink native <code>Expression</code> API. EclipseLink provides the <code>JpaCriteriaBuilder</code> interface to allow the conversion of native <code>Expression</code> objects to and from JPA <code>Expression</code> objects. This allows the EclipseLink native <code>Expression</code> API to be mixed with the JPA Criteria API.</p>
<p>The EclipseLink native <code>Expression</code> API provides the following additional functionality:</p>
<ul>
<li>
<p>Additional database functions (over 80 database functions are supported)</p>
</li>
<li>
<p>Usage of custom <code>ExpressionOperators</code></p>
</li>
<li>
<p>Embedding of SQL within an <code>Expression</code> query</p>
</li>
<li>
<p>Usage of sub-selects in the from clause</p>
</li>
<li>
<p><code>ON</code> clause support</p>
</li>
<li>
<p>Access to unmapped columns and tables</p>
</li>
<li>
<p>Historical querying</p>
</li>
</ul>
<p>EclipseLink <code>Expressions</code> can be combined with EclipseLink <code>DatabaseQuerys</code> to provide additional functionality:</p>
<ul>
<li>
<p>Unions, intersect and except clauses;</p>
</li>
<li>
<p>Hierarchical connect by clauses;</p>
</li>
<li>
<p>Batch fetching.</p>
</li>
</ul>
</div>
<!-- class="sect2" --></div>
<!-- class="sect1" --></div>
<!-- class="ind" -->
<!-- Start Footer -->
<div class="footer">
<hr />
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%">
<col width="33%" />
<col width="*" />
<col width="33%" />
<tr>
<td valign="bottom">
<table class="navigation simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100" align="center">
<col width="*" />
<col width="48%" />
<col width="48%" />
<tr>
<td>&nbsp;</td>
<td align="center"><a href="queries003.htm"><img src="../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
<td align="center"><a href="queries005.htm"><img src="../../dcommon/images/rarrow.png" alt="Next" border="0" height="16" width="16" /></a></td>
</tr>
</table>
</td>
<td align="center" width="34%"><a href="http://www.eclipse.org/eclipselink/" title="EclipseLink home"><img src="../../dcommon/images/ellogo.png" alt="EclipseLink" width="150" border="0" /></a><br />
<td valign="bottom" align="right">
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="225">
<tr>
<td>&nbsp;</td>
<td align="center" valign="top"><a href="toc.htm"><img src="../../dcommon/images/contents.png" alt="Go To Table Of Contents" border="0" height="16" width="16" /><br />
</td><td>&nbsp;</td><td align="center"><a href="../../" target="_top" class="external text" title="Search" rel="nofollow"><img src="../../dcommon/images/search.png" alt="Search" style="border:0;" /><br /><span class="mini"></span></a></td><td>&nbsp;</td><td align="center"><a href="../eclipselink_otlcg.pdf" title="PDF" target="_blank"><img src="../../dcommon/images/pdf_icon.png" style="padding-right:5px;border:0" alt="PDF"></a></td>
</tr>
</table>
</td>
</tr>
</table>
</div>
<!-- class="footer" -->
<div id="copyright">Copyright &copy; 2012 by The Eclipse Foundation under the <a href="http://www.eclipse.org/org/documents/epl-v10.php">Eclipse Public License (EPL)</a><br /> <script type="text/javascript">var LastUpdated = document.lastModified;document.writeln ("Updated: " + LastUpdated);</script> </div><!-- START: Analytics --><script type="text/javascript"> var _gaq = _gaq || []; _gaq.push(['_setAccount', 'UA-1608008-2']); _gaq.push(['_trackPageview']); (function() { var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); })(); </script><!-- END: Analytics --><!-- START: Sharethis --><script>var options={ "publisher": "e2fe9e07-fab6-4f84-83ea-0991b429842c", "position": "right", "ad": { "visible": false, "openDelay": 5, "closeDelay": 0}};var st_hover_widget = new sharethis.widgets.hoverbuttons(options);</script><!-- END: Sharethis --></body>
</html>