From 1c749e55c62b0a20b7323eebb28314940c71c5d9 Mon Sep 17 00:00:00 2001 From: Rob Bygrave Date: Thu, 7 Apr 2022 18:45:19 +1200 Subject: [PATCH] Fix javadoc in DB --- ebean-api/src/main/java/io/ebean/DB.java | 84 ++++++------------------ 1 file changed, 19 insertions(+), 65 deletions(-) diff --git a/ebean-api/src/main/java/io/ebean/DB.java b/ebean-api/src/main/java/io/ebean/DB.java index 44bd4fdb2..0b7d3fa38 100644 --- a/ebean-api/src/main/java/io/ebean/DB.java +++ b/ebean-api/src/main/java/io/ebean/DB.java @@ -22,10 +22,9 @@ 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() - *

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

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

+ *
  * 
{@code
  *
  * Database hrDatabase = DB.byName("hr");
@@ -47,7 +46,6 @@ import java.util.concurrent.Callable;
  * 

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

  *
  * 
{@code
  *
@@ -117,15 +115,12 @@ public final class DB {
    * build the WHERE and HAVING clauses. Alternatively you can use the
    * ExpressionFactory directly to create expressions to add to the query where
    * clause.
-   * 

    * 

    * Alternatively you can use the {@link Expr} as a shortcut to the
    * ExpressionFactory of the 'Default' database.
-   * 

    * 

    * You generally need to the an ExpressionFactory (or {@link Expr}) to build
    * an expression that uses OR like Expression e = Expr.or(..., ...);
-   * 

    */
   public static ExpressionFactory expressionFactory() {
     return getDefault().expressionFactory();
@@ -136,12 +131,10 @@ public final class DB {
    * 

    * This will only work when a IdGenerator is on this bean type such as a DB
    * sequence or UUID.
-   * 

    * 

    * For DB's supporting getGeneratedKeys and sequences such as Oracle10 you do
    * not need to use this method generally. It is made available for more
    * complex cases where it is useful to get an ID prior to some processing.
-   * 

    */
   public static Object nextId(Class beanType) {
     return getDefault().nextId(beanType);
@@ -151,17 +144,14 @@ public final class DB {
    * Start a transaction with 'REQUIRED' semantics.
    * 

    * With REQUIRED semantics if an active transaction already exists that transaction will be used.
-   * 

    * 

    * The transaction is stored in a ThreadLocal variable and typically you only
    * need to use the returned Transaction IF you wish to do things like
    * use batch mode, change the transaction isolation level, use savepoints or
    * log comments to the transaction log.
-   * 

    * 

-   * Example of using a transaction to span multiple calls to find(), save()
-   * etc.
-   * 

+   * Example of using a transaction to span multiple calls to find(), save() etc.
+   *
    * 
{@code
    *
    *   try (Transaction transaction = DB.beginTransaction()) {
@@ -179,7 +169,6 @@ public final class DB {
    * 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() {
     return getDefault().beginTransaction();
@@ -191,7 +180,6 @@ public final class DB {
    * You will want to do this if you want multiple Transactions in a single
    * thread or generally use transactions outside of the TransactionThreadLocal
    * management.
-   * 

    */
   public static Transaction createTransaction() {
     return getDefault().createTransaction();
@@ -211,7 +199,6 @@ public final class DB {
    * 

    * Note that this provides an try finally alternative to using {@link #executeCall(TxScope, Callable)} or
    * {@link #execute(TxScope, Runnable)}.
-   * 

    * 

    * 
REQUIRES_NEW example:

    * 
{@code
@@ -270,7 +257,7 @@ public final class DB {
 
   /**
    * Register a TransactionCallback on the currently active transaction.
-   * 

+   * 

    * If there is no currently active transaction then a PersistenceException is thrown.
    *
    * @param transactionCallback the transaction callback to be registered with the current transaction
@@ -299,14 +286,12 @@ public final class DB {
    * rollback the transaction.
    * 

    * It is preferable to use try with resources rather than this.
-   * 

    * 

    * Useful to put in a finally block to ensure the transaction is ended, rather
    * than a rollbackTransaction() in each catch block.
-   * 

    * 

    * Code example:
-   * 

+   *
    * 
{@code
    *   DB.beginTransaction();
    *   try {
@@ -337,7 +322,6 @@ public final class DB {
    * 

    * When null is passed in for b, then the 'OldValues' of a is used for the
    * difference comparison.
-   * 

    */
   public static Map diff(Object a, Object b) {
     return getDefault().diff(a, b);
@@ -348,18 +332,15 @@ public final class DB {
    * 

    * If there is no current transaction one will be created and committed for
    * you automatically.
-   * 

    * 

    * Save can cascade along relationships. For this to happen you need to
    * specify a cascade of CascadeType.ALL or CascadeType.PERSIST on the
    * OneToMany, OneToOne or ManyToMany annotation.
-   * 

    * 

    * 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
    * will be set against each order detail when it is saved.
-   * 

    */
   public static void save(Object bean) throws OptimisticLockException {
     getDefault().save(bean);
@@ -410,11 +391,9 @@ public final class DB {
    * Stateless updates: Note that the bean does not have to be previously fetched to call
    * update().You can create a new instance and set some of its properties programmatically for via
    * JSON/XML marshalling etc. This is described as a 'stateless update'.
-   * 

    * 

    * Optimistic Locking:  Note that if the version property is not set when update() is
    * called then no optimistic locking is performed (internally ConcurrencyMode.NONE is used).
-   * 

    * 

    * 
{@code
    *
@@ -531,20 +510,16 @@ public final class DB {
    * Delete the bean.
    * 

    * This will return true if the bean was deleted successfully or JDBC batch is being used.
-   * 

    * 

    * If there is no current transaction one will be created and committed for
    * you automatically.
-   * 

    * 

    * If the bean is configured with @SoftDelete then this will perform a soft
    * delete rather than a hard/permanent delete.
-   * 

    * 

    * If the Bean does not have a version property (or loaded version property) and
    * the bean does not exist then this returns false indicating that nothing was
    * deleted. Note that, if JDBC batch mode is used then this always returns true.
-   * 

    */
   public static boolean delete(Object bean) throws OptimisticLockException {
     return getDefault().delete(bean);
@@ -604,7 +579,6 @@ public final class DB {
    * 

    * Note that this resets OneToMany and ManyToMany properties so that if they
    * are accessed a lazy load will refresh the many property.
-   * 

    */
   public static void refresh(Object bean) {
     getDefault().refresh(bean);
@@ -612,6 +586,7 @@ public final class DB {
 
   /**
    * Refresh a 'many' property of a bean.
+   *
    * 
{@code
    *
    *   Order order = ...;
@@ -632,7 +607,7 @@ public final class DB {
    * Get a reference object.
    * 

    * This is sometimes described as a proxy (with lazy loading).
-   * 

+   *
    * 
{@code
    *
    *   Product product = DB.getReference(Product.class, 1);
@@ -668,7 +643,7 @@ public final class DB {
    * 

    * Note that the sorting uses a Comparator and Collections.sort(); and does
    * not invoke a DB query.
-   * 

+   *
    * 
{@code
    *
    *   // find orders and their customers
@@ -703,9 +678,8 @@ public final class DB {
    *
    * }

    * 

-   * If you want more control over the query then you can use createQuery() and
-   * Query.findOne();
-   * 

+   * If you want more control over the query then you can use createQuery() and Query.findOne();
+   *
    * 
{@code
    *
    *   // ... additionally fetching customer, customer shipping address,
@@ -745,15 +719,12 @@ public final class DB {
   }
 
   /**
-   * Look to execute a native sql query that does not returns beans but instead
-   * returns SqlRow or direct access to ResultSet (see {@link SqlQuery#findList(RowMapper)}.
-   *
+   * Look to execute a native sql query that does not return beans but instead
+   * returns SqlRow or uses {@link RowMapper}.
    * 

    * Refer to {@link DtoQuery} for native sql queries returning DTO beans.
-   * 

    * 

    * Refer to {@link #findNative(Class, String)} for native sql queries returning entity beans.
-   * 

    */
   public static SqlQuery sqlQuery(String sql) {
     return getDefault().sqlQuery(sql);
@@ -764,11 +735,9 @@ public final class DB {
    * 

    * Use this to execute a Insert Update or Delete statement. The statement will
    * be native to the database and contain database table and column names.
-   * 

    *
    * 

    * See {@link SqlUpdate} for example usage.
-   * 

    *
    * @return The SqlUpdate instance to set parameters and execute
    */
@@ -792,10 +761,9 @@ public final class DB {
    * 

    * The orm update differs from the sql update in that it you can use the bean
    * name and bean property names rather than table and column names.
-   * 

    * 

    * An example:
-   * 

+   *
    * 
{@code
    *
    *   // The bean name and properties - "topic","postCount" and "id"
@@ -828,7 +796,6 @@ public final class DB {
    * Create a named query.
    * 

    * For RawSql the named query is expected to be in ebean.xml.
-   * 

    *
    * @param beanType   The type of entity bean
    * @param namedQuery The name of the query
@@ -844,15 +811,12 @@ public final class DB {
    * 

    * You can use the methods on the Query object to specify fetch paths,
    * predicates, order by, limits etc.
-   * 

    * 

    * You then use findList(), findSet(), findMap() and findOne() to execute
    * the query and return the collection or bean.
-   * 

    * 

    * Note that a query executed by {@link Query#findList()} etc will execute against
    * the same database from which is was created.
-   * 

    *
    * @param beanType the class of entity to be fetched
    * @return A ORM Query for this beanType
@@ -904,7 +868,6 @@ public final class DB {
    * This is actually the same as {@link #createQuery(Class)}. The reason it
    * exists is that people used to JPA will probably be looking for a
    * createQuery method (the same as entityManager).
-   * 

    *
    * @param beanType the type of entity bean to find
    * @return A ORM Query object for this beanType
@@ -917,7 +880,7 @@ public final class DB {
    * Create a query using native SQL.
    * 

    * The native SQL can contain named parameters or positioned parameters.
-   * 

+   *
    * 
{@code
    *
    *   String sql = "select c.id, c.name from customer c where c.name like ? order by c.name";
@@ -942,7 +905,6 @@ public final class DB {
    * 

    * DTO beans are just normal bean like classes with public constructor(s) and setters.
    * They do not need to be registered with Ebean before use.
-   * 

    *
    * @param dtoType The type of the DTO bean the rows will be mapped into.
    * @param sql     The SQL query to execute.
@@ -979,10 +941,8 @@ public final class DB {
    * going back to the database.
    * 

    * This produces and returns a new list with the sort and filters applied.
-   * 

    * 

    * Refer to {@link Filter} for an example of its use.
-   * 

    */
   public static  Filter filter(Class beanType) {
     return getDefault().filter(beanType);
@@ -993,7 +953,7 @@ public final class DB {
    * 

    * The scope can control the transaction type, isolation and rollback
    * semantics.
-   * 

+   *
    * 
{@code
    *
    * // set specific transactional scope settings
@@ -1017,7 +977,7 @@ public final class DB {
    * 

    * The default scope runs with REQUIRED and by default will rollback on any
    * exception (checked or runtime).
-   * 

+   *
    * 
{@code
    *
    * DB.execute(() -> {
@@ -1042,7 +1002,7 @@ public final class DB {
    * 

    * The scope can control the transaction type, isolation and rollback
    * semantics.
-   * 

+   *
    * 
{@code
    *
    * // set specific transactional scope settings
@@ -1066,11 +1026,10 @@ public final class DB {
    * 

    * The default scope runs with REQUIRED and by default will rollback on any
    * exception (checked or runtime).
-   * 

    * 

    * This is basically the same as TxRunnable except that it returns an Object
    * (and you specify the return type via generics).
-   * 

+   *
    * 
{@code
    *
    * DB.executeCall(() -> {
@@ -1099,23 +1058,19 @@ public final class DB {
    * 

    * If you use DB.execute(UpdateSql) then the table modification information
    * is automatically deduced and you do not need to call this method yourself.
-   * 

    * 

    * This information is used to invalidate objects out of the cache and
    * potentially text indexes. This information is also automatically broadcast
    * across the cluster.
-   * 

    * 

    * If there is a transaction then this information is placed into the current
    * transactions event information. When the transaction is committed this
    * information is registered (with the transaction manager). If this
    * transaction is rolled back then none of the transaction event information
    * registers including the information you put in via this method.
-   * 

    * 

    * If there is NO current transaction when you call this method then this
    * information is registered immediately (with the transaction manager).
-   * 

    *
    * @param tableName the name of the table that was modified
    * @param inserts   true if rows where inserted into the table
@@ -1130,7 +1085,6 @@ public final class DB {
    * Return the BeanState for a given entity bean.
    * 

    * This will return null if the bean is not an enhanced entity bean.
-   * 

    */
   public static BeanState beanState(Object bean) {
     return getDefault().beanState(bean);