HHH-3646 - throw a better exception when criteria is placed directly …

…on component

In the CriteriaQueryTranslator, we process the path given by
a SubCriteria object looking for the entity name for the property. If
the SubCriteria was mistakenly created on a component type, we will exit
the loop using the owning entity, and will eventually end up failing
(throwing an exception) trying to lookup up the restricted property
against the entity, instead of against the component. Fix this by
throwing a more informative exception, and modify the documentation to
be explicit about how to do this properly.

documentation/src/main/docbook/manual/en-US/content/query_criteria.xml

@@ -250,7 +250,26 @@ while ( iter.hasNext() ) {
         </para>
 
     </section>
-
+
+    <section>
+        <title>Components</title>
+
+        <para>
+               To add a restriction against a property of an embedded component, the component property
+               name should be prepended to the property name when creating the <literal>Restriction</literal>.
+               The criteria object should be created on the owning entity, and cannot be created on the component 
+               itself.  For example, suppose the <literal>Cat</literal> has a component property <literal>fullName</literal>
+               with sub-properties <literal>firstName</literal> and <literal>lastName</literal>:
+	</para>
+
+	<programlisting><![CDATA[
+		List cats = session.createCriteria(Cat.class)
+			.add(Restrictions.eq("fullName.lastName", "Cattington"))
+			.list();]]>
+	</programlisting>
+
+    </section>
+
     <section id="querycriteria-examples">
         <title>Example queries</title>
 

hibernate-core/src/main/java/org/hibernate/loader/criteria/CriteriaQueryTranslator.java

@@ -269,7 +269,11 @@ else if ( ctype != null && !elementType.isEntityType() ) {
 				componentPath = "";
 			}
 			else if ( type.isComponentType() ) {
-				componentPath += '.';
+				if (!tokens.hasMoreTokens()) {
+					throw new QueryException("Criteria objects cannot be created directly on components.  Create a criteria on owning entity and use a dotted property to access component property: "+path);
+				} else {
+					componentPath += '.';
+				}
 			}
 			else {
 				throw new QueryException( "not an association: " + componentPath );