Derby
  1. Derby
  2. DERBY-1932

Reference Manual updates - JDBC Reference section

    Details

    • Type: Bug Bug
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 10.2.1.6
    • Fix Version/s: 10.5.1.1
    • Component/s: Documentation
    • Labels:
      None

      Description

      JDBC Reference:
      Section = java.sql.Blob and java.sql.Clob
      File = http://db.apache.org/derby/docs/10.2/ref/rrefjdbc96386.html
      Update =
      This section has a table titled Table 1. JDBC 2.0 java.sql.Blob Methods Supported. The first row, 3rd column of this table shows up empty in the html page but has an ' in the pdf format. The pdf format should also show the column empty. I think this happens for all the tables with no data in the pdf format

      Section = DatabaseMetaData functionality not supported
      File = http://db.apache.org/derby/docs/10.2/ref/ref-single.html#N2E3A9
      Update =
      This section says that getColumnPrivileges and getTablePrivileges are not supported. But checkin r381109 has changes to metadata.properties for these 2 functions. So, looks like these methods are probably now supported with grant revoke functionality.

      Section = Data streaming
      Files =
      (1) http://db.apache.org/derby/docs/dev/ref/rrefjavsqlprst.html
      (2) http://db.apache.org/derby/docs/dev/ref/rrefjavsqlrssc.html
      (3) http://db.apache.org/derby/docs/dev/ref/crefjavbclobnot.html
      (4) http://db.apache.org/derby/docs/dev/ref/rrefjdbc4_0summary.html

      Updates =
      (1): Rewrite section to reflect a newer JDBC version than 1.2? Comment that getUnicodeStream is deprecated and no longer implemented in Derby. Add description of getCharacterStream. Could also add info about setNCharacterStream, which is JDBC 4 only and not supported. The note under the table is no longer accurate; it only applies when using the client driver (and also only for the client?).
      (2): OK
      (3): Update list of methods (mark as deprecated, add getCharacterStream).
      (4): OK.

      1. encoding.diff
        2 kB
        Knut Anders Hatlen
      2. DERBY-1932-2.zip
        5 kB
        Kim Haase
      3. DERBY-1932-2.stat
        0.1 kB
        Kim Haase
      4. DERBY-1932-2.diff
        2 kB
        Kim Haase
      5. DERBY-1932.zip
        7 kB
        Kim Haase
      6. DERBY-1932.stat
        0.1 kB
        Kim Haase
      7. DERBY-1932.diff
        11 kB
        Kim Haase

        Activity

        Hide
        Kim Haase added a comment -

        Just realized that I meant I had committed DERBY-1932-2.diff.

        The changes have now appeared in the Latest Alpha Manuals, so this issue can be closed.

        Show
        Kim Haase added a comment - Just realized that I meant I had committed DERBY-1932 -2.diff. The changes have now appeared in the Latest Alpha Manuals, so this issue can be closed.
        Hide
        Kim Haase added a comment -

        Thanks, Knut Anders!

        Committed patch DERBY-503-2.diff to documentation trunk at revision 689842.

        Show
        Kim Haase added a comment - Thanks, Knut Anders! Committed patch DERBY-503 -2.diff to documentation trunk at revision 689842.
        Hide
        Knut Anders Hatlen added a comment -

        The patch with the formatting changes looks good to me. +1 to commit.

        Show
        Knut Anders Hatlen added a comment - The patch with the formatting changes looks good to me. +1 to commit.
        Hide
        Kim Haase added a comment -

        Marking Patch Available again for revised patch, and removing Fixed In field for the time being.

        Show
        Kim Haase added a comment - Marking Patch Available again for revised patch, and removing Fixed In field for the time being.
        Hide
        Kim Haase added a comment -

        Thanks, Knut Anders! I really appreciate the suggestions. Since I hadn't resolved the issue yet, I'm attaching another patch with your changes. There's a slight difference in the formatting changes in rrefjavsqlprst.dita, but the substance is the same.

        Show
        Kim Haase added a comment - Thanks, Knut Anders! I really appreciate the suggestions. Since I hadn't resolved the issue yet, I'm attaching another patch with your changes. There's a slight difference in the formatting changes in rrefjavsqlprst.dita, but the substance is the same.
        Hide
        Knut Anders Hatlen added a comment -

        I think the simplest way to clean up the examples is

        1) In rrefjavsqlprst, change the text above the example from "how a user can store a streamed java.io.File" to "how a user can store a streamed, ASCII-encoded java.io.File". Then there shouldn't be any problems with using setAsciiStream().

        2) In rrefjavsqlrssc, use getCharacterStream() instead of getAsciiStream(). Then char is used instead of byte throughout the example, and there won't be any issues with converting between a byte representation and characters.

        I have attached a patch (encoding.diff) which suggests how it could be done.

        Show
        Knut Anders Hatlen added a comment - I think the simplest way to clean up the examples is 1) In rrefjavsqlprst, change the text above the example from "how a user can store a streamed java.io.File" to "how a user can store a streamed, ASCII-encoded java.io.File". Then there shouldn't be any problems with using setAsciiStream(). 2) In rrefjavsqlrssc, use getCharacterStream() instead of getAsciiStream(). Then char is used instead of byte throughout the example, and there won't be any issues with converting between a byte representation and characters. I have attached a patch (encoding.diff) which suggests how it could be done.
        Hide
        Kim Haase added a comment -

        Committed patch DERBY-1932.diff to documentation trunk at revision 689203.

        Show
        Kim Haase added a comment - Committed patch DERBY-1932 .diff to documentation trunk at revision 689203.
        Hide
        Kim Haase added a comment -

        Thanks for the feedback, Knut Anders – I will commit the patch to the trunk. Should I file another JIRA on the encoding issues? I would need some help fixing the code to make it work in all (or most) locales. Or I could just add notes with your caveats.

        Show
        Kim Haase added a comment - Thanks for the feedback, Knut Anders – I will commit the patch to the trunk. Should I file another JIRA on the encoding issues? I would need some help fixing the code to make it work in all (or most) locales. Or I could just add notes with your caveats.
        Hide
        Knut Anders Hatlen added a comment -

        The patch definitely looks like an improvement, so +1 to commit.

        I think the examples in rrefjavsqlprst and rrefjavsqlrssc may have some character encoding issues, but they were not introduced by your patch and shouldn't stop you from committing.

        The possible encoding issues, are

        1) In rrefjavsqlprst, a FileInputStream is passed in to PreparedStatement.setAsciiStream() in order to update a LONG VARCHAR. This will only work as expected if the file is encoded in US-ASCII.

        2) In rrefjavsqlrssc, the byte stream we're reading from contains ASCII-encoded characters, whereas the String constructor we're using will assume that the characters are encoded with the platform's default encoding. May work on some platforms/locales and fail on others.

        Show
        Knut Anders Hatlen added a comment - The patch definitely looks like an improvement, so +1 to commit. I think the examples in rrefjavsqlprst and rrefjavsqlrssc may have some character encoding issues, but they were not introduced by your patch and shouldn't stop you from committing. The possible encoding issues, are 1) In rrefjavsqlprst, a FileInputStream is passed in to PreparedStatement.setAsciiStream() in order to update a LONG VARCHAR. This will only work as expected if the file is encoded in US-ASCII. 2) In rrefjavsqlrssc, the byte stream we're reading from contains ASCII-encoded characters, whereas the String constructor we're using will assume that the characters are encoded with the platform's default encoding. May work on some platforms/locales and fail on others.
        Hide
        Kim Haase added a comment -

        I'd like to commit this patch on Thursday 8/28, so if anyone has comments, please add them by the end of Wednesday 8/27.

        Show
        Kim Haase added a comment - I'd like to commit this patch on Thursday 8/28, so if anyone has comments, please add them by the end of Wednesday 8/27.
        Hide
        Kim Haase added a comment -

        Attaching DERBY-1932.diff, DERBY-1932.zip, and DERBY-1932.stat.

        M src/ref/rrefjavsqlprst.dita
        M src/ref/crefjavbclobnot.dita
        M src/ref/rrefjavsqlrssc.dita

        Made the following content changes: described lack of support for the setUnicodeStream and setNCharacterStream methods, and added mentions of getCharacterStream and setCharacterStream. Replaced UnicodeStream with CharacterStream in table. Changed note to make it apply only to the client driver.

        In addition to these content changes, I have made some formatting fixes to examples and to a table, added or corrected index entries, and corrected some typos.

        Show
        Kim Haase added a comment - Attaching DERBY-1932 .diff, DERBY-1932 .zip, and DERBY-1932 .stat. M src/ref/rrefjavsqlprst.dita M src/ref/crefjavbclobnot.dita M src/ref/rrefjavsqlrssc.dita Made the following content changes: described lack of support for the setUnicodeStream and setNCharacterStream methods, and added mentions of getCharacterStream and setCharacterStream. Replaced UnicodeStream with CharacterStream in table. Changed note to make it apply only to the client driver. In addition to these content changes, I have made some formatting fixes to examples and to a table, added or corrected index entries, and corrected some typos.
        Hide
        Kim Haase added a comment -

        Some fixes are needed here to tidy up the JDBC reference section, though some have already been made.

        rrefjdbc96386.html – this problem was fixed in DERBY-3409 (table entries with no implementation notes are now gone).

        rrefdmdfns.html (DatabaseMetaData functionality not supported): this topic was removed from the manual at 10.3, it appears.

        rrefjavsqlprst.html: Mention of JDBC 1.2 was removed in DERBY-3409. Not sure why note refers to getXXXStream since only setXXXStream methods exist.

        There was no indication in reviews of DERBY-3409 that setUnicodeStream was no longer implemented in Derby. This is true, however (it throws a Feature not implemented exception).

        Unless I hear otherwise, I will add info about setCharacterStream. I assume I can replace setUnicodeStream with setCharacterStream in the table (that is, that LONGVARCHAR is the preferred target data type). Please let me know if this is not the case.

        Derby doesn't support setNCharacterStream/getNCharacterStream (throws Feature not implemented exception).

        Checking the 10.3 reference manual, it appears that it is the middle note that applies to the client driver only. Is that the case? It would be hard to test this.

        crefjavbclobnot.html (Notes on Blob/Clob): remove getUnicodeStream, add getCharacterStream.

        It appears to be true that rrefjavsqlrssc.html (ResultSets) and rrefjdbc4_0summary.html need no changes – though rrefjavsqlrssc.html has an unused variable declaration ("int c:") that could be removed.

        Show
        Kim Haase added a comment - Some fixes are needed here to tidy up the JDBC reference section, though some have already been made. rrefjdbc96386.html – this problem was fixed in DERBY-3409 (table entries with no implementation notes are now gone). rrefdmdfns.html (DatabaseMetaData functionality not supported): this topic was removed from the manual at 10.3, it appears. rrefjavsqlprst.html: Mention of JDBC 1.2 was removed in DERBY-3409 . Not sure why note refers to getXXXStream since only setXXXStream methods exist. There was no indication in reviews of DERBY-3409 that setUnicodeStream was no longer implemented in Derby. This is true, however (it throws a Feature not implemented exception). Unless I hear otherwise, I will add info about setCharacterStream. I assume I can replace setUnicodeStream with setCharacterStream in the table (that is, that LONGVARCHAR is the preferred target data type). Please let me know if this is not the case. Derby doesn't support setNCharacterStream/getNCharacterStream (throws Feature not implemented exception). Checking the 10.3 reference manual, it appears that it is the middle note that applies to the client driver only. Is that the case? It would be hard to test this. crefjavbclobnot.html (Notes on Blob/Clob): remove getUnicodeStream, add getCharacterStream. It appears to be true that rrefjavsqlrssc.html (ResultSets) and rrefjdbc4_0summary.html need no changes – though rrefjavsqlrssc.html has an unused variable declaration ("int c:") that could be removed.
        Hide
        Andrew McIntyre added a comment -

        Unsetting Fix Version for unassigned issues.

        Show
        Andrew McIntyre added a comment - Unsetting Fix Version for unassigned issues.
        Hide
        Rick Hillegas added a comment -

        Reassigning to 10.2.3.0.

        Show
        Rick Hillegas added a comment - Reassigning to 10.2.3.0.

          People

          • Assignee:
            Kim Haase
            Reporter:
            Laura Stewart
          • Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development