diff --git a/querydsl-docs/src/main/docbook/content/tutorials/jpa.xml b/querydsl-docs/src/main/docbook/content/tutorials/jpa.xml
index 47f37f2e6..368582e2e 100644
--- a/querydsl-docs/src/main/docbook/content/tutorials/jpa.xml
+++ b/querydsl-docs/src/main/docbook/content/tutorials/jpa.xml
@@ -344,7 +344,7 @@ from Cat as cat
@@ -366,7 +366,7 @@ from Cat as cat
from : Define the query sources here.
- innerJoin, join, leftJoin, fullJoin, on : Define join elements using these constructs.
+ innerJoin, join, leftJoin, fullJoin, with : Define join elements using these constructs.
For the join methods the first argument is the join source and the second the target (alias).
where : Define the query filters, either in varargs form separated via commas or
@@ -610,4 +610,4 @@ List catDTOs = query.from(cat)
-
\ No newline at end of file
+
diff --git a/querydsl-docs/src/main/docbook/content/tutorials/jpa.xml~ b/querydsl-docs/src/main/docbook/content/tutorials/jpa.xml~
new file mode 100644
index 000000000..47f37f2e6
--- /dev/null
+++ b/querydsl-docs/src/main/docbook/content/tutorials/jpa.xml~
@@ -0,0 +1,613 @@
+
+
+
+
+ Querying JPA
+
+
+ Querydsl defines a general statically typed syntax for querying on top of
+ persisted domain model data. JDO and JPA are the primary integration
+ technologies for Querydsl. This guide describes how to use Querydsl
+ in combination with JPA/Hibernate.
+
+
+
+ Querydsl for JPA/Hibernate is an alternative to both JPQL and Criteria queries. It combines the dynamic nature
+ of Criteria queries with the expressiveness of JPQL and all that in a fully typesafe manner.
+
+
+
+ Maven integration
+
+
+ Add the following dependencies to your Maven project and make sure that
+ the Maven 2 repo of Mysema Source (http://source.mysema.com/maven2/releases) is accessible from your POM :
+
+
+
+ com.mysema.querydsl
+ querydsl-apt
+ ${querydsl.version}
+ provided
+
+
+
+ com.mysema.querydsl
+ querydsl-jpa
+ ${querydsl.version}
+
+
+
+ org.slf4j
+ slf4j-log4j12
+ 1.6.1
+
+]]>
+
+
+ And now, configure the Maven APT plugin :
+
+
+
+
+
+ ...
+
+ com.mysema.maven
+ maven-apt-plugin
+ 1.0
+
+
+
+ process
+
+
+ target/generated-sources/java
+ com.mysema.query.apt.jpa.JPAAnnotationProcessor
+
+
+
+
+ ...
+
+
+
+]]>
+
+
+ The JPAAnnotationProcessor finds domain types annotated with the
+ javax.persistence.Entity annotation and generates query types for them.
+
+
+
+ If you use Hibernate annotations in your domain types you should use
+ the APT processor com.mysema.query.apt.hibernate.HibernateAnnotationProcessor
+ instead.
+
+
+
+ Run clean install and you will get your Query
+ types generated into target/generated-sources/java.
+
+
+
+ If you use Eclipse, run mvn eclipse:eclipse to update your Eclipse project to include target/generated-sources/java
+ as a source folder.
+
+
+
+ Now you are able to construct JPQL query instances and instances of
+ the query domain model.
+
+
+
+
+
+
+ Ant integration
+
+ Place the jar files from the full-deps bundle on your classpath and use the following tasks for Querydsl code generation :
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+]]>
+
+ Replace src with your main source folder, generated with your folder for generated sources
+ and build with your target folder.
+
+
+
+
+
+ Generating the model from hbm.xml files
+
+ If you are using Hibernate with an XML based configuration, you can use the XML metadata to create your Querydsl model.
+
+ com.mysema.query.jpa.hibernate.HibernateDomainExporer provides the functionality for this :
+
+
+
+ The HibernateDomainExporter needs to be executed within a classpath where the domain types are visible, since the property types are resolved
+ via reflection.
+
+ All JPA annotations are ignored, but Querydsl annotations such as @QueryInit and @QueryType are taken into account.
+
+
+
+
+
+ Using query types
+
+
+ To create queries with Querydsl you need to instantiate variables and
+ Query implementations. We will start with the variables.
+
+
+
+ Let's assume that your project has the following domain type :
+
+
+
+
+
+ Querydsl will generate a query type with the simple name QCustomer into the
+ same package as Customer. QCustomer can be used as a statically
+ typed variable in Querydsl queries as a representative for the
+ Customer type.
+
+
+
+ QCustomer has a default instance variable which can be accessed as a static
+ field :
+
+
+
+
+
+ Alternatively you can define your own Customer variables like this :
+
+
+
+
+
+
+
+
+ Querying
+
+ The Querydsl JPA module supports both the JPA and the Hibernate API.
+
+
+ To use the Hibernate API you use HibernateQuery instances for your queries like this :
+
+
+
+
+ If you are using the JPA API instead, you can instantiate a JPAQuery like this :
+
+
+
+ Both HibernateQuery and JPAQuery implement the JPQLQuery interface.
+
+
+ The default configuration of JPAQuery is best suited for use with Hibernate. Whe using EclipseLink as the JPA provider, the
+ JPAQuery should be constructed like this :
+
+
+
+
+ If you want to use the standard JPA 2 serialization then create the query like this :
+
+
+
+
+ To retrieve the customer with the first name Bob you would construct a
+ query like this :
+
+
+
+
+
+ The from call defines the query source, the where part defines the
+ filter and uniqueResult defines the projection and tells Querydsl
+ to return a single element. Easy, right?
+
+
+
+ To create a query with multiple sources you use the query like this :
+
+
+
+
+
+ And to use multiple filters use it like this
+
+
+
+
+ Or like this
+
+
+
+ In native JPQL form the query would be written like this :
+
+
+from Customer as customer
+ where customer.firstName = "Bob" and customer.lastName = "Wilson"
+
+
+ If you want to combine the filters via "or" then use the following pattern
+
+
+
+
+
+
+
+ Using joins
+
+ Querydsl supports the following join variants in JPQL : inner join, join, left join and full join.
+ Join usage is typesafe, and follows the following pattern :
+
+
+
+ The native JPQL version of the query would be
+
+
+from Cat as cat
+ inner join cat.mate as mate
+ left outer join cat.kittens as kitten
+
+
+ Another example
+
+
+
+With the following JPQL version
+
+
+from Cat as cat
+ left join cat.kittens as kitten
+ with kitten.bodyWeight > 10.0
+
+
+
+
+
+
+ General usage
+
+ Use the the cascading methods of the JPQLQuery interface like this
+
+ from : Define the query sources here.
+
+ innerJoin, join, leftJoin, fullJoin, on : Define join elements using these constructs.
+ For the join methods the first argument is the join source and the second the target (alias).
+
+ where : Define the query filters, either in varargs form separated via commas or
+ cascaded via the and-operator.
+
+ groupBy : Define the group by arguments in varargs form.
+
+ having : Define the having filter of the "group by" grouping as an varags array of
+ Predicate expressions.
+
+ orderBy : Define the ordering of the result as an varargs array of order expressions.
+ Use asc() and desc() on numeric, string and other comparable expression to access the OrderSpecifier instances.
+
+ limit, offset, restrict : Define the paging of the result. Limit for max results,
+ offset for skipping rows and restrict for defining both in one call.
+
+
+
+
+
+ Ordering
+
+ The syntax for declaring ordering is
+
+
+
+ which is equivalent to the following native JPQL
+
+
+from Customer as customer
+ order by customer.lastName asc, customer.firstName desc
+
+
+
+
+
+
+ Grouping
+
+ Grouping can be done in the following form
+
+
+
+ which is equivalent to the following native JPQL
+
+
+select customer.lastName
+ from Customer as customer
+ group by customer.lastName
+
+
+
+
+
+
+ Delete clauses
+ Delete clauses in Querydsl JPA follow a simple delete-where-execute form. Here are some examples :
+
+
+
+ The second parameter of the HibernateDeleteClause constructor is the entity to be deleted.
+ The where call is optional and the execute call performs the deletion and returns the amount of deleted entities.
+
+ For JPA based Delete usage, use the JPADeleteClause instead.
+
+
+
+ Update clauses
+ Update clauses in Querydsl JPA follow a simple update-set/where-execute form. Here are some examples :
+
+
+
+ The second parameter of the HibernateUpdateClause constructor is the entity to be updated.
+ The set invocations define the property updates in SQL-Update-style and the execute call performs
+ the Update and returns the amount of updated entities.
+
+ For JPA based Update usage, use the JPAUpdateClause instead.
+
+
+
+
+
+ Subqueries
+
+ To create a subquery you create a HibernateSubQuery instance, define the query parameters
+ via from, where etc and use
+ unique or list to create a subquery, which is just a type-safe Querydsl expression for the query.
+ unique is used for a unique (single) result and list for a list result.
+
+
+
+ Another example
+
+
+
+ For JPA based sub query usage, use the JPASubQuery instead.
+
+
+
+
+ Exposing the original query
+
+ If you need to do tune the original Query before the execution of the query you can expose it like this :
+
+
+
+
+
+
+ Using Native SQL in Hibernate queries
+
+ Querydsl supports Native SQL in Hibernate via the HibernateSQLQuery class.
+
+ To use it, you must generate Querydsl query types for your SQL schema. This can be done for example
+ with the following Maven configuration :
+
+
+ com.mysema.querydsl
+ querydsl-maven-plugin
+ ${project.version}
+
+
+
+ export
+
+
+
+
+ org.apache.derby.jdbc.EmbeddedDriver
+ jdbc:derby:target/demoDB;create=true
+ com.mycompany.mydomain
+ ${project.basedir}/target/generated-sources/java
+
+
+
+ org.apache.derby
+ derby
+ ${derby.version}
+
+
+
+]]>
+
+ When the query types have successfully been generated into the location of your choice, you can use them in your
+ queries.
+
+
+ Single column query :
+
+ names = query.from(cat).list(cat.name);
+]]>
+
+ Query multiple columns :
+
+ rows = query.from(cat).list(cat.id, cat.name);
+]]>
+
+ Query all columns :
+
+ rows = query.from(cat).list(cat.all());
+ ]]>
+
+ Query in SQL, but project as entity :
+
+ cats = query.from(cat).orderBy(cat.name.asc()).list(catEntity);
+]]>
+
+ Query with joins :
+
+
+
+ Query and project into DTO :
+
+ catDTOs = query.from(cat)
+ .orderBy(cat.name.asc())
+ .list(ConstructorExpression.create(CatDTO.class, cat.id, cat.name));
+]]>
+
+ If you are using the JPA API instead of the Hibernate API, then use
+ JPASQLQuery instead of HibernateSQLQuery
+
+
+
+
\ No newline at end of file