You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cayenne.apache.org by aa...@apache.org on 2019/11/02 08:31:39 UTC
[cayenne-website] 01/02: refreshing 4.0 docs
This is an automated email from the ASF dual-hosted git repository.
aadamchik pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/cayenne-website.git
commit c48bfcdfddd71ddb2982a9b253e8560bfbddb507
Author: Andrus Adamchik <an...@objectstyle.com>
AuthorDate: Sat Nov 2 11:28:00 2019 +0300
refreshing 4.0 docs
---
src/main/site/content/docs/4.0/cayenne-guide.html | 171 ++++++++++++----------
1 file changed, 97 insertions(+), 74 deletions(-)
diff --git a/src/main/site/content/docs/4.0/cayenne-guide.html b/src/main/site/content/docs/4.0/cayenne-guide.html
index fb6bc0f..e259237 100644
--- a/src/main/site/content/docs/4.0/cayenne-guide.html
+++ b/src/main/site/content/docs/4.0/cayenne-guide.html
@@ -2034,8 +2034,15 @@ o.orderList(list);</code></pre>
<h4 id="select"><a class="anchor" href="#select"></a>ObjectSelect</h4>
<div class="sect4">
<h5 id="selecting-objects"><a class="anchor" href="#selecting-objects"></a>Selecting objects</h5>
- <div class="paragraph">
- <p>ObjectSelect supersedes older SelectQuery. SelectQuery is still available and supported.</p>
+ <div class="admonitionblock note">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa fa-info-circle fa-2x" title="Note"></i> </td>
+ <td class="content"> ObjectSelect supersedes older SelectQuery. SelectQuery is still available and supported, but will be deprecated in the future. </td>
+ </tr>
+ </tbody>
+ </table>
</div>
<div class="paragraph">
<p>ObjectSelect is the most commonly used query in Cayenne applications. This may be the only query you will ever need. It returns a list of persistent objects (or data rows) of a certain type specified in the query:</p>
@@ -2107,12 +2114,13 @@ INFO: === returned 1 row. - took 6 ms.</pre>
</div>
<div class="listingblock">
<div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">List<String> names = ObjectSelect.columnQuery(Artist.class, Artist.ARTIST_NAME)
+ <pre class="highlight"><code class="language-java java" data-lang="java">List<String> names = ObjectSelect
+ .columnQuery(Artist.class, Artist.ARTIST_NAME)
.select(context);</code></pre>
</div>
</div>
<div class="paragraph">
- <p>And here is example of selecting several properties, note that result will be <code>Object[]</code>:</p>
+ <p>And here is an example of selecting several properties. The result is a list of <code>Object[]</code>:</p>
</div>
<div class="listingblock">
<div class="content">
@@ -2170,8 +2178,18 @@ ORDER BY COUNT(t1.PAINTING_ID) DESC, t0.ARTIST_NAME</code></pre>
</div>
<div class="sect3">
<h4 id="ejbql"><a class="anchor" href="#ejbql"></a>EJBQLQuery</h4>
+ <div class="admonitionblock note">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa fa-info-circle fa-2x" title="Note"></i> </td>
+ <td class="content"> As soon as all of the <code>EJBQLQuery</code> capabilities become available in <code>ObjectSelect</code>, we are planning to deprecate <code>EJBQLQuery</code>. </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
<div class="paragraph">
- <p>EJBQLQuery was created as a part of an experiment in adopting some of Java Persistence API (JPA) approaches in Cayenne. It is a parameterized object query that is created from query String. A String used to build EJBQLQuery must conform to JPQL (JPA query language):</p>
+ <p>EJBQLQuery was created as a part of an experiment in adopting some of Java Persistence API (JPA) approaches in Cayenne. It is a parameterized object query that is created from query String. A String used to build EJBQLQuery follows JPQL (JPA Query Language) syntax:</p>
</div>
<div class="listingblock">
<div class="content">
@@ -2179,24 +2197,25 @@ ORDER BY COUNT(t1.PAINTING_ID) DESC, t0.ARTIST_NAME</code></pre>
</div>
</div>
<div class="paragraph">
- <p>JPQL details can be found in any JPA manual. Here we’ll mention only how this fits into Cayenne and what are the differences between EJBQL and other Cayenne queries.</p>
+ <p>JPQL details can be found in any JPA manual. Here we’ll focus on how this fits into Cayenne and what are the differences between EJBQL and other Cayenne queries.</p>
</div>
<div class="paragraph">
- <p>Although most frequently EJBQLQuery is used as an alternative to SelectQuery, there are also DELETE and UPDATE varieties available.</p>
+ <p>Although most frequently EJBQLQuery is used as an alternative to ObjectSelect, there are also DELETE and UPDATE varieties available.</p>
</div>
<div class="admonitionblock note">
<table>
<tbody>
<tr>
<td class="icon"> <i class="fa fa-info-circle fa-2x" title="Note"></i> </td>
- <td class="content"> As of this version of Cayenne, DELETE and UPDATE do not change the state of objects in the ObjectContext. They are run directly against the database instead. </td>
+ <td class="content"> DELETE and UPDATE do not change the state of objects in the ObjectContext. They are run directly against the database instead. </td>
</tr>
</tbody>
</table>
</div>
<div class="listingblock">
<div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">EJBQLQuery select = new EJBQLQuery("select a FROM Artist a WHERE a.name = 'Salvador Dali'");
+ <pre class="highlight"><code class="language-java java" data-lang="java">EJBQLQuery select =
+ new EJBQLQuery("select a FROM Artist a WHERE a.name = 'Salvador Dali'");
List<Artist> artists = context.performQuery(select);</code></pre>
</div>
</div>
@@ -2208,12 +2227,16 @@ context.performGenericQuery(delete);</code></pre>
</div>
<div class="listingblock">
<div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">EJBQLQuery update = new EJBQLQuery("UPDATE Painting AS p SET p.name = 'P2' WHERE p.name = 'P1'");
+ <pre class="highlight"><code class="language-java java" data-lang="java">EJBQLQuery update =
+ new EJBQLQuery("UPDATE Painting AS p SET p.name = 'P2' WHERE p.name = 'P1'");
context.performGenericQuery(update);</code></pre>
</div>
</div>
<div class="paragraph">
- <p>In most cases SelectQuery is preferred to EJBQLQuery, as it is API-based, and provides you with better compile-time checks. However sometimes you may want a completely scriptable object query. This is when you might prefer EJBQL. A more practical reason for picking EJBQL over SelectQuery though is that the former offers some extra selecting capabilities, namely aggregate functions and subqueries:</p>
+ <p>In most cases <code>ObjectSelect</code> is preferred to <code>EJBQLQuery</code>, as it is API-based, and provides you with better compile-time checks. However sometimes you may want a completely scriptable object query. This is when you might prefer EJBQL. A more practical reason for picking EJBQL over <code>ObjectSelect</code> though is that the former offers a few extra capabilities, such as subqueries.</p>
+ </div>
+ <div class="paragraph">
+ <p>Just like <code>ObjectSelect</code> <code>EJBQLQuery</code> can return a List of Object[] elements, where each entry in an array is either a DataObject or a scalar, depending on the query SELECT clause.</p>
</div>
<div class="listingblock">
<div class="content">
@@ -2226,7 +2249,7 @@ for(Object[] artistWithCount : result) {
</div>
</div>
<div class="paragraph">
- <p>This also demonstrates a previously unseen type of select result - a List of Object[] elements, where each entry in an Object[] is either a DataObject or a scalar, depending on the query SELECT clause. A result can also be a list of scalars:</p>
+ <p>A result can also be a list of scalars:</p>
</div>
<div class="listingblock">
<div class="content">
@@ -2259,10 +2282,10 @@ List<String> names = context.performQuery(query);</code></pre>
</div>
</div>
<div class="paragraph">
- <p>It is <a href="#evaluete">possible to convert</a> an <a href="#expressions">Expression</a> object used with a <a href="#select">SelectQuery</a> to EJBQL. Use the Expression#appendAsEJBQL methods for this purpose.</p>
+ <p>It is possible to convert an <a href="#expressions">Expression</a> object used with a <a href="#select">ObjectSelect</a> to EJBQL. Use the Expression#appendAsEJBQL methods for this purpose.</p>
</div>
<div class="paragraph">
- <p>While Cayenne Expressions discussed previously can be thought of as identical to JPQL WHERE clause, and indeed they are very close, there are a few noteable differences:</p>
+ <p>While Cayenne Expressions discussed previously can be thought of as identical to JPQL WHERE clause, and indeed they are very close, there are a few notable differences:</p>
</div>
<div class="ulist">
<ul>
@@ -2270,34 +2293,35 @@ List<String> names = context.performQuery(query);</code></pre>
<li> <p>Expression Parameters: SelectQuery uses "$" to denote named parameters (e.g. "$myParam"), while EJBQL uses ":" (e.g. ":myParam"). Also EJBQL supports positional parameters denoted by the question mark: "?3".</p> </li>
</ul>
</div>
- <div class="sect4">
- <h5 id="selectbyid"><a class="anchor" href="#selectbyid"></a>SelectById</h5>
- <div class="paragraph">
- <p>This query allows to search objects by their ID. It’s introduced in Cayenne 4.0 and uses new "fluent" API same as <code>ObjectSelect</code> query.</p>
- </div>
- <div class="paragraph">
- <p>Here is example of how to use it:</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">Artist artistWithId1 = SelectById.query(Artist.class, 1)
+ </div>
+ <div class="sect3">
+ <h4 id="selectbyid"><a class="anchor" href="#selectbyid"></a>SelectById</h4>
+ <div class="paragraph">
+ <p>This query allows to search objects by their ID. It’s introduced in Cayenne 4.0 and uses new "fluent" API same as <code>ObjectSelect</code> query.</p>
+ </div>
+ <div class="paragraph">
+ <p>Here is example of how to use it:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-java java" data-lang="java">Artist artistWithId1 = SelectById.query(Artist.class, 1)
.prefetch(Artist.PAINTING_ARRAY.joint())
.localCache()
.selectOne(context);</code></pre>
- </div>
</div>
</div>
- <div class="sect4">
- <h5 id="sqlselect-and-sqlexec"><a class="anchor" href="#sqlselect-and-sqlexec"></a>SQLSelect and SQLExec</h5>
- <div class="paragraph">
- <p><code>SQLSelect</code> and <code>SQLExec</code> are essentially a "fluent" versions of older <code>SQLTemplate</code> query. <code>SQLSelect</code> can be used (as name suggests) to select custom data in form of entities, separate columns or collection of <code>DataRow</code>. <code>SQLExec</code> is designed to just execute any raw SQL code (e.g. updates, deletes, DDLs, etc.) This queries support all directives described in <a href="#sqltemplate">SQLTemplate</a> section.</p>
- </div>
- <div class="paragraph">
- <p>Here is example of how to use SQLSelect:</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">// Selecting objects
+ </div>
+ <div class="sect3">
+ <h4 id="sqlselect-and-sqlexec"><a class="anchor" href="#sqlselect-and-sqlexec"></a>SQLSelect and SQLExec</h4>
+ <div class="paragraph">
+ <p><code>SQLSelect</code> and <code>SQLExec</code> are essentially a "fluent" versions of older <code>SQLTemplate</code> query. <code>SQLSelect</code> can be used (as name suggests) to select custom data in form of entities, separate columns or collection of <code>DataRow</code>. <code>SQLExec</code> is designed to just execute any raw SQL code (e.g. updates, deletes, DDLs, etc.) This queries support all directives described in <a href="#sqltemplate">SQLTemplate</a> section.</p>
+ </div>
+ <div class="paragraph">
+ <p>Here is example of how to use SQLSelect:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-java java" data-lang="java">// Selecting objects
List<Painting> paintings = SQLSelect
.query(Painting.class, "SELECT * FROM PAINTING WHERE PAINTING_TITLE LIKE #bind($title)")
.params("title", "painting%")
@@ -2311,55 +2335,54 @@ List<String> paintingNames = SQLSelect
.scalarQuery(String.class, "SELECT PAINTING_TITLE FROM PAINTING WHERE ESTIMATED_PRICE > #bind($price)")
.params("price", 100000)
.select(context);</code></pre>
- </div>
- </div>
- <div class="paragraph">
- <p>And here is example of how to use <code>SQLExec</code>:</p>
</div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">int inserted = SQLExec
+ </div>
+ <div class="paragraph">
+ <p>And here is example of how to use <code>SQLExec</code>:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-java java" data-lang="java">int inserted = SQLExec
.query("INSERT INTO ARTIST (ARTIST_ID, ARTIST_NAME) VALUES (#bind($id), #bind($name))")
.paramsArray(55, "Picasso")
.update(context);</code></pre>
- </div>
</div>
</div>
- <div class="sect4">
- <h5 id="mappedselect-and-mappedexec"><a class="anchor" href="#mappedselect-and-mappedexec"></a>MappedSelect and MappedExec</h5>
- <div class="paragraph">
- <p><code>MappedSelect</code> and <code>MappedExec</code> is a queries that are just a reference to another queries stored in the DataMap. The actual stored query can be SelectQuery, SQLTemplate, EJBQLQuery, etc. Difference between <code>MappedSelect</code> and <code>MappedExec</code> is (as reflected in their names) whether underlying query intended to select data or just to perform some generic SQL code.</p>
- </div>
- <div class="admonitionblock note">
- <table>
- <tbody>
- <tr>
- <td class="icon"> <i class="fa fa-info-circle fa-2x" title="Note"></i> </td>
- <td class="content"> These queries are "fluent" versions of deprecated <code>NamedQuery</code> class. </td>
- </tr>
- </tbody>
- </table>
- </div>
- <div class="paragraph">
- <p>Here is example of how to use <code>MappedSelect</code>:</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">List<Artist> results = MappedSelect.query("artistsByName", Artist.class)
+ </div>
+ <div class="sect3">
+ <h4 id="mappedselect-and-mappedexec"><a class="anchor" href="#mappedselect-and-mappedexec"></a>MappedSelect and MappedExec</h4>
+ <div class="paragraph">
+ <p><code>MappedSelect</code> and <code>MappedExec</code> is a queries that are just a reference to another queries stored in the DataMap. The actual stored query can be SelectQuery, SQLTemplate, EJBQLQuery, etc. Difference between <code>MappedSelect</code> and <code>MappedExec</code> is (as reflected in their names) whether underlying query intended to select data or just to perform some generic SQL code.</p>
+ </div>
+ <div class="admonitionblock note">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa fa-info-circle fa-2x" title="Note"></i> </td>
+ <td class="content"> These queries are "fluent" versions of deprecated <code>NamedQuery</code> class. </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="paragraph">
+ <p>Here is example of how to use <code>MappedSelect</code>:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-java java" data-lang="java">List<Artist> results = MappedSelect.query("artistsByName", Artist.class)
.param("name", "Picasso")
.select(context);</code></pre>
- </div>
</div>
- <div class="paragraph">
- <p>And here is example of <code>MappedExec</code>:</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="highlight"><code class="language-java java" data-lang="java">QueryResult result = MappedExec.query("updateQuery")
+ </div>
+ <div class="paragraph">
+ <p>And here is example of <code>MappedExec</code>:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="highlight"><code class="language-java java" data-lang="java">QueryResult result = MappedExec.query("updateQuery")
.param("var", "value")
.execute(context);
System.out.println("Rows updated: " + result.firstUpdateCount());</code></pre>
- </div>
</div>
</div>
</div>