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 2015/05/11 06:42:42 UTC
[7/8] cayenne git commit: 4.0 docs - ObjectSelect
4.0 docs - ObjectSelect
Project: http://git-wip-us.apache.org/repos/asf/cayenne/repo
Commit: http://git-wip-us.apache.org/repos/asf/cayenne/commit/73bff100
Tree: http://git-wip-us.apache.org/repos/asf/cayenne/tree/73bff100
Diff: http://git-wip-us.apache.org/repos/asf/cayenne/diff/73bff100
Branch: refs/heads/master
Commit: 73bff1001a56259b27aeb7aaa38cea80e8888dbb
Parents: 4f8c114
Author: aadamchik <aa...@apache.org>
Authored: Sun May 10 19:43:05 2015 -0400
Committer: aadamchik <aa...@apache.org>
Committed: Sun May 10 19:43:05 2015 -0400
----------------------------------------------------------------------
.../cayenne-guide/src/docbkx/queries.xml | 87 ++++++++++----------
1 file changed, 45 insertions(+), 42 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cayenne/blob/73bff100/docs/docbook/cayenne-guide/src/docbkx/queries.xml
----------------------------------------------------------------------
diff --git a/docs/docbook/cayenne-guide/src/docbkx/queries.xml b/docs/docbook/cayenne-guide/src/docbkx/queries.xml
index eb1f38b..2b3b580 100644
--- a/docs/docbook/cayenne-guide/src/docbkx/queries.xml
+++ b/docs/docbook/cayenne-guide/src/docbkx/queries.xml
@@ -22,61 +22,64 @@
engine. Most often queries are used to find objects matching certain criteria, but there are
other types of queries too. E.g. those allowing to run native SQL, call DB stored
procedures, etc. When committing objects, Cayenne itself creates special queries to
- insert/update/delete rows in the dabase.</para>
- <para>There is a number of built-in queries in Cayenne, described later in this chapter. Users can
- also define their own query types to abstract certain DB interactions that for whatever
- reason can not be adequately described by the built-in set. </para>
+ insert/update/delete rows in the database. </para>
+ <para>There is a number of built-in queries in Cayenne, described later in this chapter. Most of
+ the newer queries use fluent API and can be created and executed as easy-to-read one-liners.
+ Users can define their own query types to abstract certain DB interactions that for whatever
+ reason can not be adequately described by the built-in set.</para>
<para>Queries can be roughly categorized as "object" and "native". Object queries (most notably
- SelectQuery and EJBQLQuery) are built with abstractions originating in the object model (the
- "object" side in the "object-relational" divide). E.g. SelectQuery is assembled from a Java
- class of the objects to fetch, a qualifier expression, orderings, etc. - all of this
- expressed in terms of the object model.</para>
- <para>Native queries describe a desired DB operation as SQL code (SQLTemplate query) or a
- reference to a stored procedure (ProcedureQuery), etc. The results of native queries are
- usually presented as Lists of Maps, with each map representing a row in the DB (a term "data
- row" is often used to describe such a map). They can potentially be converted to objects,
- however it may take a considerable effort to do so. Native queries are also less (if at all)
- portable across databases than object queries. </para>
+ ObjectSelect, SelectById, and EJBQLQuery) are built with abstractions originating in the
+ object model (the "object" side in the "object-relational" divide). E.g. ObjectSelect is
+ assembled from a Java class of the objects to fetch, a qualifier expression, orderings, etc.
+ - all of this expressed in terms of the object model.</para>
+ <para>Native queries describe a desired DB operation as SQL code (SQLSelect, SQLTemplate query)
+ or a reference to a stored procedure (ProcedureQuery), etc. The results of native queries
+ are usually presented as Lists of Maps, with each map representing a row in the DB (a term
+ "data row" is often used to describe such a map). They can potentially be converted to
+ objects, however it may take a considerable effort to do so. Native queries are also less
+ (if at all) portable across databases than object queries. </para>
<section xml:id="selectquery">
- <title>SelectQuery</title>
- <para>SelectQuery is the most commonly used query in user applications. This may be the only
- query you will need in most appplications. It returns a list of persistent objects of a
- certain type specified in the
- query:<programlisting language="java">SelectQuery query = new SelectQuery(Artist.class);
-List<Artist> objects = context.performQuery(query);</programlisting>This
+ <title>ObjectSelect</title>
+ <para>
+ <emphasis role="italic">ObjectSelect supersedes older SelectQuery. SelectQuery is still
+ available and supported. </emphasis>
+ </para>
+ <para>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:<programlisting language="java">List<Artist> objects = ObjectSelect.query(Artist.class).select(context);</programlisting>This
returned all rows in the "ARTIST" table. If the logs were turned on, you might see the
following SQL
printed:<programlisting language="java">INFO: SELECT t0.DATE_OF_BIRTH, t0.NAME, t0.ID FROM ARTIST t0
INFO: === returned 5 row. - took 5 ms.</programlisting></para>
- <para>This SQL was generated by Cayenne from the SelectQuery above. SelectQuery can have a
- qualifier to select only the data that you care about. Qualifier is simply an Expression
- (Expressions where discussed in the previous chapter). If you only want artists whose
- name begins with 'Pablo', you might use the following qualifier expression:
- <programlisting language="java">SelectQuery query = new SelectQuery(Artist.class,
- ExpressionFactory.likeExp(Artist.NAME_PROPERTY, "Pablo%"));
-List<Artist> objects = context.performQuery(query);</programlisting>The
+ <para>This SQL was generated by Cayenne from the ObjectSelect above. ObjectSelect can have a
+ qualifier to select only the data matching specific criteria. Qualifier is simply an
+ Expression (Expressions where discussed in the previous chapter), appended to the query
+ using "where" method. If you only want artists whose name begins with 'Pablo', you might
+ use the following qualifier expression:
+ <programlisting language="java">List<Artist> objects = ObjectSelect.query(Artist.class)
+ .where(Artist.NAME.like("Pablo%"))
+ .select(context);</programlisting>The
SQL will look different this
time:<programlisting language="java">INFO: SELECT t0.DATE_OF_BIRTH, t0.NAME, t0.ID FROM ARTIST t0 WHERE t0.NAME LIKE ?
[bind: 1->NAME:'Pablo%']
INFO: === returned 1 row. - took 6 ms.</programlisting></para>
- <para>SelectQuery allows to append parts of qualifier to
- self:<programlisting language="java">SelectQuery query = new SelectQuery(Artist.class);
-query.setQualifier(ExpressionFactory.likeExp(Artist.NAME_PROPERTY, "A%"));
-query.andQualifier(ExpressionFactory.greaterExp(Artist.DATE_OF_BIRTH_PROPERTY, someDate));</programlisting></para>
- <para>To order the results of SelectQuery, one or more Orderings can be applied. Ordering
- were already discussed earlier.
- E.g.:<programlisting language="java">SelectQuery query = new SelectQuery(Artist.class);
-
-// create Ordering object explicitly
-query.addOrdering(new Ordering(Artist.DATE_OF_BIRTH_PROPERTY, SortOrder.DESCENDING));
-
-// or let SelectQuery create it behind the scenes
-query.addOrdering(Artist.NAME_PROPERTY, SortOrder.ASCENDING);</programlisting></para>
- <para>There's a number of other useful properties in SelectQuery that define what to select
+ <para>ObjectSelect allows to assemble qualifier from parts, using "and" and "or" method to
+ chain then
+ together:<programlisting language="java">List<Artist> objects = ObjectSelect.query(Artist.class)
+ .where(Artist.NAME.like("A%"))
+ .and(Artist.DATE_OF_BIRTH.gt(someDate)
+ .select(context);</programlisting></para>
+ <para>To order the results of ObjectSelect, one or more orderings can be
+ applied:<programlisting language="java">List<Artist> objects = ObjectSelect.query(Artist.class)
+ .addOrderBy(Artist.DATE_OF_BIRTH.desc())
+ .addOrderBy(Artist.NAME.asc())
+ .select(context);</programlisting></para>
+ <para>There's a number of other useful methods in ObjectSelect that define what to select
and how to optimize database interaction (prefetching, caching, fetch offset and limit,
pagination, etc.). Some of them are discussed in separate chapters on caching and
performance optimization. Others are fairly self-explanatory. Please check the API docs
- for the full extent of the SelectQuery features.</para>
+ for the full extent of the ObjectSelect features.</para>
</section>
<section xml:id="ejbqlquery">
<title>EJBQLQuery</title>