You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cayenne.apache.org by bu...@apache.org on 2013/02/18 14:14:26 UTC
svn commit: r850951 [3/3] - in /websites/staging/cayenne/trunk/content: ./
dev/ docs/3.1/cayenne-guide/ docs/3.1/cayenne-guide/css/
Modified: websites/staging/cayenne/trunk/content/docs/3.1/cayenne-guide/queries.html
==============================================================================
--- websites/staging/cayenne/trunk/content/docs/3.1/cayenne-guide/queries.html (original)
+++ websites/staging/cayenne/trunk/content/docs/3.1/cayenne-guide/queries.html Mon Feb 18 13:14:25 2013
@@ -1,6 +1,6 @@
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title>Chapter 9. Queries</title><link rel="stylesheet" type="text/css" href="css/cayenne-doc.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="index.html" title="Cayenne Guide"><link rel="up" href="cayenne-guide-part2.html" title="Part II. Cayenne Framework"><link rel="prev" href="orderings.html" title="Chapter 8. Orderings"><link rel="next" href="lifecycle-events.html" title="Chapter 10. Lifecycle Events"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 9. Queries</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="orderings.html">Prev</a> </td><th width="60%" align="center">Part II. Cayenne Framework</th><td width="20%" align="right"> <a accesskey="n" href="lifecycle-events.html">Next</a></t
d></tr></table><hr></div><div class="chapter" title="Chapter 9. Queries"><div class="titlepage"><div><div><h2 class="title"><a name="queries"></a>Chapter 9. Queries</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="queries.html#selectquery">SelectQuery</a></span></dt><dt><span class="section"><a href="queries.html#ejbqlquery">EJBQLQuery</a></span></dt><dt><span class="section"><a href="queries.html#sqltemplate">SQLTemplateQuery</a></span></dt><dt><span class="section"><a href="queries.html#procedurequery">ProcedureQuery</a></span></dt><dt><span class="section"><a href="queries.html#namedquery">NamedQuery</a></span></dt><dt><span class="section"><a href="queries.html#custom-queries">Custom Queries</a></span></dt></dl></div><p>Queries are Java objects used by the application to communicate with the database. Cayenne
+ <title xmlns:d="http://docbook.org/ns/docbook">Chapter 9. Queries</title><link rel="stylesheet" type="text/css" href="css/cayenne-doc.css"><meta xmlns:d="http://docbook.org/ns/docbook" name="keywords" content="Cayenne 3.1B3-SNAPSHOT documentation"><meta xmlns:d="http://docbook.org/ns/docbook" name="description" content="User documentation for Apache Cayenne version 3.1B3-SNAPSHOT"><link rel="home" href="index.html" title="Cayenne Guide"><link rel="up" href="cayenne-guide-part2.html" title="Part II. Cayenne Framework"><link rel="prev" href="orderings.html" title="Chapter 8. Orderings"><link rel="next" href="lifecycle-events.html" title="Chapter 10. Lifecycle Events"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div xmlns:d="http://docbook.org/ns/docbook" class="navheader"><table width="100%" summary="Navigation header"><tr><th class="versioninfo">v.3.1B3-SNAPSHOT</th><th align="center">Chap
ter 9. Queries</th><th></th></tr><tr><td width="20%" align="left"><a accesskey="p" href="orderings.html">Prev</a> </td><th width="60%" align="center"><a accesskey="u" href="cayenne-guide-part2.html">Part II. Cayenne Framework</a></th><td width="20%" align="right"> <a accesskey="n" href="lifecycle-events.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 9. Queries"><div class="titlepage"><div><div><h2 class="title"><a name="queries"></a>Chapter 9. Queries</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="queries.html#selectquery">SelectQuery</a></span></dt><dt><span class="section"><a href="queries.html#ejbqlquery">EJBQLQuery</a></span></dt><dt><span class="section"><a href="queries.html#sqltemplate">SQLTemplate</a></span></dt><dt><span class="section"><a href="queries.html#procedurequery">ProcedureQuery</a></span></dt><dt><span class="secti
on"><a href="queries.html#namedquery">NamedQuery</a></span></dt><dt><span class="section"><a href="queries.html#custom-queries">Custom Queries</a></span></dt></dl></div><p>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
@@ -11,25 +11,244 @@
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.</p><p>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 than object queries. </p><div class="section" title="SelectQuery"><div class="titlepage"><div><div><h2 class="title"><a name="selectquery"></a>SelectQuery</h2></div></div></div><p>SelectQuery is the most commonly used query in user applications. It returns a list of
- persistent objects of a certain type specified in the
+ expressed in terms of the object model.</p><p>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. </p><div class="section" title="SelectQuery"><div class="titlepage"><div><div><h2 class="title"><a name="selectquery"></a>SelectQuery</h2></div></div></div><p>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:</p><pre class="programlisting">SelectQuery query = <span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">new</span> SelectQuery(Artist.<span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">class</span>);
List<Artist> objects = context.performQuery(query);</pre><p>This
returned all rows in the "ARTIST" table. If the logs were turned on, you might see the
following SQL
printed:</p><pre class="programlisting">INFO: SELECT t0.DATE_OF_BIRTH, t0.NAME, t0.ID FROM ARTIST t0
-INFO: === returned 5 row. - took 5 ms.</pre><p>This SQL was generated by Cayenne from the SelectQuery above. SelectQuery can use a
+INFO: === returned 5 row. - took 5 ms.</pre><p>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:
- </p><pre class="programlisting">SelectQuery query = <span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">new</span> SelectQuery(Artist.<span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">class</span>,
+ </p><pre class="programlisting">SelectQuery query = <span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">new</span> SelectQuery(Artist.<span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">class</span>,
ExpressionFactory.likeExp(Artist.NAME_PROPERTY, <span xmlns="http://www.w3.org/1999/xhtml" class="hl-string">"Pablo%"</span>));
List<Artist> objects = context.performQuery(query);</pre><p>The
SQL will look different this
time:</p><pre class="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.</pre></div><div class="section" title="EJBQLQuery"><div class="titlepage"><div><div><h2 class="title"><a name="ejbqlquery"></a>EJBQLQuery</h2></div></div></div></div><div class="section" title="SQLTemplateQuery"><div class="titlepage"><div><div><h2 class="title"><a name="sqltemplate"></a>SQLTemplateQuery</h2></div></div></div></div><div class="section" title="ProcedureQuery"><div class="titlepage"><div><div><h2 class="title"><a name="procedurequery"></a>ProcedureQuery</h2></div></div></div></div><div class="section" title="NamedQuery"><div class="titlepage"><div><div><h2 class="title"><a name="namedquery"></a>NamedQuery</h2></div></div></div></div><div class="section" title="Custom Queries"><div class="titlepage"><div><div><h2 class="title"><a name="custom-queries"></a>Custom Queries</h2></div></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey=
"p" href="orderings.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="cayenne-guide-part2.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="lifecycle-events.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 8. Orderings </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 10. Lifecycle Events</td></tr></table></div></body></html>
\ No newline at end of file
+INFO: === returned 1 row. - took 6 ms.</pre><p>SelectQuery allows to append parts of qualifier to
+ self:</p><pre class="programlisting">SelectQuery query = new SelectQuery(Artist.class);
+query.setQualifier(ExpressionFactory.likeExp(Artist.NAME_PROPERTY, "A%"));
+query.andQualifier(ExpressionFactory.greaterExp(Artist.DATE_OF_BIRTH_PROPERTY, someDate));</pre><p>To order the results of SelectQuery, one or more Orderings can be applied. Ordering
+ were already discussed earlier.
+ E.g.:</p><pre class="programlisting">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);</pre><p>There's a number of other useful properties in SelectQuery 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.</p></div><div class="section" title="EJBQLQuery"><div class="titlepage"><div><div><h2 class="title"><a name="ejbqlquery"></a>EJBQLQuery</h2></div></div></div><p>EJBQLQuery was created as a part of an experiment in adopting some of Java Persistence
+ API (JPA) approaches in Cayenne. It is a parameterized object query that is created from
+ query String. A String used to build EJBQLQuery must conform to JPQL (JPA query
+ language):</p><pre class="programlisting">EJBQLQuery query = new EJBQLQuery("select a FROM Artist a");</pre><p>JPQL details can be found in any JPA manual. Here we'll mention only how this fits
+ into Cayenne and what are the differences between EJBQL and other Cayenne
+ queries.</p><p>Although most frequently EJBQLQuery is used as an alternative to SelectQuery, there
+ are also DELETE and UPDATE varieties available. </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>As of this version of Cayenne, DELETE and UPDATE do not change the state of
+ objects in the ObjectContext. They are run directly against the database
+ instead. </p></div><pre class="programlisting">EJBQLQuery select = <span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">new</span> EJBQLQuery(<span xmlns="http://www.w3.org/1999/xhtml" class="hl-string">"select a FROM Artist a WHERE a.name = 'Salvador Dali'"</span>);
+List<Artist> artists = context.performQuery(select);</pre><pre class="programlisting">EJBQLQuery delete = <span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">new</span> EJBQLQuery(<span xmlns="http://www.w3.org/1999/xhtml" class="hl-string">"delete from Painting"</span>);
+context.performGenericQuery(delete);</pre><pre class="programlisting">EJBQLQuery update = <span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">new</span> EJBQLQuery(<span xmlns="http://www.w3.org/1999/xhtml" class="hl-string">"UPDATE Painting AS p SET p.name = 'P2' WHERE p.name = 'P1'"</span>);
+context.performGenericQuery(update);</pre><p>In
+ most cases SelectQuery is preferred to EJBQLQuery, as it is API-based, and provides you
+ with better compile-time checks. However sometimes you may want a completely scriptable
+ object query. This is when you might prefer EJBQL. A more practical reason for picking
+ EJBQL over SelectQuery though is that the former offers some extra selecting
+ capabilities, namely aggregate functions and
+ subqueries:</p><pre class="programlisting">EJBQLQuery query = <span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">new</span> EJBQLQuery(<span xmlns="http://www.w3.org/1999/xhtml" class="hl-string">"select a, COUNT(p) FROM Artist a JOIN a.paintings p GROUP BY a"</span>);
+List<Object[]> result = context.performQuery(query);
+<span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">for</span>(Object[] artistWithCount : result) {
+ Artist a = (Artist) artistWithCount[<span xmlns="http://www.w3.org/1999/xhtml" class="hl-number">0</span>];
+ <span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">int</span> hasPaintings = (Integer) artistWithCount[<span xmlns="http://www.w3.org/1999/xhtml" class="hl-number">1</span>];
+}</pre><p>This
+ also demonstrates a previously unseen type of select result - a List of Object[]
+ elements, where each entry in an Object[] is either a DataObject or a scalar, depending
+ on the query SELECT clause. A result can also be a list of
+ scalars:</p><pre class="programlisting">EJBQLQuery query = new EJBQLQuery("select a.name FROM Artist a");
+List<String> names = context.performQuery(query);</pre><p>While
+ Cayenne Expressions discussed previously can be thought of as identical to JPQL WHERE
+ clause, and indeed they are very close, there are a few noteable differences:</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>Null handling: SelectQuery would translate the expressions matching NULL
+ values to the corresponding "X IS NULL" or "X IS NOT NULL" SQL syntax.
+ EJBQLQuery on the other hand requires explicit "IS NULL" (or "IS NOT NULL")
+ syntax to be used, otherwise the generated SQL will look like "X = NULL" (or
+ "X <> NULL"), which will evaluate differently.</p></li><li class="listitem"><p>Expression Parameters: SelectQuery uses "$" to denote named parameters
+ (e.g. "$myParam"), while EJBQL uses ":" (e.g. ":myParam"). Also EJBQL
+ supports positional parameters denoted by the question mark: "?3".</p></li></ul></div></div><div class="section" title="SQLTemplate"><div class="titlepage"><div><div><h2 class="title"><a name="sqltemplate"></a>SQLTemplate</h2></div></div></div><p>SQLTemplate is a query that allows to run native SQL from a Cayenne application. It
+ comes handy when the standard ORM concepts are not sufficient for a given query or an
+ update. SQL is too powerful and allows to manipulate data in ways that are not easily
+ described as a graph of related entities. Cayenne acknowledges this fact and provides
+ this facility to execute SQL, mapping the result to objects when possible. Here are
+ examples of selecting and non-selecting
+ SQLTemplates:</p><pre class="programlisting">SQLTemplate select = <span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">new</span> SQLTemplate(Artist.<span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">class</span>, <span xmlns="http://www.w3.org/1999/xhtml" class="hl-string">"select * from ARTIST"</span>);
+List<Artist> result = context.performQuery(select);</pre><pre class="programlisting">SQLTemplate update = <span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">new</span> SQLTemplate(Artist.<span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">class</span>, <span xmlns="http://www.w3.org/1999/xhtml" class="hl-string">"delete from ARTIST"</span>);
+QueryResponse response = context.performGenericQuery(update);</pre><p>Cayenne doesn't make any attempt to make sense of the SQL semantics, so it doesn't
+ know whether a given query is performing a select or update, etc. It is the the user's
+ decision to run a given query as a selecting or "generic".</p><p>
+ </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Any data modifications done to DB as a result of SQLTemplate execution do not
+ change the state of objects in the ObjectContext. So some objects in the context
+ may become stale as a result.</p></div><p>
+ </p><p>Another point to note is that the first argument to the SQLTemplate constructor - the
+ Java class - has the same meaning as in SelectQuery only when the result can be
+ converted to objects (e.g. when this is a selecting query and it is selecting all
+ columns from one table). In this case it denotes the "root" entity of this query result.
+ If the query does not denote a single entity result, this argument is only used for
+ query routing, i.e. determining which database it should be run against. You are free to
+ use any persistent class or even a DataMap instance in such situation. It will work as
+ long as the passed "root" maps to the same database as the current query.</p><p>To achieve interoperability between mutliple RDBMS a user can specify multiple SQL
+ statements for the same SQLTemplate, each corresponding to a native SQL dialect. A key
+ used to look up the right dialect during execution is a fully qualified class name of
+ the corresponding DbAdapter. If no DB-specific statement is present for a given DB, a
+ default generic statement is used. E.g. in all the examples above a default statement
+ will be used regardless of the runtime database. So in most cases you won't need to
+ explicitly "translate" your SQL to all possible dialects. Here is how this works in
+ practice:</p><pre class="programlisting">SQLTemplate select = <span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">new</span> SQLTemplate(Artist.<span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">class</span>, <span xmlns="http://www.w3.org/1999/xhtml" class="hl-string">"select * from ARTIST"</span>);
+
+<span xmlns="http://www.w3.org/1999/xhtml" class="hl-comment">// For Postgres it would be nice to trim padding of all CHAR columns.</span>
+<span xmlns="http://www.w3.org/1999/xhtml" class="hl-comment">// Otherwise those will be returned with whitespace on the right.</span>
+<span xmlns="http://www.w3.org/1999/xhtml" class="hl-comment">// assuming "NAME" is defined as CHAR...</span>
+String pgSQL = <span xmlns="http://www.w3.org/1999/xhtml" class="hl-string">"SELECT ARTIST_ID, RTRIM(NAME), DATE_OF_BIRTH FROM ARTIST"</span>;
+query.setTemplate(PostgresAdapter.<span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">class</span>.getName(), pgSQL);</pre><div class="section" title="Scripting SQLTemplate with Velocity"><div class="titlepage"><div><div><h3 class="title"><a name="sqltemplate-scripting"></a>Scripting SQLTemplate with Velocity</h3></div></div></div><p>The most interesting aspect of SQLTemplate (and the reason why it is called a
+ "template") is that a SQL string is treated by Cayenne as an Apache Velocity
+ template. Before sending it to DB as a PreparedStatement, the String is evaluated in
+ the Velocity context, that does variable substitutions, and performs special
+ callbacks in response to various directives, thus controlling query interaction with
+ the JDBC layer. </p><p>Check Velocity docs for the syntax details. Here we'll just mention the two main
+ scripting elements - "variables" (that look like <code class="code">$var</code>) and "directives"
+ (that look like <code class="code">#directive(p1 p2 p3)</code>). All built-in Velocity directives
+ are supported. Additionally Cayenne defines a number of its own directives to bind
+ parameters to PreparedStatements and to control the structure of the ResultSet.
+ These directives are described in the following sections.</p></div><div class="section" title="Variable Substitution"><div class="titlepage"><div><div><h3 class="title"><a name="sqltemplate-parameters"></a>Variable Substitution</h3></div></div></div><p>All variables in the template string are replaced from query
+ parameters:</p><pre class="programlisting">SQLTemplate query = <span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">new</span> SQLTemplate(Artist.<span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">class</span>, <span xmlns="http://www.w3.org/1999/xhtml" class="hl-string">"delete from $tableName"</span>);
+query.setParameters(Collections.singletonMap(<span xmlns="http://www.w3.org/1999/xhtml" class="hl-string">"tableName"</span>, <span xmlns="http://www.w3.org/1999/xhtml" class="hl-string">"mydb.PAINTING"</span>));
+
+<span xmlns="http://www.w3.org/1999/xhtml" class="hl-comment">// this will generate SQL like this: "delete from mydb.PAINTING"</span></pre><p>The
+ example above demonstrates the point made earlier in this chapter - even if we don't
+ know upfront which table the query will run against, we can still use a fixed "root"
+ in constructor (<code class="code">Artist.class</code> in this case) , as we are not planning on
+ converting the result to objects.</p><p>Variable substitution within the text uses "<code class="code">object.toString()</code>" method to replace the
+ variable value. Keep in mind that this may not be appropriate in all situations.
+ E.g. passing a date object in a WHERE clause expression may be converted to a String
+ not understood by the target RDBMS SQL parser. In such cases variable should be wrapped in <code class="code">#bind</code>
+ directive as described below.</p></div><div class="section" title="Directives"><div class="titlepage"><div><div><h3 class="title"><a name="sqltemplate-bind-directive"></a>Directives</h3></div></div></div><p>These are the custom directives used to customize SQLTemplate parsing and
+ integrate with the JDBC layer:</p><table frame="void" id="d0e1531"><caption>Table 9.1. cgen optional parameters</caption><col width="28%"><col width="33%"><col width="39%"><thead><tr>
+ <th>Directive</th>
+ <th>Usage</th>
+ <th>Description</th>
+ </tr></thead><tbody><tr>
+ <td><p><code class="code">#bind(value)</code></p>
+ <p><code class="code">#bind(value jdbcType)</code></p>
+ <p><code class="code">#bind(value jdbcType scale)</code></p>
+ </td>
+ <td>
+ <p><code class="code">#bind($xyz)</code></p>
+ <p><code class="code">#bind('str')</code></p>
+ <p><code class="code">#bind($xyz 'VARCHAR')</code></p>
+ <p><code class="code">#bind($xyz 'DECIMAL' 2)</code></p>
+ </td>
+ <td>
+ <p>Creates a PreparedStatement positional parameter in place of
+ the directive, binding the value to it before statement
+ execution. "<code class="code">#bind</code>" is allowed in places where a "?"
+ would be allowed in a PreparedStatement. And in such places it
+ almost always makes sense to pass objects to the template via
+ this or other forms of #bind instead of inserting them
+ inline.</p>
+ <p>A <code class="code">value</code> can either be a char constant or a
+ variable that is resolved from the query parameters. Note that
+ the variable can be a collection, that will be automatically
+ expanded into a list of individual value bindings. This is
+ useful for instance to build IN conditions. </p>
+ <p>The second parameter - <code class="code">jdbcType</code> - is a JDBC data
+ type of the parameter, as defined in
+ <code class="code">java.sql.Types</code>. </p>
+ <p>A full query example may look like this: </p>
+ <p><code class="code">update ARTIST set NAME = #bind($name) where ID =
+ #bind($id)</code></p>
+ </td>
+ </tr><tr>
+ <td>
+ <p><code class="code">#bindEqual(value)</code></p>
+ <p><code class="code">#bindEqual(value jdbcType)</code></p>
+ <p><code class="code">#bindEqual(value
+ jdbcType scale)</code></p>
+ </td>
+ <td>
+ <p><code class="code">#bindEqual($xyz)</code></p>
+ <p><code class="code">#bindEqual('str')</code></p>
+ <p><code class="code">#bindEqual($xyz 'VARCHAR')</code></p>
+ <p><code class="code">#bindEqual($xyz 'DECIMAL' 2)</code></p>
+ </td>
+ <td>
+ <p>Same as <code class="code">#bind</code>, but also includes the "=" sign in
+ front of the value binding. E.g.: </p>
+ <p><code class="code">update ARTIST set NAME = #bind($name) where ID
+ #bindEqual($id)</code></p>
+ <p>Here we took the previous example and replaced "ID =
+ #bind(..)" with "ID #bindEqual(..)". While it looks like a
+ clumsy shortcut to eliminate the equal sign, the actual reason
+ why this is useful is that it allows the value to be NULL. If
+ the value is not null, "= ?" is generated, but if it is, the
+ resulting chunk of the SQL would look like "IS NULL" and will be
+ compilant with what the DB expects.</p>
+ </td>
+ </tr><tr>
+ <td>
+ <p><code class="code">#bindNotEqual(value)</code></p>
+ <p><code class="code">#bindNotEqual(value jdbcType)</code></p>
+ <p><code class="code">#bindNotEqual(value jdbcType</code></p>
+ <p><code class="code"> scale )</code></p>
+ </td>
+ <td>
+ <p><code class="code">#bindNotEqual($xyz)</code></p>
+ <p><code class="code">#bindNotEqual('str')</code></p>
+ <p><code class="code">#bindNotEqual($xyz 'VARCHAR')</code></p>
+ <p><code class="code">#bindNotEqual($xyz 'DECIMAL' 2)</code></p>
+ </td>
+ <td>This directive deals with the same issue as <code class="code">#bindEqual</code>
+ above, only it generates "not equal" in front of the value (or IS
+ NOT NULL).</td>
+ </tr><tr>
+ <td>
+ <p><code class="code">#bindObjectEqual</code></p>
+ <p><code class="code">(value columns idColumns)</code></p>
+ </td>
+ <td>
+ <p><code class="code">#bindObjectEqual($a 't0.ID' 'ID')</code></p>
+ <p><code class="code">#bindObjectEqual($a ['t0.FK1', 't0.FK2'] ['PK1',
+ 'PK2'])</code></p>
+ </td>
+ <td>
+ <p>It can be tricky to use a Persistent object (or an ObjectId)
+ in a binding, especially for tables with compound primary keys.
+ This directive helps to handle such binding. It maps columns in
+ the query to the names of Persistent object ID columns, extracts
+ ID values from the object, and generates SQL like "COL1 = ? AND
+ COL2 = ? ..." , binding positional parameters to ID values. It
+ can also correctly handle null object.</p>
+ <p>Also notice how in the second example we are specifying a
+ Velocity array.</p>
+ </td>
+ </tr><tr>
+ <td>
+ <p><code class="code">#bindObjectNotEqual</code></p>
+ <p><code class="code">(value columns idColumns)</code></p>
+ </td>
+ <td>
+ <p><code class="code">#bindObjectNotEqual($a 't0.ID' 'ID')</code></p>
+ <p><code class="code">#bindObjectNotEqual($a ['t0.FK1', 't0.FK2'] ['PK1',
+ 'PK2'])</code></p>
+ </td>
+ <td>Same as #bindObjectEqual above, only generates "not equal" operator
+ for value comparison (or IS NOT NULL).</td>
+ </tr></tbody></table></div></div><div class="section" title="ProcedureQuery"><div class="titlepage"><div><div><h2 class="title"><a name="procedurequery"></a>ProcedureQuery</h2></div></div></div></div><div class="section" title="NamedQuery"><div class="titlepage"><div><div><h2 class="title"><a name="namedquery"></a>NamedQuery</h2></div></div></div></div><div class="section" title="Custom Queries"><div class="titlepage"><div><div><h2 class="title"><a name="custom-queries"></a>Custom Queries</h2></div></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="orderings.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="cayenne-guide-part2.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="lifecycle-events.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 8. Orderings&nbs
p;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 10. Lifecycle Events</td></tr></table></div></body></html>
\ No newline at end of file
Modified: websites/staging/cayenne/trunk/content/docs/3.1/cayenne-guide/rop-deployment.html
==============================================================================
--- websites/staging/cayenne/trunk/content/docs/3.1/cayenne-guide/rop-deployment.html (original)
+++ websites/staging/cayenne/trunk/content/docs/3.1/cayenne-guide/rop-deployment.html Mon Feb 18 13:14:25 2013
@@ -1,6 +1,6 @@
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title>Chapter 17. ROP Deployment</title><link rel="stylesheet" type="text/css" href="css/cayenne-doc.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="index.html" title="Cayenne Guide"><link rel="up" href="cayenne-guide-part3.html" title="Part III. Cayenne Framework - Remote Object Persistence"><link rel="prev" href="implementing-rop-client.html" title="Chapter 16. Implementing ROP Client"><link rel="next" href="current-limitations.html" title="Chapter 18. Current Limitations"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 17. ROP Deployment</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="implementing-rop-client.html">Prev</a> </td><th width="60%" align="center">Part III. Cayenne Framework -
Remote Object Persistence </th><td width="20%" align="right"> <a accesskey="n" href="current-limitations.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 17. ROP Deployment"><div class="titlepage"><div><div><h2 class="title"><a name="rop-deployment"></a>Chapter 17. ROP Deployment</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="rop-deployment.html#deploying-rop-server">Deploying ROP Server</a></span></dt><dt><span class="section"><a href="rop-deployment.html#deploying-rop-client">Deploying ROP Client</a></span></dt><dt><span class="section"><a href="rop-deployment.html#rop-security">Security</a></span></dt></dl></div><div class="section" title="Deploying ROP Server"><div class="titlepage"><div><div><h2 class="title"><a name="deploying-rop-server"></a>Deploying ROP Server</h2></div></div></div><div class="note" title="Note" style="margin-left: 0.5in; margin-right:
0.5in;"><h3 class="title">Note</h3><p>Recent versions of Tomcat and Jetty containers (e.g. Tomcat 6 and 7, Jetty 8) contain code
+ <title xmlns:d="http://docbook.org/ns/docbook">Chapter 17. ROP Deployment</title><link rel="stylesheet" type="text/css" href="css/cayenne-doc.css"><meta xmlns:d="http://docbook.org/ns/docbook" name="keywords" content="Cayenne 3.1B3-SNAPSHOT documentation"><meta xmlns:d="http://docbook.org/ns/docbook" name="description" content="User documentation for Apache Cayenne version 3.1B3-SNAPSHOT"><link rel="home" href="index.html" title="Cayenne Guide"><link rel="up" href="cayenne-guide-part3.html" title="Part III. Cayenne Framework - Remote Object Persistence"><link rel="prev" href="implementing-rop-client.html" title="Chapter 16. Implementing ROP Client"><link rel="next" href="current-limitations.html" title="Chapter 18. Current Limitations"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div xmlns:d="http://docbook.org/ns/docbook" class="navheader"><table width="100%" summary="Navigation header">
<tr><th class="versioninfo">v.3.1B3-SNAPSHOT</th><th align="center">Chapter 17. ROP Deployment</th><th></th></tr><tr><td width="20%" align="left"><a accesskey="p" href="implementing-rop-client.html">Prev</a> </td><th width="60%" align="center"><a accesskey="u" href="cayenne-guide-part3.html">Part III. Cayenne Framework - Remote Object Persistence </a></th><td width="20%" align="right"> <a accesskey="n" href="current-limitations.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 17. ROP Deployment"><div class="titlepage"><div><div><h2 class="title"><a name="rop-deployment"></a>Chapter 17. ROP Deployment</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="rop-deployment.html#deploying-rop-server">Deploying ROP Server</a></span></dt><dt><span class="section"><a href="rop-deployment.html#deploying-rop-client">Deploying ROP Client</a></span></dt><d
t><span class="section"><a href="rop-deployment.html#rop-security">Security</a></span></dt></dl></div><div class="section" title="Deploying ROP Server"><div class="titlepage"><div><div><h2 class="title"><a name="deploying-rop-server"></a>Deploying ROP Server</h2></div></div></div><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Recent versions of Tomcat and Jetty containers (e.g. Tomcat 6 and 7, Jetty 8) contain code
addressing a security concern related to "session fixation problem" by resetting the
existing session ID of any request that requires BASIC authentcaition. If ROP
service is protected with declarative security (see the the ROP tutorial and the
Modified: websites/staging/cayenne/trunk/content/docs/3.1/cayenne-guide/rop-setup.html
==============================================================================
--- websites/staging/cayenne/trunk/content/docs/3.1/cayenne-guide/rop-setup.html (original)
+++ websites/staging/cayenne/trunk/content/docs/3.1/cayenne-guide/rop-setup.html Mon Feb 18 13:14:25 2013
@@ -1,3 +1,3 @@
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title>Chapter 14. ROP Setup</title><link rel="stylesheet" type="text/css" href="css/cayenne-doc.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="index.html" title="Cayenne Guide"><link rel="up" href="cayenne-guide-part3.html" title="Part III. Cayenne Framework - Remote Object Persistence"><link rel="prev" href="introduction-to-rop.html" title="Chapter 13. Introduction to ROP"><link rel="next" href="implementing-rop-server.html" title="Chapter 15. Implementing ROP Server"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 14. ROP Setup</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="introduction-to-rop.html">Prev</a> </td><th width="60%" align="center">Part III. Cayenne Framework - Remote Object
Persistence </th><td width="20%" align="right"> <a accesskey="n" href="implementing-rop-server.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 14. ROP Setup"><div class="titlepage"><div><div><h2 class="title"><a name="rop-setup"></a>Chapter 14. ROP Setup</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="rop-setup.html#rop-system-requirements">System Requirements</a></span></dt><dt><span class="section"><a href="rop-setup.html#rop-jar-files-dependencies">Jar Files and Dependencies</a></span></dt></dl></div><div class="section" title="System Requirements"><div class="titlepage"><div><div><h2 class="title"><a name="rop-system-requirements"></a>System Requirements</h2></div></div></div></div><div class="section" title="Jar Files and Dependencies"><div class="titlepage"><div><div><h2 class="title"><a name="rop-jar-files-dependencies"></a>Jar Files and Dependencies</h2
></div></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="introduction-to-rop.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="cayenne-guide-part3.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="implementing-rop-server.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 13. Introduction to ROP </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 15. Implementing ROP Server</td></tr></table></div></body></html>
\ No newline at end of file
+ <title xmlns:d="http://docbook.org/ns/docbook">Chapter 14. ROP Setup</title><link rel="stylesheet" type="text/css" href="css/cayenne-doc.css"><meta xmlns:d="http://docbook.org/ns/docbook" name="keywords" content="Cayenne 3.1B3-SNAPSHOT documentation"><meta xmlns:d="http://docbook.org/ns/docbook" name="description" content="User documentation for Apache Cayenne version 3.1B3-SNAPSHOT"><link rel="home" href="index.html" title="Cayenne Guide"><link rel="up" href="cayenne-guide-part3.html" title="Part III. Cayenne Framework - Remote Object Persistence"><link rel="prev" href="introduction-to-rop.html" title="Chapter 13. Introduction to ROP"><link rel="next" href="implementing-rop-server.html" title="Chapter 15. Implementing ROP Server"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div xmlns:d="http://docbook.org/ns/docbook" class="navheader"><table width="100%" summary="Navigation header"><tr><
th class="versioninfo">v.3.1B3-SNAPSHOT</th><th align="center">Chapter 14. ROP Setup</th><th></th></tr><tr><td width="20%" align="left"><a accesskey="p" href="introduction-to-rop.html">Prev</a> </td><th width="60%" align="center"><a accesskey="u" href="cayenne-guide-part3.html">Part III. Cayenne Framework - Remote Object Persistence </a></th><td width="20%" align="right"> <a accesskey="n" href="implementing-rop-server.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 14. ROP Setup"><div class="titlepage"><div><div><h2 class="title"><a name="rop-setup"></a>Chapter 14. ROP Setup</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="rop-setup.html#rop-system-requirements">System Requirements</a></span></dt><dt><span class="section"><a href="rop-setup.html#rop-jar-files-dependencies">Jar Files and Dependencies</a></span></dt></dl></div><div class="
section" title="System Requirements"><div class="titlepage"><div><div><h2 class="title"><a name="rop-system-requirements"></a>System Requirements</h2></div></div></div></div><div class="section" title="Jar Files and Dependencies"><div class="titlepage"><div><div><h2 class="title"><a name="rop-jar-files-dependencies"></a>Jar Files and Dependencies</h2></div></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="introduction-to-rop.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="cayenne-guide-part3.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="implementing-rop-server.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 13. Introduction to ROP </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapte
r 15. Implementing ROP Server</td></tr></table></div></body></html>
\ No newline at end of file
Modified: websites/staging/cayenne/trunk/content/docs/3.1/cayenne-guide/server-configuration-properties.html
==============================================================================
--- websites/staging/cayenne/trunk/content/docs/3.1/cayenne-guide/server-configuration-properties.html (original)
+++ websites/staging/cayenne/trunk/content/docs/3.1/cayenne-guide/server-configuration-properties.html Mon Feb 18 13:14:25 2013
@@ -1,8 +1,8 @@
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title>Appendix A. Configuration Properties</title><link rel="stylesheet" type="text/css" href="css/cayenne-doc.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="index.html" title="Cayenne Guide"><link rel="up" href="index.html" title="Cayenne Guide"><link rel="prev" href="current-limitations.html" title="Chapter 18. Current Limitations"><link rel="next" href="client-configuration-properties.html" title="Appendix B. Service Collections"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Appendix A. Configuration Properties</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="current-limitations.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="client-configura
tion-properties.html">Next</a></td></tr></table><hr></div><div class="appendix" title="Appendix A. Configuration Properties"><div class="titlepage"><div><div><h2 class="title"><a name="server-configuration-properties"></a>Appendix A. Configuration Properties</h2></div></div></div><p>Note that the property names below are defined as constants in
+ <title xmlns:d="http://docbook.org/ns/docbook">Appendix A. Configuration Properties</title><link rel="stylesheet" type="text/css" href="css/cayenne-doc.css"><meta xmlns:d="http://docbook.org/ns/docbook" name="keywords" content="Cayenne 3.1B3-SNAPSHOT documentation"><meta xmlns:d="http://docbook.org/ns/docbook" name="description" content="User documentation for Apache Cayenne version 3.1B3-SNAPSHOT"><link rel="home" href="index.html" title="Cayenne Guide"><link rel="up" href="index.html" title="Cayenne Guide"><link rel="prev" href="current-limitations.html" title="Chapter 18. Current Limitations"><link rel="next" href="client-configuration-properties.html" title="Appendix B. Service Collections"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div xmlns:d="http://docbook.org/ns/docbook" class="navheader"><table width="100%" summary="Navigation header"><tr><th class="versioninfo">v.3.1B3-SNAPSHOT</th><th
align="center">Appendix A. Configuration Properties</th><th></th></tr><tr><td width="20%" align="left"><a accesskey="p" href="current-limitations.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="client-configuration-properties.html">Next</a></td></tr></table><hr></div><div class="appendix" title="Appendix A. Configuration Properties"><div class="titlepage"><div><div><h2 class="title"><a name="server-configuration-properties"></a>Appendix A. Configuration Properties</h2></div></div></div><p>Note that the property names below are defined as constants in
<code class="code">org.apache.cayenne.configuration.Constants</code> interface. </p><p>
- </p><table frame="void" id="d0e1805"><caption>Table A.1. Configuration Properties Recognized by ServerRuntime and/or ClientRuntime</caption><col width="67%"><col width="15%"><col width="18%"><thead><tr>
+ </p><table frame="void" id="d0e2146"><caption>Table A.1. Configuration Properties Recognized by ServerRuntime and/or ClientRuntime</caption><col width="67%"><col width="15%"><col width="18%"><thead><tr>
<th>Property</th>
<th>Possible Values</th>
<th>Default Value</th>
Modified: websites/staging/cayenne/trunk/content/docs/3.1/cayenne-guide/setup.html
==============================================================================
--- websites/staging/cayenne/trunk/content/docs/3.1/cayenne-guide/setup.html (original)
+++ websites/staging/cayenne/trunk/content/docs/3.1/cayenne-guide/setup.html Mon Feb 18 13:14:25 2013
@@ -1,6 +1,6 @@
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title>Chapter 1. Setup</title><link rel="stylesheet" type="text/css" href="css/cayenne-doc.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="index.html" title="Cayenne Guide"><link rel="up" href="cayenne-guide-part1.html" title="Part I. Object Relational Mapping with Cayenne"><link rel="prev" href="cayenne-guide-part1.html" title="Part I. Object Relational Mapping with Cayenne"><link rel="next" href="cayenne-mapping-structure.html" title="Chapter 2. Cayenne Mapping Structure"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 1. Setup</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="cayenne-guide-part1.html">Prev</a> </td><th width="60%" align="center">Part I. Object Relational Mapping with Cayenn
e</th><td width="20%" align="right"> <a accesskey="n" href="cayenne-mapping-structure.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 1. Setup"><div class="titlepage"><div><div><h2 class="title"><a name="setup"></a>Chapter 1. Setup</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="setup.html#system-requirements">System Requirements</a></span></dt><dt><span class="section"><a href="setup.html#running-cayennemodeler">Running CayenneModeler</a></span></dt></dl></div><div class="section" title="System Requirements"><div class="titlepage"><div><div><h2 class="title"><a name="system-requirements"></a>System Requirements</h2></div></div></div><p>
+ <title xmlns:d="http://docbook.org/ns/docbook">Chapter 1. Setup</title><link rel="stylesheet" type="text/css" href="css/cayenne-doc.css"><meta xmlns:d="http://docbook.org/ns/docbook" name="keywords" content="Cayenne 3.1B3-SNAPSHOT documentation"><meta xmlns:d="http://docbook.org/ns/docbook" name="description" content="User documentation for Apache Cayenne version 3.1B3-SNAPSHOT"><link rel="home" href="index.html" title="Cayenne Guide"><link rel="up" href="cayenne-guide-part1.html" title="Part I. Object Relational Mapping with Cayenne"><link rel="prev" href="cayenne-guide-part1.html" title="Part I. Object Relational Mapping with Cayenne"><link rel="next" href="cayenne-mapping-structure.html" title="Chapter 2. Cayenne Mapping Structure"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div xmlns:d="http://docbook.org/ns/docbook" class="navheader"><table width="100%" summary="Navigation header"><
tr><th class="versioninfo">v.3.1B3-SNAPSHOT</th><th align="center">Chapter 1. Setup</th><th></th></tr><tr><td width="20%" align="left"><a accesskey="p" href="cayenne-guide-part1.html">Prev</a> </td><th width="60%" align="center"><a accesskey="u" href="cayenne-guide-part1.html">Part I. Object Relational Mapping with Cayenne</a></th><td width="20%" align="right"> <a accesskey="n" href="cayenne-mapping-structure.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 1. Setup"><div class="titlepage"><div><div><h2 class="title"><a name="setup"></a>Chapter 1. Setup</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="setup.html#system-requirements">System Requirements</a></span></dt><dt><span class="section"><a href="setup.html#running-cayennemodeler">Running CayenneModeler</a></span></dt></dl></div><div class="section" title="System Requirements"><div c
lass="titlepage"><div><div><h2 class="title"><a name="system-requirements"></a>System Requirements</h2></div></div></div><p>
</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><span class="italic">Java</span>: Cayenne runtime framework and
CayenneModeler GUI tool are written in 100% Java, and run on any
Java-compatible platform. Required JDK version is 1.5 or higher. The last
Modified: websites/staging/cayenne/trunk/content/docs/3.1/cayenne-guide/starting-cayenne.html
==============================================================================
--- websites/staging/cayenne/trunk/content/docs/3.1/cayenne-guide/starting-cayenne.html (original)
+++ websites/staging/cayenne/trunk/content/docs/3.1/cayenne-guide/starting-cayenne.html Mon Feb 18 13:14:25 2013
@@ -1,27 +1,25 @@
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title>Chapter 5. Starting Cayenne</title><link rel="stylesheet" type="text/css" href="css/cayenne-doc.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="index.html" title="Cayenne Guide"><link rel="up" href="cayenne-guide-part2.html" title="Part II. Cayenne Framework"><link rel="prev" href="including-cayenne-in-project.html" title="Chapter 4. Including Cayenne in a Project"><link rel="next" href="persistent-objects-objectcontext.html" title="Chapter 6. Persistent Objects and ObjectContext"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 5. Starting Cayenne</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="including-cayenne-in-project.html">Prev</a> </td><th width="60%" align="center">Part II. Cay
enne Framework</th><td width="20%" align="right"> <a accesskey="n" href="persistent-objects-objectcontext.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 5. Starting Cayenne"><div class="titlepage"><div><div><h2 class="title"><a name="starting-cayenne"></a>Chapter 5. Starting Cayenne</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="starting-cayenne.html#starting-serverruntime">Starting and Stopping ServerRuntime</a></span></dt><dt><span class="section"><a href="starting-cayenne.html#d0e919">Merging Multiple Projects</a></span></dt><dt><span class="section"><a href="starting-cayenne.html#webapps">Web Applications</a></span></dt></dl></div><div class="section" title="Starting and Stopping ServerRuntime"><div class="titlepage"><div><div><h2 class="title"><a name="starting-serverruntime"></a>Starting and Stopping ServerRuntime</h2></div></div></div><p>In runtime Cay
enne is accessed via
+ <title xmlns:d="http://docbook.org/ns/docbook">Chapter 5. Starting Cayenne</title><link rel="stylesheet" type="text/css" href="css/cayenne-doc.css"><meta xmlns:d="http://docbook.org/ns/docbook" name="keywords" content="Cayenne 3.1B3-SNAPSHOT documentation"><meta xmlns:d="http://docbook.org/ns/docbook" name="description" content="User documentation for Apache Cayenne version 3.1B3-SNAPSHOT"><link rel="home" href="index.html" title="Cayenne Guide"><link rel="up" href="cayenne-guide-part2.html" title="Part II. Cayenne Framework"><link rel="prev" href="including-cayenne-in-project.html" title="Chapter 4. Including Cayenne in a Project"><link rel="next" href="persistent-objects-objectcontext.html" title="Chapter 6. Persistent Objects and ObjectContext"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div xmlns:d="http://docbook.org/ns/docbook" class="navheader"><table width="100%" summary="Navigat
ion header"><tr><th class="versioninfo">v.3.1B3-SNAPSHOT</th><th align="center">Chapter 5. Starting Cayenne</th><th></th></tr><tr><td width="20%" align="left"><a accesskey="p" href="including-cayenne-in-project.html">Prev</a> </td><th width="60%" align="center"><a accesskey="u" href="cayenne-guide-part2.html">Part II. Cayenne Framework</a></th><td width="20%" align="right"> <a accesskey="n" href="persistent-objects-objectcontext.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 5. Starting Cayenne"><div class="titlepage"><div><div><h2 class="title"><a name="starting-cayenne"></a>Chapter 5. Starting Cayenne</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="starting-cayenne.html#starting-serverruntime">Starting and Stopping ServerRuntime</a></span></dt><dt><span class="section"><a href="starting-cayenne.html#d0e919">Merging Multiple Projects<
/a></span></dt><dt><span class="section"><a href="starting-cayenne.html#webapps">Web Applications</a></span></dt></dl></div><div class="section" title="Starting and Stopping ServerRuntime"><div class="titlepage"><div><div><h2 class="title"><a name="starting-serverruntime"></a>Starting and Stopping ServerRuntime</h2></div></div></div><p>In runtime Cayenne is accessed via
<code class="code">org.apache.cayenne.configuration.server.ServerRuntime</code>. ServerRuntime is
created simply by calling a
- constructor:</p><pre class="programlisting">ServerRuntime runtime =
- <span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">new</span> ServerRuntime(<span xmlns="http://www.w3.org/1999/xhtml" class="hl-string">"com/example/cayenne-project.xml"</span>);</pre><p>The parameter you pass to the constructor is a location of the main project file. Location
+ constructor:</p><pre class="programlisting">ServerRuntime runtime = <span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">new</span> ServerRuntime(<span xmlns="http://www.w3.org/1999/xhtml" class="hl-string">"com/example/cayenne-project.xml"</span>);</pre><p>The parameter you pass to the constructor is a location of the main project file. Location
is a '/'-separated path (same path separator is used on UNIX and Windows) that is
resolved relative to the application classpath. The project file can be placed in the
root package or in a subpackage (e.g. in the code above it is in "com/example"
- subpackage).</p><p>ServerRuntime encapsulates a single Cayenne stack. Most applications will just have one
- ServerRuntime using it to create as many ObjectContexts as needed, access the Dependency
- Injection (DI) container and work with other Cayenne features. Internally ServerRuntime
- is just a thin wrapper around the DI container. Detailed features of the container are
- discussed in "Customizing Cayenne Runtime" chapter. Here we'll just show an example of
- how an application might replace a default implementation of a built-in Cayenne service
- (in this case - QueryCache) with a different
+ subpackage).</p><p>ServerRuntime encapsulates a single Cayenne stack. Most applications will just have
+ one ServerRuntime using it to create as many ObjectContexts as needed, access the
+ Dependency Injection (DI) container and work with other Cayenne features. Internally
+ ServerRuntime is just a thin wrapper around the DI container. Detailed features of the
+ container are discussed in "Customizing Cayenne Runtime" chapter. Here we'll just show
+ an example of how an application might replace a default implementation of a built-in
+ Cayenne service (in this case - QueryCache) with a different
class:</p><pre class="programlisting"><span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">public</span> <span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">class</span> MyExtensionsModule <span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">implements</span> Module {
<span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">public</span> <span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">void</span> configure(Binder binder) {
binder.bind(QueryCache.<span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">class</span>).to(EhCacheQueryCache.<span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">class</span>);
}
}</pre><pre class="programlisting">Module extensions = <span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">new</span> MyExtensionsModule();
-ServerRuntime runtime =
- <span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">new</span> ServerRuntime(<span xmlns="http://www.w3.org/1999/xhtml" class="hl-string">"com/example/cayenne-project.xml"</span>, extensions);</pre><p>It is a good idea to shut down the runtime when it is no longer needed, usually before the
+ServerRuntime runtime = <span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">new</span> ServerRuntime(<span xmlns="http://www.w3.org/1999/xhtml" class="hl-string">"com/example/cayenne-project.xml"</span>, extensions);</pre><p>It is a good idea to shut down the runtime when it is no longer needed, usually before the
application itself is shutdown: </p><pre class="programlisting">runtime.shutdown();</pre><p>When
a runtime object has the same scope as the application, this may not be always
necessary, however in some cases it is essential, and is generally considered a good
@@ -30,8 +28,7 @@ ServerRuntime runtime =
projects and merge them together in a single configuration. This way different parts of
a database can be mapped independenlty from each other (even by different software
providers), and combined in runtime when assembling an application. Doing it is as easy
- as passing multiple project locations to ServerRuntime constructor:</p><pre class="programlisting">ServerRuntime runtime =
- <span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">new</span> ServerRuntime(<span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">new</span> String[] {
+ as passing multiple project locations to ServerRuntime constructor:</p><pre class="programlisting">ServerRuntime runtime = <span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">new</span> ServerRuntime(<span xmlns="http://www.w3.org/1999/xhtml" class="hl-keyword">new</span> String[] {
<span xmlns="http://www.w3.org/1999/xhtml" class="hl-string">"com/example/cayenne-project.xml"</span>,
<span xmlns="http://www.w3.org/1999/xhtml" class="hl-string">"org/foo/cayenne-library1.xml"</span>,
<span xmlns="http://www.w3.org/1999/xhtml" class="hl-string">"org/foo/cayenne-library2.xml"</span>