This is an automated email from the ASF dual-hosted git repository.
aadamchik pushed a commit to branch STABLE-4.0
in repository https://gitbox.apache.org/repos/asf/cayenne.git
The following commit(s) were added to refs/heads/STABLE-4.0 by this push:
new 1823e02 docs: minor edits, formatting
1823e02 is described below
commit 1823e02bbd38a3b3ea98d83d1e5ae6ddf1bf88fb
Author: Andrus Adamchik <andrus@objectstyle.com>
AuthorDate: Sat Nov 2 10:28:00 2019 +0300
docs: minor edits, formatting
---
.../asciidoc/_cayenne-guide/part2/queries.adoc | 58 ++++++++++++++--------
1 file changed, 38 insertions(+), 20 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 c36a48c..c1714da 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
@@ -26,7 +26,8 @@ Native queries describe a desired DB operation as SQL code (SQLSelect, SQLTempla
===== Selecting objects
-ObjectSelect supersedes older SelectQuery. SelectQuery is still available and supported.
+NOTE: ObjectSelect supersedes older SelectQuery. SelectQuery is still available and supported,
but will be deprecated
+in the future.
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:
@@ -87,11 +88,12 @@ There's a number of other useful methods in ObjectSelect that define what
to sel
[source, java]
----
-List<String> names = ObjectSelect.columnQuery(Artist.class, Artist.ARTIST_NAME)
+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]
----
@@ -144,24 +146,31 @@ ORDER BY COUNT(t1.PAINTING_ID) DESC, t0.ARTIST_NAME
[[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.
+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.
-Although most frequently EJBQLQuery is used as an alternative to SelectQuery, there are also
DELETE and UPDATE varieties available.
-
-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);
----
@@ -173,13 +182,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");
@@ -190,16 +204,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:
-
+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, SQL]
----
@@ -220,13 +233,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".
===== SelectById