#2713 - Improve javadoc of Finder, BeanFinder, BeanRepository - deprecate use of BeanFinder server field (migrate to database)

ebean-api/src/main/java/io/ebean/BeanFinder.java

@@ -12,6 +12,7 @@ import java.util.Optional;
  * </p>
  * <pre>{@code
  *
+ * @Component
  * public class CustomerFinder extends BeanFinder<Long,Customer> {
  *
  *   @Inject
@@ -26,29 +27,37 @@ import java.util.Optional;
  *
  * @param <I> The ID type
  * @param <T> The Bean type
+ *
+ * @see BeanRepository
  */
 @NonNullApi
 public abstract class BeanFinder<I,T> {
 
+  /**
+   * Migrate to using database rather than server.
+   */
+  @Deprecated
   protected final Database server;
+  protected final Database database;
   protected final Class<T> type;
 
   /**
    * Create with the given bean type and Database instance.
    *
    * @param type The bean type
-   * @param server The Database instance typically created via Spring factory or equivalent.
+   * @param database The Database instance typically created via Spring factory or equivalent.
    */
-  protected BeanFinder(Class<T> type, Database server) {
+  protected BeanFinder(Class<T> type, Database database) {
     this.type = type;
-    this.server = server;
+    this.database = database;
+    this.server = database;
   }
 
   /**
    * Return the Database to use.
    */
   public Database db() {
-    return server;
+    return database;
   }
 
   /**
@@ -70,10 +79,10 @@ public abstract class BeanFinder<I,T> {
    * <p>
    * This is equivalent to {@link DB#byName(String)}
    *
-   * @param server The name of the Database. If this is null then the default Database is returned.
+   * @param name The name of the Database. If this is null then the default Database is returned.
    */
-  public Database db(String server) {
-    return DB.byName(server);
+  public Database db(String name) {
+    return DB.byName(name);
   }
 
   /**

ebean-api/src/main/java/io/ebean/BeanRepository.java

@@ -6,11 +6,15 @@ import io.ebean.bean.EntityBean;
 import java.util.Collection;
 
 /**
- * Provides finder functionality for use with "Dependency Injection style" use of Ebean.
+ * Provides find and persist functionality for use with "Dependency Injection style" use of Ebean.
  * <p>
+ * Extend the BeanRepository with additional finder and persisting methods as needed by the
+ * application. The intention is to keep all the related logic together, for example, all the
+ * persisting and finding logic for Customer would be in CustomerRepository.
+ *
  * <pre>{@code
  *
- * @Repository
+ * @Component
  * public class CustomerRepository extends BeanRepository<Long,Customer> {
  *
  *   @Inject
@@ -50,10 +54,10 @@ public abstract class BeanRepository<I, T> extends BeanFinder<I, T> {
    * }</pre>
    *
    * @param type   The bean type
-   * @param server The Database instance typically created via Spring factory or equivalent
+   * @param database The Database instance typically created via Spring factory or equivalent
    */
-  protected BeanRepository(Class<T> type, Database server) {
-    super(type, server);
+  protected BeanRepository(Class<T> type, Database database) {
+    super(type, database);
   }
 
   /**
@@ -122,8 +126,8 @@ public abstract class BeanRepository<I, T> extends BeanFinder<I, T> {
   /**
    * Save all the beans in the collection.
    */
-  public int saveAll(Collection<T> bean) {
-    return db().saveAll(bean);
+  public int saveAll(Collection<T> beans) {
+    return db().saveAll(beans);
   }
 
   /**

ebean-api/src/main/java/io/ebean/Finder.java

@@ -8,6 +8,9 @@ import java.util.List;
  * Intended to be used as a base class for 'Finder' implementations that can then
  * be injected or used as public static fields on the associated entity bean.
  * <p>
+ * When using dependency injection {@link BeanRepository} and {@link BeanFinder}
+ * are expected to be used rather than this Finder.
+ * <p>
  * These 'finders' are a place to organise all the finder methods for that bean type
  * and specific finder methods are expected to be added (find by unique properties etc).
  * </p>
@@ -54,6 +57,8 @@ import java.util.List;
  *
  * }</pre>
  *
+ * @see BeanRepository
+ * @see BeanFinder
  */
 @NonNullApi
 public class Finder<I, T> {