diff --git a/querydsl-docs/src/main/docbook/en-US/content/general.xml b/querydsl-docs/src/main/docbook/en-US/content/general.xml
index 3cf9ff5cf..5d51b140e 100644
--- a/querydsl-docs/src/main/docbook/en-US/content/general.xml
+++ b/querydsl-docs/src/main/docbook/en-US/content/general.xml
@@ -8,7 +8,7 @@
It follows a use case oriented structure.
-
+
diff --git a/querydsl-docs/src/main/docbook/en-US/content/general/codegen.xml b/querydsl-docs/src/main/docbook/en-US/content/general/codegen.xml
index 85a51fbc7..b49b43f8a 100644
--- a/querydsl-docs/src/main/docbook/en-US/content/general/codegen.xml
+++ b/querydsl-docs/src/main/docbook/en-US/content/general/codegen.xml
@@ -1,4 +1,4 @@
-
+
Code generation
diff --git a/querydsl-docs/src/main/docbook/en-US/content/general/creating-queries.xml b/querydsl-docs/src/main/docbook/en-US/content/general/creating-queries.xml
new file mode 100644
index 000000000..ae70754b7
--- /dev/null
+++ b/querydsl-docs/src/main/docbook/en-US/content/general/creating-queries.xml
@@ -0,0 +1,214 @@
+
+
+ Creating queries
+
+ Query construction in Querydsl involves calling query methods with expression arguments. Since
+ query methods are mostly module specific and have already been presented in the tutorial section,
+ this part will focus on expressions.
+
+ Expressions are normally constructed by accessing fields and calling methods on the generated
+ expression types of your domain module. For cases where code generation is not applicable generic ways
+ to construct expressions can be used instead
+
+
+ Complex predicates
+
+
+ To construct complex boolean expressions, use the com.mysema.query.BooleanBuilder class. It
+ implements Predicate and can be used in cascaded form:
+
+
+ getCustomer(String... names){
+ QCustomer customer = QCustomer.customer;
+ JPAQuery query = new JPAQuery(entityManager).from(customer);
+ BooleanBuilder builder = new BoolenBuilder();
+ for (String name : names){
+ builder.or(customer.name.eq(name));
+ }
+ query.where(builder); // customer.name eq name1 OR customer.name eq name2 OR ...
+ return query.list(customer);
+}
+]]>
+
+ BooleanBuilder is mutable and represents initially null and after each and
+ or or call the result of the operation.
+
+
+
+
+
+ Dynamic expressions
+
+
+ The com.mysema.query.support.Expressions
+ class is a static factory class for dynamic expression construction.
+ The factory methods are named by the returned type and are mostly self-documenting.
+
+
+
+ In general the Expressions class should be used only in cases where fluent DSL forms
+ can't be used, such as dynamic paths, custom syntax or custom operations.
+
+
+ The following expression
+
+
+
+ could be constructed like this if Q-types wouldn't be available
+
+ person = Expressions.path(Person.class, "person");
+Path personFirstName = Expressions.path(String.class, person, "firstName");
+Constant constant = Expressions.constant("P");
+Expressions.predicate(Ops.STARTS_WITH, personFirstName, constant);
+]]>
+
+ Path instances represent variables and properties, Constants are constants,
+ Operations are operations and TemplateExpression instances can be used to express
+ expressions as String templates.
+
+
+
+
+
+
+ Dynamic paths
+
+ In addition to the Expressions based expression creation Querydsl provides
+ also a more fluent API for dynamic path creation.
+
+
+ For dynamic path generation the com.mysema.query.types.path.PathBuilder class can be used. It extends
+ EntityPathBase and can be used as an alternative to class generation and alias-usage
+ for path generation.
+
+
+
+ Compared to the Expressions API PathBuilder doesn't provide direct support for unknown operations
+ or custom syntax, but the syntax is closer to the normal DSL.
+
+
+ String property:
+
+ entityPath = new
+PathBuilder(User.class, "entity");
+// fully generic access
+entityPath.get("userName");
+// .. or with supplied type
+entityPath.get("userName", String.class);
+// .. and correct signature
+entityPath.getString("userName").lower();
+]]>
+
+ List property with component type:
+
+
+
+ Using a component expression type:
+
+
+
+ Map property with key and value type:
+
+
+
+ Using a component expression type:
+
+
+
+
+
+
+ Case expressions
+
+ To construct case-when-then-else expressions use the
+ CaseBuilder class like this:
+
+
+ cases = new CaseBuilder()
+ .when(customer.annualSpending.gt(10000)).then("Premier")
+ .when(customer.annualSpending.gt(5000)).then("Gold")
+ .when(customer.annualSpending.gt(2000)).then("Silver")
+ .otherwise("Bronze");
+// The cases expression can now be used in a projection or condition
+]]>
+
+ For case expressions with equals-operations use the following simpler form instead:
+
+
+ cases = customer.annualSpending
+ .when(10000).then("Premier")
+ .when(5000).then("Gold")
+ .when(2000).then("Silver")
+ .otherwise("Bronze");
+// The cases expression can now be used in a projection or condition
+]]>
+
+ Case expressions are not yet supported in JDOQL.
+
+
+
+
+
+ Casting expressions
+
+
+ To avoid a generic signature in expression types the type hierarchies are
+ flattened. The result is that all generated query types are direct subclasses of
+ com.mysema.query.types.path.EntityPathBase
+ or
+ com.mysema.query.types.path.BeanPath
+ and cannot be directly cast to their logical supertypes.
+
+
+
+ Instead of a direct Java cast, the supertype reference is accessible via the
+ _super field. A _super-field is available in all generated query types with a single
+ supertype:
+
+
+ {
+ // ...
+}
+
+// from BankAccount extends Account
+QBankAccount extends EntityPathBase{
+
+ public final QAccount _super = new QAccount(this);
+
+ // ...
+}
+]]>
+
+ To cast from a supertype to a subtype you can use the
+ as-method of the
+ EntityPathBase class:
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/querydsl-docs/src/main/docbook/en-US/content/general/result-handling.xml b/querydsl-docs/src/main/docbook/en-US/content/general/result-handling.xml
index aeabb1be3..0db418c64 100644
--- a/querydsl-docs/src/main/docbook/en-US/content/general/result-handling.xml
+++ b/querydsl-docs/src/main/docbook/en-US/content/general/result-handling.xml
@@ -1,4 +1,4 @@
-
+
Result handling