cayenne-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ntimof...@apache.org
Subject [cayenne] branch master updated: update cayenne guide
Date Wed, 04 Sep 2019 12:20:08 GMT
This is an automated email from the ASF dual-hosted git repository.

ntimofeev 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 792cdbb  update cayenne guide
792cdbb is described below

commit 792cdbb8af443b3a458d21153ec7bfa0ecdefc39
Author: Nikita Timofeev <stariy95@gmail.com>
AuthorDate: Wed Sep 4 15:19:49 2019 +0300

    update cayenne guide
---
 .../asciidoc/_cayenne-guide/part2/expressions.adoc |   3 +-
 .../asciidoc/_cayenne-guide/part2/including.adoc   |  20 +-
 .../_cayenne-guide/part2/objectContext.adoc        |  19 +-
 .../asciidoc/_cayenne-guide/part2/queries.adoc     | 228 +++++++++++----------
 .../src/docs/asciidoc/cayenne-guide.adoc           |   7 +-
 .../re-modeler-reverseengineering-dialog.png       | Bin 52923 -> 169600 bytes
 .../src/docs/asciidoc/_upgrade-guide/header.html   |   2 +-
 .../src/docs/asciidoc/images/modeler-dbimport.png  | Bin 169600 -> 0 bytes
 8 files changed, 152 insertions(+), 127 deletions(-)

diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/expressions.adoc
b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/expressions.adoc
index 92fcf00..21475f3 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/expressions.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/expressions.adoc
@@ -207,8 +207,7 @@ Expression qualifier1 = template.params(p1);
 Null handling. Handling of Java nulls as operands is no different from normal values. Instead
of using special conditional operators,
 like SQL does (`IS NULL`, `IS NOT NULL`), "=" and "!=" expressions are used directly with
null values. It is up to Cayenne to translate expressions with nulls to the valid SQL.
 
-
-NOTE: A formal definition of the expression grammar is provided in xref:appendixC[Appendix
C]
+//NOTE: A formal definition of the expression grammar is provided in xref:appendixC[Appendix
C]
 
 ==== Creating Expressions via API
 
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/including.adoc
b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/including.adoc
index 3204b68..b168417 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/including.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/including.adoc
@@ -25,8 +25,6 @@ This is an overview of Cayenne jars that is agnostic of the build tool used.
The
 
 - `cayenne-server-{version}.jar` - contains main Cayenne runtime (adapters, DB access classes,
etc.). Most applications will require this file.
 
-- `cayenne-client-{version}.jar` - a client-side runtime for <<introduction-to-rop,
ROP applications>>
-
 - Other cayenne-* jars - various Cayenne tools extensions.
 
 ==== Dependencies
@@ -405,6 +403,19 @@ a|Regex that matches the part of the table name that needs to be stripped
off wh
 .^|boolean
 .^|Whether _DATE_, _TIME_ and _TIMESTAMP_ data types should be mapped as `java.util.Date`
or `java.time.* classes`. Default is "false", i.e. `java.time.*` will be used.
 
+.^|tableTypes
+.^|Collection<String>
+a|Collection of table types to import. By default "TABLE" and "VIEW" types are used.
+Typical types are:
+
+* TABLE
+* VIEW
+* SYSTEM TABLE
+* GLOBAL TEMPORARY
+* LOCAL TEMPORARY
+* ALIAS
+* SYNONYM
+
 .^|filters configuration
 .^|XML
 a|Detailed reverse engineering rules about what DB objects should be processed. For full
information about this parameter see <<DB-First Flow>> chapter. Here is some simple
example:
@@ -661,6 +672,11 @@ Ant tasks are the same as Maven plugin goals described above, namely
"cgen", "cd
 
 ===== cgen
 
+[source,xml]
+----
+<cgen map="${context.dir}/WEB-INF/my.map.xml"/>
+----
+
 ===== cdbgen
 
 ===== cdbimport
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/objectContext.adoc
b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/objectContext.adoc
index 62b0960..e7a3a25 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/objectContext.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/objectContext.adoc
@@ -187,14 +187,9 @@ It also provides the reverse operation - finding an object given a known
PK:
 Artist artist = Cayenne.objectForPK(context, Artist.class, 34579);
 ----
 
-If a query is expected to return 0 or 1 object, Cayenne helper class can be used to find
this object. It throws an exception if more than one object matched the query:
+For more flexibility, you could use <<SelectById>> query instead.
 
-[source, java]
-----
-Artist artist = (Artist) Cayenne.objectForQuery(context, new SelectQuery(Artist.class));
-----
-
-Feel free to explore Cayenne class API for other useful methods.
+Feel free to explore `Cayenne` class API for other useful methods.
 
 ==== ObjectContext Nesting
 In all the examples shown so far an ObjectContext would directly connect to a database to
