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 2012/10/20 14:54:40 UTC
svn commit: r1400435 - in
/cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx:
queries.xml starting-cayenne.xml
Author: aadamchik
Date: Sat Oct 20 12:54:40 2012
New Revision: 1400435
URL: http://svn.apache.org/viewvc?rev=1400435&view=rev
Log:
docs: starting on queries
(cherry picked from commit 2f606ecb0d9c90ae60cc7ff97541d2ffbf687794)
Modified:
cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/queries.xml
cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.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=1400435&r1=1400434&r2=1400435&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 Sat Oct 20 12:54:40 2012
@@ -2,6 +2,25 @@
<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
+ "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
+ 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>
<section xml:id="selectquery">
<title>SelectQuery</title>
</section>
Modified: cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml
URL: http://svn.apache.org/viewvc/cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml?rev=1400435&r1=1400434&r2=1400435&view=diff
==============================================================================
--- cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml (original)
+++ cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml Sat Oct 20 12:54:40 2012
@@ -136,10 +136,10 @@ ServerRuntime runtime =
ObjectContext scope, etc.</para>
<para>
<note>
- <para>Please do not think of CayenneFilter as the only way to start and use Cayenne in a web
- application. CayenneFilter is entirely optional. Use it if you don't have any
- special design for application service management. If you do, simply integrate
- Cayenne into that design.</para>
+ <para>You should not think of CayenneFilter as the only way to start and use Cayenne in a web
+ application. In fact CayenneFilter is entirely optional. Use it if you don't
+ have any special design for application service management. If you do, simply
+ integrate Cayenne into that design.</para>
</note>
</para>
</section>