[PECOBLR-310] Refactor internal interfaces into internal package, and fix javadoc for public interfaces (#770)

* Fix javadoc for all public interfaces

Author: gopalldb

src/main/java/com/databricks/client/jdbc/Driver.java

@@ -2,9 +2,9 @@
 
 import static com.databricks.jdbc.telemetry.TelemetryHelper.*;
 
-import com.databricks.jdbc.api.IDatabricksConnectionContext;
 import com.databricks.jdbc.api.impl.DatabricksConnection;
 import com.databricks.jdbc.api.impl.DatabricksConnectionContextFactory;
+import com.databricks.jdbc.api.internal.IDatabricksConnectionContext;
 import com.databricks.jdbc.common.DatabricksClientType;
 import com.databricks.jdbc.common.util.*;
 import com.databricks.jdbc.dbclient.IDatabricksClient;
@@ -15,7 +15,6 @@
 import com.databricks.jdbc.log.JdbcLogger;
 import com.databricks.jdbc.log.JdbcLoggerFactory;
 import com.databricks.jdbc.model.telemetry.enums.DatabricksDriverErrorCode;
-import java.sql.*;
 import java.sql.Connection;
 import java.sql.DriverManager;
 import java.sql.DriverPropertyInfo;

src/main/java/com/databricks/jdbc/api/IDatabricksConnection.java

@@ -4,11 +4,29 @@
 import java.sql.SQLException;
 import java.sql.Statement;
 
+/**
+ * Extends the standard JDBC {@link Connection} interface to provide Databricks-specific
+ * functionality. This interface adds methods to retrieve statement handles and connection
+ * identifiers.
+ */
 public interface IDatabricksConnection extends Connection {
 
-  /** Returns the statement handle for given statement-Id */
+  /**
+   * Retrieves a statement handle for a given statement ID.
+   *
+   * @param statementId The unique identifier of the statement to retrieve
+   * @return A {@link Statement} object representing the statement
+   * @throws SQLException if a database access error occurs or this method is called on a closed
+   *     connection
+   */
   Statement getStatement(String statementId) throws SQLException;
 
-  /** Returns the connection-Id for the connection */
+  /**
+   * Retrieves the unique identifier for this connection.
+   *
+   * @return A string representing the unique connection ID
+   * @throws SQLException if a database access error occurs or this method is called on a closed
+   *     connection
+   */
   String getConnectionId() throws SQLException;
 }

src/main/java/com/databricks/jdbc/api/IDatabricksResultSet.java

@@ -6,40 +6,63 @@
 import java.sql.Struct;
 import java.util.Map;
 
-/** Extension to java.sql.ResultSet interface */
+/**
+ * Extends the standard JDBC {@link ResultSet} interface to provide Databricks-specific
+ * functionality. This interface adds support for complex data types like Structs and Maps, as well
+ * as methods to retrieve statement status and execution information.
+ */
 public interface IDatabricksResultSet extends ResultSet {
 
+  /**
+   * Retrieves the SQL `Struct` from the specified column using its label.
+   *
+   * @param columnLabel the label for the column specified in the SQL query
+   * @return a `Struct` object if the column contains a struct; `null` if the value is SQL `NULL`
+   * @throws SQLException if the column is not of `STRUCT` type or if any SQL error occurs
+   */
   Struct getStruct(String columnLabel) throws SQLException;
 
-  Map<String, Object> getMap(String columbLabel) throws SQLException;
+  /**
+   * Retrieves the SQL `Map` from the specified column using its label.
+   *
+   * @param columnLabel the label for the column specified in the SQL query
+   * @return a `Map<String, Object>` if the column contains a map; `null` if the value is SQL `NULL`
+   * @throws SQLException if the column is not of `MAP` type or if any SQL error occurs
+   */
+  Map<String, Object> getMap(String columnLabel) throws SQLException;
 
   /**
-   * Returns statement-Id of associated statement
+   * Retrieves the unique identifier of the statement associated with this result set.
    *
-   * @return statement-Id
+   * @return A string representing the statement ID
    */
   String getStatementId();
 
   /**
-   * Fetches Statement status for underlying statement
+   * Retrieves the current status of the statement associated with this result set. This can be used
+   * to monitor the execution progress and state of the statement.
    *
-   * @return statement status
+   * @return The current {@link StatementStatus} of the statement
    */
   StatementStatus getStatementStatus();
 
   /**
-   * Returns update count for underlying statement execution. Returns 0 for a query statement.
+   * Retrieves the number of rows affected by the SQL statement. For SELECT statements or statements
+   * that don't modify data, this will return 0.
    *
-   * @return update count
-   * @throws SQLException
+   * @return The number of rows affected by INSERT, UPDATE, or DELETE statements
+   * @throws SQLException if a database access error occurs or this method is called on a closed
+   *     result set
    */
   long getUpdateCount() throws SQLException;
 
   /**
-   * Checks if there is an update count for underlying statement execution
+   * Checks whether the executed SQL statement has produced an update count. This is typically true
+   * for DML (Data Manipulation Language) statements like INSERT, UPDATE, or DELETE.
    *
-   * @return true for DML commands
-   * @throws SQLException
+   * @return true if the statement has produced an update count, false otherwise
+   * @throws SQLException if a database access error occurs or this method is called on a closed
+   *     result set
    */
   boolean hasUpdateCount() throws SQLException;
 

src/main/java/com/databricks/jdbc/api/IDatabricksStatement.java

@@ -4,23 +4,35 @@
 import java.sql.SQLException;
 import java.sql.Statement;
 
-/** Interface for Databricks specific statement. */
+/**
+ * Extends the standard JDBC {@link Statement} interface to provide Databricks-specific
+ * functionality. This interface adds support for asynchronous query execution and result retrieval,
+ * allowing for better handling of long-running queries and improved performance in distributed
+ * environments.
+ */
 public interface IDatabricksStatement extends Statement {
 
   /**
-   * Executes the given SQL command in async mode, and returns a lightweight instance of result set
+   * Executes the given SQL command asynchronously and returns a lightweight result set handle. This
+   * method initiates the execution but does not wait for it to complete, making it suitable for
+   * long-running queries. The actual results can be retrieved later using {@link
+   * #getExecutionResult()}.
    *
-   * @param sql SQL command to be executed
-   * @return result set for given execution
-   * @throws SQLException in case of error
+   * @param sql The SQL command to be executed
+   * @return A {@link ResultSet} handle that can be used to track and retrieve the results
+   * @throws SQLException if a database access error occurs, this method is called on a closed
+   *     statement, or the SQL command is not valid
    */
   ResultSet executeAsync(String sql) throws SQLException;
 
   /**
-   * Returns result set response for the executed statement
+   * Retrieves the result set for a previously executed statement. This method should be called
+   * after executing a statement using {@link #executeAsync(String)} to get the actual results.
    *
-   * @return result set for underlying execution
-   * @throws SQLException if statement was never executed
+   * @return A {@link ResultSet} containing the results of the statement execution in case of
+   *     successful completion, else handle for the result status.
+   * @throws SQLException if the statement was never executed, has been closed, or if a database
+   *     access error occurs
    */
   ResultSet getExecutionResult() throws SQLException;
 }

src/main/java/com/databricks/jdbc/api/IDatabricksVolumeClient.java

@@ -5,106 +5,118 @@
 import java.util.List;
 import org.apache.http.entity.InputStreamEntity;
 
+/**
+ * Interface for interacting with Databricks Unity Catalog (UC) Volumes. Provides methods for
+ * managing and accessing files and directories within UC Volumes, supporting operations such as
+ * checking existence, listing contents, and performing CRUD (Create, Read, Update, Delete)
+ * operations on objects stored in volumes.
+ */
 public interface IDatabricksVolumeClient {
 
   /**
-   * prefixExists(): Determines if a specific prefix (folder-like structure) exists in the UC Volume
-   * The prefix that we are looking for must be a part of the file name.
+   * Checks if a specific prefix (folder-like structure) exists in the UC Volume. The prefix must be
+   * a part of the file name or path.
    *
-   * @param catalog the catalog name of the cloud storage
-   * @param schema the schema name of the cloud storage
-   * @param volume the UC volume name of the cloud storage
-   * @param prefix the prefix to check for existence along with the relative path from the volume as
-   *     the root directory
-   * @param caseSensitive a boolean indicating whether the check should be case-sensitive or not
-   * @return a boolean indicating whether the prefix exists or not
+   * @param catalog the catalog name in Unity Catalog
+   * @param schema the schema name in the specified catalog
+   * @param volume the volume name in the specified schema
+   * @param prefix the prefix to check, including the relative path from the volume root
+   * @param caseSensitive whether the prefix check should be case-sensitive
+   * @return true if the prefix exists, false otherwise
+   * @throws SQLException if a database access error occurs or the volume is inaccessible
    */
   boolean prefixExists(
       String catalog, String schema, String volume, String prefix, boolean caseSensitive)
       throws SQLException;
 
   /**
-   * objectExists(): Determines if a specific object (file) exists in the UC Volume The object that
-   * we are looking for must match the file name exactly
+   * Checks if a specific object (file) exists in the UC Volume. The object path must exactly match
+   * an existing file.
    *
-   * @param catalog the catalog name of the cloud storage
-   * @param schema the schema name of the cloud storage
-   * @param volume the UC volume name of the cloud storage
-   * @param objectPath the path of the object (file) from the volume as the root directory to check
-   *     for existence within the volume (inside any sub-folder)
-   * @param caseSensitive a boolean indicating whether the check should be case-sensitive or not
-   * @return a boolean indicating whether the object exists or not
+   * @param catalog the catalog name in Unity Catalog
+   * @param schema the schema name in the specified catalog
+   * @param volume the volume name in the specified schema
+   * @param objectPath the path of the object from the volume root
+   * @param caseSensitive whether the path check should be case-sensitive
+   * @return true if the object exists, false otherwise
+   * @throws SQLException if a database access error occurs or the volume is inaccessible
    */
   boolean objectExists(
       String catalog, String schema, String volume, String objectPath, boolean caseSensitive)
       throws SQLException;
 
   /**
-   * volumeExists(): Determines if a specific volume exists in the given catalog and schema. The
-   * volume that we are looking for must match the volume name exactly.
+   * Checks if a specific volume exists in the given catalog and schema. The volume name must match
+   * exactly.
    *
-   * @param catalog the catalog name of the cloud storage
-   * @param schema the schema name of the cloud storage
-   * @param volumeName the name of the volume to check for existence
-   * @param caseSensitive a boolean indicating whether the check should be case-sensitive or not
-   * @return a boolean indicating whether the volume exists or not
+   * @param catalog the catalog name in Unity Catalog
+   * @param schema the schema name in the specified catalog
+   * @param volumeName the name of the volume to check
+   * @param caseSensitive whether the volume name check should be case-sensitive
+   * @return true if the volume exists, false otherwise
+   * @throws SQLException if a database access error occurs
    */
   boolean volumeExists(String catalog, String schema, String volumeName, boolean caseSensitive)
       throws SQLException;
 
   /**
-   * listObjects(): Lists all filenames in the UC Volume that start with a specified prefix. The
-   * prefix that we are looking for must be a part of the file path from the volume as the root.
+   * Lists all objects (files) in the UC Volume that start with a specified prefix. The prefix must
+   * be a part of the file path from the volume root.
    *
-   * @param catalog the catalog name of the cloud storage
-   * @param schema the schema name of the cloud storage
-   * @param volume the UC volume name of the cloud storage
-   * @param prefix the prefix of the filenames to list. This includes the relative path from the
-   *     volume as the root directory
-   * @param caseSensitive a boolean indicating whether the check should be case-sensitive or not
-   * @return a list of strings indicating the filenames that start with the specified prefix
+   * @param catalog the catalog name in Unity Catalog
+   * @param schema the schema name in the specified catalog
+   * @param volume the volume name in the specified schema
+   * @param prefix the prefix to filter objects by, including the relative path from volume root
+   * @param caseSensitive whether the prefix matching should be case-sensitive
+   * @return a list of object paths that match the specified prefix
+   * @throws SQLException if a database access error occurs or the volume is inaccessible
    */
   List<String> listObjects(
       String catalog, String schema, String volume, String prefix, boolean caseSensitive)
       throws SQLException;
 
   /**
-   * getObject(): Retrieves an object (file) from the UC Volume and stores it in the local path
+   * Downloads an object (file) from the UC Volume to a local path.
    *
-   * @param catalog the catalog name of the cloud storage
-   * @param schema the schema name of the cloud storage
-   * @param volume the UC volume name of the cloud storage
-   * @param objectPath the path of the object (file) from the volume as the root directory
-   * @param localPath the local path where the retrieved data is to be stored
-   * @return a boolean value indicating status of the GET operation
+   * @param catalog the catalog name in Unity Catalog
+   * @param schema the schema name in the specified catalog
+   * @param volume the volume name in the specified schema
+   * @param objectPath the path of the object in the volume
+   * @param localPath the local filesystem path where the object should be saved
+   * @return true if the download was successful, false otherwise
+   * @throws SQLException if a database access error occurs, the volume is inaccessible, or there
+   *     are issues with the local filesystem
    */
   boolean getObject(
       String catalog, String schema, String volume, String objectPath, String localPath)
       throws SQLException;
 
   /**
-   * getObject(): Retrieves an object as input stream from the UC Volume
+   * Retrieves an object as an input stream from the UC Volume. The caller is responsible for
+   * closing the returned input stream.
    *
-   * @param catalog the catalog name of the cloud storage
-   * @param schema the schema name of the cloud storage
-   * @param volume the UC volume name of the cloud storage
-   * @param objectPath the path of the object (file) from the volume as the root directory
-   * @return an instance of input stream entity
+   * @param catalog the catalog name in Unity Catalog
+   * @param schema the schema name in the specified catalog
+   * @param volume the volume name in the specified schema
+   * @param objectPath the path of the object in the volume
+   * @return an InputStreamEntity containing the object's data
+   * @throws SQLException if a database access error occurs or the volume is inaccessible
    */
   InputStreamEntity getObject(String catalog, String schema, String volume, String objectPath)
       throws SQLException;
 
   /**
-   * putObject(): Upload data from a local path to a specified path within a UC Volume.
+   * Uploads data from a local file to a specified path within a UC Volume.
    *
-   * @param catalog the catalog name of the cloud storage
-   * @param schema the schema name of the cloud storage
-   * @param volume the UC volume name of the cloud storage
-   * @param objectPath the destination path where the object (file) is to be uploaded from the
-   *     volume as the root directory
-   * @param localPath the local path from where the data is to be uploaded
-   * @param toOverwrite a boolean indicating whether to overwrite the object if it already exists
-   * @return a boolean value indicating status of the PUT operation
+   * @param catalog the catalog name in Unity Catalog
+   * @param schema the schema name in the specified catalog
+   * @param volume the volume name in the specified schema
+   * @param objectPath the destination path in the volume where the file should be uploaded
+   * @param localPath the local filesystem path of the file to upload
+   * @param toOverwrite whether to overwrite the object if it already exists
+   * @return true if the upload was successful, false otherwise
+   * @throws SQLException if a database access error occurs, the volume is inaccessible, or there
+   *     are issues with the local filesystem
    */
   boolean putObject(
       String catalog,
@@ -116,17 +128,17 @@ boolean putObject(
       throws SQLException;
 
   /**
-   * putObject(): Upload data from an input stream to a specified path within a UC Volume.
+   * Uploads data from an input stream to a specified path within a UC Volume.
    *
-   * @param catalog the catalog name of the cloud storage
-   * @param schema the schema name of the cloud storage
-   * @param volume the UC volume name of the cloud storage
-   * @param objectPath the destination path where the object (file) is to be uploaded from the
-   *     volume as the root directory
-   * @param inputStream the input stream from where the data is to be uploaded
-   * @param contentLength the length of the input stream
-   * @param toOverwrite a boolean indicating whether to overwrite the object if it already exists
-   * @return a boolean value indicating status of the PUT operation
+   * @param catalog the catalog name in Unity Catalog
+   * @param schema the schema name in the specified catalog
+   * @param volume the volume name in the specified schema
+   * @param objectPath the destination path in the volume where the data should be uploaded
+   * @param inputStream the input stream containing the data to upload
+   * @param contentLength the length of the data in bytes
+   * @param toOverwrite whether to overwrite the object if it already exists
+   * @return true if the upload was successful, false otherwise
+   * @throws SQLException if a database access error occurs or the volume is inaccessible
    */
   boolean putObject(
       String catalog,
@@ -139,13 +151,14 @@ boolean putObject(
       throws SQLException;
 
   /**
-   * deleteObject(): Remove an object from a specified path within a UC Volume
+   * Deletes an object from a specified path within a UC Volume.
    *
-   * @param catalog the catalog name of the cloud storage
-   * @param schema the schema name of the cloud storage
-   * @param volume the UC volume name of the cloud storage
-   * @param objectPath the path of the object (file) from the volume as the root directory to delete
-   * @return a boolean value indicating status of the DELETE operation
+   * @param catalog the catalog name in Unity Catalog
+   * @param schema the schema name in the specified catalog
+   * @param volume the volume name in the specified schema
+   * @param objectPath the path of the object to delete
+   * @return true if the deletion was successful, false otherwise
+   * @throws SQLException if a database access error occurs or the volume is inaccessible
    */
   boolean deleteObject(String catalog, String schema, String volume, String objectPath)
       throws SQLException;