Updated documentation

querydsl-core/src/main/java/com/mysema/query/types/path/PEntityMap.java

@@ -7,7 +7,6 @@ package com.mysema.query.types.path;
 
 import java.util.Map;
 
-import com.mysema.commons.lang.Assert;
 import com.mysema.query.types.expr.EBoolean;
 import com.mysema.query.types.expr.EConstant;
 import com.mysema.query.types.expr.ENumber;
@@ -37,6 +36,7 @@ public class PEntityMap<K, V> extends Expr<Map<K, V>> implements PMap<K, V> {
 
     private EBoolean notEmpty;
 
+    @SuppressWarnings("unchecked")
     public PEntityMap(Class<K> keyType, Class<V> valueType, String entityName,
             PathMetadata<?> metadata) {
         super((Class)Map.class);

querydsl-core/src/main/java/com/mysema/query/types/path/PathMetadata.java

@@ -116,7 +116,7 @@ public final class PathMetadata<T> {
 
     private final int hashCode;
 
-    public PathMetadata(Path<?> parent, Expr<T> expression, PathType type) {
+    private PathMetadata(Path<?> parent, Expr<T> expression, PathType type) {
         this.parent = parent;
         this.expression = expression;
         this.pathType = type;

querydsl-docs/build.sh

@@ -0,0 +1,2 @@
+#!/bin/sh
+mvn -Dxslthl.config=http://docbook.sourceforge.net/release/xsl/current/highlighting/xslthl-config.xml clean package

querydsl-docs/src/main/docbook/content/alias_usage.xml

@@ -47,8 +47,8 @@ for (String name : from($(c),cats)
   </para>
 
   <programlisting language="java">
-import static com.mysema.query.alias.GrammarWithAlias.$;
-import static com.mysema.query.alias.GrammarWithAlias.alias;
+import static com.mysema.query.alias.Alias.$;
+import static com.mysema.query.alias.Alias.alias;
   </programlisting>
 
   <para>

querydsl-docs/src/main/docbook/content/best-practices.xml

@@ -2,12 +2,51 @@
 
 <chapter id="best-practices" revision="1">
   <title>Best practices</title>
-
-  <para>TODO</para>
   
 <!-- 
         * Interface based query usage
         * Custom query extensions    
  -->
+ 
+  <sect1>
+  
+    <title>Interface based usage</title>
+  
+    <para>Whenever possible, use interface based query references : JDOQLQuery for JDO and HQLQuery for HQL</para>
+  
+  </sect1>
+  
+  <sect1>
+  
+    <title>Custom query extensions</title>
+  
+    <para>TODO</para>
+  
+  </sect1>
+ 
+  <sect1 id="dao_integration">
+  
+  <title>DAO integration</title>
+  
+  <para>A practice which we have found to be very easy to use is to provide factory methods for 
+  Query instances in DAO implementations in the following form.</para>
+  
+  <para>For HQL usage :</para>
+  
+<programlisting language="java"><![CDATA[ 
+protected HQLQuery from(PEntity<?>... o) {
+    return new HqlQueryImpl(session).from(o);
+} 
+]]></programlisting>  
+  
+  <para>For JDO usage : </para>
+  
+<programlisting language="java"><![CDATA[
+protected JDOQLQuery from(PEntity<?>... o) {
+    return new JDOQLQueryImpl(persistenceManager).from(o);
+}        
+]]></programlisting>         
+  
+  </sect1>     
   
 </chapter>

querydsl-docs/src/main/docbook/content/integration/collections.xml

@@ -21,6 +21,7 @@
 
     <programlisting language="java"><![CDATA[
 import static com.mysema.query.collections.MiniApi.*;
+import static com.mysema.query.alias.Alias.*; // for alias usage
 ]]></programlisting>
 
   </sect2>

querydsl-docs/src/main/docbook/content/integration/hql.xml

@@ -170,7 +170,161 @@ Customer bob = query.from(customer)
       filter and uniqueResult defines the projection and tells Querydsl
       to return a single element. Easy, right?
   </para>
+  
+  <para>
+    To create a query with multiple sources you just use the HQLQuery interface like this :
+  </para>
+
+    <programlisting language="java"><![CDATA[
+query.from(customer, company);    
+]]></programlisting>    
+
+   <para>
+   And to use multiple filters use it like this
+   </para>
+   
+   <programlisting language="java"><![CDATA[
+query.from(customer)
+    .where(customer.firstName.eq("Bob"), customer.lastName.eq("Wilson"));   
+]]></programlisting>   
+  
+  <para>Or like this</para>
+    
+<programlisting language="java"><![CDATA[
+query.form(customer)
+    .where(customer.firstName.eq("Bob").and(customer.lastName.eq("Wilson")));
+]]></programlisting>
+
+  <para>In native HQL form the query would be written like this : </para>
+  
+<programlisting>
+from Customer as customer
+    where customer.firstName = "Bob" and customer.lastName = "Wilson"
+</programlisting>
 
   </sect2>
+  
+  <sect2>
+  
+  <title>Using joins</title>
+  
+  <para>Querydsl supports the following join variants in HQL/JPAQL : inner join, join, left join and full join.
+    Join usage is typesafe, and follows the following pattern :</para>
+    
+<programlisting language="java"><![CDATA[  
+query.from(cat)
+    .innerJoin(cat.mate, mate)
+    .leftJoin(cat.kittens, kitten)
+    .list(cat);
+]]></programlisting>
+
+ <para>The native HQL version of the query would be </para>
+  
+<programlisting>
+from Cat as cat
+    inner join cat.mate as mate
+    left outer join cat.kittens as kitten
+</programlisting>    
+  
+  <para>Another example</para>
+  
+<programlisting language="java"><![CDATA[ 
+query.from(cat)
+    .leftJoin(cat.kittens, kitten)
+    .on(kitten.bodyWeight.gt(10.0))
+    .list(cat);
+]]></programlisting>
+
+<para>With the following HQL version</para>    
+  
+<programlisting>  
+from Cat as cat
+    left join cat.kittens as kitten
+    with kitten.bodyWeight > 10.0  
+</programlisting>  
+  
+  </sect2>
+  
+  <sect2>
+  
+  <title>Ordering</title>
+  
+  <para>The syntax for declaring ordering is </para>
+  
+<programlisting language="java"><![CDATA[ 
+query.from(customer)
+    .orderBy(customer.lastName.asc(), customer.firstName.desc())
+    .list(customer);
+]]></programlisting>
+
+  <para>which is equivalent to the following native HQL</para>  
+
+<programlisting>  
+from Customer as customer
+    order by customer.lastName asc, customer.firstName desc
+</programlisting>
+  
+  </sect2>  
+
+  <sect2>
+  
+  <title>Grouping</title>
+  
+  <para>Grouping can be done in the following form</para>
+  
+<programlisting language="java"><![CDATA[ 
+query.from(customer)
+    .groupBy(customer.lastName)
+    .list(customer.lastName);
+]]></programlisting>
+
+  <para>which is equivalent to the following native HQL</para>  
+
+<programlisting>  
+select customer.lastName
+    from Customer as customer
+    group by customer.lastName
+</programlisting>
+    
+  
+  </sect2>  
+  
+  <sect2>
+  
+  <title>Subqueries</title>
+  
+  
+  <para>Subqueries in the HQL module are just special projections of the HQLQuery interface. To create
+  a subquery you create a HQLQuery instance, define the query parameters via from, where etc and use
+  uniqueExpr or listExpr to create a subquery, which is just a type-safe Querydsl expression for the query.
+  uniqueExpr is used for a unique result and listExpr for a list result.</para>
+
+<programlisting language="java"><![CDATA[
+query().from(department)
+    .where(department.employees.size().eq(
+        query().from(d).uniqueExpr(AggregationFunctions.max(d.employees.size()))
+     )).list(department);
+]]></programlisting>   
+
+  <para>Another example</para>
+
+<programlisting language="java"><![CDATA[
+query().from(employee)
+    .where(employee.weeklyhours.gt(
+        query().from(employee.department.employees, e)
+        .where(e.manager.eq(employee.manager))
+        .uniqueExpr(AggregationFunctions.avg(e.weeklyhours))
+    )).list(employee);
+]]></programlisting>  
+
+  </sect2>      
+  
+  <sect2>
+  
+  <title>Aggregate functions</title>
+  
+  <para>Aggregate functions are available as static methods in the com.mysema.query.functions.AggreationFunctions class.</para>
+  
+  </sect2>    
 
 </sect1>

querydsl-docs/src/main/docbook/content/integration/jdoql.xml

@@ -190,6 +190,111 @@ query.close();
       to return a single element. Easy, right?
   </para>
 
+<para>
+    To create a query with multiple sources you just use the JDOQLQuery interface like this :
+  </para>
+
+    <programlisting language="java"><![CDATA[
+query.from(customer, company);    
+]]></programlisting>    
+
+   <para>
+   And to use multiple filters use it like this
+   </para>
+   
+   <programlisting language="java"><![CDATA[
+query.from(customer)
+    .where(customer.firstName.eq("Bob"), customer.lastName.eq("Wilson"));   
+]]></programlisting>   
+  
+  <para>Or like this</para>
+    
+<programlisting language="java"><![CDATA[
+query.form(customer)
+    .where(customer.firstName.eq("Bob").and(customer.lastName.eq("Wilson")));
+]]></programlisting>
+
   </sect2>
+  
+  <sect2>
+  
+  <title>Ordering</title>
+  
+  <para>The syntax for declaring ordering is </para>
+  
+<programlisting language="java"><![CDATA[ 
+query.from(customer)
+    .orderBy(customer.lastName.asc(), customer.firstName.desc())
+    .list(customer);
+]]></programlisting>
+
+  </sect2>  
+
+  <sect2>
+  
+  <title>Grouping</title>
+  
+  <para>Grouping can be done in the following form</para>
+  
+<programlisting language="java"><![CDATA[ 
+query.from(customer)
+    .groupBy(customer.lastName)
+    .list(customer.lastName);
+]]></programlisting>
+     
+  </sect2>    
+  
+  <sect2>
+  
+  <title>Subqueries</title>
+  
+  <para>Subqueries in the JDOQL module are just special projections of the JDOQLQuery interface. To create
+  a subquery you create a JDOQLQuery instance, define the query parameters via from, where etc and use
+  uniqueExpr or listExpr to create a subquery, which is just a type-safe Querydsl expression for the query.
+  uniqueExpr is used for a unique result and listExpr for a list result.</para>
+
+<programlisting language="java"><![CDATA[
+query().from(department)
+    .where(department.employees.size().eq(
+        query().from(d).uniqueExpr(AggregationFunctions.max(d.employees.size()))
+     )).list(department);  
+]]></programlisting>   
+
+  <para>represents the following native JDOQL query</para>
+  
+<programlisting>
+SELECT this FROM com.mysema.query.jdoql.models.company.Department
+WHERE this.employees.size() == 
+(SELECT max(d.employees.size()) FROM com.mysema.query.jdoql.models.company.Department d)
+</programlisting>  
+
+  <para>Another example</para>
+
+<programlisting language="java"><![CDATA[
+query().from(employee)
+    .where(employee.weeklyhours.gt(
+        query().from(employee.department.employees, e)
+        .where(e.manager.eq(employee.manager))
+        .uniqueExpr(AggregationFunctions.avg(e.weeklyhours))
+    )).list(employee);
+]]></programlisting>  
+
+<para>which represents the following native JDOQL query</para>
+
+<programlisting>
+SELECT this FROM com.mysema.query.jdoql.models.company.Employee 
+WHERE this.weeklyhours > 
+(SELECT avg(e.weeklyhours) FROM this.department.employees e WHERE e.manager == this.manager)
+</programlisting>
+          
+  </sect2>      
+  
+  <sect2>
+  
+  <title>Aggregate functions</title>
+  
+  <para>Aggregate functions are available as static methods in the com.mysema.query.functions.AggreationFunctions class.</para>
+  
+  </sect2>    
 
 </sect1>