Derby
  1. Derby
  2. DERBY-5938

Documentation says Derby works with Java 1.4.2

    Details

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

      Description

      The documentation says that Derby works with Java 1.4.2. This is not true on trunk, as support for Java 1.4.2 is removed for Derby 10.10. A quick search came up with these places that need change:

      • Getting started guide:

      http://db.apache.org/derby/docs/dev/getstart/tgssetupverify.html
      http://db.apache.org/derby/docs/dev/getstart/cgstutorialintro.html
      http://db.apache.org/derby/docs/dev/getstart/tgssetupjavaenvir.html
      http://db.apache.org/derby/docs/dev/getstart/cgsintsr.html

      Need to change the above topics to say that you need JDK 1.5 or later installed to run the examples.

      • Developer's guide:

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

      The cell for the combination Multi-User/Embedded mentions potential multi-boot problems in pre-1.4 JVMs. Derby doesn't run on pre-1.4 JVMs anymore (and hasn't done for a long time). However, the multi-boot problem is present on CDC/FP 1.1, which is still a supported platform, so maybe we should change "pre-1.4" to "J2ME" (or however we usually refer to that platform in the docs).

      • Admin guide:

      http://db.apache.org/derby/docs/dev/adminguide/cadminappsthenetworkserverandjvms.html

      Should say that the server is compatible with Java 5 and above.

      • Tools guide:

      http://db.apache.org/derby/docs/dev/tools/ctools1003034.html

      Although it's technically correct that the tools do run on Java 1.4, it's not possible to access a Derby database with them on Java 1.4 in any supported way (unsupported way: use derbytools.jar from 10.10 and derby.jar from 10.9). So we should change this topic to say Java 5 and above, perhaps also mentioning CDC/Foundation Profile 1.1.

      1. DERBY-5938.diff
        18 kB
        Kim Haase
      2. DERBY-5938.stat
        0.8 kB
        Kim Haase
      3. DERBY-5938.zip
        39 kB
        Kim Haase

        Issue Links

          Activity

          Hide
          Kim Haase added a comment -

          Thanks for tracking all those occurrences of 1.4 down, Knut. I'll make sure to catch any others.

          Maybe we need another docs.properties variable, something like min.jdk, so that any needed backporting wouldn't create inaccurate information. I think we'd have to add another filter to the filterset in the preprocess-copy target of the build.xml file as well. Does this make sense? It might simplify matters going forward.

          Show
          Kim Haase added a comment - Thanks for tracking all those occurrences of 1.4 down, Knut. I'll make sure to catch any others. Maybe we need another docs.properties variable, something like min.jdk, so that any needed backporting wouldn't create inaccurate information. I think we'd have to add another filter to the filterset in the preprocess-copy target of the build.xml file as well. Does this make sense? It might simplify matters going forward.
          Hide
          Knut Anders Hatlen added a comment -

          Adding a variable sounds like a good idea.

          Show
          Knut Anders Hatlen added a comment - Adding a variable sounds like a good idea.
          Hide
          Kim Haase added a comment -

          There's a small problem with the "SYSXPLAIN_STATEMENTS system table" topic, http://db.apache.org/derby/docs/dev/ref/rrefsysxplain_statements.html. The JVM_ID column is described as follows:

          A code indicating what version of the JVM was running when this statement was captured: '4' for J2SE_14 (JDK 1.4.0 or 1.4.1), '5' for J2SE_142 (JDK 1.4.2), '6' for J2SE_15 (JDK 1.5), or '7' for J2SE_16 (JDK 1.6).

          I have no problem with removing the items for JDK 1.4, since it is no longer supported – though it makes the numbering scheme seem odd. But there should also be an entry for JDK 7, and eventually JDK 8, etc. It appears that the code for JDK 7 is '8', as would be expected (I tried). It seems as if this topic might need to be updated every time we support a new JDK release if left as is.

          Also, the names should not be "J2SE" nor should they be "1.x" – they are Java SE 5, Java SE 6, etc. Since these supposed constants don't seem to be hard-coded anywhere, I'm thinking of changing the topic to say:

          A code indicating what version of the JVM was running when this statement was captured. The code is a character that represents the release number plus one. For example, the code for Java SE 6 is '7', and the code for Java SE 7 is '8'.

          That way, we might not have to update it for every single release.

          Show
          Kim Haase added a comment - There's a small problem with the "SYSXPLAIN_STATEMENTS system table" topic, http://db.apache.org/derby/docs/dev/ref/rrefsysxplain_statements.html . The JVM_ID column is described as follows: A code indicating what version of the JVM was running when this statement was captured: '4' for J2SE_14 (JDK 1.4.0 or 1.4.1), '5' for J2SE_142 (JDK 1.4.2), '6' for J2SE_15 (JDK 1.5), or '7' for J2SE_16 (JDK 1.6). I have no problem with removing the items for JDK 1.4, since it is no longer supported – though it makes the numbering scheme seem odd. But there should also be an entry for JDK 7, and eventually JDK 8, etc. It appears that the code for JDK 7 is '8', as would be expected (I tried). It seems as if this topic might need to be updated every time we support a new JDK release if left as is. Also, the names should not be "J2SE" nor should they be "1.x" – they are Java SE 5, Java SE 6, etc. Since these supposed constants don't seem to be hard-coded anywhere, I'm thinking of changing the topic to say: A code indicating what version of the JVM was running when this statement was captured. The code is a character that represents the release number plus one. For example, the code for Java SE 6 is '7', and the code for Java SE 7 is '8'. That way, we might not have to update it for every single release.
          Hide
          Kathey Marsden added a comment - - edited

          It is unfortunate it was encoded this way. Given that it was, I think your approach sounds ok to me if it is made to be true for Java 8. I think right now java 8 returns 8 too.

          Show
          Kathey Marsden added a comment - - edited It is unfortunate it was encoded this way. Given that it was, I think your approach sounds ok to me if it is made to be true for Java 8. I think right now java 8 returns 8 too.
          Hide
          Kim Haase added a comment -

          Thanks, Kathey, for the advice. Java 8 hasn't been released yet, so I hope the return value will be fixed by then. Should I file an issue to update java/engine/org/apache/derby/iapi/services/info/JVMInfo.java? That seems to be where the logic is located.

          Show
          Kim Haase added a comment - Thanks, Kathey, for the advice. Java 8 hasn't been released yet, so I hope the return value will be fixed by then. Should I file an issue to update java/engine/org/apache/derby/iapi/services/info/JVMInfo.java? That seems to be where the logic is located.
          Hide
          Knut Anders Hatlen added a comment -

          We might get around the Java 8 (and higher) issue by stating that the value in that column represents the JVM version targeted by the dynamically loaded modules of the running Derby engine, which may be lower than the actual running JVM version.

          Or we could just say that it's an arbitrary identifier used internally, which is what it is, and avoid the problem altogether. I'm not sure why we exposed this information in the first place. The type of the JVM_ID column is VARCHAR(32672), which is an odd choice for a column that holds an integer. Maybe it was meant to expose JVMInfo.derbyVMLevel(), which returns a string?

          Show
          Knut Anders Hatlen added a comment - We might get around the Java 8 (and higher) issue by stating that the value in that column represents the JVM version targeted by the dynamically loaded modules of the running Derby engine, which may be lower than the actual running JVM version. Or we could just say that it's an arbitrary identifier used internally, which is what it is, and avoid the problem altogether. I'm not sure why we exposed this information in the first place. The type of the JVM_ID column is VARCHAR(32672), which is an odd choice for a column that holds an integer. Maybe it was meant to expose JVMInfo.derbyVMLevel(), which returns a string?
          Hide
          Kim Haase added a comment -

          It does seem odd that it's a VARCHAR(32672) when the code is a CHAR(1) or, in the foreseeable future, CHAR(2). But figuring out why, and how to fix it, is beyond me.

          Simple character codes are common in the system tables. The current doc for this one is clearer on the reason, showing that we got stuck with two codes for 1.4 for some reason (4 for 1.4.0 and 1.4.1, 5 for 1.4.2) so the numbering went out of sync. But if we remove the part about 1.4 I don't think we should make up a reason for the oddity.

          I guess I will file a JIRA on the JVMInfo update, since early access versions of JDK 8 are available. Whether to go beyond that and make further fixes to the table I'll leave to others.

          Show
          Kim Haase added a comment - It does seem odd that it's a VARCHAR(32672) when the code is a CHAR(1) or, in the foreseeable future, CHAR(2). But figuring out why, and how to fix it, is beyond me. Simple character codes are common in the system tables. The current doc for this one is clearer on the reason, showing that we got stuck with two codes for 1.4 for some reason (4 for 1.4.0 and 1.4.1, 5 for 1.4.2) so the numbering went out of sync. But if we remove the part about 1.4 I don't think we should make up a reason for the oddity. I guess I will file a JIRA on the JVMInfo update, since early access versions of JDK 8 are available. Whether to go beyond that and make further fixes to the table I'll leave to others.
          Hide
          Kim Haase added a comment -

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

          M build.xml
          M docs.properties
          M src/devguide/rdevresman79556.dita
          M src/devguide/rdevprocsqle.dita
          M src/devguide/cdevstart18978.dita
          M src/devguide/cdevdvlp40653.dita
          M src/devguide/cdevstandardsxml.dita
          M src/devguide/rdevconcepts713.dita
          M src/devguide/derbydev.ditamap
          M src/getstart/tgssetupjavaenvir.dita
          M src/getstart/cgsintsr.dita
          M src/getstart/tgssetupverify.dita
          M src/getstart/cgstutorialintro.dita
          M src/tools/ctools1003034.dita
          M src/adminguide/cadminappsthenetworkserverandjvms.dita
          M src/adminguide/cadminapps811695.dita
          M src/adminguide/derbyadmin.ditamap
          M src/ref/rrefsysxplain_statements.dita
          M src/ref/rrefattribderegister.dita
          M src/ref/rrefjavsqlprst.dita
          M src/ref/rrefapi1003363.dita

          I created a property for the minimum JDK and used it where appropriate. I didn't use it where a specific contrast between SE 5 and SE 6 is made, because if/when the minimum supported JDK becomes SE 6, those topics will need to be rewritten.

          I found occurrences of "JDK 1.4" as well as "JDK 1.4.2", and also some occurrences of "JDK 5 and earlier".

          I removed mentions of specific versions where a feature is now supported on all current versions.

          For the multi-boot topic I used the language that is used elsewhere in the Developer's Guide to talk about the CDC platforms.

          I used this opportunity to fix a couple of trademarked terms here and there.

          Please let me know what additional fixes are needed, if any.

          Show
          Kim Haase added a comment - Attaching DERBY-5938 .diff, DERBY-5938 .stat, and DERBY-5938 .zip, with changes as follows: M build.xml M docs.properties M src/devguide/rdevresman79556.dita M src/devguide/rdevprocsqle.dita M src/devguide/cdevstart18978.dita M src/devguide/cdevdvlp40653.dita M src/devguide/cdevstandardsxml.dita M src/devguide/rdevconcepts713.dita M src/devguide/derbydev.ditamap M src/getstart/tgssetupjavaenvir.dita M src/getstart/cgsintsr.dita M src/getstart/tgssetupverify.dita M src/getstart/cgstutorialintro.dita M src/tools/ctools1003034.dita M src/adminguide/cadminappsthenetworkserverandjvms.dita M src/adminguide/cadminapps811695.dita M src/adminguide/derbyadmin.ditamap M src/ref/rrefsysxplain_statements.dita M src/ref/rrefattribderegister.dita M src/ref/rrefjavsqlprst.dita M src/ref/rrefapi1003363.dita I created a property for the minimum JDK and used it where appropriate. I didn't use it where a specific contrast between SE 5 and SE 6 is made, because if/when the minimum supported JDK becomes SE 6, those topics will need to be rewritten. I found occurrences of "JDK 1.4" as well as "JDK 1.4.2", and also some occurrences of "JDK 5 and earlier". I removed mentions of specific versions where a feature is now supported on all current versions. For the multi-boot topic I used the language that is used elsewhere in the Developer's Guide to talk about the CDC platforms. I used this opportunity to fix a couple of trademarked terms here and there. Please let me know what additional fixes are needed, if any.
          Hide
          Knut Anders Hatlen added a comment -

          Thanks, Kim. The patch looks good and complete. +1 to commit.

          Maybe the property could be used in src/ref/rrefattribderegister.dita too, where it says "JDK 5 and up"? Or perhaps we don't need to mention the version at all there, since it says "all supported Java Virtual Machines".

          Show
          Knut Anders Hatlen added a comment - Thanks, Kim. The patch looks good and complete. +1 to commit. Maybe the property could be used in src/ref/rrefattribderegister.dita too, where it says "JDK 5 and up"? Or perhaps we don't need to mention the version at all there, since it says "all supported Java Virtual Machines".
          Hide
          Kim Haase added a comment -

          Thanks very much, Knut!

          Committed patch DERBY-5938.diff to documentation trunk at revision 1398312.

          Since the deregister topic should have all references to JDKs removed when we stop supporting JDK 5, we may as well leave it with the hardcoded reference until then.

          Show
          Kim Haase added a comment - Thanks very much, Knut! Committed patch DERBY-5938 .diff to documentation trunk at revision 1398312. Since the deregister topic should have all references to JDKs removed when we stop supporting JDK 5, we may as well leave it with the hardcoded reference until then.
          Hide
          Kim Haase added a comment -

          The changes have appeared in the Latest Alpha Docs, so this issue could be closed.

          Show
          Kim Haase added a comment - The changes have appeared in the Latest Alpha Docs, so this issue could be closed.
          Hide
          Knut Anders Hatlen added a comment -

          Closing. Thanks, Kim!

          Show
          Knut Anders Hatlen added a comment - Closing. Thanks, Kim!
          Hide
          fpientka added a comment -

          one more correction for the javadoc text jdbc3\overview-summary.html, jdbc4\overview-summary.html and the index.html file
          "Derby runs on any J2SE 1.4.2 or higher virtual machine "
          should be replaced with the correct info in the release note
          "Java SE 5 and higher with JDBC 3.0, 4.0, 4.1, and 4.2."
          so derby 10.10 supports java 5 or higher, but not anymore java 1.4

          Show
          fpientka added a comment - one more correction for the javadoc text jdbc3\overview-summary.html, jdbc4\overview-summary.html and the index.html file "Derby runs on any J2SE 1.4.2 or higher virtual machine " should be replaced with the correct info in the release note "Java SE 5 and higher with JDBC 3.0, 4.0, 4.1, and 4.2." so derby 10.10 supports java 5 or higher, but not anymore java 1.4

            People

            • Assignee:
              Kim Haase
              Reporter:
              Knut Anders Hatlen
            • Votes:
              0 Vote for this issue
              Watchers:
              4 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development