* DB additionally provides a convenient way to use the 'default' Database. *
- *
- * One of the Database instances can be registered as the "default database"
- * and can be obtained using DB.getDefault()
- *
+ * 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);
}