EQL - Add / expose via EbeanServer.createQuery(type, eql) method

src/main/java/com/avaje/ebean/Ebean.java

@@ -975,39 +975,7 @@ public final class Ebean {
    * {@link Query#findSet()} etc will execute against the same EbeanServer from
    * which is was created.
    * </p>
-   * 
-   * <pre>{@code
-   *   // Find order 2 additionally fetching the customer, details and details.product
-   *   // name.
-   * 
-   *   Order order = Ebean.find(Order.class)
-   *     .fetch("customer")
-   *     .fetch("details")
-   *     .fetch("detail.product", "name")
-   *     .setId(2)
-   *     .findUnique();
-   * 
-   *   // Find order 2 additionally fetching the customer, details and details.product
-   *   // name.
-   *   // Note: same query as above but using the query language
-   *   // Note: using a named query would be preferred practice
-   * 
-   *   String oql = "find order fetch customer fetch details fetch details.product (name) where id = :orderId ";
-   * 
-   *   Query<Order> query = Ebean.find(Order.class);
-   *   query.setQuery(oql);
-   *   query.setParameter("orderId", 2);
-   * 
-   *   Order order = query.findUnique();
-   * 
-   *   // Using a named query
-   *   Query<Order> query = Ebean.find(Order.class, "with.details");
-   *   query.setParameter("orderId", 2);
-   * 
-   *   Order order = query.findUnique();
-   * 
-   * }</pre>
-   * 
+   *
    * @param beanType
    *          the class of entity to be fetched
    * @return A ORM Query object for this beanType
@@ -1017,6 +985,47 @@ public final class Ebean {
     return serverMgr.getDefaultServer().createQuery(beanType);
   }
 
+  /**
+   * Parse the Ebean query language statement returning the query which can then
+   * be modified (add expressions, change order by clause, change maxRows, change
+   * fetch and select paths etc).
+   *
+   * <h3>Example</h3>
+   *
+   * <pre>{@code
+   *
+   *
+   *   // Find order additionally fetching the customer, details and details.product name.
+   *
+   *   String eql = "fetch customer fetch details fetch details.product (name) where id = :orderId ";
+   *
+   *   Query<Order> query = Ebean.createQuery(Order.class, eql);
+   *   query.setParameter("orderId", 2);
+   *
+   *   Order order = query.findUnique();
+   *
+   *   // This is the same as:
+   *
+   *   Order order = Ebean.find(Order.class)
+   *     .fetch("customer")
+   *     .fetch("details")
+   *     .fetch("detail.product", "name")
+   *     .setId(2)
+   *     .findUnique();
+   *
+   * }</pre>
+   *
+   * @param beanType The type of bean to fetch
+   * @param eql The Ebean query
+   * @param <T> The type of the entity bean
+   *
+   * @return The query with expressions defined as per the parsed query statement
+   */
+  public static <T> Query<T> createQuery(Class<T> beanType, String eql) {
+
+    return serverMgr.getDefaultServer().createQuery(beanType, eql);
+  }
+
   /**
    * Create a query for a type of entity bean.
    * <p>

src/main/java/com/avaje/ebean/EbeanServer.java

@@ -219,6 +219,43 @@ public interface EbeanServer {
    */
   <T> Query<T> createQuery(Class<T> beanType);
 
+  /**
+   * Parse the Ebean query language statement returning the query which can then
+   * be modified (add expressions, change order by clause, change maxRows, change
+   * fetch and select paths etc).
+   *
+   * <h3>Example</h3>
+   *
+   * <pre>{@code
+   *
+   *   // Find order additionally fetching the customer, details and details.product name.
+   *
+   *   String eql = "fetch customer fetch details fetch details.product (name) where id = :orderId ";
+   *
+   *   Query<Order> query = Ebean.createQuery(Order.class, eql);
+   *   query.setParameter("orderId", 2);
+   *
+   *   Order order = query.findUnique();
+   *
+   *   // This is the same as:
+   *
+   *   Order order = Ebean.find(Order.class)
+   *     .fetch("customer")
+   *     .fetch("details")
+   *     .fetch("detail.product", "name")
+   *     .setId(2)
+   *     .findUnique();
+   *
+   * }</pre>
+   *
+   * @param beanType The type of bean to fetch
+   * @param eql The Ebean query
+   * @param <T> The type of the entity bean
+   *
+   * @return The query with expressions defined as per the parsed query statement
+   */
+  <T> Query<T> createQuery(Class<T> beanType, String eql);
+
   /**
    * Create a query for a type of entity bean.
    * <p>

src/main/java/com/avaje/ebean/OrderBy.java

@@ -213,8 +213,9 @@ public final class OrderBy<T> implements Serializable {
    * order by clause and replace.
    * </p>
    */
-  public void clear() {
+  public OrderBy<T> clear() {
     list.clear();
+    return this;
   }
 
   /**

src/main/java/com/avaje/ebeaninternal/api/SpiQuery.java

@@ -296,6 +296,14 @@ public interface SpiQuery<T> extends Query<T> {
    */
   void setLoadDescription(String loadMode, String loadDescription);
 
+  /**
+   * Check that the named parameters have had their values set.
+   */
+  void checkNamedParameters();
+
+  /**
+   * Create a named parameter placeholder.
+   */
   SpiNamedParam createNamedParameter(String parameterName);
 
   /**

src/main/java/com/avaje/ebeaninternal/server/core/DefaultServer.java

@@ -40,6 +40,7 @@ import com.avaje.ebeaninternal.server.deploy.BeanDescriptorManager;
 import com.avaje.ebeaninternal.server.deploy.BeanProperty;
 import com.avaje.ebeaninternal.server.deploy.InheritInfo;
 import com.avaje.ebeaninternal.server.el.ElFilter;
+import com.avaje.ebeaninternal.server.grammer.EqlParser;
 import com.avaje.ebeaninternal.server.lib.ShutdownManager;
 import com.avaje.ebeaninternal.server.query.CQuery;
 import com.avaje.ebeaninternal.server.query.CQueryEngine;
@@ -902,6 +903,14 @@ public final class DefaultServer implements SpiServer, SpiEbeanServer {
     throw new PersistenceException("No named query called " + namedQuery + " for bean:" + beanType.getName());
   }
 
+  @Override
+  public <T> Query<T> createQuery(Class<T> beanType, String eql) {
+
+    DefaultOrmQuery<T> query = createQuery(beanType);
+    EqlParser.parse(eql, query);
+    return query;
+  }
+
   public <T> DefaultOrmQuery<T> createQuery(Class<T> beanType) {
     BeanDescriptor<T> desc = getBeanDescriptor(beanType);
     if (desc == null) {
@@ -954,6 +963,7 @@ public final class DefaultServer implements SpiServer, SpiEbeanServer {
 
     SpiQuery<T> spiQuery = (SpiQuery<T>) query;
     spiQuery.setType(type);
+    spiQuery.checkNamedParameters();
 
     return createQueryRequest(spiQuery, t);
   }

src/main/java/com/avaje/ebeaninternal/server/grammer/EqlParser.java

@@ -7,8 +7,14 @@ import org.antlr.v4.runtime.ANTLRInputStream;
 import org.antlr.v4.runtime.CommonTokenStream;
 import org.antlr.v4.runtime.tree.ParseTreeWalker;
 
+/**
+ * Parse EQL query language applying it to an ORM query object.
+ */
 public class EqlParser {
 
+  /**
+   * Parse the raw EQL query and apply it to the supplied query.
+   */
   public static <T> void parse(String raw, SpiQuery<T> query) {
 
     EQLLexer lexer = new EQLLexer(new ANTLRInputStream(raw));

src/main/java/com/avaje/ebeaninternal/server/querydefn/DefaultOrmQuery.java

@@ -29,6 +29,7 @@ import com.avaje.ebeaninternal.server.query.CancelableQuery;
 
 import java.sql.Timestamp;
 import java.util.ArrayList;
+import java.util.Collection;
 import java.util.HashMap;
 import java.util.Iterator;
 import java.util.List;
@@ -1395,6 +1396,16 @@ public class DefaultOrmQuery<T> implements SpiQuery<T> {
     this.generatedSql = generatedSql;
   }
 
+  @Override
+  public void checkNamedParameters() {
+    if (namedParams != null) {
+      Collection<ONamedParam> values = namedParams.values();
+      for (ONamedParam value : values) {
+        value.checkValueSet();
+      }
+    }
+  }
+
   @Override
   public SpiNamedParam createNamedParameter(String name) {
     if (namedParams == null) {

src/main/java/com/avaje/ebeaninternal/server/querydefn/ONamedParam.java

@@ -2,21 +2,44 @@ package com.avaje.ebeaninternal.server.querydefn;
 
 import com.avaje.ebeaninternal.api.SpiNamedParam;
 
+import javax.persistence.PersistenceException;
+
+/**
+ * Named parameter used as placeholder in expressions created by EQL language parsing.
+ */
 public class ONamedParam implements SpiNamedParam {
 
   private final String name;
 
   private Object value;
 
+  /**
+   * Create with the given name.
+   */
   public ONamedParam(String name) {
     this.name = name;
   }
 
+  /**
+   * Set the bind value for this named parameter.
+   */
   public void setValue(Object value) {
     this.value = value;
   }
 
+  /**
+   * Return the bind value for this named parameter.
+   */
   public Object getValue() {
     return value;
   }
+
+  /**
+   * Check the bind value has been set (so does not support null value).
+   */
+  public void checkValueSet() {
+    if (value == null) {
+      throw new PersistenceException("Named parameter ["+name+"] has not had it's value set.");
+    }
+  }
 }