From 967c6d59eaab2e215d7af46f94ca510997bdf006 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timo=20Westk=C3=A4mper?= Date: Fri, 19 Apr 2013 17:42:29 +0300 Subject: [PATCH] #395 Update docs --- .../main/docbook/en-US/content/general.xml | 2 +- .../docbook/en-US/content/general/codegen.xml | 2 +- .../content/general/creating-queries.xml | 214 ++++++++++++++++++ .../en-US/content/general/result-handling.xml | 2 +- 4 files changed, 217 insertions(+), 3 deletions(-) create mode 100644 querydsl-docs/src/main/docbook/en-US/content/general/creating-queries.xml 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