Document "entity join" and "entity projection"

Author: bahusoid

doc/reference/modules/query_criteria.xml

@@ -141,12 +141,35 @@ var cats = sess.CreateCriteria<Cat>()
     .List<IDictionary>();
 foreach ( IDictionary map in cats )
 {
-    Cat cat = (Cat) map[CriteriaUtil.RootAlias];
+    Cat cat = (Cat) map[CriteriaSpecification.RootAlias];
     Cat kitten = (Cat) map["kt"];
 }]]></programlisting>
+      <para>
+        Note that for retrieving just kittens you can also use entity projection.
+        See <xref linkend="querycriteria-projection"/> for more information.
+      </para>
 
     </sect1>
-    
+
+    <sect1 id="querycriteria_entityjoin">
+      <title>Join entities without association (Entity joins or ad hoc joins)</title>
+      <para>
+        In criteria you have the ability to define a join to any entity, not just a mapped association.
+        To achieve it use <literal>CreateEntityAlias</literal> and <literal>CreateEntityCriteria</literal>. By example:
+      </para>
+
+      <programlisting><![CDATA[IList<Cat> uniquelyNamedCats = sess.CreateCriteria<Cat>("c")
+    .CreateEntityAlias(
+        "joinedCat",
+        Restrictions.And(
+            Restrictions.EqProperty("c.Name", "joinedCat.Name"),
+            Restrictions.NotEqProperty("c.Id", "joinedCat.Id")),
+        JoinType.LeftOuterJoin,
+        typeof(Cat).FullName)
+    .Add(Restrictions.IsNull("joinedCat.Id"))
+    .List();]]></programlisting>
+    </sect1>
+
     <sect1 id="querycriteria-dynamicfetching">
         <title>Dynamic association fetching</title>
 
@@ -286,6 +309,33 @@ var results = session.CreateCriteria<Cat>()
     .AddOrder( Order.Asc("kitName") )
     .List<object[]>();]]></programlisting>
 
+      <para>
+        You can also add entity projection to criteria:
+      </para>
+
+      <programlisting><![CDATA[var kittens = sess.CreateCriteria<Cat>()
+    .CreateCriteria("Kittens", "kt")
+    .Add(Expression.Eq("Name", "F%"))
+    .SetProjection(Projections.Entity(typeof(Cat), "kt"))
+    .List();]]></programlisting>
+
+      <programlisting><![CDATA[var cats = sess.CreateCriteria<Cat>()
+    .CreateCriteria("Kittens", "kt")
+    .Add(Expression.Eq("Name", "F%"))
+    .SetProjection(
+        Projections.RootEntity(),
+        Projections.Entity(typeof(Cat), "kt"))
+    .List<object[]>();
+
+foreach (var objs in cats)
+{
+    Cat cat = (Cat) objs[0];
+    Cat kitten = (Cat) objs[1];
+}]]></programlisting>
+
+      <para>
+        See <xref linkend="queryqueryover-projectionentities"/> for more information.
+      </para>
     </sect1>
 
     <sect1 id="querycriteria-detachedqueries">

doc/reference/modules/query_queryover.xml

@@ -213,6 +213,25 @@ IList<Cat> cats =
 
     </sect1>
 
+    <sect1 id="queryqueryover_entityjoin">
+      <title>Join entities without association (Entity joins or ad hoc joins)</title>
+      <para>
+        In QueryOver you have the ability to define a join to any entity, not just a mapped association.
+        To achieve it use <literal>JoinEntityAlias</literal> and <literal>JoinEntityQueryOver</literal>. By example:
+      </para>
+
+      <programlisting><![CDATA[Cat cat = null;
+Cat joinedCat = null;
+
+var uniquelyNamedCats = sess.QueryOver<Cat>(() => cat)
+    .JoinEntityAlias(
+        () => joinedCat,
+        () => cat.Name == joinedCat.Name && cat.Id != joinedCat.Id,
+        JoinType.LeftOuterJoin)
+    .Where(() => joinedCat.Id == null)
+    .List();]]></programlisting>
+    </sect1>
+
     <sect1 id="queryqueryover-aliases">
         <title>Aliases</title>
 
@@ -350,6 +369,32 @@ IList<CatSummary> catReport =
 
     </sect1>
 
+    <sect1 id="queryqueryover-projectionentities">
+      <title>Entities Projection</title>
+
+      <para>
+        You can add entity projections via <literal>AsEntity()</literal> extension.
+      </para>
+
+      <programlisting><![CDATA[Cat mate = null;
+
+var catAndMateNameList = sess.QueryOver<Cat>()
+    .JoinAlias(c => c.Mate, () => mate)
+    .Select(c => c.AsEntity(), c => mate.Name)
+    .List<object[]>();]]></programlisting>
+
+      <para>
+        Or it can be done via <literal>Projections.RootEntity</literal> and <literal>Projections.Entity</literal> methods
+        if more control over loaded entities is required. For instance entity projections can be lazy loaded 
+        or fetched with lazy properties:
+      </para>
+      <programlisting><![CDATA[.Select(
+    Projections.Entity(() => alias1).SetLazy(true),
+    Projections.Entity(() => alias2).SetFetchLazyProperties(true),
+    Projections.RootEntity()
+        )]]></programlisting>
+    </sect1>
+
     <sect1 id="queryqueryover-subqueries">
         <title>Sub-queries</title>