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 07:51:44 UTC

[cayenne] branch master updated: docs: minor edits, formatting

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.git


The following commit(s) were added to refs/heads/master by this push:
     new 20ccd0b  docs: minor edits, formatting
20ccd0b is described below

commit 20ccd0be88be1cb488cd89ee04723d2e0bd39f22
Author: Andrus Adamchik <an...@objectstyle.com>
AuthorDate: Sat Nov 2 10:49:43 2019 +0300

    docs: minor edits, formatting
---
 .../asciidoc/_cayenne-guide/part2/queries.adoc     | 72 ++++++++++------------
 1 file changed, 34 insertions(+), 38 deletions(-)

diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/queries.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/queries.adoc
index 430c5d6..1a66997 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/queries.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/queries.adoc
@@ -42,7 +42,7 @@ Native queries are also less (if at all) portable across databases than object q
 
 ===== Selecting objects
 
-`ObjectSelect` supersedes older `SelectQuery`. `SelectQuery` is deprecated since 4.2.
+NOTE: `ObjectSelect` supersedes older `SelectQuery`. `SelectQuery` is deprecated since 4.2.
 
 `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:
@@ -117,7 +117,7 @@ List<String> names = ObjectSelect.columnQuery(Artist.class, Artist.ARTIST_NAME)
     .select(context);
 ----
 
-And here is example of selecting several properties, note that result will be `Object[]`:
+And here is an example of selecting several properties. The result is a list of `Object[]`:
 
 [source, java]
 ----
@@ -326,29 +326,31 @@ See Transactions section for more details.
 [[ejbql]]
 ==== EJBQLQuery
 
-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):
+NOTE: As soon as all of the `EJBQLQuery` capabilities become available in `ObjectSelect`, we are planning to
+deprecate `EJBQLQuery`.
 
+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:
 
 [source, java]
 ----
 EJBQLQuery query = new EJBQLQuery("select a FROM Artist a");
 ----
 
-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.
-
-Although most frequently `EJBQLQuery` is used as an alternative to `SelectQuery`,
-there are also DELETE and UPDATE varieties available.
+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.
 
-NOTE: 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.
+Although most frequently EJBQLQuery is used as an alternative to ObjectSelect, there are also DELETE and UPDATE
+varieties available.
 
+NOTE: DELETE and UPDATE do not change the state of objects in the ObjectContext. They are run directly against the
+database instead.
 
 [source, java]
 ----
-EJBQLQuery select = new EJBQLQuery("select a FROM Artist a WHERE a.name = 'Salvador Dali'");
+EJBQLQuery select =
+    new EJBQLQuery("select a FROM Artist a WHERE a.name = 'Salvador Dali'");
 List<Artist> artists = context.performQuery(select);
 ----
 
@@ -360,17 +362,18 @@ context.performGenericQuery(delete);
 
 [source, java]
 ----
-EJBQLQuery update = new EJBQLQuery("UPDATE Painting AS p SET p.name = 'P2' WHERE p.name = 'P1'");
+EJBQLQuery update =
+    new EJBQLQuery("UPDATE Painting AS p SET p.name = 'P2' WHERE p.name = 'P1'");
 context.performGenericQuery(update);
 ----
 
+In most cases `ObjectSelect` 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 `ObjectSelect` though is that the former offers a few extra capabilities,
+such as subqueries.
 
-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:
-
+Just like `ObjectSelect` `EJBQLQuery` 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.
 [source, java]
 ----
 EJBQLQuery query = new EJBQLQuery("select a, COUNT(p) FROM Artist a JOIN a.paintings p GROUP BY a");
@@ -381,20 +384,15 @@ for(Object[] artistWithCount : result) {
 }
 ----
 
-
-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:
-
 [source, java]
 ----
 EJBQLQuery query = new EJBQLQuery("select a.name FROM Artist a");
 List<String> names = context.performQuery(query);
 ----
 
-EJBQLQuery supports an "IN" clause with three different usage-patterns.
-The following example would require three individual positional parameters
-(named parameters could also have been used) to be supplied.
+EJBQLQuery supports an "IN" clause with three different usage-patterns. The following example would require three
+individual positional parameters (named parameters could also have been used) to be supplied.
 
 [source, java]
 ----
@@ -417,20 +415,18 @@ The following example is functionally identical to the one prior.
 select p from Painting p where p.paintingTitle in (?1)
 ----
 
-It is xref:evaluete[possible to convert] an xref:expressions[Expression] object used with a xref:select[SelectQuery] to EJBQL.
-Use the Expression#appendAsEJBQL methods for this purpose.
+It is possible to convert an xref:expressions[Expression] object used with a xref:select[ObjectSelect] to EJBQL. Use the
+Expression#appendAsEJBQL methods for this purpose.
 
-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:
+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:
 
-- Null handling: SelectQuery would translate the expressions matching NULL values to the corresponding "X IS NULL"
-or "X IS NOT NULL" SQL syntax. EJBQLQuery on the other hand requires explicit "IS NULL" (or "IS NOT NULL")
-syntax to be used, otherwise the generated SQL will look like "X = NULL" (or "X <> NULL"),
-which will evaluate differently.
+- Null handling: SelectQuery would translate the expressions matching NULL values to the corresponding "X IS NULL" or
+"X IS NOT NULL" SQL syntax. EJBQLQuery on the other hand requires explicit "IS NULL" (or "IS NOT NULL") syntax to be
+used, otherwise the generated SQL will look like "X = NULL" (or "X <> NULL"), which will evaluate differently.
 
-- 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".
+- 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".
 
 ==== Custom Queries