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/12/26 20:20:16 UTC
svn commit: r1425994 [2/5] - in /cayenne/site/cms/trunk/content/docs/3.1:
cayenne-guide/ cayenne-guide/css/ tutorial/ tutorial/css/
Modified: cayenne/site/cms/trunk/content/docs/3.1/cayenne-guide/expressions.html
URL: http://svn.apache.org/viewvc/cayenne/site/cms/trunk/content/docs/3.1/cayenne-guide/expressions.html?rev=1425994&r1=1425993&r2=1425994&view=diff
==============================================================================
--- cayenne/site/cms/trunk/content/docs/3.1/cayenne-guide/expressions.html (original)
+++ cayenne/site/cms/trunk/content/docs/3.1/cayenne-guide/expressions.html Wed Dec 26 19:20:15 2012
@@ -1,73 +1,75 @@
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Chapter 7. Expressions</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="persistent-objects-objectcontext.html" title="Chapter 6. Persistent Objects and ObjectContext"><link rel="next" href="orderings.html" title="Chapter 8. Orderings"></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 7. Expressions</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="persistent-objects-objectcontext.html">Prev</a> </td><th width="60%" align="center">Part II. Cayenne Framework</th><td width="20%" align="righ
t"> <a accesskey="n" href="orderings.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 7. Expressions"><div class="titlepage"><div><div><h2 class="title"><a name="expressions"></a>Chapter 7. Expressions</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="expressions.html#expressions-overview">Expressions Overview</a></span></dt><dt><span class="section"><a href="expressions.html#path-expressions">Path Expressions</a></span></dt><dt><span class="section"><a href="expressions.html#expressions-from-strings">Creating Expressions from Strings </a></span></dt><dt><span class="section"><a href="expressions.html#expressions-with-expressionfactory">Creating Expressions with API</a></span></dt><dt><span class="section"><a href="expressions.html#expressions-in-memory">Evaluating Expressions in Memory</a></span></dt></dl></div><div class="section" title="Expressions Overview"><d
iv class="titlepage"><div><div><h2 class="title"><a name="expressions-overview"></a>Expressions Overview</h2></div></div></div><p>Cayenne provides a simple yet powerful object-based expression language. The most common
- usese of expressions are to build qualifiers and orderings of queries that are later
- converted to SQL by Cayenne and to evaluate in-memory against specific objects (to
- access certain values in the object graph or to perform in-memory object filtering and
- sorting). Cayenne provides API to build expressions in the code and a parser to create
- expressions from strings.</p></div><div class="section" title="Path Expressions"><div class="titlepage"><div><div><h2 class="title"><a name="path-expressions"></a>Path Expressions</h2></div></div></div><p>Before discussing how to build expressions, it is important to understand one group of
- expressions widely used in Cayenne - path expressions. There are two types of path
- expressions - object and database, used for navigating graphs of connected objects or
- joined DB tables respectively. Object paths are much more commonly used, as after all
- Cayenne is supposed to provide a degree of isolation of the object model from the
- database. However database paths are helpful in certain situations. General structure of
- path expressions is the following:</p><pre class="programlisting"> [db:]segment[+][.segment[+]...]</pre><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>"db:" is an optional prefix indicating that the following path is a DB
- path. Otherwise it is an object path.</p></li><li class="listitem"><p>"segment" is a name of a property (relationship or attribute in Cayenne
- terms) in the path. Path must have at least one segment; segments are
- separated by dot (".").</p></li><li class="listitem"><p>"+" An "OUTER JOIN" path component. Currently "+" only has effect when
- translated to SQL as OUTER JOIN. When evaluating expressions in memory, it
- is ignored.</p></li></ul></div><p>An object path expression represents a chain of property names rooted in a certain
- (unspecified during expression creation) object and "navigating" to its related value.
- E.g. a path expression "artist.name" might be a property path starting from a Painting
- object, pointing to the related Artist object, and then to its name attribute. A few
- more examples:</p><p>
- </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>"name" - can be used to navigate (read) the "name" property of a Person
- (or any other type of object that has a "name" property).</p></li><li class="listitem"><p>"artist.exhibits.closingDate" - can be used to navigate to a closing date
- of any of the exhibits of a Painting's Artist object.</p></li><li class="listitem"><p>"artist.exhibits+.closingDate" - same as the previous example, but when
- translated into SQL, an OUTER JOIN will be used for "exhibits".</p></li></ul></div><p>
- </p><p>Similarly a database path expression is a dot-separated path through DB table joins
- and columns. In Cayenne joins are mapped as DbRelationships with some symbolic names
- (the closest concept to DbRelationship name in the DB world is a named foreign key
- constraint. But DbRelationship names are usually chosen arbitrarily, without regard to
- constraints naming or even constraints presence). A database path therefore might look
- like this - "db:dbrelationshipX.dbrelationshipY.COLUMN_Z". More specific examples:</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>"db:NAME" - can be used to navigate to the value of "NAME" column of some
- unspecified table.</p></li><li class="listitem"><p>"db:artist.artistExhibits.exhibit.CLOSING_DATE" - can be used to match a
- closing date of any of the exhibits of a related artist record.</p></li></ul></div><p>Cayenne supports "aliases" in path Expressions. E.g. the same expression can be
- written using explicit path or an alias:</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>"artist.exhibits.closingDate" - full path</p></li><li class="listitem"><p>"e.closingDate" - alias "e" is used for "artist.exhibits".</p></li></ul></div><p>SelectQuery using the second form of the path expression must be made
- aware of the alias via <span class="italic">"SelectQuery.aliasPathSplits(..)"</span>, otherwise an Exception will be
- thrown. The main use of aliases is to allow users to control how SQL joins are generated
- if the same path is encountered more than once in any given Expression. Each alias for
- any given path would result in a separate join. Without aliases, a single join will be
- used for a group of matching paths.</p></div><div class="section" title="Creating Expressions from Strings"><div class="titlepage"><div><div><h2 class="title"><a name="expressions-from-strings"></a>Creating Expressions from Strings </h2></div></div></div><p>While in most cases users are likely to rely on API from the following section for
- expression creation, we'll start by showing String expressions, as this will help
- understanding the semantics. A Cayenne expression can be represented as a String, which
- can be later converted to an expression object using <code class="code">Expression.fromString</code>
- static method. Here is an
- example:</p><pre class="programlisting">String expString = "name like 'A%' and price < 1000";
+ usese of expressions are to build qualifiers and orderings of queries that are later
+ converted to SQL by Cayenne and to evaluate in-memory against specific objects (to
+ access certain values in the object graph or to perform in-memory object filtering and
+ sorting). Cayenne provides API to build expressions in the code and a parser to create
+ expressions from strings.</p></div><div class="section" title="Path Expressions"><div class="titlepage"><div><div><h2 class="title"><a name="path-expressions"></a>Path Expressions</h2></div></div></div><p>Before discussing how to build expressions, it is important to understand one group of
+ expressions widely used in Cayenne - path expressions. There are two types of path
+ expressions - object and database, used for navigating graphs of connected objects or
+ joined DB tables respectively. Object paths are much more commonly used, as after all
+ Cayenne is supposed to provide a degree of isolation of the object model from the
+ database. However database paths are helpful in certain situations. General structure of
+ path expressions is the following:</p><pre class="programlisting"> [db:]segment[+][.segment[+]...]</pre><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>"db:" is an optional prefix indicating that the following path is a DB
+ path. Otherwise it is an object path.</p></li><li class="listitem"><p>"segment" is a name of a property (relationship or attribute in Cayenne
+ terms) in the path. Path must have at least one segment; segments are
+ separated by dot (".").</p></li><li class="listitem"><p>"+" An "OUTER JOIN" path component. Currently "+" only has effect when
+ translated to SQL as OUTER JOIN. When evaluating expressions in memory, it
+ is ignored.</p></li></ul></div><p>An object path expression represents a chain of property names rooted in a certain
+ (unspecified during expression creation) object and "navigating" to its related value.
+ E.g. a path expression "artist.name" might be a property path starting from a Painting
+ object, pointing to the related Artist object, and then to its name attribute. A few
+ more examples:</p><p>
+ </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>"name" - can be used to navigate (read) the "name" property of a Person
+ (or any other type of object that has a "name" property).</p></li><li class="listitem"><p>"artist.exhibits.closingDate" - can be used to navigate to a closing date
+ of any of the exhibits of a Painting's Artist object.</p></li><li class="listitem"><p>"artist.exhibits+.closingDate" - same as the previous example, but when
+ translated into SQL, an OUTER JOIN will be used for "exhibits".</p></li></ul></div><p>
+ </p><p>Similarly a database path expression is a dot-separated path through DB table joins
+ and columns. In Cayenne joins are mapped as DbRelationships with some symbolic names
+ (the closest concept to DbRelationship name in the DB world is a named foreign key
+ constraint. But DbRelationship names are usually chosen arbitrarily, without regard to
+ constraints naming or even constraints presence). A database path therefore might look
+ like this - "db:dbrelationshipX.dbrelationshipY.COLUMN_Z". More specific examples:</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>"db:NAME" - can be used to navigate to the value of "NAME" column of some
+ unspecified table.</p></li><li class="listitem"><p>"db:artist.artistExhibits.exhibit.CLOSING_DATE" - can be used to match a
+ closing date of any of the exhibits of a related artist record.</p></li></ul></div><p>Cayenne supports "aliases" in path Expressions. E.g. the same expression can be
+ written using explicit path or an alias:</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>"artist.exhibits.closingDate" - full path</p></li><li class="listitem"><p>"e.closingDate" - alias "e" is used for "artist.exhibits".</p></li></ul></div><p>SelectQuery using the second form of the path expression must be made
+ aware of the alias via <span class="italic">
+ "SelectQuery.aliasPathSplits(..)"</span>, otherwise an Exception will be
+ thrown. The main use of aliases is to allow users to control how SQL joins are generated
+ if the same path is encountered more than once in any given Expression. Each alias for
+ any given path would result in a separate join. Without aliases, a single join will be
+ used for a group of matching paths.</p></div><div class="section" title="Creating Expressions from Strings"><div class="titlepage"><div><div><h2 class="title"><a name="expressions-from-strings"></a>Creating Expressions from Strings </h2></div></div></div><p>While in most cases users are likely to rely on API from the following section for
+ expression creation, we'll start by showing String expressions, as this will help
+ understanding the semantics. A Cayenne expression can be represented as a String, which
+ can be later converted to an expression object using <code class="code">Expression.fromString</code>
+ static method. Here is an
+ example:</p><pre class="programlisting">String expString = "name like 'A%' and price < 1000";
Expression exp = Expression.fromString(expString);</pre><p>This
- particular expression may be used to match Paintings with names that start with "A" and
- a price less than $1000. While this example is pretty self-explanatory, there are a few
- points worth mentioning. "name" and "price" here are object paths discussed earlier. As
- always, paths themselves are not attached to a specific root entity and can be applied
- to any entity that has similarly named attributes or relationships. So when we are
- saying that this expression "may be used to match Paintings", we are implying that there
- may be other entities, for which this expression is valid. Now the expression details... </p><p><span class="italic">Character constants</span> that are not paths or numeric values
- should be enclosed in single or double quotes. Two of the expressions below are
- equivalent:</p><pre class="programlisting">name = 'ABC'
+ particular expression may be used to match Paintings with names that start with "A" and
+ a price less than $1000. While this example is pretty self-explanatory, there are a few
+ points worth mentioning. "name" and "price" here are object paths discussed earlier. As
+ always, paths themselves are not attached to a specific root entity and can be applied
+ to any entity that has similarly named attributes or relationships. So when we are
+ saying that this expression "may be used to match Paintings", we are implying that there
+ may be other entities, for which this expression is valid. Now the expression details... </p><p><span class="italic">Character constants</span> that are not paths or numeric values
+ should be enclosed in single or double quotes. Two of the expressions below are
+ equivalent:</p><pre class="programlisting">name = 'ABC'
// double quotes are escaped inside Java Strings of course
name = \"ABC\"</pre><p><span class="italic">Case sensitivity.</span> Expression operators are all case
- sensitive and are usually lowercase. Complex words follow the java camel-case
- style:</p><pre class="programlisting">// valid
+ sensitive and are usually lowercase. Complex words follow the java camel-case
+ style:</p><pre class="programlisting">// valid
name likeIgnoreCase 'A%'
// invalid - will throw a parse exception
-name LIKEIGNORECASE 'A%'</pre><p><span class="italic">Grouping with
- parenthesis</span>:</p><pre class="programlisting">value = (price + 250.00) * 3</pre><p><span class="italic">Path prefixes.</span> Object expressions are unquoted strings,
- optionally prefixed by "obj:" (usually they are not prefixed at all actually). Database
- expressions are always prefixed with "db:". A special kind of prefix, not discussed yet
- is "enum:" that prefixes an enumeration
- constant:</p><pre class="programlisting">// object path
+name LIKEIGNORECASE 'A%'</pre><p><span class="italic">Grouping with parenthesis:</span>
+ </p><pre class="programlisting">value = (price + 250.00) * 3</pre><p>
+ </p><p><span class="italic">Path prefixes.</span> Object expressions are unquoted strings,
+ optionally prefixed by "obj:" (usually they are not prefixed at all actually). Database
+ expressions are always prefixed with "db:". A special kind of prefix, not discussed yet
+ is "enum:" that prefixes an enumeration
+ constant:</p><pre class="programlisting">// object path
name = 'Salvador Dali'
// same object path - a rarely used form
@@ -81,88 +83,89 @@ db:NAME = 'Salvador Dali'
// enumeration constant
name = enum:org.foo.EnumClass.VALUE1</pre><p>
- <span class="italic">Binary conditions</span> are expressions that contain a path
- on the left, a value on the right, and some operation between them, such as equals,
- like, etc. They can be used as qualifiers in
- SelectQueries:</p><pre class="programlisting">name like 'A%'</pre><p><span class="italic">Named parameters.</span> Expressions can have named parameters (names that
- start with "$"). Parameterized expressions allow to create reusable expression
- templates. Also if an Expression contains a complex object that doesn't have a simple
- String representation (e.g. a Date, a DataObject, an ObjectId), parameterizing such
- expression is the only way to represent it as String. Here are some
- examples:</p><pre class="programlisting">Expression template = Expression.fromString("name = $name");
+ <span class="italic">Binary conditions</span> are expressions that contain a path
+ on the left, a value on the right, and some operation between them, such as equals,
+ like, etc. They can be used as qualifiers in
+ SelectQueries:</p><pre class="programlisting">name like 'A%'</pre><p>
+ <span class="italic">Named parameters.</span> Expressions can have named parameters (names that
+ start with "$"). Parameterized expressions allow to create reusable expression
+ templates. Also if an Expression contains a complex object that doesn't have a simple
+ String representation (e.g. a Date, a DataObject, an ObjectId), parameterizing such
+ expression is the only way to represent it as String. Here are some
+ examples:</p><pre class="programlisting">Expression template = Expression.fromString("name = $name");
...
Map p1 = Collections.singletonMap("name", "Salvador Dali");
Expression qualifier1 = template.expWithParameters(p1);
...
Map p2 = Collections.singletonMap("name", "Monet");
Expression qualifier2 = template.expWithParameters(p2);</pre><p>To
- create a named parameterized expression with a LIKE clause, SQL wildcards must be part
- of the values in the Map and not the expression string
- itself:</p><pre class="programlisting">Expression template = Expression.fromString("name like $name");
+ create a named parameterized expression with a LIKE clause, SQL wildcards must be part
+ of the values in the Map and not the expression string
+ itself:</p><pre class="programlisting">Expression template = Expression.fromString("name like $name");
...
Map p1 = Collections.singletonMap("name", "Salvador%");
Expression qualifier1 = template.expWithParameters(p1);</pre><p>When
- matching on a relationship, parameters can be Persistent objects or
- ObjectIds:</p><pre class="programlisting">Expression template = Expression.fromString("artist = $artist");
+ matching on a relationship, parameters can be Persistent objects or
+ ObjectIds:</p><pre class="programlisting">Expression template = Expression.fromString("artist = $artist");
...
Artist dali = // asume we fetched this one already
Map p1 = Collections.singletonMap("artist", dali);
Expression qualifier1 = template.expWithParameters(p1);</pre><p>Uninitialized
- parameters will be automatically pruned from expressions, so a user can omit some
- parameters when creating an expression from a parameterized
- template:</p><pre class="programlisting">Expression template = Expression.fromString("name like $name and dateOfBirth > $date");
+ parameters will be automatically pruned from expressions, so a user can omit some
+ parameters when creating an expression from a parameterized
+ template:</p><pre class="programlisting">Expression template = Expression.fromString("name like $name and dateOfBirth > $date");
...
Map p1 = Collections.singletonMap("name", "Salvador%");
Expression qualifier1 = template.expWithParameters(p1);
-// qualifier1 is now equals to "name like 'Salvador%'", the 'dateOfBirth' condition was
+// qualifier1 is now equals to "name like 'Salvador%'", the 'dateOfBirth' condition was
// pruned, as no value was specified for the $date parameter</pre><p><span class="italic">Null handling.</span> Handling of Java nulls as operands
- is no different from normal values. Instead of using special conditional operators, like
- SQL does (IS NULL, IS NOT NULL), "=" and "!=" expressions can be used directly with null
- values. It is up to Cayenne to translate expressions with nulls to the valid SQL.</p><p>
- </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>A formal definition of all possible valid expressions in a form of JavaCC
- grammar is provided in Appendix C</p></div><p>
- </p></div><div class="section" title="Creating Expressions with API"><div class="titlepage"><div><div><h2 class="title"><a name="expressions-with-expressionfactory"></a>Creating Expressions with API</h2></div></div></div><p>Creating expressions from Strings is a powerful and dynamic approach, however a safer
- alternative is to use Java API. It provides some degree of compile-time checking of
- expressions validity. The API is cenetred around ExpressionFactory class, and the
- Expression class. ExpressionFactory contains a number of rather self-explanatory factory
- methods. We won't be going over all of them in detail, but will rather show a few
- general examples and some gotchas. </p><p>The following code recreates the expression from the previous chapter, but now using
- expression
- API:</p><pre class="programlisting">// String expression: name like 'A%' and price < 1000
+ is no different from normal values. Instead of using special conditional operators, like
+ SQL does (IS NULL, IS NOT NULL), "=" and "!=" expressions can be used directly with null
+ values. It is up to Cayenne to translate expressions with nulls to the valid SQL.</p><p>
+ </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>A formal definition of all possible valid expressions in a form of JavaCC
+ grammar is provided in Appendix C</p></div><p>
+ </p></div><div class="section" title="Creating Expressions with API"><div class="titlepage"><div><div><h2 class="title"><a name="expressions-with-expressionfactory"></a>Creating Expressions with API</h2></div></div></div><p>Creating expressions from Strings is a powerful and dynamic approach, however a safer
+ alternative is to use Java API. It provides some degree of compile-time checking of
+ expressions validity. The API is cenetred around ExpressionFactory class, and the
+ Expression class. ExpressionFactory contains a number of rather self-explanatory factory
+ methods. We won't be going over all of them in detail, but will rather show a few
+ general examples and some gotchas. </p><p>The following code recreates the expression from the previous chapter, but now using
+ expression
+ API:</p><pre class="programlisting">// String expression: name like 'A%' and price < 1000
Expression e1 = ExpressionFactory.likeExp(Painting.NAME_PROPERTY, "A%");
Expression e2 = ExpressionFactory.lessExp(Painting.PRICE_PROPERTY, 1000);
Expression finalExp = e1.andExp(e2); </pre><p>This
- is more verbose than creating it from String, but it is also more resilient to the
- entity properties renaming and precludes semantic errors in the expression String.</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The last line in the example above shows how to create a new expression by
- "chaining" 2 other epxressions. A common error when chaining expressions is to
- assume that "andExp" and "orExp" append another expression to the current
- expression. In fact a new expression is created. I.e. Expression API treats
- existing expressions as immutable.</p></div><p>As discussed earlier, Cayenne supports aliases in path Expressions, allowing to
- control how SQL joins are generated if the same path is encountered more than once in
- the same Expression. Two ExpressionFactory methods allow to implicitly generate aliases
- to "split" match paths into individual joins if
- needed:</p><pre class="programlisting">Expression matchAllExp(String path, Collection values)
+ is more verbose than creating it from String, but it is also more resilient to the
+ entity properties renaming and precludes semantic errors in the expression String.</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The last line in the example above shows how to create a new expression by
+ "chaining" 2 other epxressions. A common error when chaining expressions is to
+ assume that "andExp" and "orExp" append another expression to the current
+ expression. In fact a new expression is created. I.e. Expression API treats
+ existing expressions as immutable.</p></div><p>As discussed earlier, Cayenne supports aliases in path Expressions, allowing to
+ control how SQL joins are generated if the same path is encountered more than once in
+ the same Expression. Two ExpressionFactory methods allow to implicitly generate aliases
+ to "split" match paths into individual joins if
+ needed:</p><pre class="programlisting">Expression matchAllExp(String path, Collection values)
Expression matchAllExp(String path, Object... values)</pre><p>"Path" argument to both of these methods can use a split character (a pipe symbol '|')
- instead of dot to indicate that relationship following a path should be split into a
- separate set of joins, one per collection value. There can only be one split at most in
- any given path. Split must always precede a relationship. E.g. "|exhibits.paintings",
- "exhibits|paintings", etc. Internally Cayenne would generate distinct aliases for each
- of the split expressions, forcing separate joins.</p></div><div class="section" title="Evaluating Expressions in Memory"><div class="titlepage"><div><div><h2 class="title"><a name="expressions-in-memory"></a>Evaluating Expressions in Memory</h2></div></div></div><p>When used in a query, an expression is converted to SQL WHERE clause (or ORDER BY
- clause) by Cayenne during query execution. Thus the actual evaluation against the data
- is done by the database engine. However the same expressions can also be used for
- accessing object properties, calculating values, in-memory filtering. </p><p>Checking whether an object satisfies an
- expression:</p><pre class="programlisting">Expression e = ExpressionFactory.inExp(User.NAME_PROPERTY, "John", "Bob");
+ instead of dot to indicate that relationship following a path should be split into a
+ separate set of joins, one per collection value. There can only be one split at most in
+ any given path. Split must always precede a relationship. E.g. "|exhibits.paintings",
+ "exhibits|paintings", etc. Internally Cayenne would generate distinct aliases for each
+ of the split expressions, forcing separate joins.</p></div><div class="section" title="Evaluating Expressions in Memory"><div class="titlepage"><div><div><h2 class="title"><a name="expressions-in-memory"></a>Evaluating Expressions in Memory</h2></div></div></div><p>When used in a query, an expression is converted to SQL WHERE clause (or ORDER BY
+ clause) by Cayenne during query execution. Thus the actual evaluation against the data
+ is done by the database engine. However the same expressions can also be used for
+ accessing object properties, calculating values, in-memory filtering. </p><p>Checking whether an object satisfies an
+ expression:</p><pre class="programlisting">Expression e = ExpressionFactory.inExp(User.NAME_PROPERTY, "John", "Bob");
User user = ...
if(e.match(user)) {
...
}</pre><p>Reading
- property
- value:</p><pre class="programlisting">Expression e = Expression.fromString(User.NAME_PROPERTY);
+ property
+ value:</p><pre class="programlisting">Expression e = Expression.fromString(User.NAME_PROPERTY);
String name = e.evaluate(user);</pre><p>Filtering a list of
- objects:</p><pre class="programlisting">Expression e = ExpressionFactory.inExp(User.NAME_PROPERTY, "John", "Bob");
+ objects:</p><pre class="programlisting">Expression e = ExpressionFactory.inExp(User.NAME_PROPERTY, "John", "Bob");
List<User> unfiltered = ...
List<User> filtered = e.filterObjects(unfiltered);</pre><p>
- </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Current limitation of in-memory expressions is that no collections are
- permitted in the property path.</p></div><p>
- </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="persistent-objects-objectcontext.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="orderings.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 6. Persistent Objects and ObjectContext </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 8. Orderings</td></tr></table></div></body></html>
\ No newline at end of file
+ </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Current limitation of in-memory expressions is that no collections are
+ permitted in the property path.</p></div><p>
+ </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="persistent-objects-objectcontext.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="orderings.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 6. Persistent Objects and ObjectContext </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 8. Orderings</td></tr></table></div></body></html>
\ No newline at end of file
Modified: cayenne/site/cms/trunk/content/docs/3.1/cayenne-guide/including-cayenne-in-project.html
URL: http://svn.apache.org/viewvc/cayenne/site/cms/trunk/content/docs/3.1/cayenne-guide/including-cayenne-in-project.html?rev=1425994&r1=1425993&r2=1425994&view=diff
==============================================================================
--- cayenne/site/cms/trunk/content/docs/3.1/cayenne-guide/including-cayenne-in-project.html (original)
+++ cayenne/site/cms/trunk/content/docs/3.1/cayenne-guide/including-cayenne-in-project.html Wed Dec 26 19:20:15 2012
@@ -1,356 +1,363 @@
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Chapter 4. Including Cayenne in a Project</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="cayenne-guide-part2.html" title="Part II. Cayenne Framework"><link rel="next" href="starting-cayenne.html" title="Chapter 5. Starting Cayenne"></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 4. Including Cayenne in a Project</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="cayenne-guide-part2.html">Prev</a> </td><th width="60%" align="center">Part II. Cayenne Framework</th><td width="20%" align=
"right"> <a accesskey="n" href="starting-cayenne.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 4. Including Cayenne in a Project"><div class="titlepage"><div><div><h2 class="title"><a name="including-cayenne-in-project"></a>Chapter 4. Including Cayenne in a Project</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="including-cayenne-in-project.html#jar-files-and-depdendencies">Jar Files and Dependencies</a></span></dt><dt><span class="section"><a href="including-cayenne-in-project.html#maven-projects">Maven Projects</a></span></dt><dt><span class="section"><a href="including-cayenne-in-project.html#ant-projects">Ant Projects</a></span></dt></dl></div><div class="section" title="Jar Files and Dependencies"><div class="titlepage"><div><div><h2 class="title"><a name="jar-files-and-depdendencies"></a>Jar Files and Dependencies</h2></div></div></div><p>Cayenne distri
bution contains the following core runtime jars in the distribution
- <code class="code">lib</code> directory: </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><span class="italic">cayenne-server-x.x.jar</span> - contains full
- Cayenne runtime (DI, adapters, DB access classes, etc.). Most applications
- will use only this file.</p></li><li class="listitem"><p>cayenne-client-x.x.jar - a subset of cayenne-server.jar trimmed for use on
- the client in an ROP application.</p></li><li class="listitem"><p>Other cayenne-* jars - various Cayenne extensions.</p></li></ul></div><p>When using <code class="code">cayenne-server-x.x.jar</code> you'll need a few third party jars (all
- included in <code class="code">lib/third-party</code> directory of the distribution): </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><a class="link" href="http://velocity.apache.org/" target="_top">Apache Velocity
- Template Engine</a>, version 1.6.x (and all its dependencies bundled
- with velocity-dep)</p></li><li class="listitem"><p><a class="link" href="http://commons.apache.org/collections/" target="_top">Apache Commons
- Collections</a>, version 3.2.1</p></li><li class="listitem"><p><a class="link" href="http://commons.apache.org/logging/" target="_top">Apache
- Commons Logging</a>, version 1.1</p></li></ul></div><p>Cayenne integrates with various caching, clustering and other frameworks. These
- optional integrations will require other third-party jars that the users will need to
- obtain on their own.</p></div><div class="section" title="Maven Projects"><div class="titlepage"><div><div><h2 class="title"><a name="maven-projects"></a>Maven Projects</h2></div></div></div><p>If you are using Maven, you won't have to deal with figuring out the dependencies. You
- can simply include cayenne-server artifact in your
- POM:</p><pre class="programlisting"><dependency>
+ <code class="code">lib</code> directory: </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><span class="italic">cayenne-server-x.x.jar</span> - contains full
+ Cayenne runtime (DI, adapters, DB access classes, etc.). Most applications
+ will use only this file.</p></li><li class="listitem"><p>cayenne-client-x.x.jar - a subset of cayenne-server.jar trimmed for use on
+ the client in an ROP application.</p></li><li class="listitem"><p>Other cayenne-* jars - various Cayenne extensions.</p></li></ul></div><p>When using <code class="code">cayenne-server-x.x.jar</code> you'll need a few third party jars (all
+ included in <code class="code">lib/third-party</code> directory of the distribution): </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><a class="link" href="http://velocity.apache.org/" target="_top">Apache Velocity
+ Template Engine</a>, version 1.6.x (and all its dependencies bundled
+ with velocity-dep)</p></li><li class="listitem"><p><a class="link" href="http://commons.apache.org/collections/" target="_top">Apache Commons
+ Collections</a>, version 3.2.1</p></li><li class="listitem"><p><a class="link" href="http://commons.apache.org/logging/" target="_top">Apache
+ Commons Logging</a>, version 1.1</p></li></ul></div><p>Cayenne integrates with various caching, clustering and other frameworks. These
+ optional integrations will require other third-party jars that the users will need to
+ obtain on their own.</p></div><div class="section" title="Maven Projects"><div class="titlepage"><div><div><h2 class="title"><a name="maven-projects"></a>Maven Projects</h2></div></div></div><p>If you are using Maven, you won't have to deal with figuring out the dependencies. You
+ can simply include cayenne-server artifact in your
+ POM:</p><pre class="programlisting"><dependency>
<groupId>org.apache.cayenne</groupId>
<artifactId>cayenne-server</artifactId>
<version>X.Y.Z</version>
</dependency></pre><p>Additionally Cayenne provides a Maven plugin with a set of goals to perform various project
- tasks, such as synching generated Java classes with the mapping, described in the
- following subsection. The full plugin name is
- <code class="code">org.apache.cayenne.plugins:maven-cayenne-plugin</code>.</p><div class="section" title="cgen"><div class="titlepage"><div><div><h3 class="title"><a name="mvn-cgen"></a>cgen</h3></div></div></div><p><code class="code">cgen</code> is a <code class="code">maven-cayenne-plugin</code> goal that generates and maintains
- source (.java) files of persistent objects based on a DataMap. By default, it is
- bound to the generate-sources phase. If "makePairs" is set to "true" (which is the
- recommended default), this task will generate a pair of classes
- (superclass/subclass) for each ObjEntity in the DataMap. Superclasses should not be
- changed manually, since they are always overwritten. Subclasses are never
- overwritten and may be later customized by the user. If "makePairs" is set to
- "false", a single class will be generated for each ObjEntity. </p><p>By creating custom templates, you can use cgen to generate other output (such as
- web pages, reports, specialized code templates) based on DataMap information.</p><p>
- </p><table frame="void" id="d0e226"><caption>Table 4.1. cgen required parameters</caption><col width="14%"><col width="6%"><col width="80%"><thead><tr>
- <th>Name</th>
- <th>Type</th>
- <th>Description</th>
- </tr></thead><tbody><tr>
- <td><code class="code">map</code>
- </td>
- <td>File</td>
- <td>DataMap XML file which serves as a source of metadata for class
- generation. E.g.
- <code class="code">${project.basedir}/src/main/resources/my.map.xml</code></td>
- </tr><tr>
- <td><code class="code">destDir</code></td>
- <td>File</td>
- <td>Root destination directory for Java classes (ignoring their package
- names).</td>
- </tr></tbody></table><p>
- </p><table frame="void" id="d0e273"><caption>Table 4.2. cgen optional parameters</caption><col width="33%"><col width="8%"><col width="59%"><thead><tr>
- <th>Name</th>
- <th>Type</th>
- <th>Description</th>
- </tr></thead><tbody><tr>
- <td><code class="code">additionalMaps</code>
- </td>
- <td>File</td>
- <td>A directory that contains additional DataMap XML files that may be
- needed to resolve cross-DataMap relationships for the the main
- DataMap, for which class generation occurs.</td>
- </tr><tr>
- <td><code class="code">client</code></td>
- <td>boolean</td>
- <td>Whether we are generating classes for the client tier in a Remote
- Object Persistence application. "False" by default.</td>
- </tr><tr>
- <td><code class="code">embeddableTemplate</code></td>
- <td>String</td>
- <td>Location of a custom Velocity template file for Embeddable class
- generation. If omitted, default template is used.</td>
- </tr><tr>
- <td><code class="code">embeddableSuperTemplate</code></td>
- <td>String</td>
- <td>Location of a custom Velocity template file for Embeddable
- superclass generation. Ignored unless "makepairs" set to "true". If
- omitted, default template is used.</td>
- </tr><tr>
- <td><code class="code">encoding</code></td>
- <td>String</td>
- <td>Generated files encoding if different from the default on current
- platform. Target encoding must be supported by the JVM running the
- build. Standard encodings supported by Java on all platforms are
- US-ASCII, ISO-8859-1, UTF-8, UTF-16BE, UTF-16LE, UTF-16. See
- javadocs for java.nio.charset.Charset for more information.</td>
- </tr><tr>
- <td><code class="code">excludeEntities</code></td>
- <td>String</td>
- <td>A comma-separated list of ObjEntity patterns (expressed as a perl5
- regex) to exclude from template generation. By default none of the
- DataMap entities are excluded.</td>
- </tr><tr>
- <td><code class="code">includeEntities</code></td>
- <td>String</td>
- <td>A comma-separated list of ObjEntity patterns (expressed as a perl5
- regex) to include from template generation. By default all DataMap
- entities are included.</td>
- </tr><tr>
- <td><code class="code">makePairs</code></td>
- <td>boolean</td>
- <td>If "true" (a recommended default), will generate subclass/superclass
- pairs, with all generated code placed in superclass.</td>
- </tr><tr>
- <td><code class="code">mode</code></td>
- <td>String</td>
- <td>Specifies class generator iteration target. There are three possible
- values: "entity" (default), "datamap", "all". "entity" performs one
- generator iteration for each included ObjEntity, applying either
- standard to custom entity templates. "datamap" performs a single
- iteration, applying DataMap templates. "All" is a combination of
- entity and datamap.</td>
- </tr><tr>
- <td><code class="code">overwrite</code></td>
- <td>boolean</td>
- <td>Only has effect when "makePairs" is set to "false". If "overwrite"
- os "true", will overwrite older versions of generated classes.</td>
- </tr><tr>
- <td><code class="code">superPkg</code></td>
- <td>String</td>
- <td>Java package name of generated superclasses. Only has effect if
- "makepairs" and "usePkgPath" are set to "true" (both are true by
- default). Defines a common package for all generated Java classes.
- If omitted, each superclass will be placed in the same package as
- subclass.</td>
- </tr><tr>
- <td><code class="code">superTemplate</code></td>
- <td>String</td>
- <td>Location of a custom Velocity template file for ObjEntity superclass
- generation. Only has effect if "makepairs" set to "true". If
- omitted, default template is used.</td>
- </tr><tr>
- <td><code class="code">template</code></td>
- <td>String</td>
- <td>Location of a custom Velocity template file for ObjEntity class
- generation. If omitted, default template is used.</td>
- </tr><tr>
- <td><code class="code">usePkgPath</code></td>
- <td>boolean</td>
- <td>If set to "true" (default), a directory tree will be generated in
- "destDir" corresponding to the class package structure, if set to
- "false", classes will be generated in "destDir" ignoring their
- package.</td>
- </tr></tbody></table><p>Example - a typical class generation scenario, where pairs of classes are
- generated, and superclasses are placed in a separate package:
- </p><pre class="programlisting"><plugin>
- <groupId>org.apache.cayenne.plugins</groupId>
- <artifactId>maven-cayenne-plugin</artifactId>
- <version>X.Y.Z</version>
+ tasks, such as synching generated Java classes with the mapping, described in the
+ following subsection. The full plugin name is
+ <code class="code">org.apache.cayenne.plugins:maven-cayenne-plugin</code>.</p><div class="section" title="cgen"><div class="titlepage"><div><div><h3 class="title"><a name="mvn-cgen"></a>cgen</h3></div></div></div><p><code class="code">cgen</code> is a <code class="code">maven-cayenne-plugin</code> goal that generates and maintains
+ source (.java) files of persistent objects based on a DataMap. By default, it is
+ bound to the generate-sources phase. If "makePairs" is set to "true" (which is the
+ recommended default), this task will generate a pair of classes
+ (superclass/subclass) for each ObjEntity in the DataMap. Superclasses should not be
+ changed manually, since they are always overwritten. Subclasses are never
+ overwritten and may be later customized by the user. If "makePairs" is set to
+ "false", a single class will be generated for each ObjEntity. </p><p>By creating custom templates, you can use cgen to generate other output (such as
+ web pages, reports, specialized code templates) based on DataMap information.</p><p>
+ </p><table frame="void" id="d0e226"><caption>Table 4.1. cgen required parameters</caption><col width="14%"><col width="6%"><col width="80%"><thead><tr>
+ <th>Name</th>
+ <th>Type</th>
+ <th>Description</th>
+ </tr></thead><tbody><tr>
+ <td><code class="code">map</code>
+ </td>
+ <td>File</td>
+ <td>DataMap XML file which serves as a source of metadata for class
+ generation. E.g.
+ <code class="code">${project.basedir}/src/main/resources/my.map.xml</code></td>
+ </tr><tr>
+ <td><code class="code">destDir</code></td>
+ <td>File</td>
+ <td>Root destination directory for Java classes (ignoring their package
+ names).</td>
+ </tr></tbody></table><p>
+ </p><table frame="void" id="d0e273"><caption>Table 4.2. cgen optional parameters</caption><col width="33%"><col width="8%"><col width="59%"><thead><tr>
+ <th>Name</th>
+ <th>Type</th>
+ <th>Description</th>
+ </tr></thead><tbody><tr>
+ <td><code class="code">additionalMaps</code>
+ </td>
+ <td>File</td>
+ <td>A directory that contains additional DataMap XML files that may be
+ needed to resolve cross-DataMap relationships for the the main
+ DataMap, for which class generation occurs.</td>
+ </tr><tr>
+ <td><code class="code">client</code></td>
+ <td>boolean</td>
+ <td>Whether we are generating classes for the client tier in a Remote
+ Object Persistence application. "False" by default.</td>
+ </tr><tr>
+ <td><code class="code">embeddableTemplate</code></td>
+ <td>String</td>
+ <td>Location of a custom Velocity template file for Embeddable class
+ generation. If omitted, default template is used.</td>
+ </tr><tr>
+ <td><code class="code">embeddableSuperTemplate</code></td>
+ <td>String</td>
+ <td>Location of a custom Velocity template file for Embeddable
+ superclass generation. Ignored unless "makepairs" set to "true". If
+ omitted, default template is used.</td>
+ </tr><tr>
+ <td><code class="code">encoding</code></td>
+ <td>String</td>
+ <td>Generated files encoding if different from the default on current
+ platform. Target encoding must be supported by the JVM running the
+ build. Standard encodings supported by Java on all platforms are
+ US-ASCII, ISO-8859-1, UTF-8, UTF-16BE, UTF-16LE, UTF-16. See
+ javadocs for java.nio.charset.Charset for more information.</td>
+ </tr><tr>
+ <td><code class="code">excludeEntities</code></td>
+ <td>String</td>
+ <td>A comma-separated list of ObjEntity patterns (expressed as a perl5
+ regex) to exclude from template generation. By default none of the
+ DataMap entities are excluded.</td>
+ </tr><tr>
+ <td><code class="code">includeEntities</code></td>
+ <td>String</td>
+ <td>A comma-separated list of ObjEntity patterns (expressed as a perl5
+ regex) to include from template generation. By default all DataMap
+ entities are included.</td>
+ </tr><tr>
+ <td><code class="code">makePairs</code></td>
+ <td>boolean</td>
+ <td>If "true" (a recommended default), will generate subclass/superclass
+ pairs, with all generated code placed in superclass.</td>
+ </tr><tr>
+ <td><code class="code">mode</code></td>
+ <td>String</td>
+ <td>Specifies class generator iteration target. There are three possible
+ values: "entity" (default), "datamap", "all". "entity" performs one
+ generator iteration for each included ObjEntity, applying either
+ standard to custom entity templates. "datamap" performs a single
+ iteration, applying DataMap templates. "All" is a combination of
+ entity and datamap.</td>
+ </tr><tr>
+ <td><code class="code">overwrite</code></td>
+ <td>boolean</td>
+ <td>Only has effect when "makePairs" is set to "false". If "overwrite"
+ os "true", will overwrite older versions of generated classes.</td>
+ </tr><tr>
+ <td><code class="code">superPkg</code></td>
+ <td>String</td>
+ <td>Java package name of generated superclasses. Only has effect if
+ "makepairs" and "usePkgPath" are set to "true" (both are true by
+ default). Defines a common package for all generated Java classes.
+ If omitted, each superclass will be placed in the same package as
+ subclass.</td>
+ </tr><tr>
+ <td><code class="code">superTemplate</code></td>
+ <td>String</td>
+ <td>Location of a custom Velocity template file for ObjEntity superclass
+ generation. Only has effect if "makepairs" set to "true". If
+ omitted, default template is used.</td>
+ </tr><tr>
+ <td><code class="code">template</code></td>
+ <td>String</td>
+ <td>Location of a custom Velocity template file for ObjEntity class
+ generation. If omitted, default template is used.</td>
+ </tr><tr>
+ <td><code class="code">usePkgPath</code></td>
+ <td>boolean</td>
+ <td>If set to "true" (default), a directory tree will be generated in
+ "destDir" corresponding to the class package structure, if set to
+ "false", classes will be generated in "destDir" ignoring their
+ package.</td>
+ </tr></tbody></table><p>
+ Example - a typical class generation scenario, where pairs of classes are
+ generated, and superclasses are placed in a separate package:
+ </p><pre class="programlisting"><plugin>
+ <groupId>org.apache.cayenne.plugins</groupId>
+ <artifactId>maven-cayenne-plugin</artifactId>
+ <version>X.Y.Z</version>
- <!--
- There's an intermittent problem when using Maven/cgen in Eclipse with m2eclipse plugin that
+ <!--
+ There's an intermittent problem when using Maven/cgen in Eclipse with m2eclipse plugin that
requires placing "configuration" section at the plugin level, instead of execution
level.
- -->
- <configuration>
- <map>${project.basedir}/src/main/resources/my.map.xml</map>
- <destDir>${project.basedir}/src/main/java</destDir>
- <superPkg>org.example.model.auto</superPkg>
- </configuration>
+ -->
+ <configuration>
+ <map>${project.basedir}/src/main/resources/my.map.xml</map>
+ <destDir>${project.basedir}/src/main/java</destDir>
+ <superPkg>org.example.model.auto</superPkg>
+ </configuration>
- <executions>
- <execution>
- <goals>
- <goal>cgen</goal>
- </goals>
- </execution>
- </executions>
+ <executions>
+ <execution>
+ <goals>
+ <goal>cgen</goal>
+ </goals>
+ </execution>
+ </executions>
</plugin></pre></div><div class="section" title="cdbgen"><div class="titlepage"><div><div><h3 class="title"><a name="mvn-cdbgen"></a>cdbgen</h3></div></div></div><p><code class="code">cdbgen</code> is a <code class="code">maven-cayenne-plugin</code> goal that drops and/or generates
- tables in a database on Cayenne DataMap. By default, it is bound to the
- pre-integration-test phase.</p><table frame="void" id="d0e474"><caption>Table 4.3. cdbgen required parameters</caption><col width="14%"><col width="6%"><col width="80%"><thead><tr>
- <th>Name</th>
- <th>Type</th>
- <th>Description</th>
- </tr></thead><tbody><tr>
- <td><code class="code">map</code>
- </td>
- <td>File</td>
- <td>DataMap XML file which serves as a source of metadata for DB schema
- generation. E.g.
- <code class="code">${project.basedir}/src/main/resources/my.map.xml</code></td>
- </tr><tr>
- <td><code class="code">driver</code></td>
- <td>String</td>
- <td>A class of JDBC driver to use for the target database.</td>
- </tr><tr>
- <td><code class="code">url</code></td>
- <td>String</td>
- <td>JDBC connection URL of a target database.</td>
- </tr></tbody></table><p>
- </p><table frame="void" width="792" id="d0e534"><caption>Table 4.4. cdbgen optional parameters</caption><col width="18%"><col width="7%"><col width="79%"><thead><tr>
- <th>Name</th>
- <th>Type</th>
- <th>Description</th>
- </tr></thead><tbody><tr>
- <td><code class="code">adapter</code>
- </td>
- <td>String</td>
- <td>Java class name implementing org.apache.cayenne.dba.DbAdapter. While
- this attribute is optional (a generic JdbcAdapter is used if not
- set), it is highly recommended to specify correct target
- adapter.</td>
- </tr><tr>
- <td><code class="code">createFK</code></td>
- <td>boolean</td>
- <td>Indicates whether cdbgen should create foreign key constraints. Default is "true".</td>
- </tr><tr>
- <td><code class="code">createPK</code></td>
- <td>boolean</td>
- <td>Indicates whether cdbgen should create Cayenne-specific auto PK objects. Default is
- "true".</td>
- </tr><tr>
- <td><code class="code">createTables</code></td>
- <td>boolean</td>
- <td>Indicates whether cdbgen should create new tables. Default is "true".</td>
- </tr><tr>
- <td><code class="code">dropPK</code></td>
- <td>boolean</td>
- <td>Indicates whether cdbgen should drop Cayenne primary key support objects. Default is
- "false".</td>
- </tr><tr>
- <td><code class="code">dropTables</code></td>
- <td>boolean</td>
- <td>Indicates whether cdbgen should drop the tables before attempting to create new ones.
- Default is "false".</td>
- </tr><tr>
- <td><code class="code">password</code></td>
- <td>String</td>
- <td>Database user password.</td>
- </tr><tr>
- <td><code class="code">username</code></td>
- <td>String</td>
- <td>Database user name.</td>
- </tr></tbody></table><p>
- </p><p>Example - creating a DB schema on a local HSQLDB
- database:</p><pre class="programlisting"><plugin>
- <groupId>org.apache.cayenne.plugins</groupId>
- <artifactId>maven-cayenne-plugin</artifactId>
- <version>X.Y.Z</version>
+ tables in a database on Cayenne DataMap. By default, it is bound to the
+ pre-integration-test phase.</p><table frame="void" id="d0e474"><caption>Table 4.3. cdbgen required parameters</caption><col width="14%"><col width="10%"><col width="76%"><thead><tr>
+ <th>Name</th>
+ <th>Type</th>
+ <th>Description</th>
+ </tr></thead><tbody><tr>
+ <td><code class="code">map</code>
+ </td>
+ <td>File</td>
+ <td>DataMap XML file which serves as a source of metadata for DB schema
+ generation. E.g.
+ <code class="code">${project.basedir}/src/main/resources/my.map.xml</code></td>
+ </tr><tr>
+ <td><code class="code">driver</code></td>
+ <td>String</td>
+ <td>A class of JDBC driver to use for the target database.</td>
+ </tr><tr>
+ <td><code class="code">url</code></td>
+ <td>String</td>
+ <td>JDBC connection URL of a target database.</td>
+ </tr></tbody></table><p>
+ </p><table frame="void" id="d0e534"><caption>Table 4.4. cdbgen optional parameters</caption><col width="18%"><col width="11%"><col width="75%"><thead><tr>
+ <th>Name</th>
+ <th>Type</th>
+ <th>Description</th>
+ </tr></thead><tbody><tr>
+ <td><code class="code">adapter</code>
+ </td>
+ <td>String</td>
+ <td>Java class name implementing org.apache.cayenne.dba.DbAdapter. While
+ this attribute is optional (a generic JdbcAdapter is used if not
+ set), it is highly recommended to specify correct target
+ adapter.</td>
+ </tr><tr>
+ <td><code class="code">createFK</code></td>
+ <td>boolean</td>
+ <td>Indicates whether cdbgen should create foreign key constraints. Default is "true".</td>
+ </tr><tr>
+ <td><code class="code">createPK</code></td>
+ <td>boolean</td>
+ <td>Indicates whether cdbgen should create Cayenne-specific auto PK objects. Default is
+ "true".</td>
+ </tr><tr>
+ <td><code class="code">createTables</code></td>
+ <td>boolean</td>
+ <td>Indicates whether cdbgen should create new tables. Default is "true".</td>
+ </tr><tr>
+ <td><code class="code">dropPK</code></td>
+ <td>boolean</td>
+ <td>Indicates whether cdbgen should drop Cayenne primary key support objects. Default is
+ "false".</td>
+ </tr><tr>
+ <td><code class="code">dropTables</code></td>
+ <td>boolean</td>
+ <td>Indicates whether cdbgen should drop the tables before attempting to create new ones.
+ Default is "false".</td>
+ </tr><tr>
+ <td><code class="code">password</code></td>
+ <td>String</td>
+ <td>Database user password.</td>
+ </tr><tr>
+ <td><code class="code">username</code></td>
+ <td>String</td>
+ <td>Database user name.</td>
+ </tr></tbody></table><p>
+ </p><p>Example - creating a DB schema on a local HSQLDB
+ database:</p><pre class="programlisting"><plugin>
+ <groupId>org.apache.cayenne.plugins</groupId>
+ <artifactId>maven-cayenne-plugin</artifactId>
+ <version>X.Y.Z</version>
- <executions>
- <execution>
- <configuration>
- <map>${project.basedir}/src/main/resources/my.map.xml</map>
- <url>jdbc:hsqldb:hsql://localhost/testdb</url>
- <adapter>org.apache.cayenne.dba.hsqldb.HSQLDBAdapter</adapter>
- <driver>org.hsqldb.jdbcDriver</driver>
- <username>sa</username>
- </configuration>
- <goals>
- <goal>cdbgen</goal>
- </goals>
- </execution>
- </executions>
+ <executions>
+ <execution>
+ <configuration>
+ <map>${project.basedir}/src/main/resources/my.map.xml</map>
+ <url>jdbc:hsqldb:hsql://localhost/testdb</url>
+ <adapter>org.apache.cayenne.dba.hsqldb.HSQLDBAdapter</adapter>
+ <driver>org.hsqldb.jdbcDriver</driver>
+ <username>sa</username>
+ </configuration>
+ <goals>
+ <goal>cdbgen</goal>
+ </goals>
+ </execution>
+ </executions>
</plugin></pre></div><div class="section" title="cdbimport"><div class="titlepage"><div><div><h3 class="title"><a name="mvn-cdbimport"></a>cdbimport</h3></div></div></div><p><code class="code">cdbimport</code> is a <code class="code">maven-cayenne-plugin</code> goal that generates
- a DataMap based on an existing database schema. By default, it is bound to the
- generate-sources phase. This allows you to generate your DataMap prior to building
- your project, which may be necessary if you are also using the cgen task.</p><table frame="void" id="d0e665"><caption>Table 4.5. cdbimport required parameters</caption><col width="14%"><col width="6%"><col width="80%"><thead><tr>
- <th>Name</th>
- <th>Type</th>
- <th>Description</th>
- </tr></thead><tbody><tr>
- <td><code class="code">map</code>
- </td>
- <td>File</td>
- <td>DataMap XML file which is the destination of the schema import.
- Maybe an existing file. If this file does not exist, it is created
- when cdbimport is executed. E.g.
- <code class="code">${project.basedir}/src/main/resources/my.map.xml</code></td>
- </tr><tr>
- <td><code class="code">driver</code></td>
- <td>String</td>
- <td>A class of JDBC driver to use for the target database.</td>
- </tr><tr>
- <td><code class="code">url</code></td>
- <td>String</td>
- <td>JDBC connection URL of a target database.</td>
- </tr></tbody></table><p>
- </p><table frame="void" width="822" id="d0e725"><caption>Table 4.6. cdbimport optional parameters</caption><col width="24%"><col width="7%"><col width="79%"><thead><tr>
- <th>Name</th>
- <th>Type</th>
- <th>Description</th>
- </tr></thead><tbody><tr>
- <td><code class="code">adapter</code>
- </td>
- <td>String</td>
- <td>Java class name implementing org.apache.cayenne.dba.DbAdapter. While
- this attribute is optional (a generic JdbcAdapter is used if not
- set), it is highly recommended to specify correct target
- adapter.</td>
- </tr><tr>
- <td><code class="code">importProcedures</code></td>
- <td>boolean</td>
- <td>Indicates whether stored procedures should be imported from the
- database. Default is false. </td>
- </tr><tr>
- <td><code class="code">meaningfulPk</code></td>
- <td>boolean</td>
- <td>Indicates whether primary keys should be mapped as attributes of the
- ObjEntity. Default is false. </td>
- </tr><tr>
- <td><code class="code">namingStrategy</code></td>
- <td>String</td>
- <td>The naming strategy used for mapping database names to object entity
- names. Default is
- <code class="code">org.apache.cayenne.map.naming.SmartNamingStrategy</code>.
- </td>
- </tr><tr>
- <td><code class="code">overwriteExisting</code></td>
- <td>boolean</td>
- <td>Indicates whether existing DB and object entities should be
- overwritten. This is an all-or-nothing setting. If you need finer
- granularity, use the CayenneModeler. Default is "true". </td>
- </tr><tr>
- <td><code class="code">password</code></td>
- <td>String</td>
- <td>Database user password.</td>
- </tr><tr>
- <td><code class="code">procedurePattern</code></td>
- <td>String</td>
- <td>Pattern to match stored procedure names against for import. Default
- is to match all stored procedures. This value is only meaningful if
- importProcedures is true. </td>
- </tr><tr>
- <td><code class="code">schemaName</code></td>
- <td>String</td>
- <td>Database schema to import tables/stored procedures from. </td>
- </tr><tr>
- <td><code class="code">tablePattern</code></td>
- <td>String</td>
- <td>Pattern to match table names against for import. Default is to match
- all tables. </td>
- </tr><tr>
- <td><code class="code">username</code></td>
- <td>String</td>
- <td>Database user name.</td>
- </tr></tbody></table><p>
- </p><p>Example - loading a DB schema from a local HSQLDB database (essentially a reverse
- operation compared to the cdbgen example above)
- :</p><pre class="programlisting"><plugin>
- <groupId>org.apache.cayenne.plugins</groupId>
- <artifactId>maven-cayenne-plugin</artifactId>
- <version>X.Y.Z</version>
+ a DataMap based on an existing database schema. By default, it is bound to the
+ generate-sources phase. This allows you to generate your DataMap prior to building
+ your project, which may be necessary if you are also using the cgen task.</p><table frame="void" id="d0e665"><caption>Table 4.5. cdbimport required parameters</caption><col width="14%"><col width="10%"><col width="76%"><thead><tr>
+ <th>Name</th>
+ <th>Type</th>
+ <th>Description</th>
+ </tr></thead><tbody><tr>
+ <td><code class="code">map</code>
+ </td>
+ <td>File</td>
+ <td>DataMap XML file which is the destination of the schema import.
+ Maybe an existing file. If this file does not exist, it is created
+ when cdbimport is executed. E.g.
+ <code class="code">${project.basedir}/src/main/resources/my.map.xml</code></td>
+ </tr><tr>
+ <td><code class="code">driver</code></td>
+ <td>String</td>
+ <td>A class of JDBC driver to use for the target database.</td>
+ </tr><tr>
+ <td><code class="code">url</code></td>
+ <td>String</td>
+ <td>JDBC connection URL of a target database.</td>
+ </tr></tbody></table><p>
+ </p><table frame="void" id="d0e725"><caption>Table 4.6. cdbimport optional parameters</caption><col width="25%"><col width="10%"><col width="65%"><thead><tr>
+ <th>Name</th>
+ <th>Type</th>
+ <th>Description</th>
+ </tr></thead><tbody><tr>
+ <td><code class="code">adapter</code>
+ </td>
+ <td>String</td>
+ <td>Java class name implementing org.apache.cayenne.dba.DbAdapter. While
+ this attribute is optional (a generic JdbcAdapter is used if not
+ set), it is highly recommended to specify correct target
+ adapter.</td>
+ </tr><tr>
+ <td><code class="code">importProcedures</code></td>
+ <td>boolean</td>
+ <td>Indicates whether stored procedures should be imported from the
+ database. Default is false. </td>
+ </tr><tr>
+ <td><code class="code">meaningfulPk</code></td>
+ <td>boolean</td>
+ <td>Indicates whether primary keys should be mapped as attributes of the
+ ObjEntity. Default is false. </td>
+ </tr><tr>
+ <td><code class="code">namingStrategy</code></td>
+ <td>String</td>
+ <td>The naming strategy used for mapping database names to object entity
+ names. Default is
+ <code class="code">org.apache.cayenne.map.naming.SmartNamingStrategy</code>.
+ </td>
+ </tr><tr>
+ <td><code class="code">overwriteExisting</code></td>
+ <td>boolean</td>
+ <td>Indicates whether existing DB and object entities should be
+ overwritten. This is an all-or-nothing setting. If you need finer
+ granularity, use the CayenneModeler. Default is "true". </td>
+ </tr><tr>
+ <td><code class="code">password</code></td>
+ <td>String</td>
+ <td>Database user password.</td>
+ </tr><tr>
+ <td><code class="code">procedurePattern</code></td>
+ <td>String</td>
+ <td>Pattern to match stored procedure names against for import. Default
+ is to match all stored procedures. This value is only meaningful if
+ importProcedures is true. </td>
+ </tr><tr>
+ <td><code class="code">schemaName</code></td>
+ <td>String</td>
+ <td>Database schema to import tables/stored procedures from. </td>
+ </tr><tr>
+ <td><code class="code">tablePattern</code></td>
+ <td>String</td>
+ <td>Pattern to match table names against for import. Default is to match
+ all tables. </td>
+ </tr><tr>
+ <td><code class="code">username</code></td>
+ <td>String</td>
+ <td>Database user name.</td>
+ </tr></tbody></table><p>
+ </p><p>Example - loading a DB schema from a local HSQLDB database (essentially a reverse operation
+ compared to the cdbgen example above)
+ :</p><pre class="programlisting"><plugin>
+ <groupId>org.apache.cayenne.plugins</groupId>
+ <artifactId>maven-cayenne-plugin</artifactId>
+ <version>X.Y.Z</version>
- <executions>
- <execution>
- <configuration>
- <map>${project.basedir}/src/main/resources/my.map.xml</map>
- <url>jdbc:hsqldb:hsql://localhost/testdb</url>
- <adapter>org.apache.cayenne.dba.hsqldb.HSQLDBAdapter</adapter>
- <driver>org.hsqldb.jdbcDriver</driver>
- <username>sa</username>
- </configuration>
- <goals>
- <goal>cdbimport</goal>
- </goals>
- </execution>
- </executions>
-</plugin></pre></div></div><div class="section" title="Ant Projects"><div class="titlepage"><div><div><h2 class="title"><a name="ant-projects"></a>Ant Projects</h2></div></div></div><div class="section" title="cgen"><div class="titlepage"><div><div><h3 class="title"><a name="ant-cgen"></a>cgen</h3></div></div></div></div><div class="section" title="cdbgen"><div class="titlepage"><div><div><h3 class="title"><a name="ant-cdbgen"></a>cdbgen</h3></div></div></div></div><div class="section" title="cdbimport"><div class="titlepage"><div><div><h3 class="title"><a name="ant-cdbimport"></a>cdbimport</h3></div></div></div></div><div class="section" title="cdataport"><div class="titlepage"><div><div><h3 class="title"><a name="ant-cdataport"></a>cdataport</h3></div></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="cayenne-guide-part2.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="starting-cayenne.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part II. Cayenne Framework </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 5. Starting Cayenne</td></tr></table></div></body></html>
\ No newline at end of file
+ <executions>
+ <execution>
+ <configuration>
+ <map>${project.basedir}/src/main/resources/my.map.xml</map>
+ <url>jdbc:mysql://127.0.0.1/mydb</url>
+ <adapter>org.apache.cayenne.dba.hsqldb.HSQLDBAdapter</adapter>
+ <driver>com.mysql.jdbc.Driver</driver>
+ <username>sa</username>
+ </configuration>
+ <goals>
+ <goal>cdbimport</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin></pre></div></div><div class="section" title="Ant Projects"><div class="titlepage"><div><div><h2 class="title"><a name="ant-projects"></a>Ant Projects</h2></div></div></div><div class="section" title="cgen"><div class="titlepage"><div><div><h3 class="title"><a name="ant-cgen"></a>cgen</h3></div></div></div></div><div class="section" title="cdbgen"><div class="titlepage"><div><div><h3 class="title"><a name="ant-cdbgen"></a>cdbgen</h3></div></div></div></div><div class="section" title="cdbimport"><div class="titlepage"><div><div><h3 class="title"><a name="ant-cdbimport"></a>cdbimport</h3></div></div></div><p>This is an Ant counterpart of "cdbimport" goal of maven-cayenne-plugin described
+ above. It has exactly the same properties. Here is a usage
+ example:</p><pre class="programlisting"> <cdbimport map="${context.dir}/WEB-INF/my.map.xml"
+ driver="com.mysql.jdbc.Driver"
+ url="jdbc:mysql://127.0.0.1/mydb"
+ username="sa"/> </pre><p>
+ </p></div><div class="section" title="cdataport"><div class="titlepage"><div><div><h3 class="title"><a name="ant-cdataport"></a>cdataport</h3></div></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="cayenne-guide-part2.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="starting-cayenne.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part II. Cayenne Framework </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 5. Starting Cayenne</td></tr></table></div></body></html>
\ No newline at end of file