[DRILL-2089] Split JDBC implementation out of org.apache.drill.jdbc, so that pkg. is place for doc.

• Type: Improvement
• Status: Resolved
• Priority: Major
• Resolution: Fixed
• Fix Version/s: Future
• Component/s: Client - JDBC
• Assignee: Daniel Barclay
• Reporter: Daniel Barclay
• Created: 28/Jan/15 03:16
• Updated: 17/Jun/15 22:35
• Resolved: 17/Jun/15 22:35

Description

The JDBC implementation classes and interfaces that are not part of Drill's published JDBC interface should be moved out of package org.apache.drill.jdbc.

This will support using Javadoc to produce end-user documentation of Drill-specific JDBC API behavior (e.g., what's implemented or not, plus any extensions), and keep clear what is part of Drill's published JDBC interface vs. what is not (i.e., items that are technically accessible (public or protected) but not meant to be used by Drill users).

Parts:

1. Move most classes and packages in org.apache.drill.jdbc (e.g., DrillHandler, DrillConnectionImpl) to an implementation package (e.g., org.apache.drill.jdbc.impl).

2. Split the current org.apache.drill.jdbc.Driver into a published-interface portion still at org.apache.drill.jdbc.Driver plus an implementation portion at org.apache.drill.jdbc.impl.DriverImpl.

(org.apache.drill.jdbc.Driver would expose only the published interface (e.g., its constructor and methods from java.sql.Driver).

org.apache.drill.jdbc.impl.DriverImpl would contain methods that are not part of Drill's published JDBC interface (including methods that need to be public or protected because of using Avatica but which shouldn't be used by Drill users).)

3. As needed (for Drill extensions and for documentation), create Drill-specific interfaces extending standard JDBC interfaces.

For example, to create a place for documenting Drill-specific behavior of methods defined in java.sql.Connection, create an interface, e.g., org.apache.drill.jdbc.DrillConnection, that extends interface java.sql.Connection, adjust the internal implementation class in org.apache.drill.jdbc.impl to implement that Drill-specified interface rather than directly implementing java.sql.Connection, and then add a method declaration with the Drill-specific documentation to the Drill-specific subinterface.

4. In Drill-specific interfaces created per part 3, consider using co-variant return types to narrow return types to the Drill-specific interfaces.

For example: java.sql.Connection's createStatement() method returns type java.sql.Statement. Drill's implementation of that method will always return a Drill-specific implementation of java.sql.Statement, which will also be an implementation of the Drill-specific interface that extends java.sql.Statement. Therefore, the Drill-specific Connection interface can re-declare createStatement() as returning the Drill-specific Statement interface type (because the Drill-specific Statement type is a subtype of java.sql.Statement).

That would likely make it easier for client code to access any Drill extension methods: Although the client might have to cast or do something else special to get to the first Drill-specific interface or class, it could traverse to other objects (e.g., from connection to statement, from statement to result set, etc.) still using Drill-specific types, not needing casts or whatever as each step.

Note: Steps 1 and 2 have already been prototyped.

Issue Links

• is depended upon by: DRILL-2812 Regularize JDBC unit-level unit test class naming
• is depended upon by: DRILL-3160 Make JDBC Javadoc documentation available to users
• is depended upon by: DRILL-3216 Fix existing(+) INFORMATION_SCHEMA.COLUMNS columns
• is related to: DRILL-3262 Rename missed .impl.DrillDatabaseMetaData to .impl.DrillDatabaseMetaDataImpl to
• is required by: DRILL-3198 JDBC driver returns null from DatabaseMetaData.getTypeInfo(...)
• relates to: DRILL-2613 Implement ResultSet.getXxx(...) number-to-number data conversions
• relates to: DRILL-2961 Statement.setQueryTimeout() should throw a SQLException