some javadoc

Author: Nikolai Malygin

src/main/java/com/nmalygin/superb/jdbc/api/Appendable.java

@@ -24,6 +24,19 @@
 
 package com.nmalygin.superb.jdbc.api;
 
+/**
+ * An object to which the sql fragment can be appended.
+ *
+ * @param <T> Type of return
+ * @author Nikolai Malygin
+ */
 public interface Appendable<T> {
+    /**
+     * Appends the parametrized sql fragment with attributes to the object.
+     *
+     * @param sqlFragment Parametrized sql fragment
+     * @param withArguments Arguments for the corresponding parameters in the sqlFragment
+     * @return itself
+     */
     T append(String sqlFragment, Argument... withArguments);
 }

src/main/java/com/nmalygin/superb/jdbc/api/Argument.java

@@ -27,6 +27,19 @@
 import java.sql.PreparedStatement;
 import java.sql.SQLException;
 
+/**
+ * Parameterized sql query argument.
+ *
+ * @author Nikolai Malygin
+ */
 public interface Argument {
+
+    /**
+     *
+     * @param preparedStatement PreparedStatement
+     * @param position Index of the argument
+     * @throws SQLException if parameterIndex does not correspond to a parameter marker in the SQL statement;
+     * if a database access error occurs or this method is called on a closed PreparedStatement
+     */
     void pass(PreparedStatement preparedStatement, int position) throws SQLException;
 }

src/main/java/com/nmalygin/superb/jdbc/api/Batch.java

@@ -26,9 +26,37 @@
 
 import java.sql.SQLException;
 
+/**
+ * An object representing a batch of operations.
+ *
+ * @author Nikolai Malygin
+ */
 public interface Batch extends AutoCloseable {
+
+    /**
+     * Adding an operation to the batch.
+     *
+     * @param arguments Arguments of one operation
+     * @throws SQLException if parameterIndex does not correspond to a parameter marker in the SQL statement;
+     * if a database access error occurs or this method is called on a closed PreparedStatement
+     */
     void put(Argument... arguments) throws SQLException;
+
+    /**
+     * Apply the batch to the database.
+     *
+     * @throws SQLException if a database access error occurs, this method is called on a closed Statement or the driver does not support batch statements.
+     * if one of the commands sent to the database fails to execute properly or attempts to return a result set.
+     * if the driver has determined that the timeout value that was specified by the setQueryTimeout method has been exceeded and has at least attempted to cancel the currently running Statement
+     */
     void apply() throws SQLException;
+
+    /**
+     * Releases the batch object and JDBC resources. It is generally good practice to release resources as
+     * soon as you are finished with them to avoid tying up database resources.
+     *
+     * @throws SQLException if a database access error occurs
+     */
     @Override
     void close() throws SQLException;
 }

src/main/java/com/nmalygin/superb/jdbc/api/Batches.java

@@ -29,12 +29,6 @@
 /**
  * {@link Batch} factory.
  *
- * <p>
- * Example of use:
- * <pre>{@code
- *   Batch batch = batches.batch("INSERT INTO books(id, title) VALUES (?, ?)");
- * }</pre>
- *
  * @author Nikolai Malygin
  */
 public interface Batches {
@@ -44,6 +38,7 @@ public interface Batches {
      *
      * @param sql Parameterized sql query
      * @return The {@link Batch} object
+     * @throws SQLException if a database access error occurs or database connection is closed
      */
     Batch batch(String sql) throws SQLException;
 }

src/main/java/com/nmalygin/superb/jdbc/api/Change.java

@@ -26,6 +26,17 @@
 
 import java.sql.SQLException;
 
+/**
+ * Represents a database query like DML or DDL.
+ *
+ * @author Nikolai Malygin
+ */
 public interface Change {
+
+    /**
+     * Apply the change to the database.
+     *
+     * @throws SQLException if a database access error occurs or connection is closed
+     */
     void apply() throws SQLException;
 }

src/main/java/com/nmalygin/superb/jdbc/api/Changes.java

@@ -27,15 +27,6 @@
 /**
  * {@link Change} factory.
  *
- * <p>
- * Example of use:
- * <pre>{@code
- *   Change change = changes.change(
- *                 "INSERT INTO books (id, title) VALUES (?, ?)",
- *                 new IntParam(1),
- *                 new StringParam("Clean Code"));
- * }</pre>
- *
  * @author Nikolai Malygin
  */
 public interface Changes {

src/main/java/com/nmalygin/superb/jdbc/api/Queries.java

@@ -27,12 +27,6 @@
 /**
  * {@link Query} factory.
  *
- * <p>
- * Example of use:
- * <pre>{@code
- *   Query query = queries.query("SELECT title FROM books);
- * }</pre>
- *
  * @author Nikolai Malygin
  */
 public interface Queries {

src/main/java/com/nmalygin/superb/jdbc/api/Query.java

@@ -29,14 +29,6 @@
 /**
  * Represents a data retrieval query.
  *
- * <p>
- * Example of use:
- * <pre>{@code
- *   List<String> titles = queries
- *                 .query("SELECT title FROM books")
- *                 .executeWith(/* some handler *&#47;);
- * }</pre>
- *
  * @author Nikolai Malygin
  */
 public interface Query extends Appendable<Query> {

src/main/java/com/nmalygin/superb/jdbc/api/Rdbms.java

@@ -24,5 +24,10 @@
 
 package com.nmalygin.superb.jdbc.api;
 
+/**
+ * The Relational Database Management System object.
+ *
+ * @author Nikolai Malygin
+ */
 public interface Rdbms extends Queries, Changes, Batches, Transactions {
 }

src/main/java/com/nmalygin/superb/jdbc/api/ResultSetHandler.java

@@ -27,6 +27,20 @@
 import java.sql.ResultSet;
 import java.sql.SQLException;
 
+/**
+ * The object that processes the result set of a {@link Query}.
+ *
+ * @param <R> Type of the object that return the handle method.
+ * @author Nikolai Malygin
+ */
 public interface ResultSetHandler<R> {
+
+    /**
+     *
+     *
+     * @param resultSet ResultSet
+     * @return Some object after processing resultSet
+     * @throws SQLException
+     */
     R handle(ResultSet resultSet) throws SQLException;
 }