From 5b5ec673b4ca35ea271a62890a18974242ca8aa5 Mon Sep 17 00:00:00 2001
From: David Mansfield <david@gandalf.cobite.com>
Date: Tue, 29 Mar 2011 14:16:00 -0400
Subject: [PATCH] HHH-3646 - documentation for Criteria query of
 collection-of-component and collection-of-scalar functionality

---
 .../manual/en-US/content/query_criteria.xml   | 35 ++++++++++++++++++-
 1 file changed, 34 insertions(+), 1 deletion(-)

diff --git a/documentation/src/main/docbook/manual/en-US/content/query_criteria.xml b/documentation/src/main/docbook/manual/en-US/content/query_criteria.xml
index 466a14da11..3597978c36 100644
--- a/documentation/src/main/docbook/manual/en-US/content/query_criteria.xml
+++ b/documentation/src/main/docbook/manual/en-US/content/query_criteria.xml
@@ -251,7 +251,7 @@ while ( iter.hasNext() ) {
     
     </section>
 
-    <section>
+    <section id="querycriteria-components" revision="2">
         <title>Components</title>
 
         <para>
@@ -268,6 +268,39 @@ while ( iter.hasNext() ) {
 			.list();]]>
 	</programlisting>
 	
+	<para>
+		Note: this does not apply when querying collections of components, for that see below 
+		<xref linkend="querycriteria-collections"/>
+	</para>
+
+    </section>
+
+    <section id="querycriteria-collections" revision="1">
+	<title>Collections</title>
+	<para>
+		When using criteria against collections, there are two distinct cases.  One is if
+		the collection contains entities (eg. <literal>&lt;one-to-many/&gt;</literal> 
+		or <literal>&lt;many-to-many/&gt;</literal>) or components 
+		(<literal>&lt;composite-element/&gt;</literal> ),
+		and the second is if the collection contains scalar values 
+		(<literal>&lt;element/&gt;</literal>).
+		In the first case, the syntax is as given above in the section 
+		<xref linkend="querycriteria-associations"/> where we restrict the <literal>kittens</literal>
+		collection. Essentially we create a <literal>Criteria</literal> object against the collection
+		property and restrict the entity or component properties using that instance.
+	</para>
+	<para>
+		For queryng a collection of basic values, we still create the <literal>Criteria</literal>
+		object against the collection, but to reference the value, we use the special property 
+		&quot;elements&quot;.  For an indexed collection, we can also reference the index property using
+		the special property &quot;indices&quot;.
+	</para>
+	<programlisting><![CDATA[
+		List cats = session.createCriteria(Cat.class)
+			.createCriteria("nickNames")
+				.add(Restrictions.eq("elements", "BadBoy"))
+			.list();]]>
+	</programlisting>
     </section>
 
     <section id="querycriteria-examples">