From 54f21836b014706b42d15dac8f6ebcc3e586a2ea Mon Sep 17 00:00:00 2001 From: rbygrave Date: Thu, 18 Dec 2014 00:44:58 +1300 Subject: [PATCH] Javadoc update for RawSql --- src/main/java/com/avaje/ebean/RawSql.java | 139 +++++++++++------- .../java/com/avaje/ebean/RawSqlBuilder.java | 7 - 2 files changed, 88 insertions(+), 58 deletions(-) diff --git a/src/main/java/com/avaje/ebean/RawSql.java b/src/main/java/com/avaje/ebean/RawSql.java index c14da59e5..865dd0b4f 100644 --- a/src/main/java/com/avaje/ebean/RawSql.java +++ b/src/main/java/com/avaje/ebean/RawSql.java @@ -17,25 +17,25 @@ import com.avaje.ebean.util.CamelCaseHelper; * Unparsed RawSql: *

*

- * When RawSql is created via RawSqlBuilder.unparsed(sql) then Ebean can not + * When RawSql is created via {@link RawSqlBuilder#unparsed(String)} then Ebean can not * modify the SQL at all. It can't add any extra expressions into the SQL. *

*

* Parsed RawSql: *

*

- * When RawSql is created via RawSqlBuilder.parse(sql) then Ebean will parse the + * When RawSql is created via {@link RawSqlBuilder#parse(String)} then Ebean will parse the * SQL and find places in the SQL where it can add extra where expressions, add * extra having expressions or replace the order by clause. If you want to * explicitly tell Ebean where these insertion points are you can place special - * strings into your SQL (${where} or ${andWhere} and ${having} or - * ${andHaving}). + * strings into your SQL ({@code ${where}} or {@code ${andWhere}} and {@code ${having}} or + * {@code ${andHaving})}. *

*

- * If the SQL already includes a WHERE clause put in ${andWhere} in the location + * If the SQL already includes a WHERE clause put in {@code ${andWhere}} in the location * you want Ebean to add any extra where expressions. If the SQL doesn't have a - * WHERE clause put ${where} in instead. Similarly you can put in ${having} or - * ${andHaving} where you want Ebean put add extra having expressions. + * WHERE clause put {@code ${where}} in instead. Similarly you can put in {@code ${having}} or + * {@code ${andHaving}} where you want Ebean put add extra having expressions. *

*

* Aggregates: @@ -51,23 +51,19 @@ import com.avaje.ebean.util.CamelCaseHelper; * to hold the values for the aggregate functions (sum etc) and a @OneToOne * to Order. *

- *

- *   - *

- *

- * Example OrderAggregate - *

+ * + *

Example OrderAggregate

* - * 
+ * 
{@code
  *  ...
- *  // @Sql indicates to that this bean
+ *  // @Sql indicates to that this bean
  *  // is based on RawSql rather than a table
  * 
- * @Entity
- * @Sql    
+ * @Entity
+ * @Sql
  * public class OrderAggregate {
  * 
- *  @OneToOne
+ *  @OneToOne
  *  Order order;
  *      
  *  Double totalAmount;
@@ -76,35 +72,38 @@ import com.avaje.ebean.util.CamelCaseHelper;
  *  
  *  // getters and setters
  *  ...
- * 

- * 

- * Example 1:
- * 

+ *
+ * }
+ * + *

Example 1:

* - * 
- * String sql = " select order_id, o.status, c.id, c.name, sum(d.order_qty*d.unit_price) as totalAmount"
- *     + " from o_order o"
- *     + " join o_customer c on c.id = o.kcustomer_id "
- *     + " join o_order_detail d on d.order_id = o.id " + " group by order_id, o.status ";
+ * 
{@code
+ *
+ *   String sql = " select order_id, o.status, c.id, c.name, sum(d.order_qty*d.unit_price) as totalAmount"
+ *     + " from o_order o"
+ *     + " join o_customer c on c.id = o.kcustomer_id "
+ *     + " join o_order_detail d on d.order_id = o.id " + " group by order_id, o.status ";
  * 
- * RawSql rawSql = RawSqlBuilder.parse(sql)
+ *   RawSql rawSql = RawSqlBuilder.parse(sql)
  *     // map the sql result columns to bean properties
- *     .columnMapping("order_id", "order.id").columnMapping("o.status", "order.status")
- *     .columnMapping("c.id", "order.customer.id")
- *     .columnMapping("c.name", "order.customer.name")
+ *     .columnMapping("order_id", "order.id")
+ *     .columnMapping("o.status", "order.status")
+ *     .columnMapping("c.id", "order.customer.id")
+ *     .columnMapping("c.name", "order.customer.name")
  *     // we don't need to map this one due to the sql column alias
- *     // .columnMapping("sum(d.order_qty*d.unit_price)", "totalAmount")
+ *     // .columnMapping("sum(d.order_qty*d.unit_price)", "totalAmount")
  *     .create();
  * 
- * Query<OrderAggregate> query = Ebean.find(OrderAggregate.class);
- * query.setRawSql(rawSql).where().gt("order.id", 0).having().gt("totalAmount", 20);
+ *   List list = Ebean.find(OrderAggregate.class)
+ *       .setRawSql(rawSql)
+ *       .where().gt("order.id", 0)
+ *       .having().gt("totalAmount", 20)
+ *       .findList();
  * 
- * List<OrderAggregate> list = query.findList();
- * 

+ *
+ * }
* - *

- * Example 2: - *

+ *

Example 2:

* *

* The following example uses a FetchConfig().query() so that after the initial @@ -112,21 +111,59 @@ import com.avaje.ebean.util.CamelCaseHelper; * associated order status, orderDate along with the customer name. *

* - * 
- * String sql = " select order_id, 'ignoreMe', sum(d.order_qty*d.unit_price) as totalAmount "
- *     + " from o_order_detail d"
- *     + " group by order_id ";
+ * 
{@code
+ *
+ *  String sql = " select order_id, 'ignoreMe', sum(d.order_qty*d.unit_price) as totalAmount "
+ *     + " from o_order_detail d"
+ *     + " group by order_id ";
  * 
- * RawSql rawSql = RawSqlBuilder.parse(sql).columnMapping("order_id", "order.id")
- *     .columnMappingIgnore("'ignoreMe'").create();
+ *   RawSql rawSql = RawSqlBuilder.parse(sql)
+ *     .columnMapping("order_id", "order.id")
+ *     .columnMappingIgnore("'ignoreMe'")
+ *     .create();
  * 
- * Query<OrderAggregate> query = Ebean.find(OrderAggregate.class);
- * query.setRawSql(rawSql).fetch("order", "status,orderDate", new FetchConfig().query())
- *     .fetch("order.customer", "name").where()
- *     .gt("order.id", 0).having().gt("totalAmount", 20).order().desc("totalAmount").setMaxRows(10);
- * 
- * 

+ *   List orders = Ebean.find(OrderAggregate.class)
+ *     .setRawSql(rawSql)
+ *     .fetch("order", "status,orderDate", new FetchConfig().query())
+ *     .fetch("order.customer", "name")
+ *     .where().gt("order.id", 0)
+ *     .having().gt("totalAmount", 20)
+ *     .order().desc("totalAmount")
+ *     .setMaxRows(10)
+ *     .findList();
  * 
+ * }
+ * + * + *

Example 3: tableAliasMapping

+ *

+ * Instead of mapping each column you can map each table alias to a path using tableAliasMapping(). + *

+ * 
{@code
+ *
+ *   String rs = "select o.id, o.status, c.id, c.name, "+
+ *               " d.id, d.order_qty, p.id, p.name " +
+ *               "from o_order o join o_customer c on c.id = o.kcustomer_id " +
+ *               "join o_order_detail d on d.order_id = o.id  " +
+ *               "join o_product p on p.id = d.product_id  " +
+ *               "where o.id <= :maxOrderId  and p.id = :productId "+
+ *               "order by o.id, d.id asc";
+ *
+ *  RawSql rawSql = RawSqlBuilder.parse(rs)
+ *       .tableAliasMapping("c", "customer")
+ *       .tableAliasMapping("d", "details")
+ *       .tableAliasMapping("p", "details.product")
+ *       .create();
+ *
+ *  List ordersFromRaw = Ebean.find(Order.class)
+ *       .setRawSql(rawSql)
+ *       .setParameter("maxOrderId", 2)
+ *       .setParameter("productId", 1)
+ *       .findList();
+ *
+ * }
+ * + * *

* Note that lazy loading also works with object graphs built with RawSql. *

diff --git a/src/main/java/com/avaje/ebean/RawSqlBuilder.java b/src/main/java/com/avaje/ebean/RawSqlBuilder.java index 76418b36f..08a8c27f0 100644 --- a/src/main/java/com/avaje/ebean/RawSqlBuilder.java +++ b/src/main/java/com/avaje/ebean/RawSqlBuilder.java @@ -70,13 +70,6 @@ public class RawSqlBuilder { ColumnMapping mapping = DRawSqlColumnsParser.parse(select); return new RawSqlBuilder(sql2, mapping); } - - - private RawSqlBuilder(ResultSet resultSet, ColumnMapping columnMapping) { - this.resultSet = resultSet; - this.columnMapping = columnMapping; - this.sql = null; - } private RawSqlBuilder(Sql sql, ColumnMapping columnMapping) { this.sql = sql;