Add JavaDoc to org.seasar.doma.jdbc.command package (#1331)

Author: nakamura-to

doma-core/src/main/java/org/seasar/doma/jdbc/command/BatchDeleteCommand.java

@@ -21,12 +21,30 @@
 import org.seasar.doma.jdbc.PreparedSql;
 import org.seasar.doma.jdbc.query.BatchDeleteQuery;
 
+/**
+ * A command to execute a batch delete.
+ *
+ * <p>This command executes SQL DELETE statements in batch mode.
+ */
 public class BatchDeleteCommand extends BatchModifyCommand<BatchDeleteQuery> {
 
+  /**
+   * Creates a new instance.
+   *
+   * @param query the batch delete query
+   */
   public BatchDeleteCommand(BatchDeleteQuery query) {
     super(query);
   }
 
+  /**
+   * Executes the batch delete.
+   *
+   * @param preparedStatement the prepared statement
+   * @param sqls the SQL statements
+   * @return the array of deleted rows count
+   * @throws SQLException if a database access error occurs
+   */
   @Override
   protected int[] executeInternal(PreparedStatement preparedStatement, List<PreparedSql> sqls)
       throws SQLException {

doma-core/src/main/java/org/seasar/doma/jdbc/command/BatchInsertCommand.java

@@ -24,12 +24,34 @@
 import org.seasar.doma.jdbc.query.BatchInsertQuery;
 import org.seasar.doma.jdbc.statistic.StatisticManager;
 
+/**
+ * A command to execute a batch insert.
+ *
+ * <p>This command executes SQL INSERT statements in batch mode and generates IDs for entities if
+ * necessary.
+ */
 public class BatchInsertCommand extends BatchModifyCommand<BatchInsertQuery> {
 
+  /**
+   * Creates a new instance.
+   *
+   * @param query the batch insert query
+   */
   public BatchInsertCommand(BatchInsertQuery query) {
     super(query);
   }
 
+  /**
+   * Executes the batch insert and generates IDs if necessary.
+   *
+   * <p>If batch operation is supported, it uses the batch execution mode. Otherwise, it executes
+   * each SQL statement individually.
+   *
+   * @param preparedStatement the prepared statement
+   * @param sqls the SQL statements
+   * @return the array of inserted rows count
+   * @throws SQLException if a database access error occurs
+   */
   @Override
   protected int[] executeInternal(PreparedStatement preparedStatement, List<PreparedSql> sqls)
       throws SQLException {
@@ -57,6 +79,15 @@ protected int[] executeInternal(PreparedStatement preparedStatement, List<Prepar
     return updatedRows;
   }
 
+  /**
+   * Executes a single update operation.
+   *
+   * @param preparedStatement the prepared statement
+   * @param sql the SQL statement
+   * @return the number of affected rows
+   * @throws SQLException if a database access error occurs
+   * @throws BatchUniqueConstraintException if a unique constraint violation occurs
+   */
   protected int executeUpdate(PreparedStatement preparedStatement, PreparedSql sql)
       throws SQLException {
     try {
@@ -71,6 +102,13 @@ protected int executeUpdate(PreparedStatement preparedStatement, PreparedSql sql
     }
   }
 
+  /**
+   * Generates IDs for the batch of entities after execution.
+   *
+   * @param preparedStatement the prepared statement
+   * @param position the position of the first element in the batch
+   * @param size the size of the executed batch
+   */
   @Override
   protected void postExecuteBatch(PreparedStatement preparedStatement, int position, int size) {
     query.generateIds(preparedStatement, position, size);

doma-core/src/main/java/org/seasar/doma/jdbc/command/BatchModifyCommand.java

@@ -34,20 +34,44 @@
 import org.seasar.doma.jdbc.query.BatchModifyQuery;
 import org.seasar.doma.jdbc.statistic.StatisticManager;
 
+/**
+ * An abstract command for batch modification operations (insert, update, delete).
+ *
+ * <p>This class provides common functionality for executing SQL statements in batch mode.
+ *
+ * @param <QUERY> the query type
+ */
 public abstract class BatchModifyCommand<QUERY extends BatchModifyQuery> implements Command<int[]> {
 
+  /** The query to be executed. */
   protected final QUERY query;
 
+  /**
+   * Creates a new instance.
+   *
+   * @param query the batch modification query
+   * @throws AssertionError if the query is null
+   */
   protected BatchModifyCommand(QUERY query) {
     assertNotNull(query);
     this.query = query;
   }
 
+  /**
+   * Returns the query.
+   *
+   * @return the query
+   */
   @Override
   public QUERY getQuery() {
     return query;
   }
 
+  /**
+   * Executes the batch operation.
+   *
+   * @return the array of affected rows count
+   */
   @Override
   public int[] execute() {
     if (!query.isExecutable()) {
@@ -75,6 +99,13 @@ public int[] execute() {
     }
   }
 
+  /**
+   * Prepares a statement for execution.
+   *
+   * @param connection the database connection
+   * @param sql the SQL to be prepared
+   * @return the prepared statement
+   */
   protected PreparedStatement prepareStatement(Connection connection, PreparedSql sql) {
     if (query.isAutoGeneratedKeysSupported()) {
       Config config = query.getConfig();
@@ -89,15 +120,37 @@ protected PreparedStatement prepareStatement(Connection connection, PreparedSql
     return JdbcUtil.prepareStatement(connection, sql);
   }
 
+  /**
+   * Executes the batch operation internally.
+   *
+   * @param preparedStatement the prepared statement
+   * @param sqls the SQL statements
+   * @return the array of affected rows count
+   * @throws SQLException if a database access error occurs
+   */
   protected abstract int[] executeInternal(
       PreparedStatement preparedStatement, List<PreparedSql> sqls) throws SQLException;
 
+  /**
+   * Sets up options for the prepared statement.
+   *
+   * @param preparedStatement the prepared statement
+   * @throws SQLException if a database access error occurs
+   */
   protected void setupOptions(PreparedStatement preparedStatement) throws SQLException {
     if (query.getQueryTimeout() > 0) {
       preparedStatement.setQueryTimeout(query.getQueryTimeout());
     }
   }
 
+  /**
+   * Executes the batch operation.
+   *
+   * @param preparedStatement the prepared statement
+   * @param sqls the SQL statements
+   * @return the array of affected rows count
+   * @throws SQLException if a database access error occurs
+   */
   protected int[] executeBatch(PreparedStatement preparedStatement, List<PreparedSql> sqls)
       throws SQLException {
     StatisticManager statisticManager = query.getConfig().getStatisticManager();
@@ -129,6 +182,15 @@ protected int[] executeBatch(PreparedStatement preparedStatement, List<PreparedS
     return updatedRows;
   }
 
+  /**
+   * Executes the batch operation.
+   *
+   * @param preparedStatement the prepared statement
+   * @param sql the SQL statement
+   * @return the array of affected rows count
+   * @throws SQLException if a database access error occurs
+   * @throws BatchUniqueConstraintException if a unique constraint violation occurs
+   */
   protected int[] executeBatch(PreparedStatement preparedStatement, PreparedSql sql)
       throws SQLException {
     try {
@@ -152,17 +214,38 @@ protected int[] executeBatch(PreparedStatement preparedStatement, PreparedSql sq
    */
   protected void postExecuteBatch(PreparedStatement preparedStatement, int position, int size) {}
 
+  /**
+   * Logs the SQL statement.
+   *
+   * @param sql the SQL statement
+   */
   protected void log(PreparedSql sql) {
     JdbcLogger logger = query.getConfig().getJdbcLogger();
     logger.logSql(query.getClassName(), query.getMethodName(), sql);
   }
 
+  /**
+   * Binds parameters to the prepared statement.
+   *
+   * @param preparedStatement the prepared statement
+   * @param sql the SQL statement with parameters
+   * @throws SQLException if a database access error occurs
+   */
   protected void bindParameters(PreparedStatement preparedStatement, PreparedSql sql)
       throws SQLException {
     PreparedSqlParameterBinder binder = new PreparedSqlParameterBinder(query);
     binder.bind(preparedStatement, sql.getParameters());
   }
 
+  /**
+   * Validates the affected rows count.
+   *
+   * @param preparedStatement the prepared statement
+   * @param sql the SQL statement
+   * @param rows the array of affected rows count
+   * @throws SQLException if a database access error occurs
+   * @throws BatchOptimisticLockException if optimistic lock constraint is violated
+   */
   protected void validateRows(PreparedStatement preparedStatement, PreparedSql sql, int[] rows)
       throws SQLException {
     Dialect dialect = query.getConfig().getDialect();

doma-core/src/main/java/org/seasar/doma/jdbc/command/BatchUpdateCommand.java

@@ -21,12 +21,31 @@
 import org.seasar.doma.jdbc.PreparedSql;
 import org.seasar.doma.jdbc.query.BatchUpdateQuery;
 
+/**
+ * A command to execute a batch update.
+ *
+ * <p>This command executes SQL UPDATE statements in batch mode and increments version numbers if
+ * entities have optimistic lock control.
+ */
 public class BatchUpdateCommand extends BatchModifyCommand<BatchUpdateQuery> {
 
+  /**
+   * Creates a new instance.
+   *
+   * @param query the batch update query
+   */
   public BatchUpdateCommand(BatchUpdateQuery query) {
     super(query);
   }
 
+  /**
+   * Executes the batch update and increments version numbers.
+   *
+   * @param preparedStatement the prepared statement
+   * @param sqls the SQL statements
+   * @return the array of updated rows count
+   * @throws SQLException if a database access error occurs
+   */
   @Override
   protected int[] executeInternal(PreparedStatement preparedStatement, List<PreparedSql> sqls)
       throws SQLException {

doma-core/src/main/java/org/seasar/doma/jdbc/command/Command.java

@@ -17,9 +17,39 @@
 
 import org.seasar.doma.jdbc.query.Query;
 
+/**
+ * A core interface for executing database operations in the Doma framework.
+ *
+ * <p>This interface represents a command pattern implementation for database access. Each command
+ * encapsulates a specific database operation (such as select, insert, update, delete) along with
+ * its execution logic. Commands are responsible for executing queries and processing their results.
+ *
+ * <p>The Command interface is designed to be extensible, with various implementations for different
+ * types of database operations. Each implementation handles the specific details of executing its
+ * associated query type and processing the results.
+ *
+ * @param <RESULT> the type of result that this command produces when executed
+ */
 public interface Command<RESULT> {
 
+  /**
+   * Returns the query associated with this command.
+   *
+   * <p>The query contains the SQL statement and parameters that will be executed by this command.
+   *
+   * @return the query object that this command will execute
+   */
   Query getQuery();
 
+  /**
+   * Executes the command and returns the result.
+   *
+   * <p>This method is responsible for executing the database operation encapsulated by this
+   * command. It handles the execution of the SQL statement, processing of results, and any
+   * necessary resource management.
+   *
+   * @return the result of executing the command, the type depends on the specific command
+   *     implementation
+   */
   RESULT execute();
 }

doma-core/src/main/java/org/seasar/doma/jdbc/command/CreateCommand.java

@@ -22,19 +22,43 @@
 import org.seasar.doma.jdbc.query.CreateQuery;
 import org.seasar.doma.message.Message;
 
+/**
+ * A command to create a database object.
+ *
+ * <p>This command executes a query that creates a database object such as a table or index.
+ *
+ * @param <RESULT> the result type
+ */
 public class CreateCommand<RESULT> implements Command<RESULT> {
 
+  /** the query */
   protected final CreateQuery<RESULT> query;
 
+  /**
+   * Creates a new instance.
+   *
+   * @param query the create query
+   */
   public CreateCommand(CreateQuery<RESULT> query) {
     this.query = query;
   }
 
+  /**
+   * Returns the query.
+   *
+   * @return the query
+   */
   @Override
   public CreateQuery<RESULT> getQuery() {
     return query;
   }
 
+  /**
+   * Executes the create operation.
+   *
+   * @return the result
+   * @throws JdbcException if a database access error occurs
+   */
   @Override
   public RESULT execute() {
     Connection connection = JdbcUtil.getConnection(query.getConfig().getDataSource());