[maven-release-plugin] prepare release ebean-parent-12.11.0

Refactor io.ebean.meta API, method rename with deprecation

.gitignore

@@ -1,6 +1,4 @@
 *.autofetch
-*create-all.sql
-*drop-all.sql
 *.orig
 .classpath
 .project
@@ -12,7 +10,6 @@ ebean-autotune.xml
 ebean-profiling*.xml
 /db
 /mydb.db
-!src/test/ddl-review/*.sql
 profiling/
 
 # Intellij project files
@@ -20,4 +17,4 @@ profiling/
 *.ipr
 *.iws
 .idea/
-*uuid.state
+*uuid.state

.travis/print_surefire_reports

@@ -7,4 +7,11 @@ do
     echo ${file}
     cat ${file}
     echo
-done
+done
+
+for file in ebean-autotune/target/surefire-reports/*.txt
+do
+    echo ${file}
+    cat ${file}
+    echo
+done

CONFIGURATION.md

@@ -293,6 +293,6 @@ ebean.tenant.schemaProvider
 ebean.updateAllPropertiesInBatch
 ebean.updateChangesOnly
 ebean.updatesDeleteMissingChildren
-ebean.useJavaxValidationNotNull
+ebean.useValidationNotNull
 ebean.useJtaTransactionManager
 

ebean-api/pom.xml

@@ -0,0 +1,124 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <artifactId>ebean-parent</artifactId>
+    <groupId>io.ebean</groupId>
+    <version>12.11.0</version>
+  </parent>
+
+  <name>ebean api</name>
+  <description>ebean api</description>
+  <artifactId>ebean-api</artifactId>
+
+  <dependencies>
+
+    <!--
+    Projects are expected to explicit depend on version
+    of slf4j that they want to use
+    -->
+    <dependency>
+      <groupId>org.slf4j</groupId>
+      <artifactId>slf4j-api</artifactId>
+      <version>1.7.30</version>
+      <scope>provided</scope>
+    </dependency>
+
+    <dependency>
+      <groupId>io.avaje</groupId>
+      <artifactId>avaje-config</artifactId>
+      <version>1.3</version>
+    </dependency>
+
+    <!--
+    Class retention Nonnull and Nullable annotations
+    to assist with IDE auto-completion with Ebean API
+    -->
+    <dependency>
+      <groupId>io.avaje</groupId>
+      <artifactId>avaje-jsr305</artifactId>
+      <version>1.0</version>
+      <scope>provided</scope>
+    </dependency>
+
+    <dependency>
+      <groupId>io.ebean</groupId>
+      <artifactId>persistence-api</artifactId>
+      <version>2.2.4</version>
+    </dependency>
+
+    <dependency>
+      <groupId>io.ebean</groupId>
+      <artifactId>ebean-annotation</artifactId>
+      <version>7.2</version>
+    </dependency>
+
+    <dependency>
+      <groupId>io.ebean</groupId>
+      <artifactId>ebean-types</artifactId>
+      <version>2.1</version>
+    </dependency>
+
+    <dependency>
+      <groupId>io.ebean</groupId>
+      <artifactId>ebean-datasource-api</artifactId>
+      <version>${ebean-datasource.version}</version>
+    </dependency>
+
+    <!-- Jackson core used internally by Ebean -->
+    <dependency>
+      <groupId>com.fasterxml.jackson.core</groupId>
+      <artifactId>jackson-core</artifactId>
+      <version>${jackson.version}</version>
+      <optional>true</optional>
+    </dependency>
+
+    <!-- provided scope for JsonNode support -->
+    <dependency>
+      <groupId>com.fasterxml.jackson.core</groupId>
+      <artifactId>jackson-databind</artifactId>
+      <version>${jackson.version}</version>
+      <optional>true</optional>
+    </dependency>
+
+    <!-- Provided scope so that the H2HistoryTrigger can live in Ebean core
+     and not require a separate module for it -->
+    <dependency>
+      <groupId>com.h2database</groupId>
+      <artifactId>h2</artifactId>
+      <version>1.4.199</version>
+      <optional>true</optional>
+    </dependency>
+
+    <dependency>
+      <groupId>javax.transaction</groupId>
+      <artifactId>jta</artifactId>
+      <version>1.1</version>
+      <optional>true</optional>
+    </dependency>
+
+    <dependency>
+      <groupId>javax.servlet</groupId>
+      <artifactId>javax.servlet-api</artifactId>
+      <version>3.1.0</version>
+      <optional>true</optional>
+    </dependency>
+
+  </dependencies>
+
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-jar-plugin</artifactId>
+        <version>2.5</version>
+        <configuration>
+          <archive>
+            <manifestFile>src/main/resources/META-INF/MANIFEST.MF</manifestFile>
+          </archive>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
+
+</project>

ebean-api/src/main/java/io/ebean/BackgroundExecutor.java

@@ -0,0 +1,109 @@
+package io.ebean;
+
+import java.util.concurrent.Callable;
+import java.util.concurrent.Future;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.ScheduledFuture;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * Background executor service for executing of tasks asynchronously.
+ * <p>
+ * This service can be used to execute tasks in the background.
+ * <p>
+ * This service is managed by Ebean and will perform a clean shutdown
+ * waiting for background tasks to complete with a default 30 second
+ * timeout. Shutdown occurs prior to DataSource shutdown.
+ * <p>
+ * This also propagates MDC context from the current thread to the
+ * background task if defined.
+ */
+public interface BackgroundExecutor {
+
+  /**
+   * Execute a callable task in the background returning the Future.
+   */
+  <T> Future<T> submit(Callable<T> task);
+
+  /**
+   * Execute a runnable task in the background returning the Future.
+   */
+  Future<?> submit(Runnable task);
+
+  /**
+   * Execute a task in the background. Effectively the same as
+   * {@link BackgroundExecutor#submit(Runnable)} but returns void.
+   */
+  void execute(Runnable task);
+
+  /**
+   * Deprecated - migrate to scheduleWithFixedDelay().
+   * Execute a task periodically with a fixed delay between each execution.
+   * <p>
+   * For example, execute a runnable every minute.
+   * <p>
+   * The delay is the time between executions no matter how long the task took.
+   * That is, this method has the same behaviour characteristics as
+   * {@link ScheduledExecutorService#scheduleWithFixedDelay(Runnable, long, long, TimeUnit)}
+   */
+  @Deprecated
+  void executePeriodically(Runnable task, long delay, TimeUnit unit);
+
+  /**
+   * Deprecated - migrate to scheduleWithFixedDelay().
+   * Execute a task periodically additionally with an initial delay different from delay.
+   */
+  @Deprecated
+  void executePeriodically(Runnable task, long initialDelay, long delay, TimeUnit unit);
+
+  /**
+   * Execute a task periodically with a given delay.
+   *
+   * @param task         the task to execute
+   * @param initialDelay the time to delay first execution
+   * @param delay        the delay between the termination of one
+   *                     execution and the commencement of the next
+   * @param unit         the time unit of the initialDelay and delay parameters
+   * @return a ScheduledFuture representing pending completion of
+   * the series of repeated tasks.  The future's {@link
+   * Future#get() get()} method will never return normally,
+   * and will throw an exception upon task cancellation or
+   * abnormal termination of a task execution.
+   */
+  ScheduledFuture<?> scheduleWithFixedDelay(Runnable task, long initialDelay, long delay, TimeUnit unit);
+
+  /**
+   * Execute a task periodically with a given period.
+   *
+   * <p>If any execution of this task takes longer than its period, then
+   * subsequent executions may start late, but will not concurrently
+   * execute.
+   *
+   * @param task         the task to execute
+   * @param initialDelay the time to delay first execution
+   * @param period       the period between successive executions
+   * @param unit         the time unit of the initialDelay and period parameters
+   * @return a ScheduledFuture representing pending completion of
+   * the series of repeated tasks.  The future's {@link
+   * Future#get() get()} method will never return normally,
+   * and will throw an exception upon task cancellation or
+   * abnormal termination of a task execution.
+   */
+  ScheduledFuture<?> scheduleAtFixedRate(Runnable task, long initialDelay, long period, TimeUnit unit);
+
+  /**
+   * Schedules a Runnable for one-shot action that becomes enabled after the given delay.
+   *
+   * @return a ScheduledFuture representing pending completion of the task and
+   * whose get() method will return null upon completion
+   */
+  ScheduledFuture<?> schedule(Runnable task, long delay, TimeUnit unit);
+
+  /**
+   * Schedules a Callable for one-shot action that becomes enabled after the given delay.
+   *
+   * @return a ScheduledFuture that can be used to extract result or cancel
+   */
+  <V> ScheduledFuture<V> schedule(Callable<V> task, long delay, TimeUnit unit);
+
+}

ebean-api/src/main/java/io/ebean/CancelableQuery.java

@@ -0,0 +1,19 @@
+package io.ebean;
+
+/**
+ * Defines a cancelable query.
+ * <p>
+ * Typically holds a representation of the PreparedStatement to perform the
+ * actual cancel.
+ * </p>
+ */
+public interface CancelableQuery {
+
+  /**
+   * Cancel the query.
+   * <p>
+   * For JDBC this translates to calling cancel on the PreparedStatement.
+   * </p>
+   */
+  void cancel();
+}

ebean-api/src/main/java/io/ebean/DB.java

@@ -60,7 +60,9 @@ import java.util.concurrent.Callable;
  *
  * }</pre>
  */
