cayenne-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From aadamc...@apache.org
Subject svn commit: r1386934 - in /cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx: expressions.xml rop-deployment.xml
Date Tue, 18 Sep 2012 00:35:36 GMT
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 &lt; 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>&lt;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>&lt;Context>
 	&lt;Valve className="org.apache.catalina.authenticator.BasicAuthenticator" 
 			changeSessionIdOnAuthentication="false" />
 &lt;/Context></programlisting>(The
-			&lt;Valve> tag can also be placed within the &lt;Context> in any other locations
used by
-			Tomcat to load context configurations)</para>
+				&lt;Valve> tag can also be placed within the &lt;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>



Mime
View raw message