drill-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Daniel Barclay (Drill/MapR) (JIRA)" <j...@apache.org>
Subject [jira] [Created] (DRILL-2089) Split JDBC impl. out of org.apache.drill.jdbc, so that pkg. is place for doc.
Date Wed, 28 Jan 2015 03:17:34 GMT
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).


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

View raw message