Author: aadamchik
Date: Sun Oct 21 14:37:41 2012
New Revision: 1400658
URL: http://svn.apache.org/viewvc?rev=1400658&view=rev
Log:
docs - starting on SelectQuery
Modified:
cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/queries.xml
Modified: cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/queries.xml
URL:
http://svn.apache.org/viewvc/cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/queries.xml?rev=1400658&r1=1400657&r2=1400658&view=diff
==============================================================================
--- cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/queries.xml
(original)
+++ cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/queries.xml Sun
Oct 21 14:37:41 2012
@@ -2,27 +2,46 @@
<chapter xmlns="http://docbook.org/ns/docbook";
xmlns:xlink="http://www.w3.org/1999/xlink";
version="5.0" xml:id="queries">
<title>Queries</title>
- <para>Queries are Java objects that can be translated into SQL
statements by Cayenne. Most
- Queries used in applications are intended to find objects
matching certain criteria, but
- there are other types of queries too. Such as those allowing to
execute native SQL, invoke
- DB stored procedures, etc. Internally when committing objects,
Cayenne also uses special
- queries to insert/update/delete rows in the dabase. In other
words Queries comprise an
- extensible protocol for communication between a Java
application and a database. </para>
- <para>There is a number of built-in queries in Cayenne, described later
in this chapter. Users
- can also create their own Query types to abstract certain DB
interactions that are for
- whatever reason can not be adequately described by the built-in
set. </para>
- <para>Queries can be roughly categorized as "object", "native". Object
queries (most notably
- SelectQuery and EJBQLQuery) are built from abstractions
originating in the object model (the
+ <para>Queries are Java objects used by the application to communicate
with the database. Cayenne
+ knows how to translate queries into SQL statements appropriate
for a particular database
+ 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>
+ <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 often describe a desired DB operation using SQL
(SQLTemplate) or referring
- to stored procedures (ProcedureQuery), etc. The results of
native queries are usually
+ <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. They can potentially
be converted to objects, however often it takes a considerable
effort to do so. Native
- queries are also less (if at all) portable across databases.
</para>
+ 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. It returns a list of
+ persistent objects of a certain type specified in the
+ query:<programlisting>SelectQuery query = new
SelectQuery(Artist.class);
+List<Artist> objects = context.performQuery(query);</programlisting>This
+ returned all rows in the "ARTIST" table. If the logs
were turned on, you might see the
+ following SQL
+ printed:<programlisting>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 use 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>SelectQuery query = new
SelectQuery(Artist.class,
+ ExpressionFactory.likeExp(Artist.NAME_PROPERTY, "Pablo%"));
+List<Artist> objects = context.performQuery(query);</programlisting>The
+ SQL will look different this
+ time:<programlisting>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>
</section>
<section xml:id="ejbqlquery">
<title>EJBQLQuery</title>
