jdbi javadoc/checkstyle + make sqlobject request scoped only

jknack · jknack · commit 6dce35bbf12f · 2019-07-08T21:37:47.000-03:00
diff --git a/modules/jooby-jdbi/src/main/java/io/jooby/internal/jdbi/SqlObjectProvider.java b/modules/jooby-jdbi/src/main/java/io/jooby/internal/jdbi/SqlObjectProvider.java
@@ -5,22 +5,30 @@
  */
 package io.jooby.internal.jdbi;
 
+import io.jooby.RequestScope;
+import io.jooby.jdbi.TransactionalRequest;
 import org.jdbi.v3.core.Handle;
+import org.jdbi.v3.core.Jdbi;
 
 import javax.inject.Provider;
 
 public class SqlObjectProvider implements Provider {
-  private Provider<Handle> handle;
-
+  private Jdbi jdbi;
   private Class type;
 
-  public SqlObjectProvider(Provider<Handle> handle, Class type) {
-    this.handle = handle;
+  public SqlObjectProvider(Jdbi jdbi, Class type) {
+    this.jdbi = jdbi;
     this.type = type;
   }
 
   @Override public Object get() {
-    Handle handle = this.handle.get();
+    Handle handle = RequestScope.get(jdbi);
+    if (handle == null) {
+      // TODO: Replace with a Usage exception
+      throw new IllegalStateException(
+          "No handle was attached to current request. Make sure `" + TransactionalRequest.class
+              .getName() + "` was installed it");
+    }
     return handle.attach(type);
   }
 }
diff --git a/modules/jooby-jdbi/src/main/java/io/jooby/jdbi/JdbiModule.java b/modules/jooby-jdbi/src/main/java/io/jooby/jdbi/JdbiModule.java
@@ -22,6 +22,57 @@
 import java.util.List;
 import java.util.function.Function;
 
+/**
+ * Jdbi module:  https://jooby.io/modules/hikari.
+ *
+ * Usage:
+ *
+ * - Add hikari and jdbi dependency
+ *
+ * - Install them
+ *
+ * <pre>{@code
+ * {
+ *   install(new HikariModule());
+ *
+ *   install(new JdbiModule());
+ * }
+ * }</pre>
+ *
+ * - Use it
+ *
+ * <pre>{code
+ * {
+ *
+ *   get("/", ctx -> {
+ *     Jdbi jdbi = require(Jdbi.class);
+ *     // do with jdbi
+ *   });
+ *
+ * }
+ * }</pre>
+ *
+ * Handle instances are also available:
+ *
+ * <pre>{code
+ * {
+ *
+ *   get("/", ctx -> {
+ *     try(Handle handle = require(Handle.class)) {
+ *       // do with handle
+ *     }
+ *   });
+ *
+ * }
+ * }</pre>
+ *
+ * The use of try-with-resources is required here. Handle must be closed once you finish.
+ *
+ * For automatic handle managment see the {@link TransactionalRequest} class.
+ *
+ * @author edgar
+ * @since 2.0.0
+ */
 public class JdbiModule implements Extension {
 
   private String name;
@@ -30,26 +81,78 @@ public class JdbiModule implements Extension {
 
   private List<Class> sqlObjects = Collections.emptyList();
 
+  /**
+   * Creates a new Jdbi module using the <code>db</code> property key. This key must be
+   * present in the application configuration file, like:
+   *
+   * <pre>{@code
+   *  db.url = "jdbc:url"
+   *  db.user = dbuser
+   *  db.password = dbpass
+   * }</pre>
+   */
   public JdbiModule() {
     this("db");
   }
 
+  /**
+   * Creates a new Jdbi module. The database parameter can be one of:
+   *
+   * - A property key defined in your application configuration file, like <code>db</code>.
+   * - A special h2 database: mem, local or tmp.
+   * - A jdbc connection string, like: <code>jdbc:mysql://localhost/db</code>
+   *
+   * @param name Database key, database type or connection string.
+   */
   public JdbiModule(@Nonnull String name) {
     this.name = name;
     this.factory = null;
   }
 
-  public JdbiModule(Function<DataSource, Jdbi> factory) {
-    this();
-    this.factory = factory;
+  /**
+   * Creates a new Jdbi module using the given jdbi factory. The jdbi service is registered as
+   * <code>db</code>.
+   *
+   * @param factory Jdbi factory.
+   */
+  public JdbiModule(@Nonnull Function<DataSource, Jdbi> factory) {
+    this("db", factory);
   }
 
-  public JdbiModule(String name, Function<DataSource, Jdbi> factory) {
+  /**
+   * Creates a new Jdbi module using the given jdbi factory.
+   *
+   * @param name Name for registering the service.
+   * @param factory Jdbi factory.
+   */
+  public JdbiModule(@Nonnull String name, @Nonnull Function<DataSource, Jdbi> factory) {
     this(name);
     this.factory = factory;
   }
 
-  public JdbiModule sqlObjects(Class... sqlObjects) {
+  /**
+   * Attach SQL objects to a jdbi handle.
+   *
+   * This method simplify the injection or require of SQL objects. So, it is just a
+   * shortcut for {@link Handle#attach(Class)}. Due the SQL objects depends on a Handle this
+   * method is only available when the {@link TransactionalRequest} decorator is present.
+   *
+   * <pre>{@code
+   *   install(new JdbiModule()
+   *     .sqlObjects(UserDAO.class)
+   *   );
+   *
+   *   decorator(new TransactionalRequest());
+   *
+   *   get("/users", ctx -> {
+   *     UserDAO dao = require(UserDAO.class);
+   *   });
+   * }</pre>
+   *
+   * @param sqlObjects List of SQL object to register as services.
+   * @return This module.
+   */
+  public @Nonnull JdbiModule sqlObjects(@Nonnull Class... sqlObjects) {
     this.sqlObjects = Arrays.asList(sqlObjects);
     return this;
   }
@@ -73,7 +176,7 @@ public JdbiModule sqlObjects(Class... sqlObjects) {
 
     /** SQLObjects: */
     for (Class<?> sqlObject : sqlObjects) {
-      registry.put(sqlObject, new SqlObjectProvider(provider, sqlObject));
+      registry.put(sqlObject, new SqlObjectProvider(jdbi, sqlObject));
     }
   }
 
diff --git a/modules/jooby-jdbi/src/main/java/io/jooby/jdbi/TransactionalRequest.java b/modules/jooby-jdbi/src/main/java/io/jooby/jdbi/TransactionalRequest.java
@@ -14,22 +14,84 @@
 
 import javax.annotation.Nonnull;
 
+/**
+ * Attach {@link Handle} to the current request. The route pipeline runs inside a transaction
+ * which is commit on success or rollback in case of exception.
+ *
+ * Once route pipeline is executed the handle is detached from current request and closed it.
+ *
+ * Usage:
+ *
+ * <pre>{@code
+ * {
+ *
+ *   install(new HikariModule());
+ *
+ *   install(new JdbiModule());
+ *
+ *   decorator(new TransactionalRequest());
+ *
+ *   get("/handle", ctx -> {
+ *     Handle handle = require(Handle.class);
+ *     // work with handle.
+ *   });
+ * }
+ * }</pre>
+ *
+ * The {@link Handle} should NOT be closed it by application code.
+ *
+ * SQL Objects example:
+ *
+ * <pre>{@code
+ * {
+ *
+ *   install(new HikariModule());
+ *
+ *   install(new JdbiModule()
+ *     .sqlObjects(UserDAO.class)
+ *   );
+ *
+ *   decorator(new TransactionalRequest());
+ *
+ *   get("/handle", ctx -> {
+ *     UserDAO dao = require(UserDAO.class);
+ *     // work with user dao
+ *   });
+ * }
+ * }</pre>
+ *
+ * The <code>UserDAO</code> sql object is attached to the current/request attached {@link Handle}.
+ *
+ * @author edgar
+ * @since 2.0.0
+ */
 public class TransactionalRequest implements Decorator {
 
   private ServiceKey<Jdbi> key;
 
+  /**
+   * Creates a transactional request. A jdbi with the given name must be available in the service
+   * registry.
+   *
+   * This constructor should be used only if you have multiple Jdbi installations.
+   *
+   * @param name Jdbi service name.
+   */
   public TransactionalRequest(@Nonnull String name) {
     key = ServiceKey.key(Jdbi.class, name);
   }
 
+  /**
+   * Creates a transactional request.
+   */
   public TransactionalRequest() {
     key = ServiceKey.key(Jdbi.class);
   }
 
   @Nonnull @Override public Route.Handler apply(@Nonnull Route.Handler next) {
     return ctx -> {
       Jdbi jdbi = ctx.require(key);
-      try(Handle handle = jdbi.open()) {
+      try (Handle handle = jdbi.open()) {
         RequestScope.bind(jdbi, handle);
         return handle.inTransaction(h -> next.apply(ctx));
       } finally {
