github/ebean
4
0
Fork 0
mirror of https://github.com/ebean-orm/ebean.git synced 2024-04-21 10:51:47 +00:00
Code Issues Packages Projects Releases Wiki Activity

Javadoc update using "DB" and hide DB constructor

Browse Source
This commit is contained in:
rob bygrave
2019-03-07 12:01:05 +13:00
parent a5f435dbcf
commit e3ca5d2419
3 changed files with 91 additions and 241 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/main/java/io/ebean/DB.java
+64 -82
View File
@@ -22,11 +22,11 @@ import java.util.concurrent.Callable;
* <p>
* DB additionally provides a convenient way to use the 'default' Database.
* <p>
* <h3>Default database</h3>
* <p>
* One of the Database instances can be registered as the "default database"
* and can be obtained using <code>DB.getDefault()</code>
* </p>
* <h3>Default database</h3>
* <p>
* One of the Database instances can be registered as the "default database"
* and can be obtained using <code>DB.getDefault()</code>
* </p>
* <pre>{@code
*
* Database database = DB.getDefault();
@@ -35,8 +35,8 @@ import java.util.concurrent.Callable;
*
* <h3>Named database</h3>
* <p>
* Multiple database instances can be registered with DB and we can obtain them
* using <code>DB.byName()</code>
* Multiple database instances can be registered with DB and we can obtain them
* using <code>DB.byName()</code>
* </p>
* <pre>{@code
*
@@ -46,23 +46,29 @@ import java.util.concurrent.Callable;
*
* <h3>Convenience methods</h3>
* <p>
* 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.
* </p>
*
* <pre>{@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);
*
* }</pre>
*/
public class DB {
/**
* Hide constructor.
*/
private DB() {
}
/**
* Return the default database.
*/
@@ -150,22 +156,21 @@ public class DB {
* </p>
* <pre>{@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();
* }
*
* }</pre>
* <p>
* 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.
* </p>
*/
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();
* }
*
* }</pre>
*
* <h3>REQUIRED example:</h3>
* <pre>{@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();
*
* }
*
* }</pre>
*/
public static Transaction beginTransaction(TxScope scope) {
@@ -335,18 +335,6 @@ public class DB {
* OneToMany, OneToOne or ManyToMany annotation.
* </p>
* <p>
* In this example below the details property has a CascadeType.ALL set so
* saving an order will also save all its details.
* </p>
* <pre>{@code
* public class Order { ...
*
* @OneToMany(cascade=CascadeType.ALL, mappedBy="order")
* List<OrderDetail> details;
* ...
* }
* }</pre>
* <p>
* 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 {
* </p>
* <pre>{@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);
* ...
* }
* });
*
* }</pre>
*/
@@ -1111,19 +1099,17 @@ public class DB {
* </p>
* <pre>{@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);
* });
* }</pre>
*/
public static void execute(Runnable r) {
@@ -1138,17 +1124,16 @@ public class DB {
* </p>
* <pre>{@code
*
* // set specific transactional scope settings
* TxScope scope = TxScope.requiresNew().setIsolation(TxIsolation.SERIALIZABLE);
*
* DB.executeCall(scope, new Callable<String>() {
* 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<String>() {
* public String call() {
* User u1 = DB.find(User.class, 1);
* ...
* return u1.getEmail();
* }
* });
* }</pre>
*/
public static <T> T executeCall(TxScope scope, Callable<T> c) {
@@ -1167,21 +1152,19 @@ public class DB {
* </p>
* <pre>{@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();
* });
* }</pre>
*/
public static <T> T executeCall(Callable<T> 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);
}
src/main/java/io/ebean/overview.html
+10 -116
View File
@@ -3,130 +3,24 @@
<title>Ebean API</title>
</head>
<body BGCOLOR="#ffffff">
Ebean Object Relational Mapping (start at
<a href='com/avaje/ebean/EbeanServer.html'>EbeanServer</a> or <a href='com/avaje/ebean/Ebean.html'>Ebean</a>).
Ebean Object Relational Mapping -
<a href='io/ebean/Database.html'>Database</a> or <a href='io/ebean/DB.html'>DB</a>).
<h3>Ebean</h3>
<h4><a href='io/ebean/Database.html'>Database</a></h4>
<p>
Provides the main API for fetching and persisting beans with Ebean.
Database provides the main API for fetching and persisting beans.
</p>
<h4><a href='io/ebean/DB.html'>DB</a></h4>
<p>
For a full description of the query language refer to <a href="com/avaje/ebean/Query.html">Query</a>.
DB holds a registry of Database instances by name.
</p>
<h4><a href='https://ebean.io/docs/query'>Query</a></h4>
<p>
&nbsp;
Review the documentation for the query capabilities.
</p>
<div id="overviewexamples">
<h3>
EXAMPLE 1: Simple fetch
</h3>
<pre>{@code
// fetch order 10
Order order = Ebean.find(Order.class, 10);
}</pre>
<h3>
EXAMPLE 2: Fetch an Object with associations
</h3>
<pre>{@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();
}</pre>
<h3>
EXAMPLE 3: Fetch a list of Objects with associations
</h3>
<pre>{@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<Order> 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<OrderDetail> details = order.getDetails();
OrderDetail detail = details.get(0);
Product product = detail.getProduct();
String productName = product.getName();
}</pre>
<h3>
EXAMPLE 4: Create and save an Order
</h3>
<pre>{@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);
}</pre>
<h3>
EXAMPLE 5: Use another database
</h3>
<pre>{@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);
}</pre>
</div>
</body>
src/main/java/io/ebean/package.html
+17 -43
View File
@@ -12,21 +12,29 @@ Core API (see <a href="Database.html">Database</a>, <a href="DB.html">DB</a> and
</p>
<pre>{@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);
}</pre>
</Body>