From afaacd4eeb7bc1b0ef3440f73df22799fae3a064 Mon Sep 17 00:00:00 2001
From: Robin Bygrave <robin.bygrave@gmail.com>
Date: Mon, 23 Nov 2015 23:26:09 +1300
Subject: [PATCH] #461 - ENH: Add @Draftable support - javadoc

---
 src/main/java/com/avaje/ebean/EbeanServer.java     |  8 ++++----
 .../com/avaje/ebean/annotation/DraftDirty.java     |  4 ++++
 .../java/com/avaje/ebean/annotation/DraftOnly.java |  4 ++++
 .../java/com/avaje/ebean/annotation/Draftable.java | 14 ++++++++++++++
 .../avaje/ebean/annotation/DraftableElement.java   |  8 ++++++--
 5 files changed, 32 insertions(+), 6 deletions(-)

diff --git a/src/main/java/com/avaje/ebean/EbeanServer.java b/src/main/java/com/avaje/ebean/EbeanServer.java
index 3af896938..b7b74ae9e 100644
--- a/src/main/java/com/avaje/ebean/EbeanServer.java
+++ b/src/main/java/com/avaje/ebean/EbeanServer.java
@@ -1820,7 +1820,7 @@ public interface EbeanServer {
   JsonContext json();
 
   /**
-   * Publish a single bean given its type and id.
+   * Publish a single bean given its type and id returning the resulting live bean.
    * <p>
    * The values are published from the draft to the live bean.
    * </p>
@@ -1828,19 +1828,19 @@ public interface EbeanServer {
    * @param <T>         the type of the entity bean
    * @param beanType    the type of the entity bean
    * @param id          the id of the entity bean
-   * @param transaction the transaction the publish process should use
+   * @param transaction the transaction the publish process should use (can be null)
    */
   <T> T publish(Class<T> beanType, Object id, Transaction transaction);
 
   /**
-   * Publish the beans that match the query.
+   * Publish the beans that match the query returning the resulting published beans.
    * <p>
    * The values are published from the draft beans to the live beans.
    * </p>
    *
    * @param <T>         the type of the entity bean
    * @param query       the query used to select the draft beans to publish
-   * @param transaction the transaction the publish process should use
+   * @param transaction the transaction the publish process should use (can be null)
    */
   <T> List<T> publish(Query<T> query, Transaction transaction);
 
diff --git a/src/main/java/com/avaje/ebean/annotation/DraftDirty.java b/src/main/java/com/avaje/ebean/annotation/DraftDirty.java
index 5cb9e6b65..1ae2e895a 100644
--- a/src/main/java/com/avaje/ebean/annotation/DraftDirty.java
+++ b/src/main/java/com/avaje/ebean/annotation/DraftDirty.java
@@ -8,6 +8,10 @@ import java.lang.annotation.Target;
 /**
  * Marks a boolean property on a @Draftable bean that only exists on the 'draft' table
  * and is used to detect when a draft has unpublished changes.
+ * <p>
+ * This property will automatically have it's value set to true when a draft is saved and
+ * automatically have it's value set to false when the bean is published.
+ * </p>
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.FIELD)
diff --git a/src/main/java/com/avaje/ebean/annotation/DraftOnly.java b/src/main/java/com/avaje/ebean/annotation/DraftOnly.java
index 57d793e0f..5c7029bdb 100644
--- a/src/main/java/com/avaje/ebean/annotation/DraftOnly.java
+++ b/src/main/java/com/avaje/ebean/annotation/DraftOnly.java
@@ -7,6 +7,10 @@ import java.lang.annotation.Target;
 
 /**
  * Marks a property on a @Draftable bean that only exists on the 'draft' and not the 'live' table.
+ * <p>
+ * Typically this would be used on a property that is used as part of application 'workflow' such as
+ * a publish workflow status or when publish timestamp.
+ * </p>
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.FIELD)
diff --git a/src/main/java/com/avaje/ebean/annotation/Draftable.java b/src/main/java/com/avaje/ebean/annotation/Draftable.java
index 5110596b8..15e14369b 100644
--- a/src/main/java/com/avaje/ebean/annotation/Draftable.java
+++ b/src/main/java/com/avaje/ebean/annotation/Draftable.java
@@ -7,6 +7,20 @@ import java.lang.annotation.Target;
 
 /**
  * Used to indicate an entity bean that has 'draftable' support.
+ * <p>
+ * This means that a second set of tables is created to hold draft versions of
+ * the rows and that these can then be published which effectively copies/transfers
+ * the values from the 'draft' table to the 'live' table.
+ * </p>
+ * <p>
+ * Ebean Query supports 'find as draft' which builds the resulting object graph using
+ * the draft tables. This object graph is typically edited, approved in some application
+ * specific manor and then published.
+ * </p>
+ * <p>
+ * EbeanServer has a publish method which transfers/copies the draft object graph to
+ * the 'live' tables.
+ * </p>
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
diff --git a/src/main/java/com/avaje/ebean/annotation/DraftableElement.java b/src/main/java/com/avaje/ebean/annotation/DraftableElement.java
index 36dce8986..a932c8e36 100644
--- a/src/main/java/com/avaje/ebean/annotation/DraftableElement.java
+++ b/src/main/java/com/avaje/ebean/annotation/DraftableElement.java
@@ -6,8 +6,12 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Used to indicate an entity bean that has 'draftable' support but it not a 'root level' bean
- * but instead child related to another @Draftable entity bean.
+ * Used to indicate an entity bean that has 'draftable' support but it not a 'top level'
+ * (or root level) bean but instead child related to another @Draftable entity bean.
+ * <p>
+ * Relationships to @DraftableElements (@OneToMany, @ManyToMany etc) are automatically
+ * deemed to have Cascade.ALL for save and delete (as well as orphan removal mode).
+ * </p>
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)