Daniel Barclay (Drill/MapR) created DRILL-2089:
--------------------------------------------------
Summary: Split JDBC impl. out of org.apache.drill.jdbc, so that
pkg. is place for doc.
Key: DRILL-2089
URL: https://issues.apache.org/jira/browse/DRILL-2089
Project: Apache Drill
Issue Type: Improvement
Components: Client - JDBC
Reporter: Daniel Barclay (Drill/MapR)
Assignee: Daniel Barclay (Drill/MapR)
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 documentation and any extensions), create Drill-specific
interfaces extending standard JDBC interfaces.
For example, to create a place for documenting Drill-specific behavior of a
methods defined in {{java.sql.Connection}}, create an interface, e.g.,
{{org.apache.drill.jdbc.Connection}}, 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.
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
