From 380660913f677efe774dfcedcd739d87b0b85198 Mon Sep 17 00:00:00 2001 From: Robin Bygrave Date: Tue, 2 Aug 2016 23:42:00 +1200 Subject: [PATCH] No effective change - javadoc update on Query --- src/main/java/com/avaje/ebean/Query.java | 94 ++++-------------------- 1 file changed, 16 insertions(+), 78 deletions(-) diff --git a/src/main/java/com/avaje/ebean/Query.java b/src/main/java/com/avaje/ebean/Query.java index 3161ef96b..fc7ff5ba9 100644 --- a/src/main/java/com/avaje/ebean/Query.java +++ b/src/main/java/com/avaje/ebean/Query.java @@ -35,7 +35,6 @@ import java.util.Set; * 
{@code
  *
  * String oql =
- *   	"  find  order "
  *   	+" fetch customer "
  *   	+" fetch details "
  *   	+" where customer.name like :custName and orderDate > :minOrderDate "
@@ -96,33 +95,24 @@ import java.util.Set;
  * Refer to "ALL Properties/Columns" mode of Optimistic Concurrency checking.
  * 

  * 
{@code
- * [ find  {bean type} [ ( * | {fetch properties} ) ] ]
- * [ fetch {associated bean} [ ( * | {fetch properties} ) ] ]
+ * [ select [ ( * | {fetch properties} ) ] ]
+ * [ fetch {path} [ ( * | {fetch properties} ) ] ]
  * [ where {predicates} ]
  * [ order by {order by properties} ]
  * [ limit {max rows} [ offset {first row} ] ]
  * }

  * 

- * FIND {bean type} [ ( * | {fetch properties} ) ]
+ * SELECT [ ( * | {fetch properties} ) ]
  * 

  * 

- * With the find you specify the type of beans to fetch. You can optionally
- * specify a list of properties to fetch. If you do not specify a list of
- * properties ALL the properties for those beans are fetched.
+ * With the select you can specify a list of properties to fetch.
  * 

  * 

- * In object graph terms the find clause specifies the type of bean at
- * the root level and the fetch clauses specify the paths of the object
- * graph to populate.
- * 

- * 

- * FETCH {associated property} [ ( * | {fetch
- * properties} ) ]
+ * FETCH {path} [ ( * | {fetch properties} ) ]
  * 

  * 

  * With the fetch you specify the associated property to fetch and populate. The
- * associated property is a OneToOnem, ManyToOne, OneToMany or ManyToMany
- * property. When the query is executed Ebean will fetch the associated data.
+ * path is a OneToOne, ManyToOne, OneToMany or ManyToMany property.
  * 

  * 

  * For fetch of a path we can optionally specify a list of properties to fetch.
@@ -153,41 +143,33 @@ import java.util.Set;
  * 

  * 
Examples of Ebean's Query Language

  * 

- * Find orders fetching all its properties
- * 

- * 
{@code
- * find order
- * }

- * 

- * Find orders fetching all its properties
- * 

- * 
{@code
- * find order (*)
- * }

- * 

  * Find orders fetching its id, shipDate and status properties. Note that the id
  * property is always fetched even if it is not included in the list of fetch
  * properties.
  * 

  * 
{@code
- * find order (shipDate, status)
+ *
+ * select (shipDate, status)
+ *
  * }

  * 

  * Find orders with a named bind variable (that will need to be bound via
  * {@link Query#setParameter(String, Object)}).
  * 

  * 
{@code
- * find order
+ *
  * where customer.name like :custLike
+ *
  * }

  * 

  * Find orders and also fetch the customer with a named bind parameter. This
  * will fetch and populate both the order and customer objects.
  * 

  * 
{@code
- * find  order
+ *
  * fetch customer
  * where customer.id = :custId
+ *
  * }

  * 

  * Find orders and also fetch the customer, customer shippingAddress, order
@@ -198,57 +180,13 @@ import java.util.Set;
  * populated.
  * 

  * 
{@code
- * find  order
+ *
  * fetch customer (name)
  * fetch customer.shippingAddress
  * fetch details
  * fetch details.product (sku, name)
+ *
  * }

- * 
Early parsing of the Query

- * 

- * When you get a Query object from a named query, the query statement has
- * already been parsed. You can then add to that query (add fetch paths, add to
- * the where clause) or override some of its settings (override the order by
- * clause, first rows, max rows).
- * 

- * 

- * The thought is that you can use named queries as a 'starting point' and then
- * modify the query to suit specific needs.
- * 

- * 
Building the Where clause

- * 

- * You can add to the where clause using Expression objects or a simple String.
- * Note that the ExpressionList has methods to add most of the common
- * expressions that you will need.
- * 

- * 

- * 

- * The full WHERE clause is constructed by appending together
- * 
  • original query where clause (Named query or query.setQuery(String oql))
    • 
- * 
  • clauses added via query.where(String addToWhereClause)
    • 
- * 
  • clauses added by Expression objects
    • 
- * 
    
- * 
    
- * The above is the order that these are clauses are appended to give the full
- * WHERE clause.
- * 
    
- * 
    Design Goal
    
- * 
    
- * This query language is NOT designed to be a replacement for SQL. It is
- * designed to be a simple way to describe the "Object Graph" you want Ebean to
- * build for you. Each find/fetch represents a node in that "Object Graph" which
- * makes it easy to define for each node which properties you want to fetch.
- * 
    
- * 
    
- * Once you hit the limits of this language such as wanting aggregate functions
- * (sum, average, min etc) or recursive queries etc you use SQL. Ebean's goal is
- * to make it as easy as possible to use your own SQL to populate entity beans.
- * Refer to {@link RawSql} .
- * 
    
  *
  * @param  the type of Entity bean this query will fetch.
  */
@@ -304,7 +242,7 @@ public interface Query {
    * Specify the PersistenceContextScope to use for this query.
    * 
    
    * When this is not set the 'default' configured on {@link com.avaje.ebean.config.ServerConfig#setPersistenceContextScope(PersistenceContextScope)}
-   * is used - this value defaults to {@link com.avaje.ebean.PersistenceContextScope#TRANSACTION}.
+   * is used - this value defaults to {@link PersistenceContextScope#TRANSACTION}.
    * 
    
    * Note that the same persistence Context is used for subsequent lazy loading and query join queries.
    *