select data
@@ -263,21 +258,21 @@ When creating a new generic object, either cast your ObjectContext to
DataContex
 
 [source, java]
 ----
-DataObject generic = ((DataContext) context).newObject("GenericEntity");
+DataObject generic = (DataObject)context.newObject("GenericEntity");
 ----
 
 [source, java]
 ----
 DataObject generic = new CayenneDataObject();
-generic.setObjectId(new ObjectId("GenericEntity"));
+generic.setObjectId(ObjectId.of("GenericEntity"));
 context.registerNewObject(generic);
 ----
 
-SelectQuery for generic object should be created passing entity name String in constructor,
instead of a Java class:
+ObjectSelect for a generic object should be created passing entity name String, instead of
just a Java class:
 
 [source, java]
 ----
-SelectQuery query = new SelectQuery("GenericEntity");
+ObjectSelect<DataObject> query = ObjectSelect.query(DataObject.class, "GenericEntity");
 ----
 
 Use DataObject API to access and modify properties of a generic object:
@@ -347,7 +342,7 @@ Transaction tx = BaseTransaction.getThreadTransaction();
 tx.addConnection("mydatanode", myConnection);
 ----
 
-You can control transaction isolation level and propagation logic using TransactionDescriptor.
+You can control transaction isolation level and propagation logic using `TransactionDescriptor`.
 
 [source, java]
 ----
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 559c10b..430c5d6 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 still available and supported.
+`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:
@@ -168,116 +168,21 @@ HAVING COUNT(t1.PAINTING_ID) < ?
 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):
-
-
-[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.
-
-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.
-
-
-[source, java]
-----
-EJBQLQuery select = new EJBQLQuery("select a FROM Artist a WHERE a.name = 'Salvador Dali'");
-List<Artist> artists = context.performQuery(select);
-----
-
-[source, java]
-----
-EJBQLQuery delete = new EJBQLQuery("delete from Painting");
-context.performGenericQuery(delete);
-----
-
-[source, java]
-----
-EJBQLQuery update = new EJBQLQuery("UPDATE Painting AS p SET p.name = 'P2' WHERE p.name =
'P1'");
-context.performGenericQuery(update);
-----
-
-
-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:
-
-[source, java]
-----
-EJBQLQuery query = new EJBQLQuery("select a, COUNT(p) FROM Artist a JOIN a.paintings p GROUP
BY a");
-List<Object[]> result = context.performQuery(query);
-for(Object[] artistWithCount : result) {
-    Artist a = (Artist) artistWithCount[0];
-    int hasPaintings = (Integer) artistWithCount[1];
-}
-----
+===== Subqueries
 
-
-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:
+Since Cayenne 4.2 `ObjectSelect` supports subqueries.
+Here is a simple example of `NOT EXISTS` subquery:
 
 [source, java]
 ----
-EJBQLQuery query = new EJBQLQuery("select a.name FROM Artist a");
-List<String> names = context.performQuery(query);
+ObjectSelect<Painting> subQuery = ObjectSelect.query(Painting.class)
+        .where(Painting.TO_ARTIST.eq(Artist.ARTIST_ID_PK_PROPERTY.enclosing()));
+long count = ObjectSelect.query(Artist.class)
+        .where(ExpressionFactory.notExists(subQuery))
+        .selectCount(context);
 ----
 
-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]
-----
-select p from Painting p where p.paintingTitle in (?1,?2,?3)
-----
-
-The following example requires a single positional parameter to be supplied.
-The parameter can be any concrete implementation of the `java.util.Collection` interface
-such as `java.util.List` or `java.util.Set`.
-
-[source, java]
-----
-select p from Painting p where p.paintingTitle in ?1
-----
-
-The following example is functionally identical to the one prior.
-
-[source, java]
-----
-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.
-
-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:
-
-- 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".
-
-===== SelectById
+==== SelectById
 
 This query allows to search objects by their ID.
 It's introduced in Cayenne 4.0 and uses new "fluent" API same as `ObjectSelect` query.
@@ -292,7 +197,7 @@ Artist artistWithId1 = SelectById.query(Artist.class, 1)
     .selectOne(context);
 ----
 
-===== SQLSelect and SQLExec
+==== SQLSelect and SQLExec
 
 `SQLSelect` and `SQLExec` are essentially a "fluent" versions of older `SQLTemplate` query.
 `SQLSelect` can be used (as name suggests) to select custom data in form of entities,
@@ -341,7 +246,7 @@ int inserted = SQLExec
     .update(context);
 ----
 
-===== MappedSelect and MappedExec
+==== MappedSelect and MappedExec
 
 `MappedSelect` and `MappedExec` 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.
@@ -418,6 +323,115 @@ In this case ProcedureQueries should be executed explicitly wrapped
in an "exter
 This is one of the few cases when a user should worry about transactions at all.
 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):
+
+
+[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.
+
+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.
+
+
+[source, java]
+----
+EJBQLQuery select = new EJBQLQuery("select a FROM Artist a WHERE a.name = 'Salvador Dali'");
+List<Artist> artists = context.performQuery(select);
+----
+
+[source, java]
+----
+EJBQLQuery delete = new EJBQLQuery("delete from Painting");
+context.performGenericQuery(delete);
+----
+
+[source, java]
+----
+EJBQLQuery update = new EJBQLQuery("UPDATE Painting AS p SET p.name = 'P2' WHERE p.name =
'P1'");
+context.performGenericQuery(update);
+----
+
+
+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:
+
+[source, java]
+----
+EJBQLQuery query = new EJBQLQuery("select a, COUNT(p) FROM Artist a JOIN a.paintings p GROUP
BY a");
+List<Object[]> result = context.performQuery(query);
+for(Object[] artistWithCount : result) {
+    Artist a = (Artist) artistWithCount[0];
+    int hasPaintings = (Integer) artistWithCount[1];
+}
+----
+
+
+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.
+
+[source, java]
+----
+select p from Painting p where p.paintingTitle in (?1,?2,?3)
+----
+
+The following example requires a single positional parameter to be supplied.
+The parameter can be any concrete implementation of the `java.util.Collection` interface
+such as `java.util.List` or `java.util.Set`.
+
+[source, java]
+----
+select p from Painting p where p.paintingTitle in ?1
+----
+
+The following example is functionally identical to the one prior.
+
+[source, java]
+----
+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.
+
+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:
+
+- 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".
+
 ==== Custom Queries
 
 If a user needs some extra functionality not addressed by the existing set of Cayenne queries,
he can write his own.
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/cayenne-guide.adoc b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/cayenne-guide.adoc
index 9937bec..a712e1f 100644
--- a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/cayenne-guide.adoc
+++ b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/cayenne-guide.adoc
@@ -41,17 +41,18 @@ include::_cayenne-guide/part1.adoc[]
 
 include::_cayenne-guide/part2.adoc[]
 
-include::_cayenne-guide/part3.adoc[]
-
 include::_cayenne-guide/part4.adoc[]
 
 include::_cayenne-guide/part5.adoc[]
 
+// move ROP docs down
+include::_cayenne-guide/part3.adoc[]
+
 include::_cayenne-guide/configurationProperties.adoc[]
 
 include::_cayenne-guide/serviceCollections.adoc[]
 
-include::_cayenne-guide/expressionsBNF.adoc[]
+//include::_cayenne-guide/expressionsBNF.adoc[]
 
 include::_cayenne-guide/listOfTables.adoc[]
 
diff --git a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/images/re-modeler-reverseengineering-dialog.png
b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/images/re-modeler-reverseengineering-dialog.png
index ba6c89d..0064248 100644
Binary files a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/images/re-modeler-reverseengineering-dialog.png
and b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/images/re-modeler-reverseengineering-dialog.png
differ
diff --git a/docs/asciidoc/upgrade-guide/src/docs/asciidoc/_upgrade-guide/header.html b/docs/asciidoc/upgrade-guide/src/docs/asciidoc/_upgrade-guide/header.html
index a4b8d8b..ec97297 100644
--- a/docs/asciidoc/upgrade-guide/src/docs/asciidoc/_upgrade-guide/header.html
+++ b/docs/asciidoc/upgrade-guide/src/docs/asciidoc/_upgrade-guide/header.html
@@ -17,7 +17,7 @@
 #  under the License.
 
 title: "Guide to 4.2 Features"
-description: "This guide highlights the new features and changes introduced in Apache Cayenne
4.1"
+description: "This guide highlights the new features and changes introduced in Apache Cayenne
4.2"
 cayenneVersion: "4.2"
 docsMenuTitle: "Upgrade Guide"
 weight: 50
diff --git a/docs/asciidoc/upgrade-guide/src/docs/asciidoc/images/modeler-dbimport.png b/docs/asciidoc/upgrade-guide/src/docs/asciidoc/images/modeler-dbimport.png
deleted file mode 100644
index 0064248..0000000
Binary files a/docs/asciidoc/upgrade-guide/src/docs/asciidoc/images/modeler-dbimport.png and
/dev/null differ


Mime
View raw message