Derby
  1. Derby
  2. DERBY-5191

Documentation needed for connection URL attribute retrieveMessageText

    Details

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

      Description

      The connection URL attribute retrieveMessageText, mentioned in the Admin Guide in the topic "Accessing the Network Server by using the network client driver (cadminappsclient.dita), is not documented in the Reference Manual but should be.

      I can't find any javadoc comments on this attribute in the implementation code in java/client/org/apache/derby/jdbc/ClientBaseDataSource.java or client/org/apache/derby/client/am/Connection.java.

      The Admin Guide just says the following, noting that the default setting is true:

      "Retrieve message text from the server. A stored procedure is called to retrieve the message text with each SQLException and might start a new unit of work. Set this property to false if you do not want the performance impact or when starting new units of work."

      This last sentence is confusing. Seems like it should be something like "Set this property to false if you do not want the performance impact or do not want to start a new unit of work." Does that make more sense?

      I know the attribute is client-specific.

      Must it be combined with any other attributes, or are there some that it must NOT be combined with?

      What else needs to be said?

      I'll pick this up if someone can clear up these few points.

      1. DERBY-5191.diff
        3 kB
        Kim Haase
      2. DERBY-5191.stat
        0.1 kB
        Kim Haase
      3. rrefattribretrievemsgtext.html
        4 kB
        Kim Haase
      4. DERBY-5191-2.diff
        4 kB
        Kim Haase
      5. DERBY-5191-2.stat
        0.1 kB
        Kim Haase
      6. rrefattribretrievemsgtext.html
        4 kB
        Kim Haase
      7. rrefattribderegister.html
        5 kB
        Kim Haase

        Issue Links

          Activity

          Gavin made changes -
          Workflow jira [ 12610565 ] Default workflow, editable Closed status [ 12801074 ]
          Myrna van Lunteren made changes -
          Fix Version/s 10.8.2.2 [ 12317968 ]
          Fix Version/s 10.8.2.0 [ 12317955 ]
          Myrna van Lunteren made changes -
          Fix Version/s 10.8.2.0 [ 12317955 ]
          Fix Version/s 10.8.1.6 [ 12316676 ]
          Knut Anders Hatlen made changes -
          Fix Version/s 10.8.1.5 [ 12316676 ]
          Fix Version/s 10.8.1.4 [ 12316500 ]
          Rick Hillegas made changes -
          Fix Version/s 10.8.1.4 [ 12316500 ]
          Fix Version/s 10.8.1.3 [ 12316378 ]
          Kim Haase made changes -
          Status Resolved [ 5 ] Closed [ 6 ]
          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.
          Kim Haase made changes -
          Fix Version/s 10.8.1.3 [ 12316378 ]
          Fix Version/s 10.9.0.0 [ 12316344 ]
          Resolution Fixed [ 1 ]
          Status Open [ 1 ] Resolved [ 5 ]
          Issue & fix info [Patch Available]
          Hide
          Kim Haase added a comment -

          Committed patch DERBY-5191-2.diff to documentation trunk at revision 1099817.
          Merged to 10.8 doc branch at revision 1099824.

          Show
          Kim Haase added a comment - Committed patch DERBY-5191 -2.diff to documentation trunk at revision 1099817. Merged to 10.8 doc branch at revision 1099824.
          Hide
          Dag H. Wanvik added a comment -

          Looks good to me! Thanks, Kim. +1

          Show
          Dag H. Wanvik added a comment - Looks good to me! Thanks, Kim. +1
          Kim Haase made changes -
          Attachment DERBY-5191-2.diff [ 12477961 ]
          Attachment DERBY-5191-2.stat [ 12477962 ]
          Attachment rrefattribretrievemsgtext.html [ 12477963 ]
          Attachment rrefattribderegister.html [ 12477964 ]
          Hide
          Kim Haase added a comment -

          Attaching a second patch: DERBY-5191-2.diff, DERBY-5191-2.stat, rrefattribretrievemsgtext.html, and rrefattribderegister.html.

          A src/ref/rrefattribretrievemsgtext.dita
          M src/ref/rrefattribderegister.dita
          M src/ref/refderby.ditamap

          For these two attributes, the titles have been changed to retrieveMessageText=false and deregister=false to reflect the fact that for these attributes, the default is true, whereas for all other boolean attributes it is false.

          Show
          Kim Haase added a comment - Attaching a second patch: DERBY-5191 -2.diff, DERBY-5191 -2.stat, rrefattribretrievemsgtext.html, and rrefattribderegister.html. A src/ref/rrefattribretrievemsgtext.dita M src/ref/rrefattribderegister.dita M src/ref/refderby.ditamap For these two attributes, the titles have been changed to retrieveMessageText=false and deregister=false to reflect the fact that for these attributes, the default is true, whereas for all other boolean attributes it is false.
          Hide
          Kim Haase added a comment -

          I am working on using "=false" for the newcomers for which true is the default, since the alternative would require changes to a lot of topics (around 10) that have been the same for a while.

          Show
          Kim Haase added a comment - I am working on using "=false" for the newcomers for which true is the default, since the alternative would require changes to a lot of topics (around 10) that have been the same for a while.
          Hide
          Dag H. Wanvik added a comment -

          Thanks, Kim! I think we should either change all titles to "<attribute>=boolean [value]", or use "=false" for the two newcomers. Personally, I'd prefer the first approach. As it stands, it can be misunderstood, IMHO.

          Show
          Dag H. Wanvik added a comment - Thanks, Kim! I think we should either change all titles to "<attribute>=boolean [value] ", or use "=false" for the two newcomers. Personally, I'd prefer the first approach. As it stands, it can be misunderstood, IMHO.
          Hide
          Kim Haase added a comment -

          There is more information about retrieveMessageText in the description of DERBY-159.

          Show
          Kim Haase added a comment - There is more information about retrieveMessageText in the description of DERBY-159 .
          Kim Haase made changes -
          Link This issue is related to DERBY-159 [ DERBY-159 ]
          Hide
          Kim Haase added a comment -

          Yes, I fully admit I was not sure what to do here. It started with the deregister attribute. I think that is the first one we documented where the default is true rather than false. But for consistency with the other Booleans I left it as true. I could change both of them. I don't think there are any others like that yet.

          Show
          Kim Haase added a comment - Yes, I fully admit I was not sure what to do here. It started with the deregister attribute. I think that is the first one we documented where the default is true rather than false. But for consistency with the other Booleans I left it as true. I could change both of them. I don't think there are any others like that yet.
          Hide
          Dag H. Wanvik added a comment -

          Not sure I understand the logic of the titles in this section "<attribute>=<value>". For the boolean ones, they are all stated as "<attribute>=true". I sort of thought this meant that default would be "false"? If so, shouldn't this one be called the "retrieveMessageText=false attribute"? It seems all the other boolean ones are false by default? Or?

          Show
          Dag H. Wanvik added a comment - Not sure I understand the logic of the titles in this section "<attribute>=<value>". For the boolean ones, they are all stated as "<attribute>=true". I sort of thought this meant that default would be "false"? If so, shouldn't this one be called the "retrieveMessageText=false attribute"? It seems all the other boolean ones are false by default? Or?
          Hide
          Kim Haase added a comment -

          Thanks, Dag, for the feedback on the confusing sentence.

          The topic's first sentence begins, "If set to true (the default), ..." This is what we did with deregister=true. So I believe the default is clearly stated.

          Show
          Kim Haase added a comment - Thanks, Dag, for the feedback on the confusing sentence. The topic's first sentence begins, "If set to true (the default), ..." This is what we did with deregister=true. So I believe the default is clearly stated.
          Hide
          Dag H. Wanvik added a comment - - edited

          > This last sentence is confusing. Seems like it should be something like "Set this property to false if you do not want the performance impact or do not want to start a new unit of work." Does that make more sense?

          Yes, I think so. Is the default clearly stated (true, I believe)?

          Show
          Dag H. Wanvik added a comment - - edited > This last sentence is confusing. Seems like it should be something like "Set this property to false if you do not want the performance impact or do not want to start a new unit of work." Does that make more sense? Yes, I think so. Is the default clearly stated (true, I believe)?
          Kim Haase made changes -
          Affects Version/s 10.8.1.2 [ 12316362 ]
          Kim Haase made changes -
          Issue & fix info [Patch Available]
          Kim Haase made changes -
          Attachment DERBY-5191.diff [ 12477307 ]
          Attachment DERBY-5191.stat [ 12477308 ]
          Attachment rrefattribretrievemsgtext.html [ 12477309 ]
          Hide
          Kim Haase added a comment -

          Attaching DERBY-5191.diff, DERBY-5191.stat, and the new topic rrefattribretrievemsgtext.html, with the following changes:

          A src/ref/rrefattribretrievemsgtext.dita
          M src/ref/refderby.ditamap

          I guessed that retrieveMessageText can be combined with other attributes, since that is the case for the other client-specific attributes listed in the Admin Guide ("Accessing the Network Server by using the network client driver"). Hope that's the case.

          Please let me know if further changes are needed. I'll commit the patch by the end of the week if I don't hear anything. Thanks very much.

          Show
          Kim Haase added a comment - Attaching DERBY-5191 .diff, DERBY-5191 .stat, and the new topic rrefattribretrievemsgtext.html, with the following changes: A src/ref/rrefattribretrievemsgtext.dita M src/ref/refderby.ditamap I guessed that retrieveMessageText can be combined with other attributes, since that is the case for the other client-specific attributes listed in the Admin Guide ("Accessing the Network Server by using the network client driver"). Hope that's the case. Please let me know if further changes are needed. I'll commit the patch by the end of the week if I don't hear anything. Thanks very much.
          Kim Haase made changes -
          Field Original Value New Value
          Assignee Kim Haase [ chaase3 ]
          Kim Haase created issue -

            People

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

              Dates

              • Created:
                Updated:
                Resolved:

                Development