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

["Daniel Barclay (Drill) (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/DRILL-2089?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14488333#comment-14488333 ] 

Daniel Barclay (Drill) edited comment on DRILL-2089 at 4/13/15 8:15 PM:
------------------------------------------------------------------------

DRILL-2098 move started in DRILL-2613 work:  old class DrillResultSet split into interface DrillResultSet and class DrillResultSetImpl.


was (Author: dsbos):
DRILL-2098 move started in DRILL-2613 work.

> Split JDBC implementation 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)
>            Assignee: Daniel Barclay (Drill)
>             Fix For: Future
>
>
> 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.



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)