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 19:38:18 UTC
svn commit: r1425988 [2/4] - in
/cayenne/main/branches/STABLE-3.1/docs/docbook: cayenne-guide/src/docbkx/
getting-started-rop/src/docbkx/ getting-started/src/docbkx/ stylesheets/
Modified: cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/expressions.xml
URL: http://svn.apache.org/viewvc/cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/expressions.xml?rev=1425988&r1=1425987&r2=1425988&view=diff
==============================================================================
--- cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/expressions.xml (original)
+++ cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/expressions.xml Wed Dec 26 18:38:17 2012
@@ -1,249 +1,250 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="expressions">
- <title>Expressions</title>
- <section xml:id="expressions-overview">
- <title>Expressions Overview</title>
- <para>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.</para>
- </section>
- <section xml:id="path-expressions">
- <title>Path Expressions</title>
- <para>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:<programlisting> [db:]segment[+][.segment[+]...]</programlisting><itemizedlist>
- <listitem>
- <para>"db:" is an optional prefix indicating that the following path is a DB
- path. Otherwise it is an object path.</para>
- </listitem>
- <listitem>
- <para>"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 (".").</para>
- </listitem>
- <listitem>
- <para>"+" An "OUTER JOIN" path component. Currently "+" only has effect when
- translated to SQL as OUTER JOIN. When evaluating expressions in memory, it
- is ignored.</para>
- </listitem>
- </itemizedlist></para>
- <para>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:</para>
- <para>
- <itemizedlist>
- <listitem>
- <para>"name" - can be used to navigate (read) the "name" property of a Person
- (or any other type of object that has a "name" property).</para>
- </listitem>
- <listitem>
- <para>"artist.exhibits.closingDate" - can be used to navigate to a closing date
- of any of the exhibits of a Painting's Artist object.</para>
- </listitem>
- <listitem>
- <para>"artist.exhibits+.closingDate" - same as the previous example, but when
- translated into SQL, an OUTER JOIN will be used for "exhibits".</para>
- </listitem>
- </itemizedlist>
- </para>
- <para>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:<itemizedlist>
- <listitem>
- <para>"db:NAME" - can be used to navigate to the value of "NAME" column of some
- unspecified table.</para>
- </listitem>
- <listitem>
- <para>"db:artist.artistExhibits.exhibit.CLOSING_DATE" - can be used to match a
- closing date of any of the exhibits of a related artist record.</para>
- </listitem>
- </itemizedlist></para>
- <para>Cayenne supports "aliases" in path Expressions. E.g. the same expression can be
- written using explicit path or an alias:<itemizedlist>
- <listitem>
- <para>"artist.exhibits.closingDate" - full path</para>
- </listitem>
- <listitem>
- <para>"e.closingDate" - alias "e" is used for "artist.exhibits".</para>
- </listitem>
- </itemizedlist>SelectQuery using the second form of the path expression must be made
- aware of the alias via <emphasis role="italic"
- >"SelectQuery.aliasPathSplits(..)"</emphasis>, 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.</para>
- </section>
- <section xml:id="expressions-from-strings">
- <title>Creating Expressions from Strings </title>
- <para>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>Expression.fromString</code>
- static method. Here is an
- example:<programlisting>String expString = "name like 'A%' and price < 1000";
+ version="5.0" xml:id="expressions">
+ <title>Expressions</title>
+ <section xml:id="expressions-overview">
+ <title>Expressions Overview</title>
+ <para>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.</para>
+ </section>
+ <section xml:id="path-expressions">
+ <title>Path Expressions</title>
+ <para>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:<programlisting> [db:]segment[+][.segment[+]...]</programlisting><itemizedlist>
+ <listitem>
+ <para>"db:" is an optional prefix indicating that the following path is a DB
+ path. Otherwise it is an object path.</para>
+ </listitem>
+ <listitem>
+ <para>"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 (".").</para>
+ </listitem>
+ <listitem>
+ <para>"+" An "OUTER JOIN" path component. Currently "+" only has effect when
+ translated to SQL as OUTER JOIN. When evaluating expressions in memory, it
+ is ignored.</para>
+ </listitem>
+ </itemizedlist></para>
+ <para>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:</para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>"name" - can be used to navigate (read) the "name" property of a Person
+ (or any other type of object that has a "name" property).</para>
+ </listitem>
+ <listitem>
+ <para>"artist.exhibits.closingDate" - can be used to navigate to a closing date
+ of any of the exhibits of a Painting's Artist object.</para>
+ </listitem>
+ <listitem>
+ <para>"artist.exhibits+.closingDate" - same as the previous example, but when
+ translated into SQL, an OUTER JOIN will be used for "exhibits".</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>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:<itemizedlist>
+ <listitem>
+ <para>"db:NAME" - can be used to navigate to the value of "NAME" column of some
+ unspecified table.</para>
+ </listitem>
+ <listitem>
+ <para>"db:artist.artistExhibits.exhibit.CLOSING_DATE" - can be used to match a
+ closing date of any of the exhibits of a related artist record.</para>
+ </listitem>
+ </itemizedlist></para>
+ <para>Cayenne supports "aliases" in path Expressions. E.g. the same expression can be
+ written using explicit path or an alias:<itemizedlist>
+ <listitem>
+ <para>"artist.exhibits.closingDate" - full path</para>
+ </listitem>
+ <listitem>
+ <para>"e.closingDate" - alias "e" is used for "artist.exhibits".</para>
+ </listitem>
+ </itemizedlist>SelectQuery using the second form of the path expression must be made
+ aware of the alias via <emphasis role="italic">
+ "SelectQuery.aliasPathSplits(..)"</emphasis>, 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.</para>
+ </section>
+ <section xml:id="expressions-from-strings">
+ <title>Creating Expressions from Strings </title>
+ <para>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>Expression.fromString</code>
+ static method. Here is an
+ example:<programlisting>String expString = "name like 'A%' and price < 1000";
Expression exp = Expression.fromString(expString);</programlisting>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... </para>
- <para><emphasis role="italic">Character constants</emphasis> that are not paths or numeric values
- should be enclosed in single or double quotes. Two of the expressions below are
- equivalent:<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... </para>
+ <para><emphasis role="italic">Character constants</emphasis> that are not paths or numeric values
+ should be enclosed in single or double quotes. Two of the expressions below are
+ equivalent:<programlisting>name = 'ABC'
// double quotes are escaped inside Java Strings of course
-name = \"ABC\"</programlisting></para>
- <para><emphasis role="italic">Case sensitivity.</emphasis> Expression operators are all case
- sensitive and are usually lowercase. Complex words follow the java camel-case
- style:<programlisting>// valid
-name likeIgnoreCase 'A%'
+name = \"ABC\"</programlisting></para>
+ <para><emphasis role="italic">Case sensitivity.</emphasis> Expression operators are all case
+ sensitive and are usually lowercase. Complex words follow the java camel-case
+ style:<programlisting>// valid
+name likeIgnoreCase 'A%'
// invalid - will throw a parse exception
-name LIKEIGNORECASE 'A%'</programlisting></para>
- <para><emphasis role="italic">Grouping with
- parenthesis</emphasis>:<programlisting>value = (price + 250.00) * 3</programlisting></para>
- <para><emphasis role="italic">Path prefixes.</emphasis> 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:<programlisting>// object path
-name = 'Salvador Dali'
+name LIKEIGNORECASE 'A%'</programlisting></para>
+ <para><emphasis role="italic">Grouping with parenthesis:</emphasis>
+ <programlisting>value = (price + 250.00) * 3</programlisting>
+ </para>
+ <para><emphasis role="italic">Path prefixes.</emphasis> 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:<programlisting>// object path
+name = 'Salvador Dali'
// same object path - a rarely used form
-obj:name = 'Salvador Dali'
+obj:name = 'Salvador Dali'
// multi-segment object path
-artist.name = 'Salvador Dali'
+artist.name = 'Salvador Dali'
// db path
-db:NAME = 'Salvador Dali'
+db:NAME = 'Salvador Dali'
// enumeration constant
name = enum:org.foo.EnumClass.VALUE1</programlisting></para>
- <para>
- <emphasis role="italic">Binary conditions</emphasis> 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:<programlisting>name like 'A%'</programlisting><emphasis role="italic"
- >Named parameters.</emphasis> 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:<programlisting>Expression template = Expression.fromString("name = $name");
+ <para>
+ <emphasis role="italic">Binary conditions</emphasis> 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:<programlisting>name like 'A%'</programlisting>
+ <emphasis role="italic">Named parameters.</emphasis> 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:<programlisting>Expression template = Expression.fromString("name = $name");
...
-Map p1 = Collections.singletonMap("name", "Salvador Dali");
+Map p1 = Collections.singletonMap("name", "Salvador Dali");
Expression qualifier1 = template.expWithParameters(p1);
...
-Map p2 = Collections.singletonMap("name", "Monet");
+Map p2 = Collections.singletonMap("name", "Monet");
Expression qualifier2 = template.expWithParameters(p2);</programlisting>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:<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:<programlisting>Expression template = Expression.fromString("name like $name");
...
-Map p1 = Collections.singletonMap("name", "Salvador%");
+Map p1 = Collections.singletonMap("name", "Salvador%");
Expression qualifier1 = template.expWithParameters(p1);</programlisting>When
- matching on a relationship, parameters can be Persistent objects or
- ObjectIds:<programlisting>Expression template = Expression.fromString("artist = $artist");
+ matching on a relationship, parameters can be Persistent objects or
+ ObjectIds:<programlisting>Expression template = Expression.fromString("artist = $artist");
...
Artist dali = // asume we fetched this one already
-Map p1 = Collections.singletonMap("artist", dali);
+Map p1 = Collections.singletonMap("artist", dali);
Expression qualifier1 = template.expWithParameters(p1);</programlisting>Uninitialized
- parameters will be automatically pruned from expressions, so a user can omit some
- parameters when creating an expression from a parameterized
- template:<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:<programlisting>Expression template = Expression.fromString("name like $name and dateOfBirth > $date");
...
-Map p1 = Collections.singletonMap("name", "Salvador%");
+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</programlisting></para>
- <para><emphasis role="italic">Null handling.</emphasis> 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.</para>
- <para>
- <note>
- <para>A formal definition of all possible valid expressions in a form of JavaCC
- grammar is provided in Appendix C</para>
- </note>
- </para>
- </section>
- <section xml:id="expressions-with-expressionfactory">
- <title>Creating Expressions with API</title>
- <para>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. </para>
- <para>The following code recreates the expression from the previous chapter, but now using
- expression
- API:<programlisting language="java">// String expression: name like 'A%' and price < 1000
-Expression e1 = ExpressionFactory.likeExp(Painting.NAME_PROPERTY, "A%");
+ <para><emphasis role="italic">Null handling.</emphasis> 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.</para>
+ <para>
+ <note>
+ <para>A formal definition of all possible valid expressions in a form of JavaCC
+ grammar is provided in Appendix C</para>
+ </note>
+ </para>
+ </section>
+ <section xml:id="expressions-with-expressionfactory">
+ <title>Creating Expressions with API</title>
+ <para>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. </para>
+ <para>The following code recreates the expression from the previous chapter, but now using
+ expression
+ API:<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); </programlisting>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.<note>
- <para>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.</para>
- </note></para>
- <para>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:<programlisting language="java">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.<note>
+ <para>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.</para>
+ </note></para>
+ <para>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:<programlisting>Expression matchAllExp(String path, Collection values)
Expression matchAllExp(String path, Object... values)</programlisting></para>
- <para>"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.</para>
- </section>
- <section xml:id="expressions-in-memory">
- <title>Evaluating Expressions in Memory</title>
- <para>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. </para>
- <para>Checking whether an object satisfies an
- expression:<programlisting language="java">Expression e = ExpressionFactory.inExp(User.NAME_PROPERTY, "John", "Bob");
+ <para>"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.</para>
+ </section>
+ <section xml:id="expressions-in-memory">
+ <title>Evaluating Expressions in Memory</title>
+ <para>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. </para>
+ <para>Checking whether an object satisfies an
+ expression:<programlisting>Expression e = ExpressionFactory.inExp(User.NAME_PROPERTY, "John", "Bob");
User user = ...
if(e.match(user)) {
...
}</programlisting>Reading
- property
- value:<programlisting language="java">Expression e = Expression.fromString(User.NAME_PROPERTY);
+ property
+ value:<programlisting>Expression e = Expression.fromString(User.NAME_PROPERTY);
String name = e.evaluate(user);</programlisting></para>
- <para>Filtering a list of
- objects:<programlisting language="java">Expression e = ExpressionFactory.inExp(User.NAME_PROPERTY, "John", "Bob");
-List<User> unfiltered = ...
-List<User> filtered = e.filterObjects(unfiltered);</programlisting></para>
- <para>
- <note>
- <para>Current limitation of in-memory expressions is that no collections are
- permitted in the property path.</para>
- </note>
- </para>
- </section>
+ <para>Filtering a list of
+ objects:<programlisting>Expression e = ExpressionFactory.inExp(User.NAME_PROPERTY, "John", "Bob");
+List<User> unfiltered = ...
+List<User> filtered = e.filterObjects(unfiltered);</programlisting></para>
+ <para>
+ <note>
+ <para>Current limitation of in-memory expressions is that no collections are
+ permitted in the property path.</para>
+ </note>
+ </para>
+ </section>
</chapter>
Modified: cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/implementing-rop-server.xml
URL: http://svn.apache.org/viewvc/cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/implementing-rop-server.xml?rev=1425988&r1=1425987&r2=1425988&view=diff
==============================================================================
--- cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/implementing-rop-server.xml (original)
+++ cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/implementing-rop-server.xml Wed Dec 26 18:38:17 2012
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="implementing-rop-server">
- <title>Implementing ROP Server</title>
+ version="5.0" xml:id="implementing-rop-server">
+ <title>Implementing ROP Server</title>
</chapter>
Modified: cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/including-cayenne-in-project.xml
URL: http://svn.apache.org/viewvc/cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/including-cayenne-in-project.xml?rev=1425988&r1=1425987&r2=1425988&view=diff
==============================================================================
--- cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/including-cayenne-in-project.xml (original)
+++ cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/including-cayenne-in-project.xml Wed Dec 26 18:38:17 2012
@@ -1,535 +1,531 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="including-cayenne-in-project">
- <title>Including Cayenne in a Project</title>
- <section xml:id="jar-files-and-depdendencies">
- <title>Jar Files and Dependencies</title>
- <para>Cayenne distribution contains the following core runtime jars in the distribution
- <code>lib</code> directory: <itemizedlist>
- <listitem>
- <para><emphasis role="italic">cayenne-server-x.x.jar</emphasis> - contains full
- Cayenne runtime (DI, adapters, DB access classes, etc.). Most applications
- will use only this file.</para>
- </listitem>
- <listitem>
- <para>cayenne-client-x.x.jar - a subset of cayenne-server.jar trimmed for use on
- the client in an ROP application.</para>
- </listitem>
- <listitem>
- <para>Other cayenne-* jars - various Cayenne extensions.</para>
- </listitem>
- </itemizedlist></para>
- <para>When using <code>cayenne-server-x.x.jar</code> you'll need a few third party jars (all
- included in <code>lib/third-party</code> directory of the distribution): <itemizedlist>
- <listitem>
- <para><link xlink:href="http://velocity.apache.org/">Apache Velocity
- Template Engine</link>, version 1.6.x (and all its dependencies bundled
- with velocity-dep)</para>
- </listitem>
- <listitem>
- <para><link xlink:href="http://commons.apache.org/collections/">Apache Commons
- Collections</link>, version 3.2.1</para>
- </listitem>
- <listitem>
- <para><link xlink:href="http://commons.apache.org/logging/">Apache
- Commons Logging</link>, version 1.1</para>
- </listitem>
- </itemizedlist></para>
- <para>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.</para>
- </section>
- <section xml:id="maven-projects">
- <title>Maven Projects</title>
- <para>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:<programlisting><dependency>
+ version="5.0" xml:id="including-cayenne-in-project">
+ <title>Including Cayenne in a Project</title>
+ <section xml:id="jar-files-and-depdendencies">
+ <title>Jar Files and Dependencies</title>
+ <para>Cayenne distribution contains the following core runtime jars in the distribution
+ <code>lib</code> directory: <itemizedlist>
+ <listitem>
+ <para><emphasis role="italic">cayenne-server-x.x.jar</emphasis> - contains full
+ Cayenne runtime (DI, adapters, DB access classes, etc.). Most applications
+ will use only this file.</para>
+ </listitem>
+ <listitem>
+ <para>cayenne-client-x.x.jar - a subset of cayenne-server.jar trimmed for use on
+ the client in an ROP application.</para>
+ </listitem>
+ <listitem>
+ <para>Other cayenne-* jars - various Cayenne extensions.</para>
+ </listitem>
+ </itemizedlist></para>
+ <para>When using <code>cayenne-server-x.x.jar</code> you'll need a few third party jars (all
+ included in <code>lib/third-party</code> directory of the distribution): <itemizedlist>
+ <listitem>
+ <para><link xlink:href="http://velocity.apache.org/">Apache Velocity
+ Template Engine</link>, version 1.6.x (and all its dependencies bundled
+ with velocity-dep)</para>
+ </listitem>
+ <listitem>
+ <para><link xlink:href="http://commons.apache.org/collections/">Apache Commons
+ Collections</link>, version 3.2.1</para>
+ </listitem>
+ <listitem>
+ <para><link xlink:href="http://commons.apache.org/logging/">Apache
+ Commons Logging</link>, version 1.1</para>
+ </listitem>
+ </itemizedlist></para>
+ <para>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.</para>
+ </section>
+ <section xml:id="maven-projects">
+ <title>Maven Projects</title>
+ <para>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:<programlisting><dependency>
<groupId>org.apache.cayenne</groupId>
<artifactId>cayenne-server</artifactId>
<version>X.Y.Z</version>
</dependency></programlisting></para>
- <para>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>org.apache.cayenne.plugins:maven-cayenne-plugin</code>.</para>
- <section xml:id="mvn-cgen">
- <title>cgen</title>
- <para><code>cgen</code> is a <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. </para>
- <para>By creating custom templates, you can use cgen to generate other output (such as
- web pages, reports, specialized code templates) based on DataMap information.</para>
- <para>
- <div class="table">
- <table frame="void">
- <caption>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>map</code>
- </td>
- <td>File</td>
- <td>DataMap XML file which serves as a source of metadata for class
- generation. E.g.
- <code>${project.basedir}/src/main/resources/my.map.xml</code></td>
- </tr>
- <tr>
- <td><code>destDir</code></td>
- <td>File</td>
- <td>Root destination directory for Java classes (ignoring their package
- names).</td>
- </tr>
- </tbody>
- </table>
- </div>
- <div class="table">
- <table frame="void">
- <caption>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>
- </div>
+ <para>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>org.apache.cayenne.plugins:maven-cayenne-plugin</code>.</para>
+ <section xml:id="mvn-cgen">
+ <title>cgen</title>
+ <para><code>cgen</code> is a <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. </para>
+ <para>By creating custom templates, you can use cgen to generate other output (such as
+ web pages, reports, specialized code templates) based on DataMap information.</para>
+ <para>
+ <table frame="void">
+ <caption>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>map</code>
+ </td>
+ <td>File</td>
+ <td>DataMap XML file which serves as a source of metadata for class
+ generation. E.g.
+ <code>${project.basedir}/src/main/resources/my.map.xml</code></td>
+ </tr>
+ <tr>
+ <td><code>destDir</code></td>
+ <td>File</td>
+ <td>Root destination directory for Java classes (ignoring their package
+ names).</td>
+ </tr>
+ </tbody>
+ </table>
+ <table frame="void">
+ <caption>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>
Example - a typical class generation scenario, where pairs of classes are
- generated, and superclasses are placed in a separate package:
- <programlisting><plugin>
- <groupId>org.apache.cayenne.plugins</groupId>
- <artifactId>maven-cayenne-plugin</artifactId>
- <version>X.Y.Z</version>
+ generated, and superclasses are placed in a separate package:
+ <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></programlisting></para>
- </section>
- <section xml:id="mvn-cdbgen">
- <title>cdbgen</title>
- <para><code>cdbgen</code> is a <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.<table frame="void">
- <caption>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>map</code>
- </td>
- <td>File</td>
- <td>DataMap XML file which serves as a source of metadata for DB schema
- generation. E.g.
- <code>${project.basedir}/src/main/resources/my.map.xml</code></td>
- </tr>
- <tr>
- <td><code>driver</code></td>
- <td>String</td>
- <td>A class of JDBC driver to use for the target database.</td>
- </tr>
- <tr>
- <td><code>url</code></td>
- <td>String</td>
- <td>JDBC connection URL of a target database.</td>
- </tr>
- </tbody>
- </table></para>
- <para>
- <table frame="void" width="792">
- <caption>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>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>createFK</code></td>
- <td>boolean</td>
- <td>Indicates whether cdbgen should create foreign key constraints. Default is "true".</td>
- </tr>
- <tr>
- <td><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>createTables</code></td>
- <td>boolean</td>
- <td>Indicates whether cdbgen should create new tables. Default is "true".</td>
- </tr>
- <tr>
- <td><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>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>password</code></td>
- <td>String</td>
- <td>Database user password.</td>
- </tr>
- <tr>
- <td><code>username</code></td>
- <td>String</td>
- <td>Database user name.</td>
- </tr>
- </tbody>
- </table>
- </para>
- <para>Example - creating a DB schema on a local HSQLDB
- database:<programlisting><plugin>
- <groupId>org.apache.cayenne.plugins</groupId>
- <artifactId>maven-cayenne-plugin</artifactId>
- <version>X.Y.Z</version>
+ </section>
+ <section xml:id="mvn-cdbgen">
+ <title>cdbgen</title>
+ <para><code>cdbgen</code> is a <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.<table frame="void">
+ <caption>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>map</code>
+ </td>
+ <td>File</td>
+ <td>DataMap XML file which serves as a source of metadata for DB schema
+ generation. E.g.
+ <code>${project.basedir}/src/main/resources/my.map.xml</code></td>
+ </tr>
+ <tr>
+ <td><code>driver</code></td>
+ <td>String</td>
+ <td>A class of JDBC driver to use for the target database.</td>
+ </tr>
+ <tr>
+ <td><code>url</code></td>
+ <td>String</td>
+ <td>JDBC connection URL of a target database.</td>
+ </tr>
+ </tbody>
+ </table></para>
+ <para>
+ <table frame="void">
+ <caption>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>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>createFK</code></td>
+ <td>boolean</td>
+ <td>Indicates whether cdbgen should create foreign key constraints. Default is "true".</td>
+ </tr>
+ <tr>
+ <td><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>createTables</code></td>
+ <td>boolean</td>
+ <td>Indicates whether cdbgen should create new tables. Default is "true".</td>
+ </tr>
+ <tr>
+ <td><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>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>password</code></td>
+ <td>String</td>
+ <td>Database user password.</td>
+ </tr>
+ <tr>
+ <td><code>username</code></td>
+ <td>String</td>
+ <td>Database user name.</td>
+ </tr>
+ </tbody>
+ </table>
+ </para>
+ <para>Example - creating a DB schema on a local HSQLDB
+ database:<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></programlisting></para>
- </section>
- <section xml:id="mvn-cdbimport">
- <title>cdbimport</title>
- <para><code>cdbimport</code> is a <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.<table
- frame="void">
- <caption>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>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>${project.basedir}/src/main/resources/my.map.xml</code></td>
- </tr>
- <tr>
- <td><code>driver</code></td>
- <td>String</td>
- <td>A class of JDBC driver to use for the target database.</td>
- </tr>
- <tr>
- <td><code>url</code></td>
- <td>String</td>
- <td>JDBC connection URL of a target database.</td>
- </tr>
- </tbody>
- </table></para>
- <para>
- <table frame="void" width="822">
- <caption>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>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>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>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>namingStrategy</code></td>
- <td>String</td>
- <td>The naming strategy used for mapping database names to object entity
- names. Default is
- <code>org.apache.cayenne.map.naming.SmartNamingStrategy</code>.
- </td>
- </tr>
- <tr>
- <td><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>password</code></td>
- <td>String</td>
- <td>Database user password.</td>
- </tr>
- <tr>
- <td><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>schemaName</code></td>
- <td>String</td>
- <td>Database schema to import tables/stored procedures from. </td>
- </tr>
- <tr>
- <td><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>username</code></td>
- <td>String</td>
- <td>Database user name.</td>
- </tr>
- </tbody>
- </table>
- </para>
- <para>Example - loading a DB schema from a local HSQLDB database (essentially a reverse operation
- compared to the cdbgen example above)
- :<programlisting><plugin>
- <groupId>org.apache.cayenne.plugins</groupId>
- <artifactId>maven-cayenne-plugin</artifactId>
- <version>X.Y.Z</version>
+ </section>
+ <section xml:id="mvn-cdbimport">
+ <title>cdbimport</title>
+ <para><code>cdbimport</code> is a <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.<table
+ frame="void">
+ <caption>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>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>${project.basedir}/src/main/resources/my.map.xml</code></td>
+ </tr>
+ <tr>
+ <td><code>driver</code></td>
+ <td>String</td>
+ <td>A class of JDBC driver to use for the target database.</td>
+ </tr>
+ <tr>
+ <td><code>url</code></td>
+ <td>String</td>
+ <td>JDBC connection URL of a target database.</td>
+ </tr>
+ </tbody>
+ </table></para>
+ <para>
+ <table frame="void">
+ <caption>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>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>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>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>namingStrategy</code></td>
+ <td>String</td>
+ <td>The naming strategy used for mapping database names to object entity
+ names. Default is
+ <code>org.apache.cayenne.map.naming.SmartNamingStrategy</code>.
+ </td>
+ </tr>
+ <tr>
+ <td><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>password</code></td>
+ <td>String</td>
+ <td>Database user password.</td>
+ </tr>
+ <tr>
+ <td><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>schemaName</code></td>
+ <td>String</td>
+ <td>Database schema to import tables/stored procedures from. </td>
+ </tr>
+ <tr>
+ <td><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>username</code></td>
+ <td>String</td>
+ <td>Database user name.</td>
+ </tr>
+ </tbody>
+ </table>
+ </para>
+ <para>Example - loading a DB schema from a local HSQLDB database (essentially a reverse operation
+ compared to the cdbgen example above)
+ :<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: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>
+ <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></programlisting></para>
- </section>
- </section>
- <section xml:id="ant-projects">
- <title>Ant Projects</title>
- <section xml:id="ant-cgen">
- <title>cgen</title>
- </section>
- <section xml:id="ant-cdbgen">
- <title>cdbgen</title>
- </section>
- <section xml:id="ant-cdbimport">
- <title>cdbimport</title>
- <para>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:<programlisting> <cdbimport map="${context.dir}/WEB-INF/my.map.xml"
+ </section>
+ </section>
+ <section xml:id="ant-projects">
+ <title>Ant Projects</title>
+ <section xml:id="ant-cgen">
+ <title>cgen</title>
+ </section>
+ <section xml:id="ant-cdbgen">
+ <title>cdbgen</title>
+ </section>
+ <section xml:id="ant-cdbimport">
+ <title>cdbimport</title>
+ <para>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:<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"/> </programlisting>
- </para>
- </section>
- <section xml:id="ant-cdataport">
- <title>cdataport</title>
- </section>
- </section>
+ </para>
+ </section>
+ <section xml:id="ant-cdataport">
+ <title>cdataport</title>
+ </section>
+ </section>
</chapter>
Modified: cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/index.xml
URL: http://svn.apache.org/viewvc/cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/index.xml?rev=1425988&r1=1425987&r2=1425988&view=diff
==============================================================================
--- cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/index.xml (original)
+++ cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/index.xml Wed Dec 26 18:38:17 2012
@@ -1,31 +1,31 @@
<?xml version="1.0" encoding="UTF-8" ?>
<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml:id="cayenne-guide" xmlns:xi="http://www.w3.org/2001/XInclude">
- <info>
- <title>Cayenne Guide</title>
- <copyright>
- <year>2011-2012</year>
- <holder>Apache Software Foundation and individual authors</holder>
- </copyright>
- <legalnotice>
- <title>License</title>
- <para>Licensed to the Apache Software Foundation (ASF) under one or more contributor
- license agreements. See the NOTICE file distributed with this work for additional
- information regarding copyright ownership. The ASF licenses this file to you under
- the Apache License, Version 2.0 (the "License"); you may not use this file except in
- compliance with the License. You may obtain a copy of the License at
- http://www.apache.org/licenses/LICENSE-2.0</para>
+ xml:id="cayenne-guide" xmlns:xi="http://www.w3.org/2001/XInclude">
+ <info>
+ <title>Cayenne Guide</title>
+ <copyright>
+ <year>2011-2012</year>
+ <holder>Apache Software Foundation and individual authors</holder>
+ </copyright>
+ <legalnotice>
+ <title>License</title>
+ <para>Licensed to the Apache Software Foundation (ASF) under one or more contributor
+ license agreements. See the NOTICE file distributed with this work for additional
+ information regarding copyright ownership. The ASF licenses this file to you under
+ the Apache License, Version 2.0 (the "License"); you may not use this file except in
+ compliance with the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0</para>
- <para>Unless required by applicable law or agreed to in writing, software distributed
- under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
- CONDITIONS OF ANY KIND, either express or implied. See the License for the specific
- language governing permissions and limitations under the License.</para>
- </legalnotice>
- </info>
- <xi:include href="part1.xml"/>
- <xi:include href="part2.xml"/>
- <xi:include href="part3.xml"/>
- <xi:include href="appendix-a.xml"/>
- <xi:include href="appendix-b.xml"/>
- <xi:include href="appendix-c.xml"/>
+ <para>Unless required by applicable law or agreed to in writing, software distributed
+ under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+ CONDITIONS OF ANY KIND, either express or implied. See the License for the specific
+ language governing permissions and limitations under the License.</para>
+ </legalnotice>
+ </info>
+ <xi:include href="part1.xml"/>
+ <xi:include href="part2.xml"/>
+ <xi:include href="part3.xml"/>
+ <xi:include href="appendix-a.xml"/>
+ <xi:include href="appendix-b.xml"/>
+ <xi:include href="appendix-c.xml"/>
</book>
Modified: cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/introduction-to-rop.xml
URL: http://svn.apache.org/viewvc/cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/introduction-to-rop.xml?rev=1425988&r1=1425987&r2=1425988&view=diff
==============================================================================
--- cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/introduction-to-rop.xml (original)
+++ cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/introduction-to-rop.xml Wed Dec 26 18:38:17 2012
@@ -1,11 +1,11 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="introduction-to-rop">
- <title>Introduction to ROP</title>
- <section xml:id="what-is-rop">
- <title>What is ROP</title>
- </section>
- <section xml:id="main-features">
- <title>Main Features</title>
- </section>
+ version="5.0" xml:id="introduction-to-rop">
+ <title>Introduction to ROP</title>
+ <section xml:id="what-is-rop">
+ <title>What is ROP</title>
+ </section>
+ <section xml:id="main-features">
+ <title>Main Features</title>
+ </section>
</chapter>
Modified: cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/lifecycle-events.xml
URL: http://svn.apache.org/viewvc/cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/lifecycle-events.xml?rev=1425988&r1=1425987&r2=1425988&view=diff
==============================================================================
--- cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/lifecycle-events.xml (original)
+++ cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/lifecycle-events.xml Wed Dec 26 18:38:17 2012
@@ -1,20 +1,20 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="lifecycle-events">
- <title>Lifecycle Events</title>
- <section xml:id="types-of-lifecycle-events">
- <title>Types of Lifecycle Events</title>
- </section>
- <section xml:id="lifecycle-callbacks-listeners">
- <title>Lifecycle Callbacks and Listeners</title>
- <section xml:id="callback-listener-method-semantics">
- <title>Callback and Listener Methods Semantics</title>
- </section>
- <section xml:id="registering-callbacks-listeners">
- <title>Registering Callbacks and Listeners</title>
- </section>
- <section xml:id="comining-listeners-with-datachannelfilters">
- <title>Combining Listeners with DataChannelFilters</title>
- </section>
- </section>
+ version="5.0" xml:id="lifecycle-events">
+ <title>Lifecycle Events</title>
+ <section xml:id="types-of-lifecycle-events">
+ <title>Types of Lifecycle Events</title>
+ </section>
+ <section xml:id="lifecycle-callbacks-listeners">
+ <title>Lifecycle Callbacks and Listeners</title>
+ <section xml:id="callback-listener-method-semantics">
+ <title>Callback and Listener Methods Semantics</title>
+ </section>
+ <section xml:id="registering-callbacks-listeners">
+ <title>Registering Callbacks and Listeners</title>
+ </section>
+ <section xml:id="comining-listeners-with-datachannelfilters">
+ <title>Combining Listeners with DataChannelFilters</title>
+ </section>
+ </section>
</chapter>
Modified: cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/orderings.xml
URL: http://svn.apache.org/viewvc/cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/orderings.xml?rev=1425988&r1=1425987&r2=1425988&view=diff
==============================================================================
--- cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/orderings.xml (original)
+++ cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/orderings.xml Wed Dec 26 18:38:17 2012
@@ -1,16 +1,16 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
- version="5.0" xml:id="orderings">
- <title>Orderings</title>
- <para>An Ordering object defines how a list of objects should be ordered. Orderings are
- essentially path expressions combined with a sorting strategy. Creating an Ordering:
- <programlisting language="java">Ordering o = new Ordering(Painting.NAME_PROPERTY, SortOrder.ASENDING);</programlisting></para>
- <para>Like expressions, orderings are translated into SQL as parts of queries (and the sorting
- occurs in the database). Also like expressions, orderings can be used in memory, naturally -
- to sort
- objects:<programlisting language="java">Ordering o = new Ordering(Painting.NAME_PROPERTY, SortOrder.ASCENDING_INSENSITIVE);
+ version="5.0" xml:id="orderings">
+ <title>Orderings</title>
+ <para>An Ordering object defines how a list of objects should be ordered. Orderings are
+ essentially path expressions combined with a sorting strategy. Creating an Ordering:
+ <programlisting language="java">Ordering o = new Ordering(Painting.NAME_PROPERTY, SortOrder.ASENDING);</programlisting></para>
+ <para>Like expressions, orderings are translated into SQL as parts of queries (and the sorting
+ occurs in the database). Also like expressions, orderings can be used in memory, naturally -
+ to sort
+ objects:<programlisting language="java">Ordering o = new Ordering(Painting.NAME_PROPERTY, SortOrder.ASCENDING_INSENSITIVE);
List<Painting> list = ...
o.orderList(list);</programlisting>Note
- that unlike filtering with Expressions, ordering is performed in-place. This list object is
- reordered and no new list is created.</para>
+ that unlike filtering with Expressions, ordering is performed in-place. This list object is
+ reordered and no new list is created.</para>
</chapter>