svn commit: r1400659 - /cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/queries.xml

[aa...@apache.org]

Author: aadamchik
Date: Sun Oct 21 14:38:21 2012
New Revision: 1400659

URL: http://svn.apache.org/viewvc?rev=1400659&view=rev
Log:
docs - starting on SelectQuery

(cherry picked from commit 1504a071d0567baedc912aec0a9d5ec28a5d188c)

Modified:
    cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/queries.xml

Modified: cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/queries.xml
URL: http://svn.apache.org/viewvc/cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/queries.xml?rev=1400659&r1=1400658&r2=1400659&view=diff
==============================================================================
--- cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/queries.xml (original)
+++ cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/queries.xml Sun Oct 21 14:38:21 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&lt;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&lt;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>