Merge remote-tracking branch 'upstream/master'

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

@@ -3,8 +3,7 @@ package io.ebean;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-import java.io.IOException;
-import java.io.InputStream;
+import java.io.*;
 import java.util.Properties;
 
 /**
@@ -29,9 +28,11 @@ public final class EbeanVersion {
 
   private static void readVersion() {
     try {
-      try (InputStream in = ClassLoader.getSystemResourceAsStream("META-INF/maven/io.ebean/ebean-api/pom.properties")) {
+      try (InputStream in = ClassLoader.getSystemResourceAsStream("META-INF/ebean-maven-version.txt")) {
         if (in != null) {
-          version = readVersion(in);
+          try (LineNumberReader reader = new LineNumberReader(new InputStreamReader(in))) {
+            version = reader.readLine();
+          }
         }
       }
       log.info("ebean version: {}", version);
@@ -88,7 +89,7 @@ public final class EbeanVersion {
   }
 
   /**
-   * Returns the ebean version (read from /META-INF/maven/io.ebean/ebean/pom.properties)
+   * Returns the ebean version (read from META-INF/ebean-maven-version.txt)
    */
   public static String getVersion() {
     return version;

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

@@ -1579,10 +1579,11 @@ public interface Query<T> extends CancelableQuery {
   Query<T> setReadOnly(boolean readOnly);
 
   /**
-   * Will be deprecated - migrate to use setBeanCacheMode(CacheMode.RECACHE).
+   * Deprecated - migrate to use setBeanCacheMode(CacheMode.PUT) or other CacheMode.
    * <p>
    * When set to true all the beans from this query are loaded into the bean cache.
    */
+  @Deprecated
   Query<T> setLoadBeanCache(boolean loadBeanCache);
 
   /**

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

@@ -6,6 +6,12 @@ import java.io.Serializable;
 import java.util.Map;
 import java.util.Set;
 
+/**
+ * This is the object associated to every entity bean using byte code enhancement.
+ * <p>
+ * This provides per property state such as loaded state, changed state, original values
+ * as well as bean level dirty state etc.
+ */
 public interface EntityBeanIntercept extends Serializable {
 
   /**
@@ -282,8 +288,14 @@ public interface EntityBeanIntercept extends Serializable {
    */
   void markPropertyAsChanged(int propertyIndex);
 
+  /**
+   * Set the changed state for the given property.
+   */
   void setChangedProperty(int propertyIndex);
 
+  /**
+   * Set the changed and loaded state for the given property.
+   */
   void setChangeLoaded(int propertyIndex);
 
   /**
@@ -291,6 +303,9 @@ public interface EntityBeanIntercept extends Serializable {
    */
   void setEmbeddedPropertyDirty(int propertyIndex);
 
+  /**
+   * Set the original value for the property.
+   */
   void setOriginalValue(int propertyIndex, Object value);
 
   /**
@@ -358,6 +373,9 @@ public interface EntityBeanIntercept extends Serializable {
    */
   StringBuilder getLoadedPropertyKey();
 
+  /**
+   * Return the loaded state for all the properties.
+   */
   boolean[] getLoaded();
 
   /**
@@ -385,6 +403,9 @@ public interface EntityBeanIntercept extends Serializable {
    */
   void initialisedMany(int propertyIndex);
 
+  /**
+   * Invoke the PreGetterCallback if it has been set due to getter for the given property.
+   */
   void preGetterCallback(int propertyIndex);
 
   /**
@@ -402,8 +423,14 @@ public interface EntityBeanIntercept extends Serializable {
    */
   void preSetterMany(boolean interceptField, int propertyIndex, Object oldValue, Object newValue);
 
+  /**
+   * Set the property changed state, bean dirtyState and property original value.
+   */
   void setChangedPropertyValue(int propertyIndex, boolean setDirtyState, Object origValue);
 
+  /**
+   * Set the dirty state on the bean.
+   */
   void setDirtyStatus();
 
   /**
@@ -482,6 +509,9 @@ public interface EntityBeanIntercept extends Serializable {
    */
   void setDeletedFromCollection(boolean deletedFromCollection);
 
+  /**
+   * Return true if the bean was orphan deleted from a collection.
+   */
   boolean isOrphanDelete();
 
   /**
@@ -494,7 +524,10 @@ public interface EntityBeanIntercept extends Serializable {
    */
   Map<String, Exception> getLoadErrors();
 
-  boolean isChangedProp(int i);
+  /**
+   * Return true if the property has its changed state set.
+   */
+  boolean isChangedProp(int propertyIndex);
 
   /**
    * Return the MutableValueInfo for the given property or null.

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

@@ -6,10 +6,20 @@ import java.util.Collections;
 import java.util.Map;
 import java.util.Set;
 
+/**
+ * EntityBeanIntercept optimised for read only use.
+ * <p>
+ * For the read only use this intercept doesn't need to hold any state that is normally
+ * required for updates such as per property changed, loaded, dirty state, original values
+ * bean state etc.
+ */
 public class InterceptReadOnly implements EntityBeanIntercept {
 
   private final EntityBean owner;
 
+  /**
+   * Create with a given entity.
+   */
   public InterceptReadOnly(Object ownerBean) {
     this.owner = (EntityBean) ownerBean;
   }

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

@@ -21,7 +21,6 @@ import java.util.concurrent.locks.ReentrantLock;
  * <p>
  * This provides the mechanisms to support deferred fetching of reference beans
  * and oldValues generation for concurrency checking.
- * </p>
  */
 public final class InterceptReadWrite implements EntityBeanIntercept {
 
@@ -32,24 +31,17 @@ public final class InterceptReadWrite implements EntityBeanIntercept {
   private static final int STATE_LOADED = 2;
 
   /**
-   * Used when a bean is partially filled.
+   * Used when a bean is partially loaded.
    */
   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.
+   * Flags indicating if a property is a dirty embedded bean. Used to distinguish between an
+   * embedded bean being completely overwritten vs one with embedded properties that are 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.
    */
@@ -78,10 +70,9 @@ public final class InterceptReadWrite implements EntityBeanIntercept {
   private boolean readOnly;
   private boolean dirty;
   /**
-   * Flag set to disable lazy loading - typically for SQL "report" type entity beans.
+   * Flag set to disable lazy loading.
    */
   private boolean disableLazyLoad;
-
   /**
    * Flag set when lazy loading failed due to the underlying bean being deleted in the DB.
    */
@@ -107,7 +98,7 @@ public final class InterceptReadWrite implements EntityBeanIntercept {
   private MutableValueNext[] mutableNext;
 
   /**
-   * Create a intercept with a given entity.
+   * Create with a given entity.
    */
   public InterceptReadWrite(Object ownerBean) {
     this.owner = (EntityBean) ownerBean;

ebean-api/src/main/java/io/ebean/meta/BasicMetricVisitor.java

@@ -8,22 +8,33 @@ import java.util.List;
  */
 public class BasicMetricVisitor extends AbstractMetricVisitor implements ServerMetrics {
 
+  private final String name;
   private final List<MetaTimedMetric> timed = new ArrayList<>();
   private final List<MetaQueryMetric> query = new ArrayList<>();
   private final List<MetaCountMetric> count = new ArrayList<>();
 
+  public BasicMetricVisitor() {
+    this("db");
+  }
+
   /**
    * Construct to reset and collect everything.
    */
-  public BasicMetricVisitor() {
-    super(true, true, true, true);
+  public BasicMetricVisitor(String name) {
+    this(name, true, true, true, true);
   }
 
   /**
    * Construct specifying reset and what to collect.
    */
-  public BasicMetricVisitor(boolean reset, boolean collectTransactionMetrics, boolean collectQueryMetrics, boolean collectL2Metrics) {
+  public BasicMetricVisitor(String name, boolean reset, boolean collectTransactionMetrics, boolean collectQueryMetrics, boolean collectL2Metrics) {
     super(reset, collectTransactionMetrics, collectQueryMetrics, collectL2Metrics);
+    this.name = name;
+  }
+
+  @Override
+  public String name() {
+    return name;
   }
 
   @Override

ebean-api/src/main/java/io/ebean/meta/MetaInfoManager.java

@@ -16,6 +16,17 @@ public interface MetaInfoManager {
    */
   ServerMetrics collectMetrics();
 
+  /**
+   * Given the already collected metrics provide them in json form.
+   * <p>
+   * Expected to be used when we wish to collect the metrics and report them
+   * to some service and additionally format them as json for say output into
+   * an application log.
+   *
+   * @param metrics The already collected metrics
+   */
+  ServerMetricsAsJson metricsAsJson(ServerMetrics metrics);
+
   /**
    * Collect the metrics in raw JSON form.
    * <pre>{@code

ebean-api/src/main/java/io/ebean/meta/ServerMetrics.java

@@ -7,6 +7,11 @@ import java.util.List;
  */
 public interface ServerMetrics {
 
+  /**
+   * Return the name of the database these metrics were obtained for.
+   */
+  String name();
+
   /**
    * Return timed metrics for Transactions, labelled SqlQuery, labelled SqlUpdate.
    */

ebean-api/src/main/resources/META-INF/ebean-maven-version.txt

@@ -0,0 +1 @@
+${project.version}