Derby
  1. Derby
  2. DERBY-484

Documentation for derby.database.classpath in developers guide is misleading

    Details

    • Type: Bug Bug
    • Status: Closed
    • Priority: Minor Minor
    • Resolution: Fixed
    • Affects Version/s: 10.1.2.1
    • Fix Version/s: 10.8.2.2, 10.9.1.0
    • Component/s: Documentation
    • Labels:
      None

      Description

      10.1 alpha docs (from site)

      http://db.apache.org/derby/docs/devguide/cdevdeploy21645.html

      1) Remove sentence 'The first time you set the property, you must reboot to load the classes.'
      This is not true and is tested with lang/dcl.sql

      2) This implies there is more infomation in the tuning guide, but I don't see any.

      'See "derby.database.classpath" in Tuning Derby for more information about the property.'

      Searching the tuning guide I find no mention of derby.database.classpath
      http://db.apache.org/derby/docs/tuning/tuningderby.pdf

      1. DERBY-484-2.zip
        16 kB
        Kim Haase
      2. DERBY-484-2.stat
        0.3 kB
        Kim Haase
      3. DERBY-484-2.diff
        10 kB
        Kim Haase
      4. DERBY-484.zip
        8 kB
        Kim Haase
      5. DERBY-484.stat
        0.1 kB
        Kim Haase
      6. DERBY-484.diff
        5 kB
        Kim Haase
      7. cdevdeploy21645.html
        4 kB
        Jeff Levitt
      8. derby484.diff
        3 kB
        Jeff Levitt

        Issue Links

          Activity

          Hide
          Jeff Levitt added a comment -

          Attached patch removes the content as requested. HTML output file is included for review.

          Show
          Jeff Levitt added a comment - Attached patch removes the content as requested. HTML output file is included for review.
          Hide
          Kim Haase added a comment -

          This issue is related to the DERBY-2389 work (moving the property documentation to the Reference Manual). I will be happy to document the derby.database.classpath property if someone can point me to information about it. It is mentioned in several places in the Developer's Guide (4 topics under "Loading classes from a database").

          Show
          Kim Haase added a comment - This issue is related to the DERBY-2389 work (moving the property documentation to the Reference Manual). I will be happy to document the derby.database.classpath property if someone can point me to information about it. It is mentioned in several places in the Developer's Guide (4 topics under "Loading classes from a database").
          Hide
          Kim Haase added a comment -

          Attaching DERBY-484.diff, DERBY-484.stat, DERBY-484.zip, with the following changes:

          M src/ref/crefproper22250.dita
          M src/ref/refderby.ditamap
          A src/ref/rrefproperclasspath.dita

          I'm a little more confident about adding a topic on this property than when I abandoned this issue some time ago. Please let me know if any information is missing or needs changing. I've based the new topic on information in the Developer's Guide:

          cdevdeploy21645.dita Enable database class loading with a property

          cdevdeploy17604.dita Dynamic changes to jar files or to the database jar classpath

          cdevdeploy857611.dita Requirements for dynamic changes

          cdevdeploy857648.dita Notes on dynamic changes

          Show
          Kim Haase added a comment - Attaching DERBY-484 .diff, DERBY-484 .stat, DERBY-484 .zip, with the following changes: M src/ref/crefproper22250.dita M src/ref/refderby.ditamap A src/ref/rrefproperclasspath.dita I'm a little more confident about adding a topic on this property than when I abandoned this issue some time ago. Please let me know if any information is missing or needs changing. I've based the new topic on information in the Developer's Guide: cdevdeploy21645.dita Enable database class loading with a property cdevdeploy17604.dita Dynamic changes to jar files or to the database jar classpath cdevdeploy857611.dita Requirements for dynamic changes cdevdeploy857648.dita Notes on dynamic changes
          Hide
          Knut Anders Hatlen added a comment -

          The new topic looks good to me. Some possible improvements:

          • It's a bit opaque where the jar files come from. Perhaps change "This property must be set to enable Derby to load classes from the jar files" to "This property must be set to enable Derby to load classes from jar files installed with the SQLJ.INSTALL_JAR system procedure"? Unfortunately, there's no topic describing INSTALL_JAR in the reference manual, so we cannot create a link to it.
          • Should the last bullet in the bullet list be split into two separate bullets?
          • "Use two-part names for the jar files" -> "Use fully qualified identifiers for the jar files"?
          Show
          Knut Anders Hatlen added a comment - The new topic looks good to me. Some possible improvements: It's a bit opaque where the jar files come from. Perhaps change "This property must be set to enable Derby to load classes from the jar files" to "This property must be set to enable Derby to load classes from jar files installed with the SQLJ.INSTALL_JAR system procedure"? Unfortunately, there's no topic describing INSTALL_JAR in the reference manual, so we cannot create a link to it. Should the last bullet in the bullet list be split into two separate bullets? "Use two-part names for the jar files" -> "Use fully qualified identifiers for the jar files"?
          Hide
          Kim Haase added a comment -

          Thanks for these very helpful comments, Knut. They actually lead in several directions.

          1) The bullet-list split needs to be made in the Dev Guide topic too. I'll do that.

          2) A pointer to the exact topic(s) on SQLJ.INSTALL_JAR are a good idea. This procedure is shown briefly in the Dev Guide (http://db.apache.org/derby/docs/dev/devguide/rdevdeploy856845.html) and described a bit more fully in the Tools Guide, in a badly formatted topic (http://db.apache.org/derby/docs/dev/tools/ttoolsjarload1002986.html).

          I wonder where the documentation of these procedures actually belongs. (SQLJ.REMOVE_JAR and SQLJ.REPLACE_JAR are the others.) What kind of procedures are they? The only system procedures and functions we document in the Reference Manual are the SYSCS_UTIL ones. Should the basic reference info on the SQLJ ones be moved to the Reference Manual?

          3) I just realized that I ignored one of the original problems reported in the issue, that the statement "The first time you set the property, you must reboot to load the classes" is not true. If this is in fact the case, the property is truly dynamic, and I should change
          http://db.apache.org/derby/docs/devguide/cdevdeploy21645.html ("Enable database class loading with a property" too.

          Show
          Kim Haase added a comment - Thanks for these very helpful comments, Knut. They actually lead in several directions. 1) The bullet-list split needs to be made in the Dev Guide topic too. I'll do that. 2) A pointer to the exact topic(s) on SQLJ.INSTALL_JAR are a good idea. This procedure is shown briefly in the Dev Guide ( http://db.apache.org/derby/docs/dev/devguide/rdevdeploy856845.html ) and described a bit more fully in the Tools Guide, in a badly formatted topic ( http://db.apache.org/derby/docs/dev/tools/ttoolsjarload1002986.html ). I wonder where the documentation of these procedures actually belongs. (SQLJ.REMOVE_JAR and SQLJ.REPLACE_JAR are the others.) What kind of procedures are they? The only system procedures and functions we document in the Reference Manual are the SYSCS_UTIL ones. Should the basic reference info on the SQLJ ones be moved to the Reference Manual? 3) I just realized that I ignored one of the original problems reported in the issue, that the statement "The first time you set the property, you must reboot to load the classes" is not true. If this is in fact the case, the property is truly dynamic, and I should change http://db.apache.org/derby/docs/devguide/cdevdeploy21645.html ("Enable database class loading with a property" too.
          Hide
          Rick Hillegas added a comment -

          Hi Kim,

          I find that

          call syscs_util.syscs_set_database_property( 'derby.database.classpath', ... );

          takes effect immediately. There is no need to reboot the database.

          I also agree that the sqlj routines should be documented in the Reference Guide alongside the other database procedures. The import/export procedures are documented in the Reference Guide even though the broader topic of data migration is discussed in the Tools Guide. I don't know why the sqlj routines are documented in the Tools Guide--looks weird to me but I see that it goes back at least as far as Cloudscape 3.5.

          Show
          Rick Hillegas added a comment - Hi Kim, I find that call syscs_util.syscs_set_database_property( 'derby.database.classpath', ... ); takes effect immediately. There is no need to reboot the database. I also agree that the sqlj routines should be documented in the Reference Guide alongside the other database procedures. The import/export procedures are documented in the Reference Guide even though the broader topic of data migration is discussed in the Tools Guide. I don't know why the sqlj routines are documented in the Tools Guide--looks weird to me but I see that it goes back at least as far as Cloudscape 3.5.
          Hide
          Kim Haase added a comment -

          Thank you, Rick! That answers the next question I was going to ask (which kind of dynamic – immediate effect, or future connections only).

          I will file another issue for moving the sqlj routines to the Ref Manual.

          DERBY-1780, way back when, pointed out that the sqlj routines don't really belong in the Tools Guide (although that was not its primary focus).

          Show
          Kim Haase added a comment - Thank you, Rick! That answers the next question I was going to ask (which kind of dynamic – immediate effect, or future connections only). I will file another issue for moving the sqlj routines to the Ref Manual. DERBY-1780 , way back when, pointed out that the sqlj routines don't really belong in the Tools Guide (although that was not its primary focus).
          Hide
          Kim Haase added a comment -

          Now that the SQLJ routines are in the Reference Manual, I'm attaching DERBY-484-2.diff, DERBY-484-2.stat, and DERBY-484-2.zip, with changes to the following:

          M src/devguide/cdevdeploy15818.dita
          M src/devguide/cdevdeploy857611.dita
          M src/devguide/cdevdeploy857648.dita
          M src/devguide/cdevdeploy21645.dita
          M src/ref/crefstorejardb.dita
          M src/ref/crefproper22250.dita
          M src/ref/refderby.ditamap
          A src/ref/rrefproperclasspath.dita

          Modified topic for derby.database.classpath to incorporate comments (thanks, Knut); corrected entry in "Derby properties" (crefproper22250.dita).

          Corrected the topic id for "System procedures for storing jar files in a database" (crefstorejardb.dita).

          Modified the list in "Enable database class loading with a property" (cdevdeploy21645.dita) to incorporate Knut's comments.

          Corrected a few font inconsistencies in Developer's Guide subtopics of "Loading classes from a database" ("Create jar files for your application", "Requirements for dynamic changes", "Notes on dynamic changes".

          Please let me know if further changes are needed.

          Show
          Kim Haase added a comment - Now that the SQLJ routines are in the Reference Manual, I'm attaching DERBY-484 -2.diff, DERBY-484 -2.stat, and DERBY-484 -2.zip, with changes to the following: M src/devguide/cdevdeploy15818.dita M src/devguide/cdevdeploy857611.dita M src/devguide/cdevdeploy857648.dita M src/devguide/cdevdeploy21645.dita M src/ref/crefstorejardb.dita M src/ref/crefproper22250.dita M src/ref/refderby.ditamap A src/ref/rrefproperclasspath.dita Modified topic for derby.database.classpath to incorporate comments (thanks, Knut); corrected entry in "Derby properties" (crefproper22250.dita). Corrected the topic id for "System procedures for storing jar files in a database" (crefstorejardb.dita). Modified the list in "Enable database class loading with a property" (cdevdeploy21645.dita) to incorporate Knut's comments. Corrected a few font inconsistencies in Developer's Guide subtopics of "Loading classes from a database" ("Create jar files for your application", "Requirements for dynamic changes", "Notes on dynamic changes". Please let me know if further changes are needed.
          Hide
          Knut Anders Hatlen added a comment -

          The latest revision of the patch looks good. +1 to commit.

          Show
          Knut Anders Hatlen added a comment - The latest revision of the patch looks good. +1 to commit.
          Hide
          Kim Haase added a comment -

          Committed patch DERBY-484-2.diff to documentation trunk at revision 1124896.
          Merged to 10.8 doc branch at revision 1124980.

          Show
          Kim Haase added a comment - Committed patch DERBY-484 -2.diff to documentation trunk at revision 1124896. Merged to 10.8 doc branch at revision 1124980.
          Hide
          Kim Haase added a comment -

          Forgot to say thank you to Knut and Rick for the reviews and information.

          Show
          Kim Haase added a comment - Forgot to say thank you to Knut and Rick for the reviews and information.
          Hide
          Kim Haase added a comment -

          Fixes appeared in 10.8.2 documentation, so closing.

          Show
          Kim Haase added a comment - Fixes appeared in 10.8.2 documentation, so closing.

            People

            • Assignee:
              Kim Haase
              Reporter:
              Daniel John Debrunner
            • Votes:
              0 Vote for this issue
              Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development