Add javadoc comments for the Criteria API. (#507)

Primary parts only.

Author: nakamura-to

doma-core/src/main/java/org/seasar/doma/jdbc/criteria/Entityql.java

@@ -22,6 +22,10 @@
 import org.seasar.doma.jdbc.criteria.statement.EntityqlUpdateStatement;
 import org.seasar.doma.jdbc.criteria.statement.Statement;
 
+/**
+ * Provides the ways to query and associate entities. Use {@link NativeSql} to issue more complex
+ * SQL statements than this class does.
+ */
 public class Entityql {
 
   protected final Config config;

doma-core/src/main/java/org/seasar/doma/jdbc/criteria/NativeSql.java

@@ -25,6 +25,10 @@
 import org.seasar.doma.jdbc.criteria.statement.NativeSqlUpdateStarting;
 import org.seasar.doma.jdbc.query.SelectQuery;
 
+/**
+ * Provides the ways to issue more complex SQL statements rather than {@link Entityql} does. But
+ * note that this class doesn't support to associate entities.
+ */
 public class NativeSql {
 
   protected final Config config;

doma-core/src/main/java/org/seasar/doma/jdbc/criteria/command/package-info.java

@@ -0,0 +1,2 @@
+/** Provides classes that execute SQL statements and handle the results. */
+package org.seasar.doma.jdbc.criteria.command;

doma-core/src/main/java/org/seasar/doma/jdbc/criteria/context/DeleteSettings.java

@@ -1,39 +1,95 @@
 package org.seasar.doma.jdbc.criteria.context;
 
+import java.sql.PreparedStatement;
+
+/** Represents the settings for a DELETE criteria query. */
 public class DeleteSettings extends Settings {
   private int batchSize = 0;
   private boolean allowEmptyWhere;
   private boolean ignoreVersion;
   private boolean suppressOptimisticLockException;
 
+  /**
+   * Returns the batch size.
+   *
+   * @return the batch size. The default value is {@literal 0}.
+   */
   public int getBatchSize() {
     return batchSize;
   }
 
+  /**
+   * Sets the batch size.
+   *
+   * <p>If the value is less than 1, it is regarded as 1.
+   *
+   * @param batchSize the batch size
+   * @see PreparedStatement#executeBatch()
+   * @see PreparedStatement#addBatch()
+   */
   public void setBatchSize(int batchSize) {
     this.batchSize = batchSize;
   }
 
+  /**
+   * Returns whether the empty WHERE clause is allowed or not.
+   *
+   * @return whether the empty WHERE clause is allowed or not. The default value is {@literal
+   *     false}.
+   */
   public boolean getAllowEmptyWhere() {
     return allowEmptyWhere;
   }
 
+  /**
+   * Sets whether the empty WHERE clause is allowed or not.
+   *
+   * <p>If the value is {@literal true} and the WHERE clause is empty, {@link
+   * org.seasar.doma.jdbc.criteria.statement.EmptyWhereClauseException} will be suppressed.
+   *
+   * @param allowEmptyWhere whether the empty WHERE clause is allowed or not
+   */
   public void setAllowEmptyWhere(boolean allowEmptyWhere) {
     this.allowEmptyWhere = allowEmptyWhere;
   }
 
+  /**
+   * Returns whether to ignore the version property or not.
+   *
+   * @return whether to ignore the version property or not. The default value is {@literal false}.
+   */
   public boolean getIgnoreVersion() {
     return ignoreVersion;
   }
 
+  /**
+   * Sets whether to ignore the version property or not.
+   *
+   * <p>If the value is {@code true}, the column that mapped to the version property is excluded
+   * from the SQL DELETE statement.
+   *
+   * @param ignoreVersion whether to ignore the version property or not
+   */
   public void setIgnoreVersion(boolean ignoreVersion) {
     this.ignoreVersion = ignoreVersion;
   }
 
+  /**
+   * Returns whether to suppress {@link org.seasar.doma.jdbc.OptimisticLockException} or not.
+   *
+   * @return whether to suppress {@link org.seasar.doma.jdbc.OptimisticLockException} or not. The
+   *     default value is {@literal false}.
+   */
   public boolean getSuppressOptimisticLockException() {
     return suppressOptimisticLockException;
   }
 
+  /**
+   * Sets whether to suppress {@link org.seasar.doma.jdbc.OptimisticLockException} or not.
+   *
+   * @param suppressOptimisticLockException whether to suppress {@link
+   *     org.seasar.doma.jdbc.OptimisticLockException} or not
+   */
   public void setSuppressOptimisticLockException(boolean suppressOptimisticLockException) {
     this.suppressOptimisticLockException = suppressOptimisticLockException;
   }

doma-core/src/main/java/org/seasar/doma/jdbc/criteria/context/InsertSettings.java

@@ -1,21 +1,51 @@
 package org.seasar.doma.jdbc.criteria.context;
 
+import java.sql.PreparedStatement;
+
+/** Represents the settings for an INSERT criteria query. */
 public class InsertSettings extends Settings {
   private int batchSize = 0;
   private boolean excludeNull;
 
+  /**
+   * Returns the batch size.
+   *
+   * @return the batch size. The default value is {@literal 0}.
+   */
   public int getBatchSize() {
     return batchSize;
   }
 
+  /**
+   * Sets the batch size.
+   *
+   * <p>If the value is less than 1, it is regarded as 1.
+   *
+   * @param batchSize the batch size
+   * @see PreparedStatement#executeBatch()
+   * @see PreparedStatement#addBatch()
+   */
   public void setBatchSize(int batchSize) {
     this.batchSize = batchSize;
   }
 
+  /**
+   * Returns whether to exclude null properties or not.
+   *
+   * @return whether to exclude null properties or not. The default value is {@literal false}.
+   */
   public boolean getExcludeNull() {
     return excludeNull;
   }
 
+  /**
+   * Sets whether to exclude null properties or not.
+   *
+   * <p>If the value is {@code true}, the null properties are excluded from the SQL INSERT
+   * statement.
+   *
+   * @param excludeNull whether to exclude null properties or not
+   */
   public void setExcludeNull(boolean excludeNull) {
     this.excludeNull = excludeNull;
   }

doma-core/src/main/java/org/seasar/doma/jdbc/criteria/context/SelectSettings.java

@@ -1,30 +1,74 @@
 package org.seasar.doma.jdbc.criteria.context;
 
+import java.sql.Statement;
+
+/** Represents the settings for a SELECT criteria query. */
 public class SelectSettings extends Settings {
   private boolean allowEmptyWhere = true;
   private int fetchSize = 0;
   private int maxRows = 0;
 
+  /**
+   * Returns whether the empty WHERE clause is allowed or not.
+   *
+   * @return whether the empty WHERE clause is allowed or not. The default value is {@literal true}.
+   */
   public boolean getAllowEmptyWhere() {
     return allowEmptyWhere;
   }
 
+  /**
+   * Sets whether the empty WHERE clause is allowed or not.
+   *
+   * <p>If the value is {@literal false} and the WHERE clause is empty, {@link
+   * org.seasar.doma.jdbc.criteria.statement.EmptyWhereClauseException} will be thrown.
+   *
+   * @param allowEmptyWhere whether the empty WHERE clause is allowed or not
+   */
   public void setAllowEmptyWhere(boolean allowEmptyWhere) {
     this.allowEmptyWhere = allowEmptyWhere;
   }
 
+  /**
+   * Returns the fetch size.
+   *
+   * @return the fetch size. The default value is {@literal 0}.
+   */
   public int getFetchSize() {
     return fetchSize;
   }
 
+  /**
+   * Sets the fetch size.
+   *
+   * <p>If the value is greater than or equal to 1, it is passed to {@link
+   * Statement#setFetchSize(int)}.
+   *
+   * @param fetchSize the fetch size
+   * @see Statement#setFetchSize(int)
+   */
   public void setFetchSize(int fetchSize) {
     this.fetchSize = fetchSize;
   }
 
+  /**
+   * Returns the maximum number of rows for a {@code ResultSet} object.
+   *
+   * @return the maximum number of rows. The default value is {@literal 0}
+   */
   public int getMaxRows() {
     return maxRows;
   }
 
+  /**
+   * Sets the maximum number of rows for a {@code ResultSet} object.
+   *
+   * <p>If the value is greater than or equal to 1, it is passed to {@link
+   * Statement#setMaxRows(int)}.
+   *
+   * @param maxRows the maximum number of rows
+   * @see Statement#setMaxRows(int)
+   */
   public void setMaxRows(int maxRows) {
     this.maxRows = maxRows;
   }

doma-core/src/main/java/org/seasar/doma/jdbc/criteria/context/Settings.java

@@ -1,35 +1,73 @@
 package org.seasar.doma.jdbc.criteria.context;
 
+import java.sql.Statement;
 import java.util.Objects;
 import org.seasar.doma.jdbc.SqlLogType;
 
+/** Represents the settings for a criteria query. */
 public class Settings {
   private String comment;
   private SqlLogType sqlLogType = SqlLogType.FORMATTED;
   private int queryTimeout = 0;
 
+  /**
+   * Returns the comment for the SQL statement.
+   *
+   * @return the comment. The default value is {@literal null}.
+   */
   public String getComment() {
     return comment;
   }
 
+  /**
+   * Sets the comment for the SQL statement.
+   *
+   * <p>The implementation of {@link org.seasar.doma.jdbc.Commenter} can use this value.
+   *
+   * @param comment the comment for the SQL statement
+   */
   public void setComment(String comment) {
     Objects.requireNonNull(comment);
     this.comment = comment;
   }
 
+  /**
+   * Returns the SQL log type.
+   *
+   * @return the SQL log type. The default value is {@link SqlLogType#FORMATTED }
+   */
   public SqlLogType getSqlLogType() {
     return sqlLogType;
   }
 
+  /**
+   * Sets the SQL log type.
+   *
+   * <p>Specify {@link SqlLogType#RAW } or {@link SqlLogType#NONE } for the sensitive SQL statement.
+   *
+   * @param sqlLogType the SQL log type
+   */
   public void setSqlLogType(SqlLogType sqlLogType) {
     Objects.requireNonNull(sqlLogType);
     this.sqlLogType = sqlLogType;
   }
 
+  /**
+   * Returns the query timeout limit in seconds.
+   *
+   * @return the query timeout limit in seconds. The default value is {@literal 0}.
+   */
   public int getQueryTimeout() {
     return queryTimeout;
   }
 
+  /**
+   * Sets the query timeout limit in seconds.
+   *
+   * @param queryTimeout the query timeout limit in seconds. If the value is greater than or equal
+   *     to 1, it is passed to {@link Statement#setQueryTimeout(int)}.
+   * @see Statement#setQueryTimeout(int)
+   */
   public void setQueryTimeout(int queryTimeout) {
     this.queryTimeout = queryTimeout;
   }