WL#17215: Implement JDBC 4.3/4.5 Statement/Connection.enquote* methods

This feature addresses the request tracked under BUG#112083/Bug#35716870.

JDBC 4.3 (introduced in Java 9) added the following methods with default implementations to java.sql.Statement:

• enquoteIdentifier(String identifier, boolean alwaysQuote)

• enquoteLiteral(String val)

• enquoteNCharLiteral(String val)

• isSimpleIdentifier(String identifier)

By default, these implementations use the double quote character (") for quoting identifiers, ignoring the value returned by DatabaseMetaData.getIdentifierQuoteString(). Since MySQL uses a different quoting convention, the default implementation is non-compliant with MySQL standards and therefore must be overridden in MySQL Connector/J.

Although Connector/J targets Java 8 (which predates JDBC 4.3), these methods—if declared with their exact Java 9 signatures—will be available when running under higher Java versions. This implementation is designed to remain compatible with Java 8 for both compilation and testing; thus, the implementation will not be fully utilized unless run on a compatible Java version, and this should be considered an anticipatory change.

Addendum: Java 26 (JDBC 4.5) introduces methods with identical signatures and semantics on java.sql.Connection. This work must be extended to implement those methods as well, ensuring MySQL Connector/J is prepared for the upcoming Java release. Any changes described below for the java.sql.Statement API must be replicated for the new java.sql.Connection API.

Functional Requirements:

• FR.1: Override JDBC 4.3 Statement Methods for MySQL Compliance:

  The following methods from java.sql.Statement—enquoteIdentifier(String identifier, boolean alwaysQuote), enquoteLiteral(String val), enquoteNCharLiteral(String val), and isSimpleIdentifier(String identifier)—must be explicitly implemented in Connector/J.

  The implementations must ensure MySQL SQL syntax compliance, particularly with regard to identifier and literal quoting conventions.

• FR.2: Correct Identifier Quoting Behavior:

  enquoteIdentifier must use MySQL's identifier quote character (obtained by calling DatabaseMetaData.getIdentifierQuoteString()) rather than the JDBC default double quote (").

  The method must return the identifier properly quoted as per MySQL conventions, respecting the alwaysQuote parameter.

• FR.3: Correct Literal and NCharLiteral Quoting Behavior:

  enquoteLiteral must return the input string quoted as a MySQL-compliant string literal using single quotes ('), with proper escaping for embedded quotes.

  enquoteNCharLiteral must behave similarly but with additional handling for the NCHAR literal prefix, if applicable.

• FR.4: Accurate Identifier Validation:

  isSimpleIdentifier must correctly determine, using MySQL's rules, whether a string is a simple identifier that does not require quoting.

• FR.5: Backward Compatibility and Conditional Availability:

  The codebase and implementation must maintain source-level compatibility with Java 8, i.e., no Java 9+ APIs or language features outside of the method signatures and overrides.

  These new methods should be available and functional when Connector/J is run under Java 9 or later, though they will be inert/inaccessible when running under Java 8.

  Compilation and testing frameworks must continue to target Java 8.

Non-functional Requirements:

• NFR.1: No Impact on Existing Feature Set:

  The new method implementations must not affect existing Connector/J functionality on any supported platform.

Objective

Enhance MySQL Connector/J to ensure compliance with JDBC 4.3's statement methods, specifically regarding the quoting and validation of SQL identifiers and literals, while maintaining backward compatibility with Java 8.

Scope

• Implement JDBC 4.3 Methods:

  Override and implement the following JDBC 4.3 methods:

• public String enquoteIdentifier(String identifier, boolean alwaysQuote)

• public String enquoteLiteral(String val)

• public String enquoteNCharLiteral(String val)

• public boolean isSimpleIdentifier(String identifier)

  Implementations must comply with MySQL SQL syntax and JDBC requirements.

• Base Implementation:

  The original method implementations from the Java 9 SDK may be used as a base for this feature. Modifications must be applied to ensure compatibility with MySQL's quoting conventions and to integrate the use of DatabaseMetaData.getIdentifierQuoteString() for retrieving the correct identifier quote character.

• Quoting Character:

  Identifier quoting must use the character returned by DatabaseMetaData.getIdentifierQuoteString() rather than any hard-coded value.

• Backward Compatibility:

  The implementation must remain source-compatible with Java 8. Full method functionality will be accessible when running on Java 9 or later.

• Documentation:

  Update the Connector/J documentation to clarify the behavior of these methods and specify requirements or limitations based on the Java runtime version.

Key Considerations

• No impact to existing Connector/J functionality or Java 8 compilation and testing processes.

• Designed as a forward-compatible change supporting future JDBC standards and runtime environments.

• All changes must adhere to Oracle's security, compliance, and development best practices.

N/A