blob: 50c3e466a1b152e9af0abc773cde55da3da6783f [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 Expression Components | 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 Expression Components" />
<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="expressions001.htm" title="Previous" type="text/html" />
<link rel="next" href="nosql.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="expressions001.htm"><img src="../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
<td align="center"><a href="nosql.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="CJAJIGEE" name="CJAJIGEE"></a><a id="OTLCG94244" name="OTLCG94244"></a>
<div class="sect1">
<h1 class="sect1"><font face="arial, helvetica, sans-serif" color="#330099">About Expression Components</font></h1>
<p>A simple expression usually consists of the following three parts:</p>
<ul>
<li>
<p>The <em>attribute</em>, which represents a mapped attribute or query key of the persistent class</p>
</li>
<li>
<p>The <em>operator</em>, which is an expression method that implements boolean logic, such as <code>GreaterThan</code>, <code>Equal</code>, or <code>Like</code></p>
</li>
<li>
<p>The <em>constant</em> or <em>comparison</em>, which refers to the value used to select the object</p>
</li>
</ul>
<p>In the following code fragment, the attribute is <code>lastName</code>, the operator is <code>equal</code> and the constant is the string "<code>Smith</code>". The <code>expressionBuilder</code> substitutes for the object or objects to be read from the database. In this example, <code>expressionBuilder</code> represents employees.</p>
<pre xml:space="preserve" class="oac_no_warn">
expressionBuilder.get("lastName").equal("Smith");
</pre>
<p>You can use the following components when constructing an <code>Expression</code>:</p>
<ul>
<li>
<p><a href="#CJABDJIC">Boolean Logic</a></p>
</li>
<li>
<p><a href="#CJAEGFGE">Database Functions and Operators</a></p>
</li>
<li>
<p><a href="#CJADHIHG">Oracle XMLType Functions</a></p>
</li>
<li>
<p><a href="#CJAGJAGI">Platform and User-Defined Functions</a></p>
</li>
<li>
<p><a href="#CJAGEJBC">Expressions for One-to-One and Aggregate Object Relationships</a></p>
</li>
<li>
<p><a href="#CJAIJIIF">Expressions for Joining and Complex Relationships</a></p>
</li>
</ul>
<a id="CJABDJIC" name="CJABDJIC"></a><a id="OTLCG94245" name="OTLCG94245"></a>
<div class="sect2">
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Boolean Logic</font></h2>
<p>Expressions use standard boolean operators, such as <code>AND</code>, <code>OR</code>, and <code>NOT</code>, and you can combine multiple expressions to form more complex expressions.</p>
</div>
<!-- class="sect2" -->
<a id="CJAEGFGE" name="CJAEGFGE"></a><a id="OTLCG94247" name="OTLCG94247"></a>
<div class="sect2">
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Database Functions and Operators</font></h2>
<p>EclipseLink supports many database functions using standard operator names that are translated to different databases. EclipseLink operators are supported on any database that has an equivalent function (or set of functions). For more information and a list of all supported functions and operators see "OPERATOR" and "FUNCTION" in <em>Jakarta Persistence API (JPA) Extensions Reference for EclipseLink</em></p>
<p>EclipseLink expressions support a variety of database functions, which are described in the <code>Expression</code> class. Database functions let you define more flexible queries. You can use these functions in either a report query using a <code>SELECT</code> clause, or with comparisons in a query's selection criteria using a <code>WHERE</code> clause.</p>
<div align="center">
<div class="inftblnote"><br />
<table class="Note oac_no_warn" summary="" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
<tbody>
<tr>
<td align="left">
<p class="note"><img src="../../dcommon/images/note_icon.png" width="16" height="16" alt="Note" style="vertical-align:middle;padding-right:5px;" />Note:</p>
<p>Some functions may be database platform-specific.</p>
</td>
</tr>
</tbody>
</table>
<br /></div>
<!-- class="inftblnote" --></div>
<p>Operators are relational operations that compare two values. EclipseLink expression operators are described in the <code>ExpressionOperator</code> class.</p>
<p>Mathematical functions are available through the <code>ExpressionMath</code> class. Mathematical function support in expressions is similar to the support provided by the Java class <code>java.lang.Math</code>.</p>
<a id="CJADHIHG" name="CJADHIHG"></a><a id="OTLCG94254" name="OTLCG94254"></a>
<div class="sect3">
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Oracle XMLType Functions</font></h3>
<p>You can use the following operators when constructing queries against data mapped to Oracle Database <code>XMLType</code> column:</p>
<ul>
<li>
<p><code>extract</code>&mdash;Takes an XPath string and returns an XMLType which corresponds to the part of the original document that matches the XPath.</p>
</li>
<li>
<p><code>extractValue</code>&mdash;Takes an XPath string and returns either a numerical or string value based on the contents of the node pointed to by the XPath.</p>
</li>
<li>
<p><code>existsNode</code>&mdash;Takes an XPath expression and returns the number of nodes that match the XPath.</p>
</li>
<li>
<p><code>getStringVal</code>&mdash;Gets the string representation of an <code>XMLType</code> object.</p>
</li>
<li>
<p><code>getNumberVal</code>&mdash;Gets the numerical representation of an <code>XMLType</code> object.</p>
</li>
<li>
<p><code>isFragment</code>&mdash;Evaluates to 0 if the XML is a well formed document. Evaluates to 1 if the document is a fragment.</p>
</li>
</ul>
</div>
<!-- class="sect3" --></div>
<!-- class="sect2" -->
<a id="CJAGJAGI" name="CJAGJAGI"></a><a id="OTLCG94256" name="OTLCG94256"></a>
<div class="sect2">
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Platform and User-Defined Functions</font></h2>
<p>You can use the <code>Expression</code> method <code>getFunction</code> to access database functions that EclipseLink does not support directly. The <code>Expression</code> API includes additional forms of the <code>getFunction</code> method that allow you to specify arguments. You can also create your own custom functions. For more information, see <em>Java API Reference for EclipseLink</em>.</p>
</div>
<!-- class="sect2" -->
<a id="CJAGEJBC" name="CJAGEJBC"></a><a id="OTLCG94258" name="OTLCG94258"></a>
<div class="sect2">
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Expressions for One-to-One and Aggregate Object Relationships</font></h2>
<p>Expressions can include an attribute that has a one-to-one relationship with another persistent class. A one-to-one relationship translates naturally into an SQL join that returns a single row.</p>
</div>
<!-- class="sect2" -->
<a id="CJAIJIIF" name="CJAIJIIF"></a><a id="OTLCG94260" name="OTLCG94260"></a>
<div class="sect2">
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Expressions for Joining and Complex Relationships</font></h2>
<p>You can query against complex relationships, such as one-to-many, many-to-many, direct collection, and aggregate collection relationships. Expressions for these types of relationships are more complex to build, because the relationships do not map directly to joins that yield a single row per object.</p>
<p>This section describes the following:</p>
<ul>
<li>
<p><a href="#CJABCJII">About Joins</a></p>
</li>
<li>
<p><a href="#CJAJIHBJ">Using EclipseLink Expression API for Joins</a></p>
</li>
</ul>
<a id="CJABCJII" name="CJABCJII"></a><a id="OTLCG94261" name="OTLCG94261"></a>
<div class="sect3">
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">About Joins</font></h3>
<p>A <strong>join</strong> is a relational database query that combines rows from two or more tables. Relational databases perform a join whenever multiple tables appear in the query's <code>FROM</code> clause. The query's select list can select any columns from any of these tables.</p>
<p>An inner join (sometimes called a "simple join") is a join of two or more tables that returns only those rows that satisfy the join condition.</p>
<p>An outer join extends the result of an inner join. An outer join returns all rows that satisfy the join condition and also returns some or all of those rows from one table for which no rows from the other satisfy the join condition. Outer joins can be categorized as left or right:</p>
<ul>
<li>
<p>A query that performs a left outer join of tables A and B returns all rows from A. For all rows in A that have no matching rows in B, the database returns null for any select list expressions containing columns of B.</p>
</li>
<li>
<p>A query that performs a right outer join of tables A and B returns all rows from B. For all rows in B that have no matching rows in A, the database returns null for any select list expressions containing columns of A.</p>
</li>
</ul>
<p>When you query with a join expression, EclipseLink can use joins to check values from other objects or other tables that represent parts of the same object. Although this works well under most circumstances, it can cause problems when you query against a one-to-one relationship, in which one side of the relationship is not present.</p>
<p>For example, <code>Employee</code> objects may have an <code>Address</code> object, but if the <code>Address</code> is unknown, it is <code>null</code> at the object level and has a null foreign key at the database level. When you attempt a read that traverses the relationship, missing objects cause the query to return unexpected results. Consider the following expression:</p>
<pre xml:space="preserve" class="oac_no_warn">
(emp.get("firstName").equal("Steve")).or(emp.get("address"). get("city").equal("Ottawa"))
</pre>
<p>In this case, employees with no address do not appear in the result set, regardless of their first name. Although not obvious at the object level, this behavior is fundamental to the nature of relational databases.</p>
<p>Outer joins rectify this problem in the databases that support them. In this example, the use of an outer join provides the expected result: all employees named Steve appear in the result set, even if their address is unknown.</p>
<p>To implement an outer join, use <code>Expression</code> method <code>getAllowingNull</code>, rather than <code>get</code>, and <code>Expression</code> method <code>anyOfAllowingNone</code>, rather than <code>anyOf</code>.</p>
<p>For example:</p>
<pre xml:space="preserve" class="oac_no_warn">
(emp.get("firstName").equal("Steve")).or(
emp.getAllowingNull("address").get("city").equal("Ottawa"))
</pre>
<p>Support and syntax for outer joins vary widely between databases and database drivers. EclipseLink supports outer joins for most databases.</p>
</div>
<!-- class="sect3" -->
<a id="CJAJIHBJ" name="CJAJIHBJ"></a><a id="OTLCG94262" name="OTLCG94262"></a>
<div class="sect3">
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Using EclipseLink Expression API for Joins</font></h3>
<p>You can use joins anywhere expressions are used, including: selection-criteria, ordering, report queries, partial objects, one-to-one relational mappings, and join reading.</p>
<p>Use the Expression API shown in <a href="#CACHEEHJ">Table 10-1</a> to configure inner and outer join expressions.</p>
<div class="tblhruleformal"><a id="OTLCG94263" name="OTLCG94263"></a><a id="sthref66" name="sthref66"></a><a id="CACHEEHJ" name="CACHEEHJ"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Table 10-1 Expression API for Joins</font></em></strong></p>
<table class="HRuleFormal" title="Expression API for Joins" summary="This table summarizes the expression operators you can use to configure joins and indicates which operators support inner and outer joins on one-to-one, one-to-many, and many-to-many mapped attributes." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
<col width="*" />
<col width="26%" />
<col width="34%" />
<thead>
<tr align="left" valign="top">
<th align="left" valign="bottom" id="r1c1-t3"><font face="Arial, Helvetica, sans-serif"><strong>Expression API</strong></font></th>
<th align="left" valign="bottom" id="r1c2-t3"><font face="Arial, Helvetica, sans-serif"><strong>Type of Join</strong></font></th>
<th align="left" valign="bottom" id="r1c3-t3"><font face="Arial, Helvetica, sans-serif"><strong>Type of Mapping</strong></font></th>
</tr>
</thead>
<tbody>
<tr align="left" valign="top">
<td align="left" id="r2c1-t3" headers="r1c1-t3">
<p><code>get</code></p>
</td>
<td align="left" headers="r2c1-t3 r1c2-t3">
<p>inner</p>
</td>
<td align="left" headers="r2c1-t3 r1c3-t3">
<p>one-to-one</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r3c1-t3" headers="r1c1-t3">
<p><code>getAllowingNull</code></p>
</td>
<td align="left" headers="r3c1-t3 r1c2-t3">
<p>outer</p>
</td>
<td align="left" headers="r3c1-t3 r1c3-t3">
<p>one-to-one</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r4c1-t3" headers="r1c1-t3">
<p><code>anyOf</code></p>
</td>
<td align="left" headers="r4c1-t3 r1c2-t3">
<p>inner</p>
</td>
<td align="left" headers="r4c1-t3 r1c3-t3">
<p>one-to-many, many-to-many</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r5c1-t3" headers="r1c1-t3">
<p><code>anyOfAllowingNone</code></p>
</td>
<td align="left" headers="r5c1-t3 r1c2-t3">
<p>outer</p>
</td>
<td align="left" headers="r5c1-t3 r1c3-t3">
<p>one-to-many, many-to-many</p>
</td>
</tr>
</tbody>
</table>
<br /></div>
<!-- class="tblhruleformal" -->
<p>To query across a one-to-many or many-to-many relationship, use the <code>anyOf</code> operation. As its name suggests, this operation supports queries that return all items on the "many" side of the relationship that satisfy the query criteria.</p>
</div>
<!-- class="sect3" --></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="expressions001.htm"><img src="../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
<td align="center"><a href="nosql.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>