Derby
  1. Derby
  2. DERBY-5696

Documentation on LOBs needs some fixes

    Details

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

      Description

      DERBY-5489 points out some issues with multiple getXXX calls on LOBs that are not fully documented. The information should probably be added to "Notes on mapping of java.sql.Blob and java.sql.Clob interfaces". In addition, the topic "Mapping of java.sql.Blob and java.sql.Clob interfaces" has a typo and could probably use some additional information as well.

      1. rrefjdbc96386.html
        10 kB
        Kim Haase
      2. rrefjdbc96386.html
        10 kB
        Kim Haase
      3. DERBY-5696-2.diff
        0.9 kB
        Kim Haase
      4. DERBY-5696.diff
        0.9 kB
        Kim Haase

        Issue Links

          Activity

          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.
          Hide
          Kim Haase added a comment -

          Thanks again, Kristian.

          Committed patch DERBY-5696-2.diff to documentation trunk at revision 1335100.

          Show
          Kim Haase added a comment - Thanks again, Kristian. Committed patch DERBY-5696 -2.diff to documentation trunk at revision 1335100.
          Hide
          Kristian Waagan added a comment -

          Looks good, Kim.
          +1 to commit

          Show
          Kristian Waagan added a comment - Looks good, Kim. +1 to commit
          Hide
          Kim Haase added a comment -

          Thanks again, Kristian – attaching a second patch, DERBY-5696-2.diff and the modified rrefjdbc96386.html, that makes the change you suggested.

          Show
          Kim Haase added a comment - Thanks again, Kristian – attaching a second patch, DERBY-5696 -2.diff and the modified rrefjdbc96386.html, that makes the change you suggested.
          Hide
          Kim Haase added a comment -

          I think the change you suggest is worth making, Kristian – I'll file another patch. Thanks!

          Show
          Kim Haase added a comment - I think the change you suggest is worth making, Kristian – I'll file another patch. Thanks!
          Hide
          Kristian Waagan added a comment -

          Thanks, Kim.

          Is it clear enough that "You can access a LOB column only once" really means "You can access a given LOB column only once within a row"?

          With respect to detail, I think this is sufficient for the reference manual.

          Show
          Kristian Waagan added a comment - Thanks, Kim. Is it clear enough that "You can access a LOB column only once" really means "You can access a given LOB column only once within a row"? With respect to detail, I think this is sufficient for the reference manual.
          Hide
          Kim Haase added a comment -

          Sorry, the change is in the attached DERBY-5696.diff and rrefjdbc96386.html.

          Show
          Kim Haase added a comment - Sorry, the change is in the attached DERBY-5696 .diff and rrefjdbc96386.html.
          Hide
          Kim Haase added a comment -

          I think that we can get away with adding just one sentence to the topic, placed reasonably prominently (in a paragraph of its own). I think this covers the main point that needs making and that details are already provided elsewhere.

          If this doesn't get it quite right or could use more detail, please let me know.

          Show
          Kim Haase added a comment - I think that we can get away with adding just one sentence to the topic, placed reasonably prominently (in a paragraph of its own). I think this covers the main point that needs making and that details are already provided elsewhere. If this doesn't get it quite right or could use more detail, please let me know.
          Hide
          Kim Haase added a comment -

          Thanks very much for that explanation, Kristian. I'll work with it and file a patch that I hope will put things correctly.

          Show
          Kim Haase added a comment - Thanks very much for that explanation, Kristian. I'll work with it and file a patch that I hope will put things correctly.
          Hide
          Kristian Waagan added a comment -

          Hi Kim,

          The base rule is that you can only access a LOB column once. To access a column you invoke a getter on it.
          The exceptions to that rule are getBytes and getString, which allow you to invoke those two getters as many times as you like, given none of the other getters has been invoked already, and additionally one other getter as the last invocation.

          The reason for the exception to the rule is to avoid breaking existing applications that work correctly. getBytes and getString ([1]) are different because they always materialize the value. With materialized values you don't have the problems with stream positioning that you have [in Derby] when serving content off a store stream.

          The fact that you can invoke getBytes/getString multiple times is not really an important thing to note in the manual. What users need to know is that you can only invoke a getter once on a LOB column. If we document the special behavior of getBytes/getString, it is to allow user to understand the behavior they are seeing in their application. Some users may use/abuse that for convenience - that's fine as long as they know their large objects are small object

          Don't hesitate to ask further questions if my explanation is unclear.

          [1] ResultSet.get[Bytes|String] and Blob.getBytes/Clob.getSubString are different as the former alway fetch the whole value, whereas the latter allows for fetching only parts of the value.

          Show
          Kristian Waagan added a comment - Hi Kim, The base rule is that you can only access a LOB column once. To access a column you invoke a getter on it. The exceptions to that rule are getBytes and getString, which allow you to invoke those two getters as many times as you like, given none of the other getters has been invoked already, and additionally one other getter as the last invocation. The reason for the exception to the rule is to avoid breaking existing applications that work correctly. getBytes and getString ( [1] ) are different because they always materialize the value. With materialized values you don't have the problems with stream positioning that you have [in Derby] when serving content off a store stream. The fact that you can invoke getBytes/getString multiple times is not really an important thing to note in the manual. What users need to know is that you can only invoke a getter once on a LOB column. If we document the special behavior of getBytes/getString, it is to allow user to understand the behavior they are seeing in their application. Some users may use/abuse that for convenience - that's fine as long as they know their large objects are small object Don't hesitate to ask further questions if my explanation is unclear. [1] ResultSet.get [Bytes|String] and Blob.getBytes/Clob.getSubString are different as the former alway fetch the whole value, whereas the latter allows for fetching only parts of the value.
          Hide
          Kim Haase added a comment -

          I'm trying to figure out how to document the behavior noted in DERBY-5489, but I'm a little confused. I was going to say something like

          "If you call one of the ResultSet methods getBytes, getString, or getObject on a LOB after a different getter has already been invoked, an error occurs."

          However, that seems to apply to items a, b, d, and e below, but not to c. Why is it okay to call getObject after getBytes, but not the other way around?

          a) OK: getBytes - getBytes
          b) FAILS: getObject - getBytes
          c) OK: getBytes - getObject
          d) FAILS: getBytes - getObject - getBytes
          e) FAILS: getBlob - getBinaryStream

          Thanks for any advice.

          Show
          Kim Haase added a comment - I'm trying to figure out how to document the behavior noted in DERBY-5489 , but I'm a little confused. I was going to say something like "If you call one of the ResultSet methods getBytes, getString, or getObject on a LOB after a different getter has already been invoked, an error occurs." However, that seems to apply to items a, b, d, and e below, but not to c. Why is it okay to call getObject after getBytes, but not the other way around? a) OK: getBytes - getBytes b) FAILS: getObject - getBytes c) OK: getBytes - getObject d) FAILS: getBytes - getObject - getBytes e) FAILS: getBlob - getBinaryStream Thanks for any advice.

            People

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

              Dates

              • Created:
                Updated:
                Resolved:

                Development