Derby
  1. Derby
  2. DERBY-5612

Puzzling documentation about the URL to a database on the classpath

    Details

    • Type: Bug Bug
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 10.9.1.0
    • Fix Version/s: 10.9.1.0
    • Component/s: Documentation
    • Labels:
      None
    • Urgency:
      Normal

      Description

      The "Accessing databases from the classpath" section of the Derby Developer's Guide says that you can access a database on the classpath by putting a forward slash in front of the database name (and then adding other path legs as needed). I don't find that it works this way. I ran the following experiment:

      1) I put a database called nast in the testRun/extin subdirectory of the current directory.

      2) Then I put testRun/extin on the classpath.

      3) Then I tried connecting to the database with various URLs.

      The following URLs could not find the database:

      connect 'jdbc:derby:/nast;user=KIWI;password=KIWI_password';
      connect 'jdbc:derby:nast;user=KIWI;password=KIWI_password';
      connect 'jdbc:derby:classpath:/nast;user=KIWI;password=KIWI_password';

      But the following URL found the database:

      connect 'jdbc:derby:classpath:nast;user=KIWI;password=KIWI_password';

      This is not what I expected from the documentation in the Developer's Guide.

      1. DERBY-5612-2.zip
        12 kB
        Kim Haase
      2. DERBY-5612-2.stat
        0.3 kB
        Kim Haase
      3. DERBY-5612-2.diff
        12 kB
        Kim Haase
      4. DERBY-5612.zip
        16 kB
        Kim Haase
      5. DERBY-5612.stat
        0.3 kB
        Kim Haase
      6. DERBY-5612.diff
        7 kB
        Kim Haase

        Issue Links

          Activity

          Hide
          Knut Anders Hatlen added a comment -

          I didn't get it to work without the classpath sub-sub-protocol in any version, but with 10.0 and 10.1 it looks like it works with a leading slash when specifying the classpath sub-sub-protocol explicitly. Not so with 10.2 and later.

          Show
          Knut Anders Hatlen added a comment - I didn't get it to work without the classpath sub-sub-protocol in any version, but with 10.0 and 10.1 it looks like it works with a leading slash when specifying the classpath sub-sub-protocol explicitly. Not so with 10.2 and later.
          Hide
          Knut Anders Hatlen added a comment -

          The change was introduced by this commit:

          ------------------------------------------------------------------------
          r240111 | djd | 2005-08-25 20:02:57 +0200 (Thu, 25 Aug 2005) | 9 lines

          DERBY-540 Do not prepend database name for classpath databases with leading slash.This causes
          databases to be not found when in jar files on the database. Correct the lookup of resources
          in the class path storage factory to not use the methods that prepend the current class name,
          instead use methods from ClassLoader directly. The leading slash was incorrectly added to avoid
          the automatic package prepending performed by Class.getResource.
          Removed code that tried to optimise not using the thread context class loader, simply have a
          fixed lookup for resources of thread context class loader followed by class loader for Derby/system classloader.
          Add lang/dbjar.sql to test databases within a jar and within a jar on the classpath and class loading from such databases.

          ------------------------------------------------------------------------

          Show
          Knut Anders Hatlen added a comment - The change was introduced by this commit: ------------------------------------------------------------------------ r240111 | djd | 2005-08-25 20:02:57 +0200 (Thu, 25 Aug 2005) | 9 lines DERBY-540 Do not prepend database name for classpath databases with leading slash.This causes databases to be not found when in jar files on the database. Correct the lookup of resources in the class path storage factory to not use the methods that prepend the current class name, instead use methods from ClassLoader directly. The leading slash was incorrectly added to avoid the automatic package prepending performed by Class.getResource. Removed code that tried to optimise not using the thread context class loader, simply have a fixed lookup for resources of thread context class loader followed by class loader for Derby/system classloader. Add lang/dbjar.sql to test databases within a jar and within a jar on the classpath and class loading from such databases. ------------------------------------------------------------------------
          Hide
          Kim Haase added a comment -

          Thanks for noticing this, Rick. Looks like the change fell through the documentation cracks back in 2005. Better late than never.

          Show
          Kim Haase added a comment - Thanks for noticing this, Rick. Looks like the change fell through the documentation cracks back in 2005. Better late than never.
          Hide
          Kim Haase added a comment -

          Is there a distinction between jar and zip files on the classpath and databases on the classpath? Several topics mention the initial backslash for jar/zip files. For example:

          http://db.apache.org/derby/docs/dev/devguide/tdevdeploy39856.html
          http://db.apache.org/derby/docs/dev/devguide/rdevdvlp847152.html

          It also looks as if not just the "Accessing databases from the classpath" topic but some others need fixes:

          http://db.apache.org/derby/docs/dev/devguide/rdevdvlp22102.html
          http://db.apache.org/derby/docs/dev/devguide/cdevdeploy18716.html
          http://db.apache.org/derby/docs/dev/devguide/cdevdvlp17453.html

          Show
          Kim Haase added a comment - Is there a distinction between jar and zip files on the classpath and databases on the classpath? Several topics mention the initial backslash for jar/zip files. For example: http://db.apache.org/derby/docs/dev/devguide/tdevdeploy39856.html http://db.apache.org/derby/docs/dev/devguide/rdevdvlp847152.html It also looks as if not just the "Accessing databases from the classpath" topic but some others need fixes: http://db.apache.org/derby/docs/dev/devguide/rdevdvlp22102.html http://db.apache.org/derby/docs/dev/devguide/cdevdeploy18716.html http://db.apache.org/derby/docs/dev/devguide/cdevdvlp17453.html
          Hide
          Rick Hillegas added a comment -

          Hi Kim,

          A database doesn't need to be in a jar file in order to be accessed via the classpath, although that is probably common usage. If the classpath contains a directory and that directory has a database as a subdirectory, then the database can be accessed via the classpath subprotocol. Thanks.

          Show
          Rick Hillegas added a comment - Hi Kim, A database doesn't need to be in a jar file in order to be accessed via the classpath, although that is probably common usage. If the classpath contains a directory and that directory has a database as a subdirectory, then the database can be accessed via the classpath subprotocol. Thanks.
          Hide
          Kim Haase added a comment -

          > A database doesn't need to be in a jar file in order to be accessed via the
          > classpath, although that is probably common usage. If the classpath contains
          > a directory and that directory has a database as a subdirectory, then the
          > database can be accessed via the classpath subprotocol. Thanks.

          I think my question is sort of from the other end. I know that a database can be accessed from the classpath whether it is in a jar/zip or not. But is the syntax exactly the same in both cases? That is, if the db is in a jar/zip, is the classpath subsubprotocol required and must there be no backslash after the colon?

          Show
          Kim Haase added a comment - > A database doesn't need to be in a jar file in order to be accessed via the > classpath, although that is probably common usage. If the classpath contains > a directory and that directory has a database as a subdirectory, then the > database can be accessed via the classpath subprotocol. Thanks. I think my question is sort of from the other end. I know that a database can be accessed from the classpath whether it is in a jar/zip or not. But is the syntax exactly the same in both cases? That is, if the db is in a jar/zip, is the classpath subsubprotocol required and must there be no backslash after the colon?
          Hide
          Knut Anders Hatlen added a comment -

          Hi Kim,

          The syntax appears to be the same in both cases. In my experiments, both when the db was in a jar and when it was in a directory, the classpath subsubprotocol was required and there should be no slash after the colon.

          Show
          Knut Anders Hatlen added a comment - Hi Kim, The syntax appears to be the same in both cases. In my experiments, both when the db was in a jar and when it was in a directory, the classpath subsubprotocol was required and there should be no slash after the colon.
          Hide
          Kim Haase added a comment -

          Thanks, Knut. I've been working on that assumption (same syntax for jars and directories) and am glad to have it confirmed.

          Show
          Kim Haase added a comment - Thanks, Knut. I've been working on that assumption (same syntax for jars and directories) and am glad to have it confirmed.
          Hide
          Kim Haase added a comment -

          Attaching DERBY-5612.diff, DERBY-5612.stat, and DERBY-5612.zip, with changes as follows:

          M src/devguide/rdevdvlp847152.dita
          M src/devguide/cdevdvlp91854.dita
          M src/devguide/tdevdeploy39856.dita
          M src/devguide/cdevdeploy18716.dita
          M src/devguide/cdevdvlp17453.dita
          M src/devguide/rdevdvlp22102.dita
          M src/devguide/cdevdvlp40350.dita

          I hope I made all the needed fixes. I also have to confess that the change to cdevdvlp40350.dita merely adds a missing topic link. I thought I might need to make changes to it and noticed the problem.

          Thanks in advance.

          Show
          Kim Haase added a comment - Attaching DERBY-5612 .diff, DERBY-5612 .stat, and DERBY-5612 .zip, with changes as follows: M src/devguide/rdevdvlp847152.dita M src/devguide/cdevdvlp91854.dita M src/devguide/tdevdeploy39856.dita M src/devguide/cdevdeploy18716.dita M src/devguide/cdevdvlp17453.dita M src/devguide/rdevdvlp22102.dita M src/devguide/cdevdvlp40350.dita I hope I made all the needed fixes. I also have to confess that the change to cdevdvlp40350.dita merely adds a missing topic link. I thought I might need to make changes to it and noticed the problem. Thanks in advance.
          Hide
          Kim Haase added a comment -

          (Not sure why "Repro attached" was checked.)

          Show
          Kim Haase added a comment - (Not sure why "Repro attached" was checked.)
          Hide
          Knut Anders Hatlen added a comment -

          The changes look fine to me. +1 to commit.

          Some other things we might need to change:

          tdevdeploy39856: There's still a reference to a URL that uses the wrong syntax. (The "standard syntax" in bullet 2.)

          cdevdeploy18716: If I read this topic correctly, it still implies that it is possible to access a db in the classpath without specifying the classpath subsubprotocol. Perhaps the entire topic should go away, as the ambiguity it describes does not exist?

          cdevdeploy856333: Same here. Remove topic?

          Show
          Knut Anders Hatlen added a comment - The changes look fine to me. +1 to commit. Some other things we might need to change: tdevdeploy39856: There's still a reference to a URL that uses the wrong syntax. (The "standard syntax" in bullet 2.) cdevdeploy18716: If I read this topic correctly, it still implies that it is possible to access a db in the classpath without specifying the classpath subsubprotocol. Perhaps the entire topic should go away, as the ambiguity it describes does not exist? cdevdeploy856333: Same here. Remove topic?
          Hide
          Kim Haase added a comment -

          Thanks, Knut! I was wondering about those two subtopics (cdevdeploy18716 and cdevdeploy856333) and am happy to remove them.

          I don't understand why the "standard syntax" in tdevdeploy39856 is wrong, though. It seems to be the same as what is shown in http://db.apache.org/derby/docs/dev/devguide/cdevdvlp24155.html for accessing jar files.

          Show
          Kim Haase added a comment - Thanks, Knut! I was wondering about those two subtopics (cdevdeploy18716 and cdevdeploy856333) and am happy to remove them. I don't understand why the "standard syntax" in tdevdeploy39856 is wrong, though. It seems to be the same as what is shown in http://db.apache.org/derby/docs/dev/devguide/cdevdvlp24155.html for accessing jar files.
          Hide
          Kim Haase added a comment -

          Another possible discovery in the revised "Database connection examples" (rdevdvlp22102): Under the third bullet, on the example jdbc:derby:/reference/phrases/french, should the last sentence be removed?

          "If a jar file storing databases were in the user's classpath, this could also be a path within the jar file."

          This would be another item for a second patch.

          Show
          Kim Haase added a comment - Another possible discovery in the revised "Database connection examples" (rdevdvlp22102): Under the third bullet, on the example jdbc:derby:/reference/phrases/french, should the last sentence be removed? "If a jar file storing databases were in the user's classpath, this could also be a path within the jar file." This would be another item for a second patch.
          Hide
          Kim Haase added a comment -

          Committed patch DERBY-5612.diff to documentation trunk at revision 1326640. A second patch with additional fixes will follow.

          Show
          Kim Haase added a comment - Committed patch DERBY-5612 .diff to documentation trunk at revision 1326640. A second patch with additional fixes will follow.
          Hide
          Knut Anders Hatlen added a comment -

          > I don't understand why the "standard syntax" in tdevdeploy39856 is wrong, though.

          It lacks the classpath subsubprotocol that's required to access a database in a jar on the classpath, and it has a leading slash. If those two problems are fixed, it becomes identical to the other URL mentioned there, so it can be removed.

          > It seems to be the same as what is shown in http://db.apache.org/derby/docs/dev/devguide/cdevdvlp24155.html for accessing jar files.

          Yes, that one looks wrong too.

          > Another possible discovery in the revised "Database connection examples" (rdevdvlp22102): Under the third bullet, on the example jdbc:derby:/reference/phrases/french, should the last sentence be removed?

          Yes, I believe so. In the same topic, the eighth bullet (jdbc:derby:/myDB) should be removed, the tenth bullet (jdbc:derby:classpath:myDB) should have its last sentence removed, and the twelfth bullet (jdbc:derby:directory:myDB) should have its last sentence removed too.

          Do you think we've found them all now?

          Show
          Knut Anders Hatlen added a comment - > I don't understand why the "standard syntax" in tdevdeploy39856 is wrong, though. It lacks the classpath subsubprotocol that's required to access a database in a jar on the classpath, and it has a leading slash. If those two problems are fixed, it becomes identical to the other URL mentioned there, so it can be removed. > It seems to be the same as what is shown in http://db.apache.org/derby/docs/dev/devguide/cdevdvlp24155.html for accessing jar files. Yes, that one looks wrong too. > Another possible discovery in the revised "Database connection examples" (rdevdvlp22102): Under the third bullet, on the example jdbc:derby:/reference/phrases/french, should the last sentence be removed? Yes, I believe so. In the same topic, the eighth bullet (jdbc:derby:/myDB) should be removed, the tenth bullet (jdbc:derby:classpath:myDB) should have its last sentence removed, and the twelfth bullet (jdbc:derby:directory:myDB) should have its last sentence removed too. Do you think we've found them all now?
          Hide
          Kim Haase added a comment -

          Thanks, Knut – I suddenly noticed one more in the "Database connection examples" after I sent that one, but of course you found more.

          I bet there are more still. Take a look at "Derby JDBC database connection URL" (cdevdvlp17453). Is there any point at all to the "directory" subsubprotocol now?

          Show
          Kim Haase added a comment - Thanks, Knut – I suddenly noticed one more in the "Database connection examples" after I sent that one, but of course you found more. I bet there are more still. Take a look at "Derby JDBC database connection URL" (cdevdvlp17453). Is there any point at all to the "directory" subsubprotocol now?
          Hide
          Kim Haase added a comment -

          I hope we've made more progress here – attaching DERBY-5612-2.diff, DERBY-5612-2.stat, and DERBY-5612-2.zip, which modifies 5 topics and removes 2:

          M src/devguide/tdevdeploy39856.dita
          M src/devguide/derbydev.ditamap
          D src/devguide/cdevdeploy18716.dita
          M src/devguide/cdevdvlp17453.dita
          M src/devguide/cdevdvlp24155.dita
          M src/devguide/rdevdvlp22102.dita
          M src/devguide/cdevdvlp40350.dita
          D src/devguide/cdevdeploy856333.dita

          Thanks again, Knut – further edits are welcome.

          Show
          Kim Haase added a comment - I hope we've made more progress here – attaching DERBY-5612 -2.diff, DERBY-5612 -2.stat, and DERBY-5612 -2.zip, which modifies 5 topics and removes 2: M src/devguide/tdevdeploy39856.dita M src/devguide/derbydev.ditamap D src/devguide/cdevdeploy18716.dita M src/devguide/cdevdvlp17453.dita M src/devguide/cdevdvlp24155.dita M src/devguide/rdevdvlp22102.dita M src/devguide/cdevdvlp40350.dita D src/devguide/cdevdeploy856333.dita Thanks again, Knut – further edits are welcome.
          Hide
          Knut Anders Hatlen added a comment -

          +1 to the patch.

          You're probably right that there's not much point in the directory subsubprotocol now, since it will always be picked implicitly if no subsubprotocol is specified.

          Show
          Knut Anders Hatlen added a comment - +1 to the patch. You're probably right that there's not much point in the directory subsubprotocol now, since it will always be picked implicitly if no subsubprotocol is specified.
          Hide
          Kim Haase added a comment -

          Thanks again, Knut!

          Committed patch DERBY-5612-2.diff to documentation trunk at revision 1327511.

          Show
          Kim Haase added a comment - Thanks again, Knut! Committed patch DERBY-5612 -2.diff to documentation trunk at revision 1327511.
          Hide
          Kim Haase added a comment -

          Changes have appeared in Latest Alpha Manuals.

          Show
          Kim Haase added a comment - Changes have appeared in Latest Alpha Manuals.

            People

            • Assignee:
              Kim Haase
              Reporter:
              Rick Hillegas
            • Votes:
              0 Vote for this issue
              Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development