-public class DB {
+public final class DB {
+
+  private static final DbContext context = DbContext.getInstance();
 
   /**
    * Hide constructor.
@@ -68,11 +70,18 @@ public class DB {
   private DB() {
   }
 
+  /**
+   * Backdoor for registering a mock implementation of Database as the default database.
+   */
+  protected static Database mock(String name, Database server, boolean defaultServer) {
+    return context.mock(name, server, defaultServer);
+  }
+
   /**
    * Return the default database.
    */
   public static Database getDefault() {
-    return Ebean.getDefaultServer();
+    return context.getDefault();
   }
 
   /**
@@ -81,25 +90,24 @@ public class DB {
    * @param name The name of the database
    */
   public static Database byName(String name) {
-    return Ebean.getServer(name);
+    return context.get(name);
   }
 
-//  /**
-//   * Register the server with this Ebean singleton. Specify if the registered
-//   * server is the primary/default database.
-//   */
-//  public static void register(EbeanServer server, boolean defaultServer) {
-//    serverMgr.register(server, defaultServer);
-//  }
-//
-//  /**
-//   * Backdoor for registering a mock implementation of EbeanServer as the default database.
-//   */
-//  protected static EbeanServer mock(String name, EbeanServer server, boolean defaultServer) {
-//    EbeanServer originalPrimaryServer = serverMgr.defaultServer;
-//    serverMgr.registerWithName(name, server, defaultServer);
-//    return originalPrimaryServer;
-//  }
+  /**
+   * Return the ScriptRunner for the default database.
+   * <p>
+   * Useful to run SQL scripts that are resources. For example a test script
+   * for inserting seed data for a particular test.
+   *
+   * <pre>{@code
+   *
+   *   DB.script().run("/scripts/test-script.sql")
+   *
+   * }</pre>
+   */
+  public static ScriptRunner script() {
+    return getDefault().script();
+  }
 
   /**
    * Return the ExpressionFactory from the default database.

ebean-api/src/main/java/io/ebean/Database.java

@@ -1,5 +1,6 @@
 package io.ebean;
 
+import io.ebean.annotation.Platform;
 import io.ebean.annotation.TxIsolation;
 import io.ebean.cache.ServerCacheManager;
 import io.ebean.config.DatabaseConfig;
@@ -13,6 +14,7 @@ import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 import javax.persistence.OptimisticLockException;
 import javax.persistence.PersistenceException;
+import javax.sql.DataSource;
 import java.util.Collection;
 import java.util.List;
 import java.util.Map;
@@ -92,6 +94,11 @@ import java.util.concurrent.Callable;
  */
 public interface Database {
 
+  /**
+   * Shutdown the Database instance.
+   */
+  void shutdown();
+
   /**
    * Shutdown the Database instance programmatically.
    * <p>
@@ -115,6 +122,16 @@ public interface Database {
    */
   AutoTune getAutoTune();
 
+  /**
+   * Return the associated DataSource for this Database instance.
+   */
+  DataSource getDataSource();
+
+  /**
+   * Return the associated read only DataSource for this Database instance (can be null).
+   */
+  DataSource getReadOnlyDataSource();
+
   /**
    * Return the name. This is used with {@link DB#byName(String)} to get a
    * Database that was registered with the DB singleton.
@@ -132,6 +149,25 @@ public interface Database {
    */
   MetaInfoManager getMetaInfoManager();
 
+  /**
+   * Return the platform used for this database instance.
+   * <p>
+   * Note many platforms have multiple specific platform types so often we want to
+   * get the base platform via {@link Platform#base()}.
+   * </p>
+   * <pre>{@code
+   *
+   *  Platform platform = database.getPlatform().base();
+   *  if (platform == Platform.MYSQL) {
+   *    // do MySql specific function
+   *  }
+   *
+   * }</pre>
+   *
+   * @return platform for this database instance
+   */
+  Platform getPlatform();
+
   /**
    * Return the extended API intended for use by plugins.
    */

ebean-api/src/main/java/io/ebean/DatabaseFactory.java

@@ -0,0 +1,164 @@
+package io.ebean;
+
+import io.ebean.config.ContainerConfig;
+import io.ebean.config.DatabaseConfig;
+import io.ebean.service.SpiContainer;
+import io.ebean.service.SpiContainerFactory;
+
+import javax.persistence.PersistenceException;
+import java.util.Iterator;
+import java.util.Properties;
+import java.util.ServiceLoader;
+import java.util.concurrent.locks.ReentrantLock;
+
+/**
+ * Creates Database instances.
+ * <p>
+ * This uses either DatabaseConfig or properties in the application.properties file to
+ * configure and create a Database instance.
+ * </p>
+ * <p>
+ * The Database instance can either be registered with the DB singleton or
+ * not. The DB singleton effectively holds a map of Database by a name.
+ * If the Database is registered with the DB singleton you can retrieve it
+ * later via {@link DB#byName(String)}.
+ * </p>
+ * <p>
+ * One Database can be nominated as the 'default/primary' Database. Many
+ * methods on the DB singleton such as {@link DB#find(Class)} are just a
+ * convenient way of using the 'default/primary' Database.
+ * </p>
+ */
+public class DatabaseFactory {
+
+  private static final ReentrantLock lock = new ReentrantLock();
+  private static SpiContainer container;
+  private static String defaultServerName;
+
+  static {
+    EbeanVersion.getVersion();
+  }
+
+  /**
+   * Initialise the container with clustering configuration.
+   * <p>
+   * Call this prior to creating any Database instances or alternatively set the
+   * ContainerConfig on the DatabaseConfig when creating the first Database instance.
+   */
+  public static void initialiseContainer(ContainerConfig containerConfig) {
+    lock.lock();
+    try {
+      getContainer(containerConfig);
+    } finally {
+      lock.unlock();
+    }
+  }
+
+  /**
+   * Create using properties to configure the database.
+   */
+  public static Database create(String name) {
+    lock.lock();
+    try {
+      return getContainer(null).createServer(name);
+    } finally {
+      lock.unlock();
+    }
+  }
+
+  /**
+   * Create using the DatabaseConfig object to configure the database.
+   */
+  public static Database create(DatabaseConfig config) {
+    lock.lock();
+    try {
+      if (config.getName() == null) {
+        throw new PersistenceException("The name is null (it is required)");
+      }
+      Database server = createInternal(config);
+      if (config.isRegister()) {
+        if (config.isDefaultServer()) {
+          if (defaultServerName != null && !defaultServerName.equals(config.getName())) {
+            throw new IllegalStateException("Registering [" + config.getName() + "] as the default server but [" + defaultServerName + "] is already registered as the default");
+          }
+          defaultServerName = config.getName();
+        }
+        DbPrimary.setSkip(true);
+        DbContext.getInstance().register(server, config.isDefaultServer());
+      }
+      return server;
+    } finally {
+      lock.unlock();
+    }
+  }
+
+  /**
+   * Create using the DatabaseConfig additionally specifying a classLoader to use as the context class loader.
+   */
+  public static Database createWithContextClassLoader(DatabaseConfig config, ClassLoader classLoader) {
+    lock.lock();
+    try {
+      ClassLoader currentContextLoader = Thread.currentThread().getContextClassLoader();
+      Thread.currentThread().setContextClassLoader(classLoader);
+      try {
+        return DatabaseFactory.create(config);
+      } finally {
+        // set the currentContextLoader back
+        Thread.currentThread().setContextClassLoader(currentContextLoader);
+      }
+    } finally {
+      lock.unlock();
+    }
+  }
+
+  /**
+   * Shutdown gracefully all Database instances cleaning up any resources as required.
+   * <p>
+   * This is typically invoked via JVM shutdown hook and not explicitly called.
+   * </p>
+   */
+  public static void shutdown() {
+    lock.lock();
+    try {
+      container.shutdown();
+    } finally {
+      lock.unlock();
+    }
+  }
+
+  private static Database createInternal(DatabaseConfig config) {
+    return getContainer(config.getContainerConfig()).createServer(config);
+  }
+
+  /**
+   * Get the EbeanContainer initialising it if necessary.
+   *
+   * @param containerConfig the configuration controlling clustering communication
+   */
+  private static SpiContainer getContainer(ContainerConfig containerConfig) {
+    // thread safe in that all calling methods hold lock
+    if (container != null) {
+      return container;
+    }
+
+    if (containerConfig == null) {
+      // effectively load configuration from ebean.properties
+      Properties properties = DbPrimary.getProperties();
+      containerConfig = new ContainerConfig();
+      containerConfig.loadFromProperties(properties);
+    }
+    container = createContainer(containerConfig);
+    return container;
+  }
+
+  /**
+   * Create the container instance using the configuration.
+   */
+  protected static SpiContainer createContainer(ContainerConfig containerConfig) {
+    Iterator<SpiContainerFactory> factories = ServiceLoader.load(SpiContainerFactory.class).iterator();
+    if (factories.hasNext()) {
+      return factories.next().create(containerConfig);
+    }
+    throw new IllegalStateException("Service loader didn't find a SpiContainerFactory?");
+  }
+}

ebean-api/src/main/java/io/ebean/DbContext.java

@@ -0,0 +1,139 @@
+package io.ebean;
+
+import io.ebean.config.BeanNotEnhancedException;
+import io.ebean.datasource.DataSourceConfigurationException;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import javax.persistence.PersistenceException;
+import java.util.HashMap;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.locks.ReentrantLock;
+
+/**
+ * Holds Database instances.
+ */
+final class DbContext {
+
+  private static final Logger logger = LoggerFactory.getLogger(DbContext.class);
+
+  static {
+    EbeanVersion.getVersion();
+  }
+
+  private static final DbContext INSTANCE = new DbContext();
+
+  private final ConcurrentHashMap<String, Database> concMap = new ConcurrentHashMap<>();
+
+  private final HashMap<String, Database> syncMap = new HashMap<>();
+
+  private final ReentrantLock lock = new ReentrantLock();
+
+  /**
+   * The 'default' Database.
+   */
+  private Database defaultDatabase;
+
+  private DbContext() {
+    try {
+      if (!DbPrimary.isSkip()) {
+        // look to see if there is a default server defined
+        String defaultName = DbPrimary.getDefaultServerName();
+        logger.debug("defaultName:{}", defaultName);
+        if (defaultName != null && !defaultName.trim().isEmpty()) {
+          defaultDatabase = getWithCreate(defaultName.trim());
+        }
+      }
+    } catch (BeanNotEnhancedException e) {
+      throw e;
+
+    } catch (DataSourceConfigurationException e) {
+      String msg = "Configuration error creating DataSource for the default Database." +
+        " This typically means a missing application-test.yaml or missing ebean-test dependency." +
+        " See https://ebean.io/docs/trouble-shooting#datasource";
+      throw new DataSourceConfigurationException(msg, e);
+
+    } catch (Throwable e) {
+      logger.error("Error trying to create the default Database", e);
+      throw new RuntimeException(e);
+    }
+  }
+
+  /**
+   * Return the shared singleton instance.
+   */
+  static DbContext getInstance() {
+    return INSTANCE;
+  }
+
+  /**
+   * Return the default database.
+   */
+  Database getDefault() {
+    if (defaultDatabase == null) {
+      String msg = "The default Database has not been defined?";
+      msg += " This is normally set via the ebean.datasource.default property.";
+      msg += " Otherwise it should be registered programmatically via registerServer()";
+      throw new PersistenceException(msg);
+    }
+    return defaultDatabase;
+  }
+
+  /**
+   * Return the database by name.
+   */
+  Database get(String name) {
+    if (name == null || name.isEmpty()) {
+      return defaultDatabase;
+    }
+    Database server = concMap.get(name);
+    if (server != null) {
+      return server;
+    }
+    return getWithCreate(name);
+  }
+
+  /**
+   * Read, create and put of Databases.
+   */
+  private Database getWithCreate(String name) {
+    lock.lock();
+    try {
+      Database server = syncMap.get(name);
+      if (server == null) {
+        // register when creating server this way
+        server = DatabaseFactory.create(name);
+        register(server, false);
+      }
+      return server;
+    } finally {
+      lock.unlock();
+    }
+  }
+
+  /**
+   * Register a server so we can get it by its name.
+   */
+  void register(Database server, boolean isDefault) {
+    registerWithName(server.getName(), server, isDefault);
+  }
+
+  private void registerWithName(String name, Database server, boolean isDefault) {
+    lock.lock();
+    try {
+      concMap.put(name, server);
+      syncMap.put(name, server);
+      if (isDefault) {
+        defaultDatabase = server;
+      }
+    } finally {
+      lock.unlock();
+    }
+  }
+
+  Database mock(String name, Database server, boolean defaultServer) {
+    Database originalPrimaryServer = this.defaultDatabase;
+    registerWithName(name, server, defaultServer);
+    return originalPrimaryServer;
+  }
+}

ebean-api/src/main/java/io/ebean/DbPrimary.java

@@ -3,55 +3,75 @@ package io.ebean;
 import io.avaje.config.Config;
 
 import java.util.Properties;
+import java.util.concurrent.locks.ReentrantLock;
 
 /**
  * Provides singleton state for the default database.
  * <p/>
  * Intended for internal use as part of bootup, construction, registration of the default database.
  */
-class PrimaryServer {
+class DbPrimary {
 
+  private static final ReentrantLock lock = new ReentrantLock();
   private static String defaultServerName;
-
   private static boolean skip;
 
   /**
    * Set whether to skip automatically creating the primary database.
    */
-  static synchronized void setSkip(boolean skip) {
-    PrimaryServer.skip = skip;
+  static void setSkip(boolean skip) {
+    lock.lock();
+    try {
+      DbPrimary.skip = skip;
+    } finally {
+      lock.unlock();
+    }
   }
 
   /**
    * Return true to skip automatically creating the primary database.
    */
-  static synchronized boolean isSkip() {
-    return skip;
+  static boolean isSkip() {
+    lock.lock();
+    try {
+      return skip;
+    } finally {
+      lock.unlock();
+    }
   }
 
   /**
    * Return the default database name.
    */
-  static synchronized String getDefaultServerName() {
-    getProperties();
-    return defaultServerName;
+  static String getDefaultServerName() {
+    lock.lock();
+    try {
+      getProperties();
+      return defaultServerName;
+    } finally {
+      lock.unlock();
+    }
   }
 
   /**
    * Return the default configuration Properties.
    */
-  static synchronized Properties getProperties() {
-    if (defaultServerName == null) {
-      defaultServerName = determineDefaultServerName();
+  static Properties getProperties() {
+    lock.lock();
+    try {
+      if (defaultServerName == null) {
+        defaultServerName = determineDefaultServerName();
+      }
+      return Config.asProperties();
+    } finally {
+      lock.unlock();
     }
-    return Config.asProperties();
   }
 
   /**
    * Determine and return the default server name checking system environment variables and then global properties.
    */
   private static String determineDefaultServerName() {
-
     String defaultServerName = System.getenv("EBEAN_DB");
     defaultServerName = System.getProperty("db", defaultServerName);
     defaultServerName = System.getProperty("ebean_db", defaultServerName);

ebean-api/src/main/java/io/ebean/DocumentStore.java

@@ -1,9 +1,9 @@
 package io.ebean;
 
-import io.ebeanservice.docstore.api.DocQueryRequest;
-import io.ebeanservice.docstore.api.RawDoc;
-import javax.annotation.Nullable;
+import io.ebean.docstore.DocQueryContext;
+import io.ebean.docstore.RawDoc;
 
+import javax.annotation.Nullable;
 import java.io.IOException;
 import java.util.List;
 import java.util.Map;
@@ -69,7 +69,7 @@ public interface DocumentStore {
    * }</pre>
    */
   @Nullable
-  <T> T find(DocQueryRequest<T> request);
+  <T> T find(DocQueryContext<T> request);
 
   /**
    * Execute the find list query. This request is prepared to execute secondary queries.
@@ -86,7 +86,7 @@ public interface DocumentStore {
    *
    * }</pre>
    */
-  <T> List<T> findList(DocQueryRequest<T> request);
+  <T> List<T> findList(DocQueryContext<T> request);
 
   /**
    * Execute the query against the document store returning the paged list.
@@ -107,7 +107,7 @@ public interface DocumentStore {
    *
    * }</pre>
    */
-  <T> PagedList<T> findPagedList(DocQueryRequest<T> request);
+  <T> PagedList<T> findPagedList(DocQueryContext<T> request);
 
   /**
    * Execute the query against the document store with the expectation of a large set of results
@@ -129,7 +129,7 @@ public interface DocumentStore {
    *
    * }</pre>
    */
-  <T> void findEach(DocQueryRequest<T> query, Consumer<T> consumer);
+  <T> void findEach(DocQueryContext<T> query, Consumer<T> consumer);
 
   /**
    * Execute the query against the document store with the expectation of a large set of results
@@ -161,7 +161,7 @@ public interface DocumentStore {
    *
    * }</pre>
    */
-  <T> void findEachWhile(DocQueryRequest<T> query, Predicate<T> consumer);
+  <T> void findEachWhile(DocQueryContext<T> query, Predicate<T> consumer);
 
   /**
    * Find each processing raw documents.

ebean-api/src/main/java/io/ebean/DtoQuery.java

@@ -6,6 +6,7 @@ import java.util.List;
 import java.util.Optional;
 import java.util.function.Consumer;
 import java.util.function.Predicate;
+import java.util.stream.Stream;
 
 /**
  * Query for performing native SQL queries that return DTO Bean's.
@@ -37,7 +38,7 @@ import java.util.function.Predicate;
  *
  * }</pre>
  */
-public interface DtoQuery<T> {
+public interface DtoQuery<T> extends CancelableQuery {
 
   /**
    * Execute the query returning a list.
@@ -45,6 +46,26 @@ public interface DtoQuery<T> {
   @Nonnull
   List<T> findList();
 
+  /**
+   * Execute the query iterating a row at a time.
+   * <p>
+   * Note that the QueryIterator holds resources related to the underlying
+   * resultSet and potentially connection and MUST be closed. We should use
+   * QueryIterator in a <em>try with resource block</em>.
+   */
+  @Nonnull
+  QueryIterator<T> findIterate();
+
+  /**
+   * Execute the query returning a Stream.
+   * <p>
+   * Note that the Stream holds resources related to the underlying
+   * resultSet and potentially connection and MUST be closed. We should use
+   * the Stream in a <em>try with resource block</em>.
+   */
+  @Nonnull
+  Stream<T> findStream();
+
   /**
    * Execute the query iterating a row at a time.
    * <p>
@@ -53,6 +74,17 @@ public interface DtoQuery<T> {
    */
   void findEach(Consumer<T> consumer);
 
+  /**
+   * Execute the query iterating the results and batching them for the consumer.
+   * <p>
+   * This runs like findEach streaming results from the database but just collects the results
+   * into batches to pass to the consumer.
+   *
+   * @param batch    The number of dto beans to collect before given them to the consumer
+   * @param consumer The consumer to process the batch of DTO beans
+   */
+  void findEach(int batch, Consumer<List<T>> consumer);
+
   /**
    * Execute the query iterating a row at a time with the ability to stop consuming part way through.
    * <p>

ebean-api/src/main/java/io/ebean/Ebean.java

@@ -2,29 +2,22 @@ package io.ebean;
 
 import io.ebean.annotation.TxIsolation;
 import io.ebean.cache.ServerCacheManager;
-import io.ebean.config.BeanNotEnhancedException;
-import io.ebean.config.ServerConfig;
-import io.ebean.datasource.DataSourceConfigurationException;
 import io.ebean.plugin.Property;
 import io.ebean.text.csv.CsvReader;
 import io.ebean.text.json.JsonContext;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
 
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 import javax.persistence.OptimisticLockException;
 import javax.persistence.PersistenceException;
 import java.util.Collection;
-import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
 import java.util.concurrent.Callable;
-import java.util.concurrent.ConcurrentHashMap;
 
 /**
- * Ebean will be Deprecated - please migrate to use DB.
+ * Deprecated - please migrate to use <code>io.ebean.DB</code>.
  * <p>
  * Ebean is a registry of {@link Database} by name. Ebean has now been renamed to {@link DB}.
  * <p>
@@ -32,124 +25,10 @@ import java.util.concurrent.ConcurrentHashMap;
  * <p>
  * The preference is to use DB and Database rather than Ebean and EbeanServer.
  */
+@Deprecated
 public final class Ebean {
-  private static final Logger logger = LoggerFactory.getLogger(Ebean.class);
 
-  static {
-    EbeanVersion.getVersion(); // initialises the version class and logs the version.
-  }
-
-  /**
-   * Manages creation and cache of Databases.
-   */
-  private static final Ebean.ServerManager serverMgr = new Ebean.ServerManager();
-
-  /**
-   * Helper class for managing fast and safe access and creation of Databases.
-   */
-  private static final class ServerManager {
-
-    /**
-     * Cache for fast concurrent read access.
-     */
-    private final ConcurrentHashMap<String, EbeanServer> concMap = new ConcurrentHashMap<>();
-
-    /**
-     * Cache for synchronized read, creation and put. Protected by the monitor object.
-     */
-    private final HashMap<String, EbeanServer> syncMap = new HashMap<>();
-
-    private final Object monitor = new Object();
-
-    /**
-     * The 'default' Database.
-     */
-    private EbeanServer defaultServer;
-
-    private ServerManager() {
-
-      try {
-        if (!PrimaryServer.isSkip()) {
-          // look to see if there is a default server defined
-          String defaultName = PrimaryServer.getDefaultServerName();
-          logger.debug("defaultName:{}", defaultName);
-          if (defaultName != null && !defaultName.trim().isEmpty()) {
-            defaultServer = getWithCreate(defaultName.trim());
-          }
-        }
-      } catch (BeanNotEnhancedException e) {
-        throw e;
-
-      } catch (DataSourceConfigurationException e) {
-        String msg = "Configuration error creating DataSource for the default Database." +
-          " This typically means a missing application-test.yaml or missing ebean-test dependency." +
-          " See https://ebean.io/docs/trouble-shooting#datasource";
-        throw new DataSourceConfigurationException(msg, e);
-
-      } catch (Throwable e) {
-        logger.error("Error trying to create the default Database", e);
-        throw new RuntimeException(e);
-      }
-    }
-
-    private EbeanServer getDefaultServer() {
-      if (defaultServer == null) {
-        String msg = "The default Database has not been defined?";
-        msg += " This is normally set via the ebean.datasource.default property.";
-        msg += " Otherwise it should be registered programmatically via registerServer()";
-        throw new PersistenceException(msg);
-      }
-      return defaultServer;
-    }
-
-    private EbeanServer get(String name) {
-      if (name == null || name.isEmpty()) {
-        return defaultServer;
-      }
-      // non-synchronized read
-      EbeanServer server = concMap.get(name);
-      if (server != null) {
-        return server;
-      }
-      // synchronized read, create and put
-      return getWithCreate(name);
-    }
-
-    /**
-     * Synchronized read, create and put of Databases.
-     */
-    private EbeanServer getWithCreate(String name) {
-
-      synchronized (monitor) {
-
-        EbeanServer server = syncMap.get(name);
-        if (server == null) {
-          // register when creating server this way
-          server = EbeanServerFactory.create(name);
-          register(server, false);
-        }
-        return server;
-      }
-    }
-
-    /**
-     * Register a server so we can get it by its name.
-     */
-    private void register(EbeanServer server, boolean isDefaultServer) {
-      registerWithName(server.getName(), server, isDefaultServer);
-    }
-
-    private void registerWithName(String name, EbeanServer server, boolean isDefaultServer) {
-      synchronized (monitor) {
-        concMap.put(name, server);
-        syncMap.put(name, server);
-        if (isDefaultServer) {
-          defaultServer = server;
-        }
-      }
-    }
-
-  }
+  private static final DbContext context = DbContext.getInstance();
 
   private Ebean() {
   }
@@ -173,7 +52,7 @@ public final class Ebean {
    * @param name the name of the server, can use null for the 'default server'
    */
   public static EbeanServer getServer(String name) {
-    return serverMgr.get(name);
+    return (EbeanServer)context.get(name);
   }
 
   /**
@@ -183,7 +62,27 @@ public final class Ebean {
    * </p>
    */
   public static EbeanServer getDefaultServer() {
-    return serverMgr.getDefaultServer();
+    return (EbeanServer)context.getDefault();
+  }
+
+  /**
+   * Register the server with this Ebean singleton. Specify if the registered
+   * server is the primary/default database.
+   */
+  @Deprecated
+  public static void register(EbeanServer server, boolean defaultServer) {
+    context.register(server, defaultServer);
+  }
+
+  /**
+   * Backdoor for registering a mock implementation of EbeanServer as the default database.
+   */
+  protected static EbeanServer mock(String name, EbeanServer server, boolean defaultServer) {
+    return (EbeanServer)context.mock(name, server, defaultServer);
+  }
+
+  private static Database getDefault() {
+    return context.getDefault();
   }
 
   /**
@@ -204,24 +103,7 @@ public final class Ebean {
    * </p>
    */
   public static ExpressionFactory getExpressionFactory() {
-    return serverMgr.getDefaultServer().getExpressionFactory();
-  }
-
-  /**
-   * Register the server with this Ebean singleton. Specify if the registered
-   * server is the primary/default database.
-   */
-  public static void register(EbeanServer server, boolean defaultServer) {
-    serverMgr.register(server, defaultServer);
-  }
-
-  /**
-   * Backdoor for registering a mock implementation of EbeanServer as the default database.
-   */
-  protected static EbeanServer mock(String name, EbeanServer server, boolean defaultServer) {
-    EbeanServer originalPrimaryServer = serverMgr.defaultServer;
-    serverMgr.registerWithName(name, server, defaultServer);
-    return originalPrimaryServer;
+    return getDefault().getExpressionFactory();
   }
 
   /**
@@ -237,7 +119,7 @@ public final class Ebean {
    * </p>
    */
   public static Object nextId(Class<?> beanType) {
-    return serverMgr.getDefaultServer().nextId(beanType);
+    return getDefault().nextId(beanType);
   }
 
   /**
@@ -283,7 +165,7 @@ public final class Ebean {
    * </p>
    */
   public static Transaction beginTransaction() {
-    return serverMgr.getDefaultServer().beginTransaction();
+    return getDefault().beginTransaction();
   }
 
   /**
@@ -292,7 +174,7 @@ public final class Ebean {
    * @param isolation the Transaction isolation level
    */
   public static Transaction beginTransaction(TxIsolation isolation) {
-    return serverMgr.getDefaultServer().beginTransaction(isolation);
+    return getDefault().beginTransaction(isolation);
   }
 
   /**
@@ -345,7 +227,7 @@ public final class Ebean {
    * }</pre>
    */
   public static Transaction beginTransaction(TxScope scope) {
-    return serverMgr.getDefaultServer().beginTransaction(scope);
+    return getDefault().beginTransaction(scope);
   }
 
   /**
@@ -353,7 +235,7 @@ public final class Ebean {
    * in scope.
    */
   public static Transaction currentTransaction() {
-    return serverMgr.getDefaultServer().currentTransaction();
+    return getDefault().currentTransaction();
   }
 
   /**
@@ -383,21 +265,21 @@ public final class Ebean {
    * @throws PersistenceException if there is no currently active transaction
    */
   public static void register(TransactionCallback transactionCallback) throws PersistenceException {
-    serverMgr.getDefaultServer().register(transactionCallback);
+    getDefault().register(transactionCallback);
   }
 
   /**
    * Commit the current transaction.
    */
   public static void commitTransaction() {
-    serverMgr.getDefaultServer().commitTransaction();
+    getDefault().commitTransaction();
   }
 
   /**
    * Rollback the current transaction.
    */
   public static void rollbackTransaction() {
-    serverMgr.getDefaultServer().rollbackTransaction();
+    getDefault().rollbackTransaction();
   }
 
   /**
@@ -425,14 +307,14 @@ public final class Ebean {
    * }</pre>
    */
   public static void endTransaction() {
-    serverMgr.getDefaultServer().endTransaction();
+    getDefault().endTransaction();
   }
 
   /**
    * Mark the current transaction as rollback only.
    */
   public static void setRollbackOnly() {
-    serverMgr.getDefaultServer().currentTransaction().setRollbackOnly();
+    getDefault().currentTransaction().setRollbackOnly();
   }
 
   /**
@@ -443,7 +325,7 @@ public final class Ebean {
    * </p>
    */
   public static Map<String, ValuePair> diff(Object a, Object b) {
-    return serverMgr.getDefaultServer().diff(a, b);
+    return getDefault().diff(a, b);
   }
 
   /**
@@ -477,7 +359,7 @@ public final class Ebean {
    * </p>
    */
   public static void save(Object bean) throws OptimisticLockException {
-    serverMgr.getDefaultServer().save(bean);
+    getDefault().save(bean);
   }
 
   /**
@@ -485,14 +367,14 @@ public final class Ebean {
    * want to explicitly insert it.
    */
   public static void insert(Object bean) {
-    serverMgr.getDefaultServer().insert(bean);
+    getDefault().insert(bean);
   }
 
   /**
    * Insert a collection of beans.
    */
   public static void insertAll(Collection<?> beans) {
-    serverMgr.getDefaultServer().insertAll(beans);
+    getDefault().insertAll(beans);
   }
 
   /**
@@ -515,7 +397,7 @@ public final class Ebean {
    * }</pre>
    */
   public static void markAsDirty(Object bean) throws OptimisticLockException {
-    serverMgr.getDefaultServer().markAsDirty(bean);
+    getDefault().markAsDirty(bean);
   }
 
   /**
@@ -530,16 +412,6 @@ public final class Ebean {
    * <b>Optimistic Locking: </b> Note that if the version property is not set when update() is
    * called then no optimistic locking is performed (internally ConcurrencyMode.NONE is used).
    * </p>
-   * <p>
-   * <b>{@link ServerConfig#setUpdatesDeleteMissingChildren(boolean)}: </b> When cascade saving to a
-   * OneToMany or ManyToMany the updatesDeleteMissingChildren setting controls if any other children
-   * that are in the database but are not in the collection are deleted.
-   * </p>
-   * <p>
-   * <b>{@link ServerConfig#setUpdateChangesOnly(boolean)}: </b> The updateChangesOnly setting
-   * controls if only the changed properties are included in the update or if all the loaded
-   * properties are included instead.
-   * </p>
    * <pre>{@code
    *
    *   // A 'stateless update' example
@@ -552,14 +424,14 @@ public final class Ebean {
    * }</pre>
    */
   public static void update(Object bean) throws OptimisticLockException {
-    serverMgr.getDefaultServer().update(bean);
+    getDefault().update(bean);
   }
 
   /**
    * Update the beans in the collection.
    */
   public static void updateAll(Collection<?> beans) throws OptimisticLockException {
-    serverMgr.getDefaultServer().updateAll(beans);
+    getDefault().updateAll(beans);
   }
 
   /**
@@ -568,7 +440,7 @@ public final class Ebean {
    * @param bean The bean to merge
    */
   public static void merge(Object bean) {
-    serverMgr.getDefaultServer().merge(bean);
+    getDefault().merge(bean);
   }
 
   /**
@@ -578,14 +450,14 @@ public final class Ebean {
    * @param options The options to control the merge
    */
   public static void merge(Object bean, MergeOptions options) {
-    serverMgr.getDefaultServer().merge(bean, options);
+    getDefault().merge(bean, options);
   }
 
   /**
    * Save all the beans from a Collection.
    */
   public static int saveAll(Collection<?> beans) throws OptimisticLockException {
-    return serverMgr.getDefaultServer().saveAll(beans);
+    return getDefault().saveAll(beans);
   }
 
   /**
@@ -636,7 +508,7 @@ public final class Ebean {
    */
   @Nonnull
   public static Set<Property> checkUniqueness(Object bean) {
-    return serverMgr.getDefaultServer().checkUniqueness(bean);
+    return getDefault().checkUniqueness(bean);
   }
 
   /**
@@ -644,7 +516,7 @@ public final class Ebean {
    */
   @Nonnull
   public static Set<Property> checkUniqueness(Object bean, Transaction transaction) {
-    return serverMgr.getDefaultServer().checkUniqueness(bean, transaction);
+    return getDefault().checkUniqueness(bean, transaction);
   }
 
   /**
@@ -667,56 +539,56 @@ public final class Ebean {
    * </p>
    */
   public static boolean delete(Object bean) throws OptimisticLockException {
-    return serverMgr.getDefaultServer().delete(bean);
+    return getDefault().delete(bean);
   }
 
   /**
    * Delete the bean in permanent fashion (will not use soft delete).
    */
   public static boolean deletePermanent(Object bean) throws OptimisticLockException {
-    return serverMgr.getDefaultServer().deletePermanent(bean);
+    return getDefault().deletePermanent(bean);
   }
 
   /**
    * Delete the bean given its type and id.
    */
   public static int delete(Class<?> beanType, Object id) {
-    return serverMgr.getDefaultServer().delete(beanType, id);
+    return getDefault().delete(beanType, id);
   }
 
   /**
    * Delete permanent the bean given its type and id.
    */
   public static int deletePermanent(Class<?> beanType, Object id) {
-    return serverMgr.getDefaultServer().deletePermanent(beanType, id);
+    return getDefault().deletePermanent(beanType, id);
   }
 
   /**
    * Delete several beans given their type and id values.
    */
   public static int deleteAll(Class<?> beanType, Collection<?> ids) {
-    return serverMgr.getDefaultServer().deleteAll(beanType, ids);
+    return getDefault().deleteAll(beanType, ids);
   }
 
   /**
    * Delete permanent several beans given their type and id values.
    */
   public static int deleteAllPermanent(Class<?> beanType, Collection<?> ids) {
-    return serverMgr.getDefaultServer().deleteAllPermanent(beanType, ids);
+    return getDefault().deleteAllPermanent(beanType, ids);
   }
 
   /**
    * Delete all the beans in the Collection.
    */
   public static int deleteAll(Collection<?> beans) throws OptimisticLockException {
-    return serverMgr.getDefaultServer().deleteAll(beans);
+    return getDefault().deleteAll(beans);
   }
 
   /**
    * Delete permanent all the beans in the Collection (will not use soft delete).
    */
   public static int deleteAllPermanent(Collection<?> beans) throws OptimisticLockException {
-    return serverMgr.getDefaultServer().deleteAllPermanent(beans);
+    return getDefault().deleteAllPermanent(beans);
   }
 
   /**
@@ -727,7 +599,7 @@ public final class Ebean {
    * </p>
    */
   public static void refresh(Object bean) {
-    serverMgr.getDefaultServer().refresh(bean);
+    getDefault().refresh(bean);
   }
 
   /**
@@ -745,7 +617,7 @@ public final class Ebean {
    * @param manyPropertyName the property name of the List Set or Map to refresh.
    */
   public static void refreshMany(Object bean, String manyPropertyName) {
-    serverMgr.getDefaultServer().refreshMany(bean, manyPropertyName);
+    getDefault().refreshMany(bean, manyPropertyName);
   }
 
   /**
@@ -770,7 +642,7 @@ public final class Ebean {
    * @param id       the id value
    */
   public static <T> T getReference(Class<T> beanType, Object id) {
-    return serverMgr.getDefaultServer().getReference(beanType, id);
+    return getDefault().getReference(beanType, id);
   }
 
   /**
@@ -813,7 +685,7 @@ public final class Ebean {
    * @param sortByClause the properties to sort the list by
    */
   public static <T> void sort(List<T> list, String sortByClause) {
-    serverMgr.getDefaultServer().sort(list, sortByClause);
+    getDefault().sort(list, sortByClause);
   }
 
   /**
@@ -863,7 +735,7 @@ public final class Ebean {
    */
   @Nullable
   public static <T> T find(Class<T> beanType, Object id) {
-    return serverMgr.getDefaultServer().find(beanType, id);
+    return getDefault().find(beanType, id);
   }
 
   /**
@@ -878,7 +750,7 @@ public final class Ebean {
    */
   @Deprecated
   public static SqlQuery createSqlQuery(String sql) {
-    return serverMgr.getDefaultServer().sqlQuery(sql);
+    return getDefault().sqlQuery(sql);
   }
 
   /**
@@ -893,7 +765,7 @@ public final class Ebean {
    */
   @Deprecated
   public static SqlUpdate createSqlUpdate(String sql) {
-    return serverMgr.getDefaultServer().sqlUpdate(sql);
+    return getDefault().sqlUpdate(sql);
   }
 
   /**
@@ -902,7 +774,7 @@ public final class Ebean {
    * @see CallableSql
    */
   public static CallableSql createCallableSql(String sql) {
-    return serverMgr.getDefaultServer().createCallableSql(sql);
+    return getDefault().createCallableSql(sql);
   }
 
   /**
@@ -934,16 +806,14 @@ public final class Ebean {
    * }</pre>
    */
   public static <T> Update<T> createUpdate(Class<T> beanType, String ormUpdate) {
-
-    return serverMgr.getDefaultServer().createUpdate(beanType, ormUpdate);
+    return getDefault().createUpdate(beanType, ormUpdate);
   }
 
   /**
    * Create a CsvReader for a given beanType.
    */
   public static <T> CsvReader<T> createCsvReader(Class<T> beanType) {
-
-    return serverMgr.getDefaultServer().createCsvReader(beanType);
+    return getDefault().createCsvReader(beanType);
   }
 
   /**
@@ -958,7 +828,7 @@ public final class Ebean {
    * @return The query
    */
   public static <T> Query<T> createNamedQuery(Class<T> beanType, String namedQuery) {
-    return serverMgr.getDefaultServer().createNamedQuery(beanType, namedQuery);
+    return getDefault().createNamedQuery(beanType, namedQuery);
   }
 
   /**
@@ -981,8 +851,7 @@ public final class Ebean {
    * @return A ORM Query object for this beanType
    */
   public static <T> Query<T> createQuery(Class<T> beanType) {
-
-    return serverMgr.getDefaultServer().createQuery(beanType);
+    return getDefault().createQuery(beanType);
   }
 
   /**
@@ -1019,8 +888,7 @@ public final class Ebean {
    * @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);
+    return getDefault().createQuery(beanType, eql);
   }
 
   /**
@@ -1035,8 +903,7 @@ public final class Ebean {
    * @return A ORM Query object for this beanType
    */
   public static <T> Query<T> find(Class<T> beanType) {
-
-    return serverMgr.getDefaultServer().find(beanType);
+    return getDefault().find(beanType);
   }
 
   /**
@@ -1059,7 +926,7 @@ public final class Ebean {
    * @return The query to set parameters and execute
    */
   public static <T> Query<T> findNative(Class<T> beanType, String nativeSql) {
-    return serverMgr.getDefaultServer().findNative(beanType, nativeSql);
+    return getDefault().findNative(beanType, nativeSql);
   }
 
   /**
@@ -1074,7 +941,7 @@ public final class Ebean {
    * @param <T>     The type of the DTO bean.
    */
   public static <T> DtoQuery<T> findDto(Class<T> dtoType, String sql) {
-    return serverMgr.getDefaultServer().findDto(dtoType, sql);
+    return getDefault().findDto(dtoType, sql);
   }
 
   /**
@@ -1096,7 +963,7 @@ public final class Ebean {
    * @return The update query to use
    */
   public static <T> UpdateQuery<T> update(Class<T> beanType) {
-    return serverMgr.getDefaultServer().update(beanType);
+    return getDefault().update(beanType);
   }
 
   /**
@@ -1110,7 +977,7 @@ public final class Ebean {
    * </p>
    */
   public static <T> Filter<T> filter(Class<T> beanType) {
-    return serverMgr.getDefaultServer().filter(beanType);
+    return getDefault().filter(beanType);
   }
 
   /**
@@ -1153,7 +1020,7 @@ public final class Ebean {
    * @see Ebean#execute(CallableSql)
    */
   public static int execute(SqlUpdate sqlUpdate) {
-    return serverMgr.getDefaultServer().execute(sqlUpdate);
+    return getDefault().execute(sqlUpdate);
   }
 
   /**
@@ -1181,7 +1048,7 @@ public final class Ebean {
    * @see Ebean#execute(SqlUpdate)
    */
   public static int execute(CallableSql callableSql) {
-    return serverMgr.getDefaultServer().execute(callableSql);
+    return getDefault().execute(callableSql);
   }
 
   /**
@@ -1205,7 +1072,7 @@ public final class Ebean {
    * }</pre>
    */
   public static void execute(TxScope scope, Runnable r) {
-    serverMgr.getDefaultServer().execute(scope, r);
+    getDefault().execute(scope, r);
   }
 
   /**
@@ -1232,7 +1099,7 @@ public final class Ebean {
    * }</pre>
    */
   public static void execute(Runnable r) {
-    serverMgr.getDefaultServer().execute(r);
+    getDefault().execute(r);
   }
 
   /**
@@ -1257,7 +1124,7 @@ public final class Ebean {
    * }</pre>
    */
   public static <T> T executeCall(TxScope scope, Callable<T> c) {
-    return serverMgr.getDefaultServer().executeCall(scope, c);
+    return getDefault().executeCall(scope, c);
   }
 
   /**
@@ -1290,7 +1157,7 @@ public final class Ebean {
    * }</pre>
    */
   public static <T> T executeCall(Callable<T> c) {
-    return serverMgr.getDefaultServer().executeCall(c);
+    return getDefault().executeCall(c);
   }
 
   /**
@@ -1324,8 +1191,7 @@ public final class Ebean {
    * @param deletes   true if rows on the table where deleted
    */
   public static void externalModification(String tableName, boolean inserts, boolean updates, boolean deletes) {
-
-    serverMgr.getDefaultServer().externalModification(tableName, inserts, updates, deletes);
+    getDefault().externalModification(tableName, inserts, updates, deletes);
   }
 
   /**
@@ -1335,14 +1201,14 @@ public final class Ebean {
    * </p>
    */
   public static BeanState getBeanState(Object bean) {
-    return serverMgr.getDefaultServer().getBeanState(bean);
+    return getDefault().getBeanState(bean);
   }
 
   /**
    * Return the manager of the server cache ("L2" cache).
    */
   public static ServerCacheManager getServerCacheManager() {
-    return serverMgr.getDefaultServer().getServerCacheManager();
+    return getDefault().getServerCacheManager();
   }
 
   /**
@@ -1350,14 +1216,14 @@ public final class Ebean {
    * queries.
    */
   public static BackgroundExecutor getBackgroundExecutor() {
-    return serverMgr.getDefaultServer().getBackgroundExecutor();
+    return getDefault().getBackgroundExecutor();
   }
 
   /**
    * Return the JsonContext for reading/writing JSON.
    */
   public static JsonContext json() {
-    return serverMgr.getDefaultServer().json();
+    return getDefault().json();
   }
 
 }

ebean-api/src/main/java/io/ebean/EbeanServer.java

@@ -1,6 +1,7 @@
 package io.ebean;
 
 /**
+ * Deprecated - please migrate to <code>io.ebean.Database</code>.
  * Provides the API for fetching and saving beans to a particular Database.
  * <p>
  * Effectively this is an alias for {@link Database} which is now the new
@@ -8,6 +9,7 @@ package io.ebean;
  * <p>
  * The preference is to use DB and Database rather than Ebean and EbeanServer.
  */
+@Deprecated
 public interface EbeanServer extends Database {
 
 }

ebean-api/src/main/java/io/ebean/EbeanServerFactory.java

@@ -0,0 +1,70 @@
+package io.ebean;
+
+import io.ebean.config.ContainerConfig;
+import io.ebean.config.ServerConfig;
+
+/**
+ * Deprecated - please migrate to DatabaseFactory.
+ * <p>
+ * Creates EbeanServer instances.
+ * <p>
+ * This uses either a ServerConfig or properties in the ebean.properties file to
+ * configure and create a EbeanServer instance.
+ * </p>
+ * <p>
+ * The EbeanServer instance can either be registered with the Ebean singleton or
+ * not. The Ebean singleton effectively holds a map of EbeanServers by a name.
+ * If the EbeanServer is registered with the Ebean singleton you can retrieve it
+ * later via {@link Ebean#getServer(String)}.
+ * </p>
+ * <p>
+ * One EbeanServer can be nominated as the 'default/primary' EbeanServer. Many
+ * methods on the Ebean singleton such as {@link Ebean#find(Class)} are just a
+ * convenient way of using the 'default/primary' EbeanServer.
+ * </p>
+ */
+@Deprecated
+public class EbeanServerFactory {
+
+  /**
+   * Initialise the container with clustering configuration.
+   * <p>
+   * Call this prior to creating any EbeanServer instances or alternatively set the
+   * ContainerConfig on the ServerConfig when creating the first EbeanServer instance.
+   */
+  public static void initialiseContainer(ContainerConfig containerConfig) {
+    DatabaseFactory.initialiseContainer(containerConfig);
+  }
+
+  /**
+   * Create using ebean.properties to configure the database.
+   */
+  public static EbeanServer create(String name) {
+    return (EbeanServer)DatabaseFactory.create(name);
+  }
+
+  /**
+   * Create using the ServerConfig object to configure the database.
+   */
+  public static EbeanServer create(ServerConfig config) {
+    return (EbeanServer)DatabaseFactory.create(config);
+  }
+
+  /**
+   * Create using the ServerConfig additionally specifying a classLoader to use as the context class loader.
+   */
+  public static EbeanServer createWithContextClassLoader(ServerConfig config, ClassLoader classLoader) {
+    return (EbeanServer)DatabaseFactory.createWithContextClassLoader(config, classLoader);
+  }
+
+  /**
+   * Shutdown gracefully all EbeanServers cleaning up any resources as required.
+   * <p>
+   * This is typically invoked via JVM shutdown hook and not explicitly called.
+   * </p>
+   */
+  public static void shutdown() {
+    DatabaseFactory.shutdown();
+  }
+
+}

ebean-api/src/main/java/io/ebean/EbeanVersion.java

@@ -6,18 +6,18 @@ import org.slf4j.LoggerFactory;
 import java.io.IOException;
 import java.io.InputStream;
 import java.util.Properties;
+
 /**
- * Class to determine the ebean version. (
- * @author Roland Praml, FOCONIS AG
+ * Class to determine the ebean version.
  *
+ * @author Roland Praml, FOCONIS AG
  */
 public class EbeanVersion {
-  private EbeanVersion() {
 
-  }
   private static final Logger logger = LoggerFactory.getLogger(EbeanVersion.class);
 
   private static String version = "unknown";
+
   static {
     try {
       Properties prop = new Properties();
@@ -34,6 +34,10 @@ public class EbeanVersion {
     }
   }
 
+  private EbeanVersion() {
+    // hide
+  }
+
   /**
    * Returns the ebean version (read from /META-INF/maven/io.ebean/ebean/pom.properties)
    */

ebean-api/src/main/java/io/ebean/Expr.java

@@ -53,7 +53,7 @@ public class Expr {
   }
 
   /**
-   * In Range - property >= value1 and property < value2.
+   * In Range - {@code property >= value1 and property < value2}.
    * <p>
    * Unlike Between inRange is "half open" and usually more useful for use with dates or timestamps.
    * </p>

ebean-api/src/main/java/io/ebean/ExpressionFactory.java

@@ -155,7 +155,7 @@ public interface ExpressionFactory {
   Expression ineObject(String propertyName, Object value);
 
   /**
-   * In Range - property >= value1 and property < value2.
+   * In Range - {@code property >= value1 and property < value2}.
    * <p>
    * Unlike Between inRange is "half open" and usually more useful for use with dates or timestamps.
    * </p>
@@ -199,6 +199,14 @@ public interface ExpressionFactory {
    */
   Expression gtOrNull(String propertyName, Object value);
 
+  /**
+   * Greater than or Equal to OR Null ({@code >= or null })
+   * <p>
+   * A convenient expression combining GE and Is Null.  Most often useful for range
+   * expressions where the top range value is nullable.
+   */
+  Expression geOrNull(String propertyName, Object value);
+
   /**
    * Greater Than - property greater than the given value.
    */
@@ -218,6 +226,14 @@ public interface ExpressionFactory {
    */
   Expression ltOrNull(String propertyName, Object value);
 
+  /**
+   * Less Than or Equal to OR Null ({@code <= or null })
+   * <p>
+   * A convenient expression combining LE and Is Null.  Most often useful for range
+   * expressions where the bottom range value is nullable.
+   */
+  Expression leOrNull(String propertyName, Object value);
+
   /**
    * Less Than - property less than the given value.
    */

ebean-api/src/main/java/io/ebean/ExpressionList.java

@@ -70,30 +70,40 @@ public interface ExpressionList<T> {
    */
   ExpressionList<T> order(String orderByClause);
 
+  /**
+   * Set the order by clause replacing the existing order by clause if there is
+   * one.
+   * <p>
+   * This follows SQL syntax using commas between each property with the
+   * optional asc and desc keywords representing ascending and descending order
+   * respectively.
+   */
+  ExpressionList<T> orderBy(String orderBy);
+
   /**
    * Return the OrderBy so that you can append an ascending or descending
    * property to the order by clause.
    * <p>
    * This will never return a null. If no order by clause exists then an 'empty'
    * OrderBy object is returned.
-   * </p>
+   * <p>
+   * This is the same as <code>orderBy()</code>
    */
   OrderBy<T> order();
 
   /**
-   * Deprecated migrate to order().
+   * Return the OrderBy so that you can append an ascending or descending
+   * property to the order by clause.
+   * <p>
+   * This will never return a null. If no order by clause exists then an 'empty'
+   * OrderBy object is returned.
+   * <p>
+   * This is the same as <code>order()</code>
    */
-  @Deprecated
   OrderBy<T> orderBy();
 
   /**
-   * Deprecated migrate to {@link #order(String)}
-   */
-  @Deprecated
-  Query<T> orderBy(String orderBy);
-
-  /**
-   * Deprecated migrate to {@link #order(String)}
+   * Deprecated migrate to {@link #orderBy(String)}
    */
   @Deprecated
   Query<T> setOrderBy(String orderBy);
@@ -159,6 +169,28 @@ public interface ExpressionList<T> {
    */
   UpdateQuery<T> asUpdate();
 
+  /**
+   * Execute the query with the given lock type and WAIT.
+   * <p>
+   * Note that <code>forUpdate()</code> is the same as
+   * <code>withLock(LockType.UPDATE)</code>.
+   * <p>
+   * Provides us with the ability to explicitly use Postgres
+   * SHARE, KEY SHARE, NO KEY UPDATE and UPDATE row locks.
+   */
+  Query<T> withLock(Query.LockType lockType);
+
+  /**
+   * Execute the query with the given lock type and lock wait.
+   * <p>
+   * Note that <code>forUpdateNoWait()</code> is the same as
+   * <code>withLock(LockType.UPDATE, LockWait.NOWAIT)</code>.
+   * <p>
+   * Provides us with the ability to explicitly use Postgres
+   * SHARE, KEY SHARE, NO KEY UPDATE and UPDATE row locks.
+   */
+  Query<T> withLock(Query.LockType lockType, Query.LockWait lockWait);
+
   /**
    * Execute using "for update" clause which results in the DB locking the record.
    */
@@ -275,6 +307,13 @@ public interface ExpressionList<T> {
    */
   void findEach(Consumer<T> consumer);
 
+  /**
+   * Execute findEach with a batch consumer.
+   *
+   * @see Query#findEach(int, Consumer)
+   */
+  void findEach(int batch, Consumer<List<T>> consumer);
+
   /**
    * Execute the query processing the beans one at a time with the ability to
    * stop processing before reading all the beans.
@@ -849,7 +888,7 @@ public interface ExpressionList<T> {
   ExpressionList<T> inRangeWith(String lowProperty, String highProperty, Object value);
 
   /**
-   * In Range - property >= value1 and property < value2.
+   * In Range - {@code property >= value1 and property < value2}.
    * <p>
    * Unlike Between inRange is "half open" and usually more useful for use with dates or timestamps.
    * </p>
@@ -876,6 +915,11 @@ public interface ExpressionList<T> {
    */
   ExpressionList<T> gtOrNull(String propertyName, Object value);
 
+  /**
+   * Greater Than or Equal to OR Null - ({@code >= or null }).
+   */
+  ExpressionList<T> geOrNull(String propertyName, Object value);
+
   /**
    * Greater Than or Equal to - property greater than or equal to the given
    * value.
@@ -892,6 +936,11 @@ public interface ExpressionList<T> {
    */
   ExpressionList<T> ltOrNull(String propertyName, Object value);
 
+  /**
+   * Less Than or Equal to OR Null - ({@code <= or null }).
+   */
+  ExpressionList<T> leOrNull(String propertyName, Object value);
+
   /**
    * Less Than or Equal to - property less than or equal to the given value.
    */
@@ -1241,26 +1290,35 @@ public interface ExpressionList<T> {
   /**
    * Add raw expression with a single parameter.
    * <p>
-   * The raw expression should contain a single ? at the location of the
-   * parameter.
-   * </p>
+   * The raw expression should contain a single ? or ?1
+   * at the location of the parameter.  We use ?1 when binding a
+   * collection for an IN expression.
    * <p>
    * When properties in the clause are fully qualified as table-column names
    * then they are not translated. logical property name names (not fully
    * qualified) will still be translated to their physical name.
-   * </p>
    * <p>
-   * <h4>Example:</h4>
+   * <h4>Examples:</h4>
    * <pre>{@code
    *
    *   // use a database function
    *   raw("add_days(orderDate, 10) < ?", someDate)
    *
+   *   raw("name like ?", "Rob%")
+   *
+   *   raw("name in (?1)", asList("Rob", "Fiona", "Jack"))
+   *
+   *   raw("name = any(?)", asList("Rob", "Fiona", "Jack"))
+   *
    * }</pre>
    *
-   * <h4>Subquery example:</h4>
+   * <h4>Subquery examples:</h4>
    * <pre>{@code
    *
+   *   // Bind collection using ?1
+   *   .raw("id in (select c.id from o_customer c where c.name in (?1))", asList("Rob", "Fiona", "Jack"))
+   *
+   *   // Using Postgres ANY expression
    *   .raw("t0.customer_id in (select customer_id from customer_group where group_id = any(?::uuid[]))", groupIds)
    *
    * }</pre>
@@ -1270,14 +1328,25 @@ public interface ExpressionList<T> {
   /**
    * Add raw expression with an array of parameters.
    * <p>
-   * The raw expression should contain the same number of ? as there are
-   * parameters.
-   * </p>
+   * The raw expression should contain the same number of ? or ?1, ?2 ... bind parameters
+   * as there are values. We use ?1, ?2 etc when binding a collection for an IN expression.
    * <p>
    * When properties in the clause are fully qualified as table-column names
    * then they are not translated. logical property name names (not fully
    * qualified) will still be translated to their physical name.
    * </p>
+   *
+   * <h4>Examples:</h4>
+   * <pre>{@code
+   *
+   *   raw("unitPrice > ? and product.id > ?", 2, 3)
+   *
+   *   raw("(status = ? or (orderDate < ? and shipDate is null) or customer.name like ?)",
+   *         Order.Status.APPROVED,
+   *         new Timestamp(System.currentTimeMillis()),
+   *         "Rob")
+   *
+   * }</pre></pre>
    */
   ExpressionList<T> raw(String raw, Object... values);
 
@@ -1602,7 +1671,7 @@ public interface ExpressionList<T> {
   ExpressionList<T> endAnd();
 
   /**
-   * End a AND junction - synonym for endJunction().
+   * End a OR junction - synonym for endJunction().
    */
   ExpressionList<T> endOr();
 

ebean-api/src/main/java/io/ebean/ExtendedServer.java

@@ -67,7 +67,7 @@ public interface ExtendedServer {
    *
    * @return True if the query finds a matching row in the database
    */
-  <T> boolean exists(Query<?> ormQuery, Transaction transaction);
+  <T> boolean exists(Query<T> ormQuery, Transaction transaction);
 
   /**
    * Return the number of 'top level' or 'root' entities this query should return.
@@ -92,11 +92,9 @@ public interface ExtendedServer {
    * {@link #findEachWhile(Query, Predicate, Transaction)} is preferred
    * to findIterate(). The reason is that those methods automatically take care of
    * closing the queryIterator (and the underlying jdbc statement and resultSet).
-   * </p>
    * <p>
    * This is similar to findEach in that not all the result beans need to be held
    * in memory at the same time and as such is good for processing large queries.
-   * </p>
    *
    * @see Query#findIterate()
    * @see Query#findEach(Consumer)
@@ -106,7 +104,10 @@ public interface ExtendedServer {
   <T> QueryIterator<T> findIterate(Query<T> query, Transaction transaction);
 
   /**
-   * Return the query result as a Stream using a single persistence context.
+   * Execute the query returning the result as a Stream.
+   * <p>
+   * Note that this can support very large queries iterating any number of results.
+   * To do so internally it can use multiple persistence contexts.
    * <p>
    * Note that the stream needs to be closed so use with try with resources.
    * </p>
@@ -115,12 +116,17 @@ public interface ExtendedServer {
   <T> Stream<T> findStream(Query<T> query, Transaction transaction);
 
   /**
-   * Return the query result as a Stream (with multiple persistence contexts).
+   * Deprecated - migrate to findStream().
+   * <p>
+   * Execute the query returning the result as a Stream.
+   * <p>
+   * Note that this can support very large queries iterating any number of results.
+   * To do so internally it can use multiple persistence contexts.
    * <p>
    * Note that the stream needs to be closed so use with try with resources.
-   * </p>
    */
   @Nonnull
+  @Deprecated
   <T> Stream<T> findLargeStream(Query<T> query, Transaction transaction);
 
   /**
@@ -153,6 +159,13 @@ public interface ExtendedServer {
    */
   <T> void findEach(Query<T> query, Consumer<T> consumer, Transaction transaction);
 
+  /**
+   * Execute findEach with batch consumer.
+   *
+   * @see Query#findEach(int, Consumer)
+   */
+  <T> void findEach(Query<T> query, int batch, Consumer<List<T>> consumer, Transaction t);
+
   /**
    * Execute the query visiting the each bean one at a time.
    * <p>

ebean-api/src/main/java/io/ebean/FetchConfig.java

@@ -0,0 +1,243 @@
+package io.ebean;
+
+import java.io.Serializable;
+
+/**
+ * Defines how a relationship is fetched via either normal SQL join,
+ * a eager secondary query, via lazy loading or via eagerly hitting L2 cache.
+ * <p>
+ * <pre>{@code
+ * // Normal fetch join results in a single SQL query
+ * List<Order> list = DB.find(Order.class).fetch("details").findList();
+ *
+ * }</pre>
+ * <p>
+ * Example: Using a "query join" instead of a "fetch join" we instead use 2 SQL queries
+ * </p>
+ * <p>
+ * <pre>{@code
+ *
+ * // This will use 2 SQL queries to build this object graph
+ * List<Order> list =
+ *     DB.find(Order.class)
+ *         .fetch("details", FetchConfig.ofQuery())
+ *         .findList();
+ *
+ * // query 1) find order
+ * // query 2) find orderDetails where order.id in (?,?...) // first 100 order id's
+ *
+ * }</pre>
+ *
+ * @author mario
+ * @author rbygrave
+ */
+public class FetchConfig implements Serializable {
+
+  private static final long serialVersionUID = 1L;
+
+  private static final int JOIN_MODE = 0;
+  private static final int QUERY_MODE = 1;
+  private static final int LAZY_MODE = 2;
+  private static final int CACHE_MODE = 3;
+
+  private int mode;
+  private int batchSize;
+  private int hashCode;
+
+  /**
+   * Deprecated - migrate to one of the static factory methods like {@link FetchConfig#ofQuery()}
+   * <p>
+   * Construct using default JOIN mode.
+   */
+  @Deprecated
+  public FetchConfig() {
+    //this.mode = JOIN_MODE;
+    this.batchSize = 100;
+    this.hashCode = 1000;
+  }
+
+  private FetchConfig(int mode, int batchSize) {
+    this.mode = mode;
+    this.batchSize = batchSize;
+    this.hashCode = mode + 10 * batchSize;
+  }
+
+  /**
+   * Return FetchConfig to eagerly fetch the relationship using L2 cache.
+   * <p>
+   * Any cache misses will be loaded by secondary query to the database.
+   */
+  public static FetchConfig ofCache() {
+    return new FetchConfig(CACHE_MODE, 100);
+  }
+
+  /**
+   * Return FetchConfig to eagerly fetch the relationship using a secondary query.
+   */
+  public static FetchConfig ofQuery() {
+    return new FetchConfig(QUERY_MODE, 100);
+  }
+
+  /**
+   * Return FetchConfig to eagerly fetch the relationship using a secondary with a given batch size.
+   */
+  public static FetchConfig ofQuery(int batchSize) {
+    return new FetchConfig(QUERY_MODE, batchSize);
+  }
+
+  /**
+   * Return FetchConfig to lazily load the relationship.
+   */
+  public static FetchConfig ofLazy() {
+    return new FetchConfig(LAZY_MODE, 0);
+  }
+
+  /**
+   * Return FetchConfig to lazily load the relationship specifying the batch size.
+   */
+  public static FetchConfig ofLazy(int batchSize) {
+    return new FetchConfig(LAZY_MODE, batchSize);
+  }
+
+  /**
+   * Return FetchConfig to fetch the relationship using SQL join.
+   */
+  public static FetchConfig ofDefault() {
+    return new FetchConfig(JOIN_MODE, 100);
+  }
+
+  /**
+   * We want to migrate away from mutating FetchConfig to a fully immutable FetchConfig.
+   */
+  private FetchConfig mutate(int mode, int batchSize) {
+    if (batchSize < 0) {
+      throw new IllegalArgumentException("batch size " + batchSize + " must be > 0");
+    }
+    this.mode = mode;
+    this.batchSize = batchSize;
+    this.hashCode = mode + 10 * batchSize;
+    return this;
+  }
+
+  /**
+   * Deprecated - migrate to FetchConfig.ofLazy().
+   */
+  @Deprecated
+  public FetchConfig lazy() {
+    return mutate(LAZY_MODE, 0);
+  }
+
+  /**
+   * Deprecated - migrate to FetchConfig.ofLazy(batchSize).
+   */
+  @Deprecated
+  public FetchConfig lazy(int batchSize) {
+    return mutate(LAZY_MODE, batchSize);
+  }
+
+  /**
+   * Deprecated - migrate to FetchConfig.ofQuery().
+   * <p>
+   * Eagerly fetch the beans in this path as a separate query (rather than as
+   * part of the main query).
+   * <p>
+   * This will use the default batch size for separate query which is 100.
+   */
+  @Deprecated
+  public FetchConfig query() {
+    return mutate(QUERY_MODE, 100);
+  }
+
+  /**
+   * Deprecated - migrate to FetchConfig.ofQuery(batchSize).
+   * <p>
+   * Eagerly fetch the beans in this path as a separate query (rather than as
+   * part of the main query).
+   * <p>
+   * The queryBatchSize is the number of parent id's that this separate query
+   * will load per batch.
+   * <p>
+   * This will load all beans on this path eagerly unless a {@link #lazy(int)}
+   * is also used.
+   *
+   * @param batchSize the batch size used to load beans on this path
+   */
+  @Deprecated
+  public FetchConfig query(int batchSize) {
+    return mutate(QUERY_MODE, batchSize);
+  }
+
+  /**
+   * Deprecated - migrate to FetchConfig.ofQuery(batchSize).
+   * <p>
+   * Eagerly fetch the first batch of beans on this path.
+   * This is similar to {@link #query(int)} but only fetches the first batch.
+   * <p>
+   * If there are more parent beans than the batch size then they will not be
+   * loaded eagerly but instead use lazy loading.
+   *
+   * @param batchSize the number of parent beans this path is populated for
+   */
+  @Deprecated
+  public FetchConfig queryFirst(int batchSize) {
+    return query(batchSize);
+  }
+
+  /**
+   * Deprecated - migrate to FetchConfig.ofCache().
+   * <p>
+   * Eagerly fetch the beans fetching the beans from the L2 bean cache
+   * and using the DB for beans not in the cache.
+   */
+  @Deprecated
+  public FetchConfig cache() {
+    return mutate(CACHE_MODE, 100);
+  }
+
+  /**
+   * Return the batch size for fetching.
+   */
+  public int getBatchSize() {
+    return batchSize;
+  }
+
+  /**
+   * Return true if the fetch should use the L2 cache.
+   */
+  public boolean isCache() {
+    return mode == CACHE_MODE;
+  }
+
+  /**
+   * Return true if the fetch should be a eager secondary query.
+   */
+  public boolean isQuery() {
+    return mode == QUERY_MODE;
+  }
+
+  /**
+   * Return true if the fetch should be a lazy query.
+   */
+  public boolean isLazy() {
+    return mode == LAZY_MODE;
+  }
+
+  /**
+   * Return true if the fetch should try to use SQL join.
+   */
+  public boolean isJoin() {
+    return mode == JOIN_MODE;
+  }
+
+  @Override
+  public boolean equals(Object o) {
+    if (this == o) return true;
+    if (o == null || getClass() != o.getClass()) return false;
+    return (hashCode == ((FetchConfig) o).hashCode);
+  }
+
+  @Override
+  public int hashCode() {
+    return hashCode;
+  }
+}

ebean-api/src/main/java/io/ebean/Finder.java

@@ -43,6 +43,7 @@ import java.util.List;
  *   public static final CustomerFinder find = new CustomerFinder();
  *   ...
  *
+ * }
  * }</pre>
  * <p>
  *  When the Finder is registered as a field on Customer it can then be used like:
@@ -85,6 +86,7 @@ public class Finder<I, T> {
    *   public static final CustomerFinder find = new CustomerFinder();
    *   ...
    *
+   * }
    * }</pre>
    */
   public Finder(Class<T> type) {

ebean-api/src/main/java/io/ebean/Model.java

@@ -32,19 +32,19 @@ import io.ebean.bean.EntityBean;
  *     // Typically there is a common base model that has some
  *     // common properties like the ones below
  *
- *     @MappedSuperclass
- *     public class BaseModel extends Model {
+ *   @MappedSuperclass
+ *   public class BaseModel extends Model {
  *
- *       @Id Long id;
+ *     @Id Long id;
  *
- *       @Version Long version;
+ *     @Version Long version;
  *
- *       @WhenCreated Timestamp whenCreated;
+ *     @WhenCreated Timestamp whenCreated;
  *
- *       @WhenUpdated Timestamp whenUpdated;
- *
- *       ...
+ *     @WhenUpdated Timestamp whenUpdated;
  *
+ *     ...
+ *   }
  * }</pre>
  * <p>
  * <h3>Extend the Model</h3>

ebean-api/src/main/java/io/ebean/ModifyAwareType.java

@@ -1,11 +1,9 @@
-package io.ebeaninternal.json;
-
-import java.io.Serializable;
+package io.ebean;
 
 /**
  * Owner object notified when a modification is detected.
  */
-public interface ModifyAwareOwner extends Serializable {
+public interface ModifyAwareType {
 
   /**
    * Return true if the value is considered dirty.
@@ -16,11 +14,6 @@ public interface ModifyAwareOwner extends Serializable {
   /**
    * Marks the object as modified.
    */
-  void markAsModified();
-
-  /**
-   * Reset the dirty state to clean.
-   */
-  void resetMarkedDirty();
+  void setMarkedDirty(boolean markedDirty);
 
 }

ebean-api/src/main/java/io/ebean/OrderBy.java

@@ -1,7 +1,5 @@
 package io.ebean;
 
-import io.ebean.util.StringHelper;
-
 import java.io.Serializable;
 import java.util.ArrayList;
 import java.util.List;
@@ -18,7 +16,7 @@ import java.util.Objects;
  * on the Query object.
  * </p>
  */
-public final class OrderBy<T> implements Serializable {
+public class OrderBy<T> implements Serializable {
 
   private static final long serialVersionUID = 9157089257745730539L;
 
@@ -71,7 +69,6 @@ public final class OrderBy<T> implements Serializable {
    * Add a property with ascending order to this OrderBy.
    */
   public Query<T> asc(String propertyName) {
-
     list.add(new Property(propertyName, true));
     return query;
   }
@@ -100,7 +97,6 @@ public final class OrderBy<T> implements Serializable {
     return query;
   }
 
-
   /**
    * Return true if the property is known to be contained in the order by clause.
    */
@@ -209,7 +205,6 @@ public final class OrderBy<T> implements Serializable {
     if (!(obj instanceof OrderBy<?>)) {
       return false;
     }
-
     OrderBy<?> e = (OrderBy<?>) obj;
     return e.list.equals(list);
   }
@@ -251,7 +246,7 @@ public final class OrderBy<T> implements Serializable {
   /**
    * A property and its ascending descending order.
    */
-  public static final class Property implements Serializable {
+  public static class Property implements Serializable {
 
     private static final long serialVersionUID = 1546009780322478077L;
 
@@ -341,7 +336,7 @@ public final class OrderBy<T> implements Serializable {
         if (collation != null)  {
           if (collation.contains("${}")) {
             // this is a complex collation, e.g. DB2 - we must replace the property
-            sb.append(StringHelper.replaceString(collation, "${}", property));
+            sb.append(collation.replace("${}", property));
           } else {
             sb.append(property);
             sb.append(" collate ").append(collation);
@@ -417,13 +412,10 @@ public final class OrderBy<T> implements Serializable {
   }
 
   private void parse(String orderByClause) {
-
     if (orderByClause == null) {
       return;
     }
-
-    String[] chunks = orderByClause.split(",");
-    for (String chunk : chunks) {
+    for (String chunk : orderByClause.split(",")) {
       Property p = parseProperty(chunk);
       if (p != null) {
         list.add(p);
@@ -469,8 +461,7 @@ public final class OrderBy<T> implements Serializable {
     if (s.startsWith("desc")) {
       return false;
     }
-    String m = "Expecting [" + s + "] to be asc or desc?";
-    throw new RuntimeException(m);
+    throw new RuntimeException("Expecting [" + s + "] to be asc or desc?");
   }
 
   private boolean isEmptyString(String s) {

ebean-api/src/main/java/io/ebean/PagedList.java

@@ -94,8 +94,8 @@ public interface PagedList<T> {
    * Return the Future row count. You might get this if you wish to cancel the total row count query
    * or specify a timeout for the row count query.
    * <p>
-   * The loadRowCount() & getTotalRowCount() methods internally make use of this getFutureRowCount() method.
-   * Generally I expect people to prefer loadRowCount() & getTotalRowCount() over getFutureRowCount().
+   * The loadRowCount() and getTotalRowCount() methods internally make use of this getFutureRowCount() method.
+   * Generally I expect people to prefer loadRowCount() and getTotalRowCount() over getFutureRowCount().
    * </p>
    * <pre>{@code
    *

ebean-api/src/main/java/io/ebean/PersistenceContextScope.java

@@ -6,7 +6,7 @@ package io.ebean;
  * Ebean has traditionally used Transaction scope for the PersistenceContext. This is used to change the scope to
  * use (by default) and explicitly set the scope to use for an individual query.
  *
- * @see io.ebean.config.ServerConfig#setPersistenceContextScope(PersistenceContextScope)
+ * @see io.ebean.config.DatabaseConfig#setPersistenceContextScope(PersistenceContextScope)
  * @see Query#setPersistenceContextScope(PersistenceContextScope)
  */
 public enum PersistenceContextScope {

ebean-api/src/main/java/io/ebean/ProfileLocation.java

@@ -45,6 +45,14 @@ public interface ProfileLocation {
    */
   String label();
 
+  /**
+   * Return a hash of the location that intentionally excludes the line number.
+   * <p>
+   * The hash is expected to be stable regardless of line number in the source file
+   * so that is identifies the class and method location over a long time.
+   */
+  long hash();
+
   /**
    * Return the full location.
    */

ebean-api/src/main/java/io/ebean/Query.java

@@ -177,16 +177,47 @@ import java.util.stream.Stream;
  *
  * @param <T> the type of Entity bean this query will fetch.
  */
-public interface Query<T> {
+public interface Query<T> extends CancelableQuery {
 
   /**
-   * For update mode.
+   * The lock type (strength) to use with query FOR UPDATE row locking.
    */
-  enum ForUpdate {
+  enum LockType {
+    /**
+     * The default lock type being either UPDATE or NO_KEY_UPDATE based on
+     * PlatformConfig.forUpdateNoKey configuration (Postgres option).
+     */
+    DEFAULT,
+
+    /**
+     * FOR UPDATE.
+     */
+    UPDATE,
+
+    /**
+     * FOR NO KEY UPDATE (Postgres only).
+     */
+    NO_KEY_UPDATE,
+
+    /**
+     * FOR SHARE (Postgres only).
+     */
+    SHARE,
+
+    /**
+     * FOR KEY SHARE (Postgres only).
+     */
+    KEY_SHARE
+  }
+
+  /**
+   * FOR UPDATE wait mode.
+   */
+  enum LockWait {
     /**
      * Standard For update clause.
      */
-    BASE,
+    WAIT,
 
     /**
      * For update with No Wait option.
@@ -260,15 +291,6 @@ public interface Query<T> {
    */
   UpdateQuery<T> asUpdate();
 
-  /**
-   * Cancel the query execution if supported by the underlying database and
-   * driver.
-   * <p>
-   * This must be called from a different thread to the query executor.
-   * </p>
-   */
-  void cancel();
-
   /**
    * Return a copy of the query.
    * <p>
@@ -283,7 +305,7 @@ public interface Query<T> {
   /**
    * Specify the PersistenceContextScope to use for this query.
    * <p/>
-   * When this is not set the 'default' configured on {@link io.ebean.config.ServerConfig#setPersistenceContextScope(PersistenceContextScope)}
+   * When this is not set the 'default' configured on {@link io.ebean.config.DatabaseConfig#setPersistenceContextScope(PersistenceContextScope)}
    * is used - this value defaults to {@link PersistenceContextScope#TRANSACTION}.
    * <p/>
    * Note that the same persistence Context is used for subsequent lazy loading and query join queries.
@@ -483,7 +505,7 @@ public interface Query<T> {
    * </p>
    * <pre>{@code
    *
-   *  fetch(path, fetchProperties, new FetchConfig().query())
+   *  fetch(path, fetchProperties, FetchConfig.ofQuery())
    *
    * }</pre>
    * <p>
@@ -517,7 +539,7 @@ public interface Query<T> {
    * </p>
    * <pre>{@code
    *
-   *  fetch(path, fetchProperties, new FetchConfig().lazy())
+   *  fetch(path, fetchProperties, FetchConfig.ofLazy())
    *
    * }</pre>
    * <p>
@@ -542,7 +564,7 @@ public interface Query<T> {
    * // fetch customers (their id, name and status)
    * List<Customer> customers = DB.find(Customer.class)
    *     .select("name, status")
-   *     .fetch("contacts", "firstName,lastName,email", new FetchConfig().lazy(10))
+   *     .fetch("contacts", "firstName,lastName,email", FetchConfig.ofLazy(10))
    *     .findList();
    *
    * }</pre>
@@ -579,7 +601,7 @@ public interface Query<T> {
    * </p>
    * <pre>{@code
    *
-   *  fetch(path, new FetchConfig().query())
+   *  fetch(path, FetchConfig.ofQuery())
    *
    * }</pre>
    * <p>
@@ -608,7 +630,7 @@ public interface Query<T> {
    * </p>
    * <pre>{@code
    *
-   *  fetch(path, new FetchConfig().lazy())
+   *  fetch(path, FetchConfig.ofLazy())
    *
    * }</pre>
    * <p>
@@ -631,7 +653,7 @@ public interface Query<T> {
    * // fetch customers (their id, name and status)
    * List<Customer> customers = DB.find(Customer.class)
    *     // lazy fetch contacts with a batch size of 100
-   *     .fetch("contacts", new FetchConfig().lazy(100))
+   *     .fetch("contacts", FetchConfig.ofLazy(100))
    *     .findList();
    *
    * }</pre>
@@ -711,9 +733,9 @@ public interface Query<T> {
   /**
    * Execute the query returning the result as a Stream.
    * <p>
-   * Note that this will hold all resulting beans in memory using a single
-   * persistence context. Use findLargeStream() for queries that expect to
-   * return a large number of results.
+   * Note that this can support very large queries iterating
+   * any number of results. To do so internally it can use
+   * multiple persistence contexts.
    * </p>
    * <pre>{@code
    *
@@ -731,6 +753,8 @@ public interface Query<T> {
   Stream<T> findStream();
 
   /**
+   * Deprecated - migrate to findStream.
+   * <p>
    * Execute the query returning the result as a Stream.
    * <p>
    * Note that this uses multiple persistence contexts such that we can use
@@ -749,6 +773,7 @@ public interface Query<T> {
    * }</pre>
    */
   @Nonnull
+  @Deprecated
   Stream<T> findLargeStream();
 
   /**
@@ -776,7 +801,7 @@ public interface Query<T> {
    * </p>
    * <p>
    * This method is functionally equivalent to findIterate() but instead of using an
-   * iterator uses the Consumer interface which is better suited to use with Java8 closures.
+   * iterator uses the Consumer interface which is better suited to use with closures.
    * </p>
    * <pre>{@code
    *
@@ -795,6 +820,21 @@ public interface Query<T> {
    */
   void findEach(Consumer<T> consumer);
 
+  /**
+   * Execute findEach streaming query batching the results for consuming.
+   * <p>
+   * This query execution will stream the results and is suited to consuming
+   * large numbers of results from the database.
+   * <p>
+   * Typically we use this batch consumer when we want to do further processing on
+   * the beans and want to do that processing in batch form, for example - 100 at
+   * a time.
+   *
+   * @param batch    The number of beans processed in the batch
+   * @param consumer Process the batch of beans
+   */
+  void findEach(int batch, Consumer<List<T>> consumer);
+
   /**
    * Execute the query using callbacks to a visitor to process the resulting
    * beans one at a time.
@@ -805,12 +845,12 @@ public interface Query<T> {
    * </p>
    * <p>
    * This method is functionally equivalent to findIterate() but instead of using an
-   * iterator uses the Predicate (SAM) interface which is better suited to use with Java8 closures.
+   * iterator uses the Predicate interface which is better suited to use with closures.
    * </p>
    * <pre>{@code
    *
    *  DB.find(Customer.class)
-   *     .fetch("contacts", new FetchConfig().query(2))
+   *     .fetchQuery("contacts")
    *     .where().eq("status", Status.NEW)
    *     .order().asc("id")
    *     .setMaxRows(2000)
@@ -1352,9 +1392,13 @@ public interface Query<T> {
   Query<T> having(Expression addExpressionToHaving);
 
   /**
-   * Deprecated migrate to {@link #order(String)}
+   * Set the order by clause replacing the existing order by clause if there is
+   * one.
+   * <p>
+   * This follows SQL syntax using commas between each property with the
+   * optional asc and desc keywords representing ascending and descending order
+   * respectively.
    */
-  @Deprecated
   Query<T> orderBy(String orderByClause);
 
   /**
@@ -1373,13 +1417,20 @@ public interface Query<T> {
    * <p>
    * This will never return a null. If no order by clause exists then an 'empty'
    * OrderBy object is returned.
+   * <p>
+   * This is the same as <code>orderBy()</code>
    */
   OrderBy<T> order();
 
   /**
-   * Deprecated migrate to order().
+   * Return the OrderBy so that you can append an ascending or descending
+   * property to the order by clause.
+   * <p>
+   * This will never return a null. If no order by clause exists then an 'empty'
+   * OrderBy object is returned.
+   * <p>
+   * This is the same as <code>order()</code>
    */
-  @Deprecated
   OrderBy<T> orderBy();
 
   /**
@@ -1388,9 +1439,8 @@ public interface Query<T> {
   Query<T> setOrder(OrderBy<T> orderBy);
 
   /**
-   * Deprecated migrate to {@link #setOrder(OrderBy)}
+   * Set an OrderBy object to replace any existing OrderBy clause.
    */
-  @Deprecated
   Query<T> setOrderBy(OrderBy<T> orderBy);
 
   /**
@@ -1600,8 +1650,32 @@ public interface Query<T> {
    */
   String getGeneratedSql();
 
+  /**
+   * Execute the query with the given lock type and WAIT.
+   * <p>
+   * Note that <code>forUpdate()</code> is the same as
+   * <code>withLock(LockType.UPDATE)</code>.
+   * <p>
+   * Provides us with the ability to explicitly use Postgres
+   * SHARE, KEY SHARE, NO KEY UPDATE and UPDATE row locks.
+   */
+  Query<T> withLock(LockType lockType);
+
+  /**
+   * Execute the query with the given lock type and lock wait.
+   * <p>
+   * Note that <code>forUpdateNoWait()</code> is the same as
+   * <code>withLock(LockType.UPDATE, LockWait.NOWAIT)</code>.
+   * <p>
+   * Provides us with the ability to explicitly use Postgres
+   * SHARE, KEY SHARE, NO KEY UPDATE and UPDATE row locks.
+   */
+  Query<T> withLock(LockType lockType, LockWait lockWait);
+
   /**
    * Execute using "for update" clause which results in the DB locking the record.
+   * <p>
+   * The same as <code>withLock(LockType.UPDATE, LockWait.WAIT)</code>.
    */
   Query<T> forUpdate();
 
@@ -1609,7 +1683,8 @@ public interface Query<T> {
    * Execute using "for update" clause with "no wait" option.
    * <p>
    * This is typically a Postgres and Oracle only option at this stage.
-   * </p>
+   * <p>
+   * The same as <code>withLock(LockType.UPDATE, LockWait.NOWAIT)</code>.
    */
   Query<T> forUpdateNoWait();
 
@@ -1617,7 +1692,8 @@ public interface Query<T> {
    * Execute using "for update" clause with "skip locked" option.
    * <p>
    * This is typically a Postgres and Oracle only option at this stage.
-   * </p>
+   * <p>
+   * The same as <code>withLock(LockType.UPDATE, LockWait.SKIPLOCKED)</code>.
    */
   Query<T> forUpdateSkipLocked();
 
@@ -1627,9 +1703,14 @@ public interface Query<T> {
   boolean isForUpdate();
 
   /**
-   * Return the "for update" mode to use.
+   * Return the "for update" wait mode to use.
    */
-  ForUpdate getForUpdateMode();
+  LockWait getForUpdateLockWait();
+
+  /**
+   * Return the lock type (strength) to use with "for update".
+   */
+  LockType getForUpdateLockType();
 
   /**
    * Set root table alias.

ebean-api/src/main/java/io/ebean/QueryIterator.java

@@ -56,7 +56,7 @@ import java.util.Iterator;
  *
  * @param <T> the type of entity bean in the iteration
  */
-public interface QueryIterator<T> extends Iterator<T>, java.io.Closeable {
+public interface QueryIterator<T> extends Iterator<T>, AutoCloseable {
 
   /**
    * Returns <tt>true</tt> if the iteration has more elements.
@@ -70,12 +70,6 @@ public interface QueryIterator<T> extends Iterator<T>, java.io.Closeable {
   @Override
   T next();
 
-  /**
-   * Remove is not allowed.
-   */
-  @Override
-  void remove();
-
   /**
    * Close the underlying resources held by this iterator.
    */

ebean-api/src/main/java/io/ebean/RawSql.java

@@ -6,17 +6,13 @@ package io.ebean;
  * <p>
  * If you don't want to build object graphs you can use {@link SqlQuery} instead
  * which returns {@link SqlRow} objects rather than entity beans.
- * </p>
  * <p>
  * <b>Unparsed RawSql:</b>
- * </p>
  * <p>
  * 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.
- * </p>
  * <p>
  * <b>Parsed RawSql:</b>
- * </p>
  * <p>
  * 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
@@ -24,16 +20,13 @@ package io.ebean;
  * explicitly tell Ebean where these insertion points are you can place special
  * strings into your SQL ({@code ${where}} or {@code ${andWhere}} and {@code ${having}} or
  * {@code ${andHaving})}.
- * </p>
  * <p>
  * 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 {@code ${where}} in instead. Similarly you can put in {@code ${having}} or
  * {@code ${andHaving}} where you want Ebean put add extra having expressions.
- * </p>
  * <p>
  * <b>Aggregates:</b>
- * </p>
  * <p>
  * Often RawSql will be used with Aggregate functions (sum, avg, max etc). The
  * follow example shows an example based on Total Order Amount -
@@ -44,38 +37,37 @@ package io.ebean;
  * on RawSql and not based on a real DB Table or DB View. It has some properties
  * to hold the values for the aggregate functions (sum etc) and a &#064;OneToOne
  * to Order.
- * </p>
  * <p>
  * <h3>Example OrderAggregate</h3>
  * <pre>{@code
  *  ...
- *  // @Sql indicates to that this bean
- *  // is based on RawSql rather than a table
+ *   // @Sql indicates to that this bean
+ *   // is based on RawSql rather than a table
  *
- * @Entity
- * @Sql
- * public class OrderAggregate {
+ *   @Entity
+ *   @Sql
+ *   public class OrderAggregate {
  *
- *  @OneToOne
- *  Order order;
+ *    @OneToOne
+ *    Order order;
  *
- *  Double totalAmount;
+ *    Double totalAmount;
  *
- *  Double totalItems;
- *
- *  // getters and setters
- *  ...
+ *    Double totalItems;
  *
+ *    // getters and setters
+ *    ...
+ *   }
  * }</pre>
- * <p>
+ *
  * <h3>Example 1:</h3>
- * <p>
+ *
  * <pre>{@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 ";
+ *   String sql = " select order_id, o.status, c.id, c.name, sum(l.order_qty*l.unit_price) as totalAmount"
+ *     + " from order o"
+ *     + " join customer c on c.id = o.customer_id "
+ *     + " join order_line l on l.order_id = o.id " + " group by order_id, o.status ";
  *
  *   RawSql rawSql = RawSqlBuilder.parse(sql)
  *     // map the sql result columns to bean properties
@@ -95,18 +87,17 @@ package io.ebean;
  *
  *
  * }</pre>
- * <p>
+ *
  * <h3>Example 2:</h3>
  * <p>
  * The following example uses a FetchConfig().query() so that after the initial
  * RawSql query is executed Ebean executes a secondary query to fetch the
  * associated order status, orderDate along with the customer name.
- * </p>
- * <p>
+ *
  * <pre>{@code
  *
- *  String sql = " select order_id, 'ignoreMe', sum(d.order_qty*d.unit_price) as totalAmount "
- *     + " from o_order_detail d"
+ *  String sql = " select order_id, 'ignoreMe', sum(l.order_qty*l.unit_price) as totalAmount "
+ *     + " from order_line l"
  *     + " group by order_id ";
  *
  *   RawSql rawSql = RawSqlBuilder.parse(sql)
@@ -116,7 +107,7 @@ package io.ebean;
  *
  *   List<OrderAggregate> orders = DB.find(OrderAggregate.class)
  *     .setRawSql(rawSql)
- *     .fetch("order", "status,orderDate", new FetchConfig().query())
+ *     .fetch("order", "status,orderDate", FetchConfig.ofQuery())
  *     .fetch("order.customer", "name")
  *     .where().gt("order.id", 0)
  *     .having().gt("totalAmount", 20)
@@ -125,25 +116,23 @@ package io.ebean;
  *     .findList();
  *
  * }</pre>
- * <p>
  * <h3>Example 3: tableAliasMapping</h3>
  * <p>
  * Instead of mapping each column you can map each table alias to a path using tableAliasMapping().
- * </p>
  * <pre>{@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  " +
+ *               " l.id, l.order_qty, p.id, p.name " +
+ *               "from orders o join o_customer c on c.id = o.customer_id " +
+ *               "join order_line l on l.order_id = o.id  " +
+ *               "join product p on p.id = l.product_id  " +
  *               "where o.id <= :maxOrderId  and p.id = :productId "+
- *               "order by o.id, d.id asc";
+ *               "order by o.id, l.id asc";
  *
  *  RawSql rawSql = RawSqlBuilder.parse(rs)
  *       .tableAliasMapping("c", "customer")
- *       .tableAliasMapping("d", "details")
- *       .tableAliasMapping("p", "details.product")
+ *       .tableAliasMapping("l", "lines")
+ *       .tableAliasMapping("p", "lines.product")
  *       .create();
  *
  *  List<Order> ordersFromRaw = DB.find(Order.class)
@@ -154,9 +143,7 @@ package io.ebean;
  *
  * }</pre>
  * <p>
- * <p>
  * Note that lazy loading also works with object graphs built with RawSql.
- * </p>
  */
 public interface RawSql {
 

ebean-api/src/main/java/io/ebean/SqlQuery.java

@@ -37,7 +37,7 @@ import java.util.function.Predicate;
  *
  * }</pre>
  */
-public interface SqlQuery extends Serializable {
+public interface SqlQuery extends Serializable, CancelableQuery {
 
   /**
    * Execute the query returning a list.
@@ -224,12 +224,49 @@ public interface SqlQuery extends Serializable {
    *
    * }</pre>
    *
+   * <p>
+   * When binding a collection of values into a IN expression we should use
+   * indexed parameters like ?1, ?2, ?3 etc rather than just ?.
+   * </p>
+   *
+   * <pre>{@code
+   *
+   *   String sql = "select c.id, c.name from customer c where c.name in (?1)";
+   *
+   *   List<SqlRow> rows = DB.sqlQuery(sql)
+   *       .setParameter(asList("Rob", "Fiona", "Jack"))
+   *       .findList();
+   *
+   *
+   *   List<SqlRow> rows = DB.sqlQuery(sql)
+   *       .setParameter(1, asList("Rob", "Fiona", "Jack"))
+   *       .findList();
+   * }</pre>
+   *
    * @param value The value to bind
    */
   SqlQuery setParameter(Object value);
 
   /**
    * Bind the parameter by its index position (1 based like JDBC).
+   * <p>
+   * When binding a collection of values into a IN expression we should use
+   * indexed parameters like ?1, ?2, ?3 etc rather than just ?.
+   * </p>
+   *
+   * <pre>{@code
+   *
+   *   String sql = "select c.id, c.name from customer c where c.name in (?1)";
+   *
+   *   List<SqlRow> rows = DB.sqlQuery(sql)
+   *       .setParameter(asList("Rob", "Fiona", "Jack"))
+   *       .findList();
+   *
+   *
+   *   List<SqlRow> rows = DB.sqlQuery(sql)
+   *       .setParameter(1, asList("Rob", "Fiona", "Jack"))
+   *       .findList();
+   * }</pre>
    */
   SqlQuery setParameter(int position, Object value);
 
@@ -328,5 +365,10 @@ public interface SqlQuery extends Serializable {
      * Return the list of values.
      */
     List<T> findList();
+
+    /**
+     * Find streaming the result effectively consuming a row at a time.
+     */
+    void findEach(Consumer<T> consumer);
   }
 }

ebean-api/src/main/java/io/ebean/SqlUpdate.java

@@ -5,18 +5,16 @@ package io.ebean;
  * <p>
  * Provides a simple way to execute raw SQL insert update or delete statements
  * without having to resort to JDBC.
- * </p>
  * <p>
  * Supports the use of positioned or named parameters and can automatically
  * notify Ebean of the table modified so that Ebean can maintain its cache.
- * </p>
  * <p>
  * Note that {@link #setAutoTableMod(boolean)} and
  * Ebean#externalModification(String, boolean, boolean, boolean)} can be to
  * notify Ebean of external changes and enable Ebean to maintain it's "L2"
  * server cache.
- * </p>
  *
+ * <h2>Positioned parameter example</h2>
  * <pre>{@code
  *
  *   // example using 'positioned' parameters
@@ -30,6 +28,7 @@ package io.ebean;
  *
  * }</pre>
  *
+ * <h2>Named parameter example</h2>
  * <pre>{@code
  *
  *   // example using 'named' parameters
@@ -45,8 +44,31 @@ package io.ebean;
  *   String msg = "There were " + rows + " rows updated";
  *
  * }</pre>
+ *
+ * <h2>Index parameter examples (e.g. ?1, ?2, ?3 ...)</h2>
  * <p>
- * <h3>Example: Using setNextParameter()</h3>
+ * We can use index parameters like ?1, ?2, ?3 etc when binding arrays/collections
+ * of values into an IN expression.
+ * </p>
+ * <pre>{@code
+ *
+ *   // Binding a list of 3 values (9991, 9992, 9993) into an IN expression
+ *
+ *   DB.sqlUpdate("delete from o_customer where name = ? and id in (?2)")
+ *     .setParameter(1, "Foo")
+ *     .setParameter(2, asList(9991, 9992, 9993))
+ *     .execute();
+ *
+ *   // note this effectively is the same as
+ *
+ *   DB.sqlUpdate("delete from o_customer where name = ? and id in (?2)")
+ *     .setParameter("Foo")
+ *     .setParameter(asList(9991, 9992, 9993))
+ *     .execute();
+ *
+ * }</pre>
+ *
+ * <h3>Example: Using setParameter()</h3>
  * <pre>{@code
  *
  *  String sql = "insert into audit_log (id, description, modified_description) values (?,?,?)";
@@ -56,19 +78,19 @@ package io.ebean;
  *  try (Transaction txn = DB.beginTransaction()) {
  *    txn.setBatchMode(true);
  *
- *    insert.setNextParameter(10000);
- *    insert.setNextParameter("hello");
- *    insert.setNextParameter("rob");
+ *    insert.setParameter(10000);
+ *    insert.setParameter("hello");
+ *    insert.setParameter("rob");
  *    insert.execute();
  *
- *    insert.setNextParameter(10001);
- *    insert.setNextParameter("goodbye");
- *    insert.setNextParameter("rob");
+ *    insert.setParameter(10001);
+ *    insert.setParameter("goodbye");
+ *    insert.setParameter("rob");
  *    insert.execute();
  *
- *    insert.setNextParameter(10002);
- *    insert.setNextParameter("chow");
- *    insert.setNextParameter("bob");
+ *    insert.setParameter(10002);
+ *    insert.setParameter("chow");
+ *    insert.setParameter("bob");
  *    insert.execute();
  *
  *    txn.commit();
@@ -81,19 +103,19 @@ package io.ebean;
  *
  *   try (Transaction txn = DB.beginTransaction()) {
  *
- *     insert.setNextParameter(10000);
- *     insert.setNextParameter("hello");
- *     insert.setNextParameter("rob");
+ *     insert.setParameter(10000);
+ *     insert.setParameter("hello");
+ *     insert.setParameter("rob");
  *     insert.addBatch();
  *
- *     insert.setNextParameter(10001);
- *     insert.setNextParameter("goodbye");
- *     insert.setNextParameter("rob");
+ *     insert.setParameter(10001);
+ *     insert.setParameter("goodbye");
+ *     insert.setParameter("rob");
  *     insert.addBatch();
  *
- *     insert.setNextParameter(10002);
- *     insert.setNextParameter("chow");
- *     insert.setNextParameter("bob");
+ *     insert.setParameter(10002);
+ *     insert.setParameter("chow");
+ *     insert.setParameter("bob");
  *     insert.addBatch();
  *
  *     int[] rows = insert.executeBatch();

ebean-api/src/main/java/io/ebean/Transaction.java

@@ -2,8 +2,8 @@ package io.ebean;
 
 import io.ebean.annotation.DocStoreMode;
 import io.ebean.annotation.PersistBatch;
+import io.ebean.config.DatabaseConfig;
 import io.ebean.config.DocStoreConfig;
-import io.ebean.config.ServerConfig;
 
 import javax.persistence.PersistenceException;
 import java.sql.Connection;
@@ -59,6 +59,14 @@ public interface Transaction extends AutoCloseable {
    */
   void register(TransactionCallback callback);
 
+  /**
+   * EXPERIMENTAL - turn on automatic persistence of dirty beans and batchMode true.
+   * <p>
+   * With this turned on beans that are dirty in the persistence context
+   * are automatically persisted on flush() and commit().
+   */
+  void setAutoPersistUpdates(boolean autoPersistUpdates);
+
   /**
    * Set a label on the transaction.
    * <p>
@@ -226,7 +234,7 @@ public interface Transaction extends AutoCloseable {
   /**
    * Set if the L2 cache should be skipped for "find by id" and "find by natural key" queries.
    * <p>
-   * By default {@link ServerConfig#isSkipCacheAfterWrite()} is true and that means that for
+   * By default {@link DatabaseConfig#isSkipCacheAfterWrite()} is true and that means that for
    * "find by id" and "find by natural key" queries which normally hit L2 bean cache automatically
    * - will not do so after a persist/write on the transaction.
    * </p>
@@ -235,7 +243,7 @@ public interface Transaction extends AutoCloseable {
    * will skip the L2 bean cache or not (regardless of whether the transaction is considered "read only").
    * </p>
    * <p>
-   * Refer to {@link ServerConfig#setSkipCacheAfterWrite(boolean)} for configuring the default behavior
+   * Refer to {@link DatabaseConfig#setSkipCacheAfterWrite(boolean)} for configuring the default behavior
    * for using the L2 bean cache in transactions spanning multiple query/persist requests.
    * </p>
    *
@@ -276,7 +284,7 @@ public interface Transaction extends AutoCloseable {
    *
    * }</pre>
    *
-   * @see ServerConfig#isSkipCacheAfterWrite()
+   * @see DatabaseConfig#isSkipCacheAfterWrite()
    */
   void setSkipCache(boolean skipCache);
 
@@ -313,7 +321,7 @@ public interface Transaction extends AutoCloseable {
    * <h3>getGeneratedKeys</h3>
    * <p>
    * Often with large batch inserts we want to turn off getGeneratedKeys. We do
-   * this via {@link #setBatchGetGeneratedKeys(boolean)}.
+   * this via {@link #setGetGeneratedKeys(boolean)}.
    * Also note that some JDBC drivers do not support getGeneratedKeys in JDBC batch mode.
    * </p>
    * <pre>{@code
@@ -339,15 +347,12 @@ public interface Transaction extends AutoCloseable {
    * The batch is automatically flushed when it hits the batch size and also when we
    * execute queries or when we mix UpdateSql and CallableSql with save and delete of
    * beans.
-   * </p>
    * <p>
    * We use {@link #flush()} to explicitly flush the batch and we can use
-   * {@link #setBatchFlushOnQuery(boolean)} and {@link #setBatchFlushOnMixed(boolean)}
+   * {@link #setFlushOnQuery(boolean)} and {@link #setFlushOnMixed(boolean)}
    * to control the automatic flushing behaviour.
-   * </p>
    * <p>
    * Example: batch processing of CallableSql executing every 10 rows
-   * </p>
    *
    * <pre>{@code
    *
@@ -392,17 +397,14 @@ public interface Transaction extends AutoCloseable {
    * <p>
    * This only takes effect when batch mode on the transaction has not already meant that
    * JDBC batch mode is being used.
-   * </p>
    * <p>
    * This is useful when the single save() or delete() cascades. For example, inserting a 'master' cascades
    * and inserts a collection of 'detail' beans. The detail beans can be inserted using JDBC batch.
-   * </p>
    * <p>
    * This is effectively already turned on for all platforms apart from older Sql Server.
-   * </p>
    *
    * @param batchMode the batch mode to use per save(), insert(), update() or delete()
-   * @see io.ebean.config.ServerConfig#setPersistBatchOnCascade(PersistBatch)
+   * @see io.ebean.config.DatabaseConfig#setPersistBatchOnCascade(PersistBatch)
    */
   void setBatchOnCascade(boolean batchMode);
 
@@ -422,17 +424,29 @@ public interface Transaction extends AutoCloseable {
   int getBatchSize();
 
   /**
-   * Specify if you want batched inserts to use getGeneratedKeys.
+   * Specify if we want batched inserts to use getGeneratedKeys.
    * <p>
    * By default batched inserts will try to use getGeneratedKeys if it is
    * supported by the underlying jdbc driver and database.
-   * </p>
    * <p>
-   * You may want to turn getGeneratedKeys off when you are inserting a large
-   * number of objects and you don't care about getting back the ids.
-   * </p>
+   * We want to turn off getGeneratedKeys when we are inserting a large
+   * number of objects and we don't care about getting back the ids. In this
+   * way we avoid the extra cost of getting back the generated id values
+   * from the database.
+   * <p>
+   * Note that when we do turn off getGeneratedKeys then we have the limitation
+   * that after a bean has been inserted we are unable to then mutate the bean
+   * and update it in the same transaction as we have not obtained it's id value.
    */
-  void setBatchGetGeneratedKeys(boolean getGeneratedKeys);
+  void setGetGeneratedKeys(boolean getGeneratedKeys);
+
+  /**
+   * Deprecated renamed to setGetGeneratedKeys().
+   */
+  @Deprecated
+  default void setBatchGetGeneratedKeys(boolean getGeneratedKeys) {
+    setGetGeneratedKeys(getGeneratedKeys);
+  }
 
   /**
    * By default when mixing UpdateSql (or CallableSql) with Beans the batch is
@@ -441,15 +455,21 @@ public interface Transaction extends AutoCloseable {
    * <p>
    * If you want to execute both WITHOUT having the batch automatically flush
    * you need to call this with batchFlushOnMixed = false.
-   * </p>
    * <p>
    * Note that UpdateSql and CallableSql are ALWAYS executed first (before the
    * beans are executed). This is because the UpdateSql and CallableSql have
    * already been bound to their PreparedStatements. The beans on the other hand
    * have a 2 step process (delayed binding).
-   * </p>
    */
-  void setBatchFlushOnMixed(boolean batchFlushOnMixed);
+  void setFlushOnMixed(boolean batchFlushOnMixed);
+
+  /**
+   * Deprecated renamed to setFlushOnMixed().
+   */
+  @Deprecated
+  default void setBatchFlushOnMixed(boolean batchFlushOnMixed) {
+    setFlushOnMixed(batchFlushOnMixed);
+  }
 
   /**
    * By default executing a query will automatically flush any batched
@@ -457,25 +477,38 @@ public interface Transaction extends AutoCloseable {
    * <p>
    * Calling this method with batchFlushOnQuery = false means that you can
    * execute a query and the batch will not be automatically flushed.
-   * </p>
    */
-  void setBatchFlushOnQuery(boolean batchFlushOnQuery);
+  void setFlushOnQuery(boolean batchFlushOnQuery);
+
+  /**
+   * Deprecated renamed to setFlushOnQuery().
+   */
+  @Deprecated
+  default void setBatchFlushOnQuery(boolean batchFlushOnQuery) {
+    setFlushOnQuery(batchFlushOnQuery);
+  }
 
   /**
    * Return true if the batch (of persisted beans or executed UpdateSql etc)
    * should be flushed prior to executing a query.
    * <p>
    * The default is for this to be true.
-   * </p>
    */
-  boolean isBatchFlushOnQuery();
+  boolean isFlushOnQuery();
+
+  /**
+   * Deprecated renamed to isFlushOnQuery().
+   */
+  @Deprecated
+  default boolean isBatchFlushOnQuery() {
+    return isFlushOnQuery();
+  }
 
   /**
    * The batch will be flushing automatically but you can use this to explicitly
    * flush the batch if you like.
    * <p>
    * Flushing occurs automatically when:
-   * </p>
    * <ul>
    * <li>the batch size is reached</li>
    * <li>A query is executed on the same transaction</li>
@@ -487,11 +520,11 @@ public interface Transaction extends AutoCloseable {
   void flush() throws PersistenceException;
 
   /**
-   * This is a synonym for flush() and will be deprecated.
+   * Deprecated - migrate to flush().
    * <p>
    * flush() is preferred as it matches the JPA flush() method.
-   * </p>
    */
+  @Deprecated
   void flushBatch() throws PersistenceException;
 
   /**
@@ -501,11 +534,9 @@ public interface Transaction extends AutoCloseable {
    * commit() rollback() and end() methods on the Transaction should still be
    * used. Calling these methods on the Connection would be a big no no unless
    * you know what you are doing.
-   * </p>
    * <p>
    * Examples of when a developer may wish to use the connection directly are:
    * Savepoints, advanced CLOB BLOB use and advanced stored procedure calls.
-   * </p>
    */
   Connection getConnection();
 
@@ -513,17 +544,14 @@ public interface Transaction extends AutoCloseable {
    * Add table modification information to the TransactionEvent.
    * <p>
    * Use this in conjunction with getConnection() and raw JDBC.
-   * </p>
    * <p>
    * This effectively informs Ebean of the data that has been changed by the
    * transaction and this information is normally automatically handled by Ebean
    * when you save entity beans or use UpdateSql etc.
-   * </p>
    * <p>
    * If you use raw JDBC then you can use this method to inform Ebean for the
    * tables that have been modified. Ebean uses this information to keep its
    * caches in synch and maintain text indexes.
-   * </p>
    */
   void addModification(String tableName, boolean inserts, boolean updates, boolean deletes);
 

ebean-api/src/main/java/io/ebean/TxScope.java

@@ -2,6 +2,7 @@ package io.ebean;
 
 import io.ebean.annotation.PersistBatch;
 import io.ebean.annotation.TxIsolation;
+import io.ebean.annotation.TxOption;
 import io.ebean.annotation.TxType;
 
 import java.util.ArrayList;
@@ -33,6 +34,8 @@ public final class TxScope {
 
   private TxIsolation isolation;
 
+  private TxOption autoPersistUpdates;
+
   private PersistBatch batch;
 
   private PersistBatch batchOnCascade;
@@ -123,6 +126,13 @@ public final class TxScope {
       + "] serverName[" + serverName + "] rollbackFor[" + rollbackFor + "] noRollbackFor[" + noRollbackFor + "]";
   }
 
+  /**
+   * Return the AutoPersistUpdates mode as a nullable Boolean.
+   */
+  public Boolean getAutoPersistUpdates() {
+    return autoPersistUpdates == null ? null : autoPersistUpdates.asBoolean();
+  }
+
   /**
    * Return true if PersistBatch has been set.
    */
@@ -176,6 +186,14 @@ public final class TxScope {
     return this;
   }
 
+  /**
+   * Set the autoPersistUpdates mode.
+   */
+  public TxScope setAutoPersistUpdates(TxOption autoPersistUpdates) {
+    this.autoPersistUpdates = autoPersistUpdates;
+    return this;
+  }
+
   /**
    * Return the transaction profile id.
    */

ebean-api/src/main/java/io/ebean/Update.java

@@ -12,26 +12,27 @@ package io.ebean;
  * The following is an example of named updates on an entity bean.
  * </p>
  * <pre>{@code
- *  ...
- * @NamedUpdates(value = {
- *   @NamedUpdate(
- *      name = "setTitle",
- *      notifyCache = false,
- *      update = "update topic set title = :title, postCount = :count where id = :id"),
- *  @NamedUpdate(
- *      name = "setPostCount",
- *      notifyCache = false,
- *      update = "update f_topic set post_count = :postCount where id = :id"),
- *  @NamedUpdate(
- *      name = "incrementPostCount",
- *      notifyCache = false,
- *      update = "update Topic set postCount = postCount + 1 where id = :id")
- *      //update = "update f_topic set post_count = post_count + 1 where id = :id")
- *  })
- * @Entity
- * @Table(name = "f_topic")
- * public class Topic {
- *  ...
+ *    ...
+ *   @NamedUpdates(value = {
+ *     @NamedUpdate(
+ *       name = "setTitle",
+ *       notifyCache = false,
+ *       update = "update topic set title = :title, postCount = :count where id = :id"),
+ *    @NamedUpdate(
+ *       name = "setPostCount",
+ *       notifyCache = false,
+ *       update = "update f_topic set post_count = :postCount where id = :id"),
+ *    @NamedUpdate(
+ *       name = "incrementPostCount",
+ *       notifyCache = false,
+ *       update = "update Topic set postCount = postCount + 1 where id = :id")
+ *       //update = "update f_topic set post_count = post_count + 1 where id = :id")
+ *   })
+ *   @Entity
+ *   @Table(name = "f_topic")
+ *   public class Topic {
+ *     ...
+ *   }
  * }</pre>
  *
  * <p>

ebean-api/src/main/java/io/ebean/bean/BeanCollection.java

@@ -13,12 +13,10 @@ import java.util.Set;
  * from the Map Set or List. The purpose of gathering the additions and removals
  * is to support persisting ManyToMany objects. The additions and removals
  * become inserts and deletes from the intersection table.
- * </p>
  * <p>
  * Technically this is <em>NOT</em> an extension of
  * <em>java.util.Collection</em>. The reason being that java.util.Map is not a
  * Collection. I realise this makes this name confusing so I apologise for that.
- * </p>
  */
 public interface BeanCollection<E> extends Serializable {
 
@@ -68,7 +66,6 @@ public interface BeanCollection<E> extends Serializable {
    * Return true if the collection is uninitialised or is empty without any held modifications.
    * <p>
    * Returning true means can safely skip cascade save for this bean collection.
-   * </p>
    */
   boolean isSkipSave();
 
@@ -93,7 +90,6 @@ public interface BeanCollection<E> extends Serializable {
    * <p>
    * That is, if the collection was not loaded due to filterMany predicates etc
    * then make sure the collection is set to empty.
-   * </p>
    */
   boolean checkEmptyLazyLoad();
 
@@ -136,10 +132,7 @@ public interface BeanCollection<E> extends Serializable {
   boolean isReadOnly();
 
   /**
-   * Add the bean to the collection.
-   * <p>
-   * This is disallowed for BeanMap.
-   * </p>
+   * Add the bean to the collection. This is disallowed for BeanMap.
    */
   void internalAdd(Object bean);
 
@@ -168,7 +161,6 @@ public interface BeanCollection<E> extends Serializable {
    * Map.Entry.
    * <p>
    * For maps this returns the entrySet as we need the keys of the map.
-   * </p>
    */
   Collection<?> getActualEntries();
 
@@ -185,6 +177,11 @@ public interface BeanCollection<E> extends Serializable {
    */
   boolean isReference();
 
+  /**
+   * Return true if the collection is modify listening and has modifications.
+   */
+  boolean hasModifications();
+
   /**
    * Set modify listening on or off. This is used to keep track of objects that
    * have been added to or removed from the list set or map.
@@ -192,7 +189,6 @@ public interface BeanCollection<E> extends Serializable {
    * This is required only for ManyToMany collections. The additions and
    * deletions are used to insert or delete entries from the intersection table.
    * Otherwise modifyListening is false.
-   * </p>
    */
   void setModifyListening(ModifyListenMode modifyListenMode);
 
@@ -206,7 +202,6 @@ public interface BeanCollection<E> extends Serializable {
    * <p>
    * This will potentially end up as an insert into a intersection table for a
    * ManyToMany.
-   * </p>
    */
   void modifyAddition(E bean);
 
@@ -215,7 +210,6 @@ public interface BeanCollection<E> extends Serializable {
    * <p>
    * This will potentially end up as an delete from an intersection table for a
    * ManyToMany.
-   * </p>
    */
   void modifyRemoval(Object bean);
 

ebean-api/src/main/java/io/ebean/bean/BeanLoader.java

@@ -1,5 +1,7 @@
 package io.ebean.bean;
 
+import java.util.concurrent.locks.Lock;
+
 /**
  * Loads a entity bean.
  * <p>
@@ -18,4 +20,9 @@ public interface BeanLoader {
    */
   void loadBean(EntityBeanIntercept ebi);
 
+  /**
+   * Obtain a lock on the loader.
+   */
+  Lock lock();
+
 }

ebean-api/src/main/java/io/ebean/bean/EntityBean.java

@@ -27,17 +27,6 @@ public interface EntityBean extends Serializable {
     throw new NotEnhancedException();
   }
 
-  /**
-   * Return the enhancement marker value.
-   * <p>
-   * This is the class name of the enhanced class and used to check that all
-   * entity classes are enhanced (specifically not just a super class).
-   * </p>
-   */
-  default String _ebean_getMarker() {
-    throw new NotEnhancedException();
-  }
-
   /**
    * Create and return a new entity bean instance.
    */

ebean-api/src/main/java/io/ebean/bean/EntityBeanIntercept.java

@@ -14,6 +14,8 @@ import java.util.LinkedHashMap;
 import java.util.LinkedHashSet;
 import java.util.Map;
 import java.util.Set;
+import java.util.concurrent.locks.Lock;
+import java.util.concurrent.locks.ReentrantLock;
 
 /**
  * This is the object added to every entity bean using byte code enhancement.
@@ -30,35 +32,52 @@ public final class EntityBeanIntercept implements Serializable {
   private static final int STATE_REFERENCE = 1;
   private static final int STATE_LOADED = 2;
 
+  /**
+   * Used when a bean is partially filled.
+   */
+  private static final byte FLAG_LOADED_PROP = 1;
+  private static final byte FLAG_CHANGED_PROP = 2;
+  private static final byte FLAG_CHANGEDLOADED_PROP = 3;
+  /**
+   * Flags indicating if a property is a dirty embedded bean. Used to distinguish
+   * between an embedded bean being completely overwritten and one of its
+   * embedded properties being made dirty.
+   */
+  private static final byte FLAG_EMBEDDED_DIRTY = 4;
+  /**
+   * Flags indicating if a property is a dirty embedded bean. Used to distinguish
+   * between an embedded bean being completely overwritten and one of its
+   * embedded properties being made dirty.
+   */
+  private static final byte FLAG_ORIG_VALUE_SET = 8;
+
+  /**
+   * Flags indicating if the mutable hash is set.
+   */
+  private static final byte FLAG_MUTABLE_HASH_SET = 16;
+
+  private transient final ReentrantLock lock = new ReentrantLock();
   private transient NodeUsageCollector nodeUsageCollector;
-
   private transient PersistenceContext persistenceContext;
-
   private transient BeanLoader beanLoader;
-
   private transient PreGetterCallback preGetterCallback;
 
   private String ebeanServerName;
+  private boolean deletedFromCollection;
 
   /**
    * The actual entity bean that 'owns' this intercept.
    */
   private final EntityBean owner;
-
   private EntityBean embeddedOwner;
   private int embeddedOwnerIndex;
-
   /**
    * One of NEW, REF, UPD.
    */
   private int state;
-
   private boolean forceUpdate;
-
   private boolean readOnly;
-
   private boolean dirty;
-
   /**
    * Flag set to disable lazy loading - typically for SQL "report" type entity beans.
    */
@@ -68,41 +87,26 @@ public final class EntityBeanIntercept implements Serializable {
    * Flag set when lazy loading failed due to the underlying bean being deleted in the DB.
    */
   private boolean lazyLoadFailure;
-
-  /**
-   * Used when a bean is partially filled.
-   */
-  private static final byte FLAG_LOADED_PROP = 1;
-
-  /**
-   * Set of changed properties.
-   */
-  private static final byte FLAG_CHANGED_PROP = 2;
-
-  /**
-   * Flags indicating if a property is a dirty embedded bean. Used to distingush
-   * between an embedded bean being completely overwritten and one of its
-   * embedded properties being made dirty.
-   */
-  private static final byte FLAG_EMBEDDED_DIRTY = 4;
-
-  /**
-   * Flags indicating if a property is a dirty embedded bean. Used to distingush
-   * between an embedded bean being completely overwritten and one of its
-   * embedded properties being made dirty.
-   */
-  private static final byte FLAG_ORIG_VALUE_SET = 8;
-
-  private final byte[] flags;
-
   private boolean fullyLoadedBean;
   private boolean loadedFromCache;
+  private final byte[] flags;
   private Object[] origValues;
   private Exception[] loadErrors;
   private int lazyLoadProperty = -1;
   private Object ownerId;
   private int sortOrder;
 
+  /**
+   * Holds information of json loaded jackson beans (e.g. the original json or checksum).
+   */
+  private MutableValueInfo[] mutableInfo;
+
+  /**
+   * Holds json content determined at point of dirty check.
+   * Stored here on dirty check such that we only convert to json once.
+   */
+  private MutableValueNext[] mutableNext;
+
   /**
    * Create a intercept with a given entity.
    */
@@ -240,6 +244,17 @@ public final class EntityBeanIntercept implements Serializable {
    * if any embedded beans are either new or dirty (and hence need saving).
    */
   public boolean isDirty() {
+    if (dirty) {
+      return true;
+    }
+    if (mutableInfo != null) {
+      for (int i = 0; i < mutableInfo.length; i++) {
+        if (mutableInfo[i] != null && !mutableInfo[i].isEqualToObject(owner._ebean_getField(i))) {
+          dirty = true;
+          break;
+        }
+      }
+    }
     return dirty;
   }
 
@@ -369,28 +384,26 @@ public final class EntityBeanIntercept implements Serializable {
   /**
    * Set the loaded state to true.
    * <p>
-   * Calls to setter methods after the bean is loaded can result in 'Old Values'
-   * being created to support ConcurrencyMode.ALL
-   * </p>
+   * Calls to setter methods after the bean is loaded can result in
+   * 'Old Values' being created.
    * <p>
    * Worth noting that this is also set after a insert/update. By doing so it
    * 'resets' the bean for making further changes and saving again.
-   * </p>
    */
   public void setLoaded() {
     this.state = STATE_LOADED;
     this.owner._ebean_setEmbeddedLoaded();
     this.lazyLoadProperty = -1;
     this.origValues = null;
+    this.mutableNext = null;
     for (int i = 0; i < flags.length; i++) {
-      flags[i] &= ~(FLAG_CHANGED_PROP + FLAG_ORIG_VALUE_SET);
+      flags[i] &= ~(FLAG_CHANGED_PROP | FLAG_ORIG_VALUE_SET);
     }
     this.dirty = false;
   }
 
   /**
-   * When finished loading for lazy or refresh on an already partially populated
-   * bean.
+   * When finished loading for lazy or refresh on an already partially populated bean.
    */
   public void setLoadedLazy() {
     this.state = STATE_LOADED;
@@ -421,9 +434,6 @@ public final class EntityBeanIntercept implements Serializable {
 
   /**
    * Set true to turn off lazy loading.
-   * <p>
-   * Typically used to disable lazy loading on SQL based report beans.
-   * </p>
    */
   public void setDisableLazyLoad(boolean disableLazyLoad) {
     this.disableLazyLoad = disableLazyLoad;
@@ -443,7 +453,6 @@ public final class EntityBeanIntercept implements Serializable {
    * Return true if the embedded bean is new or dirty and hence needs saving.
    */
   public boolean isEmbeddedNewOrDirty(Object embeddedBean) {
-
     if (embeddedBean == null) {
       // if it was previously set then the owning bean would
       // have oldValues containing the previous embedded bean
@@ -451,7 +460,6 @@ public final class EntityBeanIntercept implements Serializable {
     }
     if (embeddedBean instanceof EntityBean) {
       return ((EntityBean) embeddedBean)._ebean_getIntercept().isNewOrDirty();
-
     } else {
       // non-enhanced so must assume it is new and needs to be saved
       return true;
@@ -462,6 +470,10 @@ public final class EntityBeanIntercept implements Serializable {
    * Return the original value that was changed via an update.
    */
   public Object getOrigValue(int propertyIndex) {
+    if ((flags[propertyIndex] & (FLAG_ORIG_VALUE_SET | FLAG_MUTABLE_HASH_SET)) == FLAG_MUTABLE_HASH_SET) {
+      // mutable hash set, but not ORIG_VALUE
+      setOriginalValue(propertyIndex, mutableInfo[propertyIndex].get());
+    }
     if (origValues == null) {
       return null;
     }
@@ -469,8 +481,8 @@ public final class EntityBeanIntercept implements Serializable {
   }
 
   /**
-   * Finds the index position of a given property. Returns -1 if the property
-   * can not be found.
+   * Finds the index position of a given property. Returns -1 if the
+   * property can not be found.
    */
   public int findProperty(String propertyName) {
     String[] names = owner._ebean_getPropertyNames();
@@ -493,10 +505,10 @@ public final class EntityBeanIntercept implements Serializable {
   }
 
   /**
-   * Return the number of properties.s
+   * Return the number of properties.
    */
   public int getPropertyLength() {
-    return owner._ebean_getPropertyNames().length;
+    return flags.length;
   }
 
   /**
@@ -515,8 +527,7 @@ public final class EntityBeanIntercept implements Serializable {
   }
 
   /**
-   * Set the property to be treated as unloaded. Used for properties initialised in default
-   * constructor.
+   * Set the property to be treated as unloaded. Used for properties initialised in default constructor.
    */
   public void setPropertyUnloaded(int propertyIndex) {
     flags[propertyIndex] &= ~FLAG_LOADED_PROP;
@@ -572,6 +583,10 @@ public final class EntityBeanIntercept implements Serializable {
     flags[propertyIndex] |= FLAG_CHANGED_PROP;
   }
 
+  private void setChangeLoaded(int propertyIndex) {
+    flags[propertyIndex] |= FLAG_CHANGEDLOADED_PROP;
+  }
+
   /**
    * Set that an embedded bean has had one of its properties changed.
    */
@@ -581,7 +596,7 @@ public final class EntityBeanIntercept implements Serializable {
 
   private void setOriginalValue(int propertyIndex, Object value) {
     if (origValues == null) {
-      origValues = new Object[owner._ebean_getPropertyNames().length];
+      origValues = new Object[flags.length];
     }
     if ((flags[propertyIndex] & FLAG_ORIG_VALUE_SET) == 0) {
       flags[propertyIndex] |= FLAG_ORIG_VALUE_SET;
@@ -594,7 +609,7 @@ public final class EntityBeanIntercept implements Serializable {
    */
   private void setOriginalValueForce(int propertyIndex, Object value) {
     if (origValues == null) {
-      origValues = new Object[owner._ebean_getPropertyNames().length];
+      origValues = new Object[flags.length];
     }
     origValues[propertyIndex] = value;
   }
@@ -603,7 +618,6 @@ public final class EntityBeanIntercept implements Serializable {
    * For forced update on a 'New' bean set all the loaded properties to changed.
    */
   public void setNewBeanForUpdate() {
-
     for (int i = 0; i < flags.length; i++) {
       if ((flags[i] & FLAG_LOADED_PROP) != 0) {
         flags[i] |= FLAG_CHANGED_PROP;
@@ -656,10 +670,9 @@ public final class EntityBeanIntercept implements Serializable {
   public void addDirtyPropertyNames(Set<String> props, String prefix) {
     int len = getPropertyLength();
     for (int i = 0; i < len; i++) {
-      if ((flags[i] & FLAG_CHANGED_PROP) != 0) {
+      if (isChangedProp(i)) {
         // the property has been changed on this bean
-        String propName = (prefix == null ? getProperty(i) : prefix + getProperty(i));
-        props.add(propName);
+        props.add((prefix == null ? getProperty(i) : prefix + getProperty(i)));
       } else if ((flags[i] & FLAG_EMBEDDED_DIRTY) != 0) {
         // an embedded property has been changed - recurse
         EntityBean embeddedBean = (EntityBean) owner._ebean_getField(i);
@@ -672,12 +685,10 @@ public final class EntityBeanIntercept implements Serializable {
    * Return true if any of the given property names are dirty.
    */
   public boolean hasDirtyProperty(Set<String> propertyNames) {
-
     String[] names = owner._ebean_getPropertyNames();
     int len = getPropertyLength();
     for (int i = 0; i < len; i++) {
-      if ((flags[i] & FLAG_CHANGED_PROP) != 0) {
-        // the property has been changed on this bean
+      if (isChangedProp(i)) {
         if (propertyNames.contains(names[i])) {
           return true;
         }
@@ -705,15 +716,14 @@ public final class EntityBeanIntercept implements Serializable {
   public void addDirtyPropertyValues(Map<String, ValuePair> dirtyValues, String prefix) {
     int len = getPropertyLength();
     for (int i = 0; i < len; i++) {
-      if ((flags[i] & FLAG_CHANGED_PROP) != 0) {
+      if (isChangedProp(i)) {
         // the property has been changed on this bean
         String propName = (prefix == null ? getProperty(i) : prefix + getProperty(i));
         Object newVal = owner._ebean_getField(i);
         Object oldVal = getOrigValue(i);
-        if (!areEqual(oldVal, newVal)) {
+        if (notEqual(oldVal, newVal)) {
           dirtyValues.put(propName, new ValuePair(newVal, oldVal));
         }
-
       } else if ((flags[i] & FLAG_EMBEDDED_DIRTY) != 0) {
         // an embedded property has been changed - recurse
         EntityBean embeddedBean = (EntityBean) owner._ebean_getField(i);
@@ -728,14 +738,13 @@ public final class EntityBeanIntercept implements Serializable {
   public void addDirtyPropertyValues(BeanDiffVisitor visitor) {
     int len = getPropertyLength();
     for (int i = 0; i < len; i++) {
-      if ((flags[i] & FLAG_CHANGED_PROP) != 0) {
+      if (isChangedProp(i)) {
         // the property has been changed on this bean
         Object newVal = owner._ebean_getField(i);
         Object oldVal = getOrigValue(i);
-        if (!areEqual(oldVal, newVal)) {
+        if (notEqual(oldVal, newVal)) {
           visitor.visit(i, newVal, oldVal);
         }
-
       } else if ((flags[i] & FLAG_EMBEDDED_DIRTY) != 0) {
         // an embedded property has been changed - recurse
         EntityBean embeddedBean = (EntityBean) owner._ebean_getField(i);
@@ -756,7 +765,7 @@ public final class EntityBeanIntercept implements Serializable {
   }
 
   /**
-   * Add and return a dirty property hash recursing into embedded beans.
+   * Add and return a dirty property hash.
    */
   private void addDirtyPropertyKey(StringBuilder sb) {
     if (sortOrder > 0) {
@@ -764,7 +773,7 @@ public final class EntityBeanIntercept implements Serializable {
     }
     int len = getPropertyLength();
     for (int i = 0; i < len; i++) {
-      if ((flags[i] & FLAG_CHANGED_PROP) != 0) {
+      if ((flags[i] & FLAG_CHANGED_PROP) != 0) { // we do not check against mutablecontent here.
         sb.append(i).append(',');
       } else if ((flags[i] & FLAG_EMBEDDED_DIRTY) != 0) {
         // an embedded property has been changed - recurse
@@ -816,25 +825,28 @@ public final class EntityBeanIntercept implements Serializable {
    * Load the bean when it is a reference.
    */
   protected void loadBean(int loadProperty) {
-
-    synchronized (this) {
+    lock.lock();
+    try {
       if (beanLoader == null) {
         final Database database = DB.byName(ebeanServerName);
         if (database == null) {
           throw new PersistenceException("Database [" + ebeanServerName + "] was not found?");
         }
-
         // For stand alone reference bean or after deserialisation lazy load
         // using the ebeanServer. Synchronise only on the bean.
-        loadBeanInternal(loadProperty, database.getPluginApi());
+        loadBeanInternal(loadProperty, database.getPluginApi().beanLoader());
         return;
       }
+    } finally {
+      lock.unlock();
     }
-
-    synchronized (beanLoader) {
+    final Lock lock = beanLoader.lock();
+    try {
       // Lazy loading using LoadBeanContext which supports batch loading
       // Synchronise on the beanLoader (a 'node' of the LoadBeanContext 'tree')
       loadBeanInternal(loadProperty, beanLoader);
+    } finally {
+      lock.unlock();
     }
   }
 
@@ -842,32 +854,24 @@ public final class EntityBeanIntercept implements Serializable {
    * Invoke the lazy loading. This method is synchronised externally.
    */
   private void loadBeanInternal(int loadProperty, BeanLoader loader) {
-
     if ((flags[loadProperty] & FLAG_LOADED_PROP) != 0) {
       // race condition where multiple threads calling preGetter concurrently
       return;
     }
-
     if (lazyLoadFailure) {
       // failed when batch lazy loaded by another bean in the batch
       throw new EntityNotFoundException("(Lazy) loading failed on type:" + owner.getClass().getName() + " id:" + ownerId + " - Bean has been deleted");
     }
-
     if (lazyLoadProperty == -1) {
-
       lazyLoadProperty = loadProperty;
-
       if (nodeUsageCollector != null) {
         nodeUsageCollector.setLoadProperty(getProperty(lazyLoadProperty));
       }
-
       loader.loadBean(this);
-
       if (lazyLoadFailure) {
         // failed when lazy loading this bean
         throw new EntityNotFoundException("Lazy loading failed on type:" + owner.getClass().getName() + " id:" + ownerId + " - Bean has been deleted.");
       }
-
       // bean should be loaded and intercepting now. setLoaded() has
       // been called by the lazy loading mechanism
     }
@@ -877,32 +881,31 @@ public final class EntityBeanIntercept implements Serializable {
    * Helper method to check if two objects are equal.
    */
   @SuppressWarnings({"unchecked", "rawtypes"})
-  protected boolean areEqual(Object obj1, Object obj2) {
+  protected static boolean notEqual(Object obj1, Object obj2) {
     if (obj1 == null) {
-      return (obj2 == null);
+      return (obj2 != null);
     }
     if (obj2 == null) {
-      return false;
+      return true;
     }
     if (obj1 == obj2) {
-      return true;
+      return false;
     }
     if (obj1 instanceof BigDecimal) {
       // Use comparable for BigDecimal as equals
       // uses scale in comparison...
       if (obj2 instanceof BigDecimal) {
         Comparable com1 = (Comparable) obj1;
-        return (com1.compareTo(obj2) == 0);
-
+        return (com1.compareTo(obj2) != 0);
       } else {
-        return false;
+        return true;
       }
     }
     if (obj1 instanceof URL) {
       // use the string format to determine if dirty
-      return obj1.toString().equals(obj2.toString());
+      return !obj1.toString().equals(obj2.toString());
     }
-    return obj1.equals(obj2);
+    return !obj1.equals(obj2);
   }
 
   /**
@@ -913,6 +916,7 @@ public final class EntityBeanIntercept implements Serializable {
   }
 
   private void preGetterCallback(int propertyIndex) {
+    PreGetterCallback preGetterCallback = this.preGetterCallback;
     if (preGetterCallback != null) {
       preGetterCallback.preGetterTrigger(propertyIndex);
     }
@@ -942,25 +946,24 @@ public final class EntityBeanIntercept implements Serializable {
   }
 
   /**
-   * OneToMany and ManyToMany don't have any interception so just check for
-   * PropertyChangeSupport.
+   * OneToMany and ManyToMany only set loaded state.
    */
   public void preSetterMany(boolean interceptField, int propertyIndex, Object oldValue, Object newValue) {
-
-    if (readOnly) {
-      throw new IllegalStateException("This bean is readOnly");
+    if (state == STATE_NEW) {
+      setLoadedProperty(propertyIndex);
+    } else {
+      if (readOnly) {
+        throw new IllegalStateException("This bean is readOnly");
+      }
+      setChangeLoaded(propertyIndex);
     }
-
-    setLoadedProperty(propertyIndex);
   }
 
   private void setChangedPropertyValue(int propertyIndex, boolean setDirtyState, Object origValue) {
-
     if (readOnly) {
       throw new IllegalStateException("This bean is readOnly");
     }
     setChangedProperty(propertyIndex);
-
     if (setDirtyState) {
       setOriginalValue(propertyIndex, origValue);
       setDirtyStatus();
@@ -985,20 +988,17 @@ public final class EntityBeanIntercept implements Serializable {
    * the old values for use with ConcurrencyMode.ALL.
    */
   public void preSetter(boolean intercept, int propertyIndex, Object oldValue, Object newValue) {
-
     if (state == STATE_NEW) {
       setLoadedProperty(propertyIndex);
-    } else if (!areEqual(oldValue, newValue)) {
+    } else if (notEqual(oldValue, newValue)) {
       setChangedPropertyValue(propertyIndex, intercept, oldValue);
     }
   }
 
-
   /**
    * Check for primitive boolean.
    */
   public void preSetter(boolean intercept, int propertyIndex, boolean oldValue, boolean newValue) {
-
     if (state == STATE_NEW) {
       setLoadedProperty(propertyIndex);
     } else if (oldValue != newValue) {
@@ -1010,7 +1010,6 @@ public final class EntityBeanIntercept implements Serializable {
    * Check for primitive int.
    */
   public void preSetter(boolean intercept, int propertyIndex, int oldValue, int newValue) {
-
     if (state == STATE_NEW) {
       setLoadedProperty(propertyIndex);
     } else if (oldValue != newValue) {
@@ -1022,7 +1021,6 @@ public final class EntityBeanIntercept implements Serializable {
    * long.
    */
   public void preSetter(boolean intercept, int propertyIndex, long oldValue, long newValue) {
-
     if (state == STATE_NEW) {
       setLoadedProperty(propertyIndex);
     } else if (oldValue != newValue) {
@@ -1034,7 +1032,6 @@ public final class EntityBeanIntercept implements Serializable {
    * double.
    */
   public void preSetter(boolean intercept, int propertyIndex, double oldValue, double newValue) {
-
     if (state == STATE_NEW) {
       setLoadedProperty(propertyIndex);
     } else if (Double.compare(oldValue, newValue) != 0) {
@@ -1046,7 +1043,6 @@ public final class EntityBeanIntercept implements Serializable {
    * float.
    */
   public void preSetter(boolean intercept, int propertyIndex, float oldValue, float newValue) {
-
     if (state == STATE_NEW) {
       setLoadedProperty(propertyIndex);
     } else if (Float.compare(oldValue, newValue) != 0) {
@@ -1058,7 +1054,6 @@ public final class EntityBeanIntercept implements Serializable {
    * short.
    */
   public void preSetter(boolean intercept, int propertyIndex, short oldValue, short newValue) {
-
     if (state == STATE_NEW) {
       setLoadedProperty(propertyIndex);
     } else if (oldValue != newValue) {
@@ -1070,7 +1065,6 @@ public final class EntityBeanIntercept implements Serializable {
    * char.
    */
   public void preSetter(boolean intercept, int propertyIndex, char oldValue, char newValue) {
-
     if (state == STATE_NEW) {
       setLoadedProperty(propertyIndex);
     } else if (oldValue != newValue) {
@@ -1082,7 +1076,6 @@ public final class EntityBeanIntercept implements Serializable {
    * byte.
    */
   public void preSetter(boolean intercept, int propertyIndex, byte oldValue, byte newValue) {
-
     if (state == STATE_NEW) {
       setLoadedProperty(propertyIndex);
     } else if (oldValue != newValue) {
@@ -1094,7 +1087,6 @@ public final class EntityBeanIntercept implements Serializable {
    * char[].
    */
   public void preSetter(boolean intercept, int propertyIndex, char[] oldValue, char[] newValue) {
-
     if (state == STATE_NEW) {
       setLoadedProperty(propertyIndex);
     } else if (!Arrays.equals(oldValue, newValue)) {
@@ -1106,7 +1098,6 @@ public final class EntityBeanIntercept implements Serializable {
    * byte[].
    */
   public void preSetter(boolean intercept, int propertyIndex, byte[] oldValue, byte[] newValue) {
-
     if (state == STATE_NEW) {
       setLoadedProperty(propertyIndex);
     } else if (!Arrays.equals(oldValue, newValue)) {
@@ -1137,12 +1128,23 @@ public final class EntityBeanIntercept implements Serializable {
     this.sortOrder = sortOrder;
   }
 
+  /**
+   * Set if the entity was deleted from a BeanCollection.
+   */
+  public void setDeletedFromCollection(final boolean deletedFromCollection) {
+    this.deletedFromCollection = deletedFromCollection;
+  }
+
+  public boolean isOrphanDelete() {
+    return deletedFromCollection && !isNew();
+  }
+
   /**
    * Set the load error that happened on this property.
    */
   public void setLoadError(int propertyIndex, Exception t) {
     if (loadErrors == null) {
-      loadErrors = new Exception[owner._ebean_getPropertyNames().length];
+      loadErrors = new Exception[flags.length];
     }
     loadErrors[propertyIndex] = t;
     flags[propertyIndex] |= FLAG_LOADED_PROP;
@@ -1168,4 +1170,62 @@ public final class EntityBeanIntercept implements Serializable {
     }
     return ret;
   }
+
+  private boolean isChangedProp(int i) {
+    if ((flags[i] & FLAG_CHANGED_PROP) != 0) {
+      return true;
+    } else if (mutableInfo == null || mutableInfo[i] == null || mutableInfo[i].isEqualToObject(owner._ebean_getField(i))) {
+      return false;
+    } else {
+      // mark for change
+      flags[i] |= FLAG_CHANGED_PROP;
+      dirty = true; // this makes the bean automatically dirty!
+      return true;
+    }
+  }
+
+  /**
+   * Return the MutableValueInfo for the given property or null.
+   */
+  public MutableValueInfo mutableInfo(int propertyIndex) {
+    return mutableInfo == null ? null : mutableInfo[propertyIndex];
+  }
+
+  /**
+   * Set the MutableValueInfo for the given property.
+   */
+  public void mutableInfo(int propertyIndex, MutableValueInfo info) {
+    if (mutableInfo == null) {
+      mutableInfo = new MutableValueInfo[flags.length];
+    }
+    flags[propertyIndex] |= FLAG_MUTABLE_HASH_SET;
+    mutableInfo[propertyIndex] = info;
+  }
+
+  /**
+   * Dirty detection set the next mutable property content and info .
+   * <p>
+   * Set here as the mutable property dirty detection is based on json content comparison.
+   * We only want to perform the json serialisation once so storing it here as part of
+   * dirty detection so that we can get it back to bind in insert or update etc.
+   */
+  public void mutableNext(int propertyIndex, MutableValueNext next) {
+    if (mutableNext == null) {
+      mutableNext = new MutableValueNext[flags.length];
+    }
+    mutableNext[propertyIndex] = next;
+  }
+
+  /**
+   * Update the 'next' mutable info returning the content that was obtained via dirty detection.
+   */
+  public String mutableNext(int propertyIndex) {
+    if (mutableNext == null) {
+      return null;
+    }
+    final MutableValueNext next = mutableNext[propertyIndex];
+    mutableInfo(propertyIndex, next.info());
+    return next.content();
+  }
+
 }

ebean-api/src/main/java/io/ebean/bean/MutableValueInfo.java

@@ -0,0 +1,42 @@
+package io.ebean.bean;
+
+/**
+ * Holds information on mutable values (like plain beans stored as json).
+ * <p>
+ * Used internally in EntityBeanIntercept for dirty detection on mutable values.
+ * Typically, mutation detection is based on a hash/checksum of json content or the
+ * original json content itself.
+ * <p>
+ * Refer to the mapping options {@code @DbJson(mutationDetection)}.
+ */
+public interface MutableValueInfo {
+
+  /**
+   * Compares the given json returning null if deemed unchanged or returning
+   * the MutableValueNext to use if deemed dirty/changed.
+   * <p>
+   * Returning MutableValueNext allows an implementation based on hash/checksum
+   * to only perform that computation once.
+   *
+   * @return Null if deemed unchanged or the MutableValueNext if deemed changed.
+   */
+  MutableValueNext nextDirty(String json);
+
+  /**
+   * Compares the given object to an internal value.
+   * <p>
+   * This is used to support changelog/beanState. The implementation can serialize the
+   * object into json form and compare it against the original json.
+   */
+  boolean isEqualToObject(Object obj);
+
+  /**
+   * Creates a new instance from the internal json string.
+   * <p>
+   * This is used to provide an original/old value for change logging / persist listeners.
+   * This is only available for properties that have {@code @DbJson(keepSource=true)}.
+   */
+  default Object get() {
+    return null;
+  }
+}

ebean-api/src/main/java/io/ebean/bean/MutableValueNext.java

@@ -0,0 +1,17 @@
+package io.ebean.bean;
+
+/**
+ * Represents a next value to use for mutable content properties (DbJson with jackson beans).
+ */
+public interface MutableValueNext {
+
+  /**
+   * Return the next content to use. Provided such that we serialise to json once.
+   */
+  String content();
+
+  /**
+   * Return the next MutableValueInfo to use after an update.
+   */
+  MutableValueInfo info();
+}

ebean-api/src/main/java/io/ebean/bean/PersistenceContext.java

@@ -5,7 +5,6 @@ package io.ebean.bean;
  * <p>
  * This is used to ensure only one instance for a given entity type and id is
  * used to build object graphs from queries and lazy loading.
- * </p>
  */
 public interface PersistenceContext {
 
@@ -20,7 +19,6 @@ public interface PersistenceContext {
    * <p>
    * Returns an existing entity bean (if one is already there) and otherwise
    * returns null.
-   * </p>
    */
   Object putIfAbsent(Class<?> rootType, Object id, Object bean);
 
@@ -61,12 +59,27 @@ public interface PersistenceContext {
    */
   int size(Class<?> rootType);
 
+  /**
+   * Return a copy of the Persistence context to use for large query iteration.
+   */
+  PersistenceContext forIterate();
+
+  /**
+   * Return a new Persistence context during iteration of large query result.
+   */
+  PersistenceContext forIterateReset();
+
+  /**
+   * Return true if the persistence context has grown and hit the 'reset limit'
+   * during large query iteration.
+   */
+  boolean resetLimit();
+
   /**
    * Wrapper on a bean to also indicate if a bean has been deleted.
    * <p>
    * If a bean has been deleted then for the same persistence context is should
    * not be able to be fetched from persistence context or L2 cache.
-   * </p>
    */
   class WithOption {
 

ebean-api/src/main/java/io/ebean/bean/SingleBeanLoader.java

@@ -2,11 +2,16 @@ package io.ebean.bean;
 
 import io.ebean.Database;
 
+import java.util.concurrent.locks.Lock;
+import java.util.concurrent.locks.ReentrantLock;
+
 /**
  * BeanLoader used when single beans are loaded (which is usually not ideal / N+1).
  */
 public abstract class SingleBeanLoader implements BeanLoader {
 
+  private final ReentrantLock lock = new ReentrantLock();
+
   protected final Database database;
 
   SingleBeanLoader(Database database) {
@@ -18,6 +23,12 @@ public abstract class SingleBeanLoader implements BeanLoader {
     return database.getName();
   }
 
+  @Override
+  public Lock lock() {
+    lock.lock();
+    return lock;
+  }
+
   /**
    * Single bean lazy loaded when bean from L2 cache.
    */
@@ -45,4 +56,18 @@ public abstract class SingleBeanLoader implements BeanLoader {
       database.getPluginApi().loadBeanRef(ebi);
     }
   }
+
+  /**
+   * Single bean lazy loaded when a reference bean.
+   */
+  public static class Dflt extends SingleBeanLoader {
+    public Dflt(Database database) {
+      super(database);
+    }
+
+    @Override
+    public void loadBean(EntityBeanIntercept ebi) {
+      database.getPluginApi().loadBean(ebi);
+    }
+  }
 }