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/09/18 02:35:36 UTC
svn commit: r1386934 - in
/cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx:
expressions.xml rop-deployment.xml
Author: aadamchik
Date: Tue Sep 18 00:35:36 2012
New Revision: 1386934
URL: http://svn.apache.org/viewvc?rev=1386934&view=rev
Log:
docs - expressionfromstring
(cherry picked from commit 3ec84029494635702a7f4919b016f86f649aa1e0)
Modified:
cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/expressions.xml
cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/rop-deployment.xml
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=1386934&r1=1386933&r2=1386934&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 Tue Sep 18 00:35:36 2012
@@ -88,8 +88,90 @@
used for a group of matching paths.</para>
</section>
<section xml:id="expressions-from-strings">
- <title>Creating Expressions from Strings</title>
- <para>For a full grammar check Appendix C.</para>
+ <title>Creating Expressions from Strings </title>
+ <para>While in most cases users are likely to rely on API for expressions creation, as described
+ in the following chapter, we'll start by discussing String expressions, as this will
+ help to understand the expressions structure. Expressions can be created using
+ <code>Expression.fromString</code> method. Here is an
+ example:<programlisting>Expression e = Expression.fromString("name like 'A%' and price < 1000");</programlisting>This
+ 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 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%'
+
+// 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'
+
+// same object path - a rarely used form
+obj:name = 'Salvador Dali'
+
+// multi-segment object path
+artist.name = 'Salvador Dali'
+
+// db path
+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. This warrants a full code
+ example:<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);</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");
+...
+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");
+...
+Artist dali = // asume we fetched this one already
+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");
+...
+Map p1 = Collections.singletonMap("name", "Salvador%");
+Expression qualifier1 = template.expWithParameters(p1);
+
+// qualifier1 is now equals to "name like 'Salvador%'", the 'dateOfBirth' condition was
+// pruned, as no value was specified for the $date parameter</programlisting><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 ExpressionFactory</title>
Modified: cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/rop-deployment.xml
URL: http://svn.apache.org/viewvc/cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/rop-deployment.xml?rev=1386934&r1=1386933&r2=1386934&view=diff
==============================================================================
--- cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/rop-deployment.xml (original)
+++ cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/rop-deployment.xml Tue Sep 18 00:35:36 2012
@@ -4,21 +4,24 @@
<title>ROP Deployment</title>
<section xml:id="deploying-rop-server">
<title>Deploying ROP Server</title>
- <para>Recent versions of Tomcat and Jetty containers (e.g. Tomcat 6 and 7, Jetty 8) are
- addressing a security concern related to "session fixation problem" by resetting the
- existing session ID of any request that requires BASIC authentcaition. If ROP service is
- protected with declarative security (see the the ROP tutorial and the following chapters
- on security), this feature prevents the ROP client from attaching to its session,
- resulting in MissingSessionExceptions. To solve that you will need to either switch to
- an alternative security mechanism, or disable "session fixation problem" protections of
- the container. E.g. the later can be achieved in Tomcat 7 by adding the following
- <emphasis>context.xml</emphasis> file to the webapp's META-INF/ directory:
- <programlisting><Context>
+
+ <note><para>Recent versions of Tomcat and Jetty containers (e.g. Tomcat 6 and 7, Jetty 8) contain code
+ addressing a security concern related to "session fixation problem" by resetting the
+ existing session ID of any request that requires BASIC authentcaition. If ROP
+ service is protected with declarative security (see the the ROP tutorial and the
+ following chapters on security), this feature prevents the ROP client from attaching
+ to its session, resulting in MissingSessionExceptions. To solve that you will need
+ to either switch to an alternative security mechanism, or disable "session fixation
+ problem" protections of the container. E.g. the later can be achieved in Tomcat 7 by
+ adding the following <emphasis>context.xml</emphasis> file to the webapp's META-INF/
+ directory:
+ <programlisting><Context>
<Valve className="org.apache.catalina.authenticator.BasicAuthenticator"
changeSessionIdOnAuthentication="false" />
</Context></programlisting>(The
- <Valve> tag can also be placed within the <Context> in any other locations used by
- Tomcat to load context configurations)</para>
+ <Valve> tag can also be placed within the <Context> in any other locations
+ used by Tomcat to load context configurations)</para></note>
+
</section>
<section xml:id="deploying-rop-client">
<title>Deploying ROP Client</title>