Author: aadamchik
Date: Sat Oct 20 12:52:41 2012
New Revision: 1400432
URL: http://svn.apache.org/viewvc?rev=1400432&view=rev
Log:
docs: starting on queries
Modified:
cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/queries.xml
cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.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=1400432&r1=1400431&r2=1400432&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 Sat
Oct 20 12:52:41 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/trunk/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml
URL:
http://svn.apache.org/viewvc/cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml?rev=1400432&r1=1400431&r2=1400432&view=diff
==============================================================================
---
cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml
(original)
+++
cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml
Sat Oct 20 12:52:41 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>
