[jira] [Commented] (DERBY-7097) Update documentation to allow users to properly use EmbeddedDriver

classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view
|

[jira] [Commented] (DERBY-7097) Update documentation to allow users to properly use EmbeddedDriver

Richard N. Hillegas (Jira)

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

Daniel Le Berre commented on DERBY-7097:
----------------------------------------

My issue still holds.

Sure, I can drop derby.jar, derbyshared.jar and derbutools.jar in $TOMCATHOME/lib and my datasource will work fine.

But I have been dropping only derby.jar there for more than a decade to make it work.

Release 1.0.15 changes this. This is a huge change, not just for me, but for a lot of old and new users, which will not only use Derby official documentation but also tutorials found on the internet.

And from the description of the new packages, in [Libraries provided by Derby|https://db.apache.org/derby/docs/10.15/getstart/rgslib46043.html], I have no reason to use derbytools.jar to access the embedded driver, so no reason to put that jar in $TOMCATHOME/lib directory.

This issue is about making clear that a long standing way to proceed is no longer possible.

If the embedded driver in 10.15 is no longer 
org.apache.derby.jdbc.EmbeddedDriver
 but a new non API one that is not meant to to be known from the user, then derbytools.jar should be described as providing wintage/legacy EmbeddedDriver for compatibility reasons.

Sorry to be picky about this, but I shouldn't need to check which class are in a jar file to use a tool. The documentation should be clear about requirements. It has always been the case for derby in the past. I wish it will be the same in the future.

> Update documentation to allow users to properly use EmbeddedDriver
> ------------------------------------------------------------------
>
>                 Key: DERBY-7097
>                 URL: https://issues.apache.org/jira/browse/DERBY-7097
>             Project: Derby
>          Issue Type: Bug
>          Components: Documentation
>    Affects Versions: 10.15.2.0
>            Reporter: Daniel Le Berre
>            Priority: Major
>         Attachments: derby-7097-01-aa-jpms-related-website-changes.diff, derby-7097-01-ab-jpms-related-website-changes.diff, derby-7097-02-aa-releaseSummary.diff, derby-7097-03-aa-embeddedDemo.diff
>
>
> In earlier version of Derby, and as reported in the documentation, the EmbeddedDriver class was in derby.jar.
> As such, it was quite easy to deploy a webapp with an embedded derby database: it was sufficient to just add a derby.jar file to the project library.
> In current releases of derby (10.15.2.0), the EmbeddedDriver class is no longer in the derby.jar file but in the derbytools.jar file.
> ```
> $ for i in `ls *.jar`; do echo $i ; jar tf $i | grep Driver ; done
>  derby.jar
>  org/apache/derby/iapi/jdbc/AutoloadedDriver$1.class
>  org/apache/derby/iapi/jdbc/AutoloadedDriver.class
>  org/apache/derby/iapi/jdbc/Driver42.class
>  org/apache/derby/iapi/jdbc/InternalDriver$1.class
>  org/apache/derby/iapi/jdbc/InternalDriver$2.class
>  org/apache/derby/iapi/jdbc/InternalDriver$3.class
>  org/apache/derby/iapi/jdbc/InternalDriver$4.class
>  org/apache/derby/iapi/jdbc/InternalDriver$5.class
>  org/apache/derby/iapi/jdbc/InternalDriver$DaemonThreadFactory.class
>  org/apache/derby/iapi/jdbc/InternalDriver$LoginCallable.class
>  org/apache/derby/iapi/jdbc/InternalDriver.class
>  META-INF/services/java.sql.Driver
>  derbyLocale_cs.jar
>  derbyLocale_de_DE.jar
>  derbyLocale_es.jar
>  derbyLocale_fr.jar
>  derbyLocale_hu.jar
>  derbyLocale_it.jar
>  derbyLocale_ja_JP.jar
>  derbyLocale_ko_KR.jar
>  derbyLocale_pl.jar
>  derbyLocale_pt_BR.jar
>  derbyLocale_ru.jar
>  derbyLocale_zh_CN.jar
>  derbyLocale_zh_TW.jar
>  derbyclient.jar
>  org/apache/derby/client/ClientAutoloadedDriver.class
>  META-INF/services/java.sql.Driver
>  derbynet.jar
>  derbyoptionaltools.jar
>  derbyrun.jar
>  derbyshared.jar
>  derbytools.jar
>  org/apache/derby/jdbc/ClientDriver.class
>  org/apache/derby/jdbc/ClientDriver40.class
>  org/apache/derby/jdbc/EmbeddedDriver.class
> ```
> As such, most of the tutorials found on the internet about "how to use derby in embedded mode" are just wrong because they simply mention derby.jar as a dependency.
> Worst, derby own documentation is not up to date: as such, I had no way to understand why new releases of this tool that I have been using for more than a decade in the classroom suddenly did not work anymore.
> The explanation is finally simple: I just wonder how such impacting decision could be done without proper documentation.
> I am also surprised to be the first one reporting this, since the problem exists since at least a year.
> There are two possible fix to this issue:
>  * move back the EmbeddedDriver class to derby.jar (my favorite option I would say), but I guess there is a good reason for moving those classes to derbytools.jar
>  * update the documentation on Derby's web site, with a quite visible alert about this change.
>  
> I have been a pretty happy user of derby for years, and will certainly be in the future. Thanks for that great tool. However, that breaking change has been particularly annoying, which is the reason of that bug report.



--
This message was sent by Atlassian Jira
(v8.3.4#803005)