From e3ca5d2419fcd5ace6f276c8c9c52fae3dde1249 Mon Sep 17 00:00:00 2001 From: rob bygrave Date: Thu, 7 Mar 2019 12:01:05 +1300 Subject: [PATCH] Javadoc update using "DB" and hide DB constructor --- src/main/java/io/ebean/DB.java | 146 ++++++++++++--------------- src/main/java/io/ebean/overview.html | 126 ++--------------------- src/main/java/io/ebean/package.html | 60 ++++------- 3 files changed, 91 insertions(+), 241 deletions(-) diff --git a/src/main/java/io/ebean/DB.java b/src/main/java/io/ebean/DB.java index 198795856..db386a5e5 100644 --- a/src/main/java/io/ebean/DB.java +++ b/src/main/java/io/ebean/DB.java @@ -22,11 +22,11 @@ import java.util.concurrent.Callable; *

* DB additionally provides a convenient way to use the 'default' Database. *

- *

Default database

- *

- * One of the Database instances can be registered as the "default database" - * and can be obtained using DB.getDefault() - *

+ *

Default database

+ *

+ * One of the Database instances can be registered as the "default database" + * and can be obtained using DB.getDefault() + *

* 
{@code
  *
  * Database database = DB.getDefault();
@@ -35,8 +35,8 @@ import java.util.concurrent.Callable;
  *
  * 
Named database

  * 

- *   Multiple database instances can be registered with DB and we can obtain them
- *   using DB.byName()
+ * Multiple database instances can be registered with DB and we can obtain them
+ * using DB.byName()
  * 

  * 
{@code
  *
@@ -46,23 +46,29 @@ import java.util.concurrent.Callable;
  *
  * 
Convenience methods

  * 

- *   DB has methods like {@link #find(Class)} and {@link #save(Object)} which are
- *   just convenience for using the default database.
+ * DB has methods like {@link #find(Class)} and {@link #save(Object)} which are
+ * just convenience for using the default database.
  * 

  *
  * 
{@code
  *
- *   // fetch using the default database
- *   Order order = DB.find(Order.class, 10);
+ * // fetch using the default database
+ * Order order = DB.find(Order.class, 10);
  *
- *   // is the same as
- *   Database database = DB.getDefault();
- *   Order order = database.find(Order.class, 10);
+ * // is the same as
+ * Database database = DB.getDefault();
+ * Order order = database.find(Order.class, 10);
  *
  * }

  */
 public class DB {
 
+  /**
+   * Hide constructor.
+   */
+  private DB() {
+  }
+
   /**
    * Return the default database.
    */
@@ -150,22 +156,21 @@ public class DB {
    * 

    * 
{@code
    *
-   *   try (Transaction txn = DB.beginTransaction()) {
-   * 	   Order order = DB.find(Order.class,10); ...
+   *   try (Transaction transaction = DB.beginTransaction()) {
    *
-   * 	   DB.save(order);
+   *     Order order = DB.find(Order.class, 42);
+   *     order.setStatus(Status.COMPLETE);
+   *     order.save();
    *
-   * 	   txn.commit();
+   *     transaction.commit();
    *   }
    *
    * }

    * 

-   * If you want to externalise the transaction management then you should be
-   * able to do this via Database. Specifically with Database you can pass
-   * the transaction to the various find() and save() execute() methods. This
-   * gives you the ability to create the transactions yourself externally from
-   * Ebean and pass those transactions through to the various methods available
-   * on Database.
+   * If we want to externalise the transaction management then we do this via Database.
+   * With Database we can pass the transaction to the various find(), save() and execute()
+   * methods. This gives us the ability to create the transactions externally from Ebean
+   * and use the transaction explicitly via the various methods available on Database.
    * 

    */
   public static Transaction beginTransaction() {
@@ -194,29 +199,24 @@ public class DB {
    * // suspend it until this transaction ends
    *
    * try (Transaction txn = DB.beginTransaction(TxScope.requiresNew())) {
-   *
    *   ...
    *
    *   // commit the transaction
    *   txn.commit();
    * }
-   *
    * }

+   *
    * 
REQUIRED example:

    * 
{@code
-   *
    * // start a new transaction if there is not a current transaction
    *
    * try (Transaction txn = DB.beginTransaction(TxScope.required())) {
-   *
    *   ...
    *
    *   // commit the transaction if it was created or
    *   // do nothing if there was already a current transaction
    *   txn.commit();
-   *
    * }
-   *
    * }

    */
   public static Transaction beginTransaction(TxScope scope) {
@@ -335,18 +335,6 @@ public class DB {
    * OneToMany, OneToOne or ManyToMany annotation.
    * 

    * 

-   * In this example below the details property has a CascadeType.ALL set so
-   * saving an order will also save all its details.
-   * 

-   * 
{@code
-   *   public class Order { ...
-   *
-   * 	   @OneToMany(cascade=CascadeType.ALL, mappedBy="order")
-   * 	   List details;
-   * 	   ...
-   *   }
-   * }

-   * 

    * When a save cascades via a OneToMany or ManyToMany Ebean will automatically
    * set the 'parent' object to the 'detail' object. In the example below in
    * saving the order and cascade saving the order details the 'parent' order
@@ -1087,15 +1075,15 @@ public class DB {
    * 

    * 
{@code
    *
-   *   // set specific transactional scope settings
-   *   TxScope scope = TxScope.requiresNew().setIsolation(TxIsolation.SERIALIZABLE);
+   * // set specific transactional scope settings
+   * TxScope scope = TxScope.requiresNew().setIsolation(TxIsolation.SERIALIZABLE);
    *
-   *   DB.execute(scope, new TxRunnable() {
-   * 	   public void run() {
-   * 		   User u1 = DB.find(User.class, 1);
-   * 		   ...
-   * 	   }
-   *   });
+   * DB.execute(scope, new TxRunnable() {
+   *   public void run() {
+   * 	   User u1 = DB.find(User.class, 1);
+   *     ...
+   *   }
+   * });
    *
    * }

    */
@@ -1111,19 +1099,17 @@ public class DB {
    * 

    * 
{@code
    *
-   *   DB.execute(() -> {
+   * DB.execute(() -> {
    *
-   *       User u1 = DB.find(User.class, 1);
-   *       User u2 = DB.find(User.class, 2);
+   *   User u1 = DB.find(User.class, 1);
+   *   User u2 = DB.find(User.class, 2);
    *
-   *       u1.setName("u1 mod");
-   *       u2.setName("u2 mod");
-   *
-   *       DB.save(u1);
-   *       DB.save(u2);
-   *
-   *   });
+   *   u1.setName("u1 mod");
+   *   u2.setName("u2 mod");
    *
+   *   DB.save(u1);
+   *   DB.save(u2);
+   * });
    * }

    */
   public static void execute(Runnable r) {
@@ -1138,17 +1124,16 @@ public class DB {
    * 

    * 
{@code
    *
-   *   // set specific transactional scope settings
-   *   TxScope scope = TxScope.requiresNew().setIsolation(TxIsolation.SERIALIZABLE);
-   *
-   *   DB.executeCall(scope, new Callable() {
-   * 	   public String call() {
-   * 		   User u1 = DB.find(User.class, 1);
-   * 		   ...
-   * 		   return u1.getEmail();
-   * 	   }
-   *   });
+   * // set specific transactional scope settings
+   * TxScope scope = TxScope.requiresNew().setIsolation(TxIsolation.SERIALIZABLE);
    *
+   * DB.executeCall(scope, new Callable() {
+   *   public String call() {
+   * 	   User u1 = DB.find(User.class, 1);
+   * 		 ...
+   * 		 return u1.getEmail();
+   *   }
+   * });
    * }

    */
   public static  T executeCall(TxScope scope, Callable c) {
@@ -1167,21 +1152,19 @@ public class DB {
    * 

    * 
{@code
    *
-   *   DB.executeCall(() -> {
+   * DB.executeCall(() -> {
    *
-   *       User u1 = DB.find(User.class, 1);
-   *       User u2 = DB.find(User.class, 2);
+   *   User u1 = DB.find(User.class, 1);
+   *   User u2 = DB.find(User.class, 2);
    *
-   *       u1.setName("u1 mod");
-   *       u2.setName("u2 mod");
+   *   u1.setName("u1 mod");
+   *   u2.setName("u2 mod");
    *
-   *       DB.save(u1);
-   *       DB.save(u2);
-   *
-   *       return u1.getEmail();
-   *
-   *   });
+   *   DB.save(u1);
+   *   DB.save(u2);
    *
+   *   return u1.getEmail();
+   * });
    * }

    */
   public static  T executeCall(Callable c) {
@@ -1219,7 +1202,6 @@ public class DB {
    * @param deletes   true if rows on the table where deleted
    */
   public static void externalModification(String tableName, boolean inserts, boolean updates, boolean deletes) {
-
     getDefault().externalModification(tableName, inserts, updates, deletes);
   }
 
diff --git a/src/main/java/io/ebean/overview.html b/src/main/java/io/ebean/overview.html
index 0c0a17139..3db912a27 100644
--- a/src/main/java/io/ebean/overview.html
+++ b/src/main/java/io/ebean/overview.html
@@ -3,130 +3,24 @@
   Ebean API
 
 
-Ebean Object Relational Mapping (start at
-EbeanServer or Ebean).
+Ebean Object Relational Mapping -
+Database or DB).
 
 
-
Ebean

+
Database

 

-  Provides the main API for fetching and persisting beans with Ebean.
+  Database provides the main API for fetching and persisting beans.
 

+
+
DB

 

-  For a full description of the query language refer to Query.
+  DB holds a registry of Database instances by name.
 

+
+
Query

 

-   
+  Review the documentation for the query capabilities.
 

-

-  

-    EXAMPLE 1: Simple fetch
-  

-  
{@code
-// fetch order 10
-Order order = Ebean.find(Order.class, 10);
-}

-
-  

-    EXAMPLE 2: Fetch an Object with associations
-  

-  
{@code
-// fetch Customer 7 including their billing and shipping addresses
-Customer customer = Ebean.find(Customer.class)
-    .fetch("billingAddress");
-    .fetch("shippingAddress");
-    .setId(7)
-    .findOne();
-
-
-Address billAddr = customer.getBillingAddress();
-Address shipAddr = customer.getShippingAddress();
-}

-
-  

-    EXAMPLE 3: Fetch a list of Objects with associations
-  

-  
{@code
-// Note: This example shows a "Partial Object".
-//       For the product objects associated with the
-//       order details only the product id and name is
-//       fetched (the product objects are partially populated).
-
-// fetch orders for customer.id = 2
-List orderList = Ebean.find(Order.class);
-    .fetch("customer")
-    .fetch("customer.shippingAddress")
-    .fetch("details")
-    .fetch("details.product","name")
-    .where().eq("customer.id",2)
-    .findList();
-
-
-// Note: Only the product id and name is fetched for the
-//       product details. This is referred to as a
-//       "Partial Object" (one that is partially populated).
-
-
-// code that traverses the object graph...
-
-Order order = orderList.get(0);
-Customer customer = order.getCustomer();
-Address shipAddr = customer.getShippingAddress();
-
-List details = order.getDetails();
-OrderDetail detail = details.get(0);
-Product product = detail.getProduct();
-String productName = product.getName();
-
-}

-
-  

-    EXAMPLE 4: Create and save an Order
-  

-  
{@code
-// get a Customer reference so we don't hit the database
-Customer custRef = Ebean.getReference(Customer.class, 7);
-
-// create a new Order object
-Order newOrder = new Order();
-newOrder.setStatus(Order.Status.NEW);
-newOrder.setCustomer(custRef);
-
-ArrayList orderLines = new ArrayList();
-newOrder.setLines(orderLines);
-...
-
-// add a line to the order
-Product prodRef = Ebean.getReference(Product.class, 41);
-OrderLine line = new OrderLine();
-line.setProduct(prodRef);
-line.setQuantity(10);
-orderLines.add(line);
-...
-
-// save the order and its lines in a single transaction
-// NB: assumes CascadeType.PERSIST is set on the order lines association
-Ebean.save(newOrder);
-
-}

-
-  

-    EXAMPLE 5: Use another database
-  

-  
{@code
-// Get access to the Human Resources EbeanServer/Database
-EbeanServer hrServer = Ebean.getServer("HR");
-
-
-// fetch contact 3 from the HR database
-Contact contact = hrServer.find(Contact.class, 3);
-
-contact.setStatus(Contact.Status.INACTIVE);
-...
-
-// save the contact back to the HR database
-hrServer.save(contact);
-}

-

 
 
 
diff --git a/src/main/java/io/ebean/package.html b/src/main/java/io/ebean/package.html
index 4aa8efb94..f1524bdc6 100644
--- a/src/main/java/io/ebean/package.html
+++ b/src/main/java/io/ebean/package.html
@@ -12,21 +12,29 @@ Core API (see Database, DB and
 

 
 
{@code
-// EXAMPLE 1: Simple fetch.
-//========================
 
-// fetch order 10
+// Example find by id
+
 Order order = DB.find(Order.class, 10);
 
 
+// Example save
 
-// EXAMPLE 2: Fetch an Object with associations
-//=============================================
+Customer customer = DB.getReference(Customer.class, 42);
 
-// fetch Customer 7 including their billing and shipping addresses
-Customer customer =
-	DB.find(Customer.class)
-		.setId(7)
+Order newOrder = new Order();
+newOrder.setStatus(Order.Status.NEW);
+newOrder.setCustomer(customer);
+...
+
+DB.save(newOrder);
+
+
+// Example: Eagerly fetching associations
+
+// fetch Customer 42 including their billing and shipping addresses
+Customer customer = DB.find(Customer.class)
+		.setId(42)
 		.fetch("billingAddress")
 		.fetch("shippingAddress")
 		.findOne();
@@ -34,40 +42,6 @@ Customer customer =
 Address billAddr = customer.getBillingAddress();
 Address shipAddr = customer.getShippingAddress();
 
-
-
-
-// EXAMPLE 3: Create and save an Order
-//=====================================
-
-// get a Customer reference so we don't hit the database
-Customer customer = DB.getReference(Customer.class, 7);
-
-// create a new Order object
-Order newOrder = new Order();
-newOrder.setStatus(Order.Status.NEW);
-newOrder.setCustomer(customer);
-...
-
-
-DB.save(newOrder);
-
-
-
-// EXAMPLE 4: Use another database
-//=================================
-
-// Get access to the Human Resources EbeanServer/Database
-Database hrDatabase = DB.byName("HR");
-
-
-Contact contact = hrDatabase.find(Contact.class, 42);
-
-contact.setStatus(Contact.Status.INACTIVE);
-...
-
-// save the contact back to the HR database
-hrDatabase.save(contact);
 }