Details

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

      Description

      The new features introduced in DERBY-690, DERBY-231, DERBY-775 and DERBY-100 should be documented in the Derby documentation.

      This includes:

      • updatable cursors do longer need to "FOR UPDATE" clause
      • Scrollable insensitive resultsets can be updatable
      • ResultSet.insertRow()
      1. DERBY-717.diff
        19 kB
        Andreas Korneliussen
      2. DERBY-717.stat
        0.3 kB
        Andreas Korneliussen
      3. derby-717.tar.gz
        7 kB
        Andreas Korneliussen
      4. DERBY-717v2.diff
        19 kB
        Andreas Korneliussen
      5. DERBY-717v3.diff
        27 kB
        Andreas Korneliussen
      6. DERBY-717v3.stat
        0.4 kB
        Andreas Korneliussen
      7. derby-717v3.tar.gz
        11 kB
        Andreas Korneliussen
      8. DERBY-717v4.diff
        72 kB
        Andreas Korneliussen
      9. DERBY-717v4.stat
        1 kB
        Andreas Korneliussen
      10. derby-717v4.tar.gz
        58 kB
        Andreas Korneliussen

        Activity

        Gavin made changes -
        Workflow jira [ 12343887 ] Default workflow, editable Closed status [ 12797656 ]
        Andreas Korneliussen made changes -
        Status Resolved [ 5 ] Closed [ 6 ]
        Andreas Korneliussen made changes -
        Resolution Fixed [ 1 ]
        Status Open [ 1 ] Resolved [ 5 ]
        Fix Version/s 10.2.0.0 [ 11187 ]
        Derby Info [Patch Available]
        Hide
        Andreas Korneliussen added a comment -

        Committed revision 413877.

        Show
        Andreas Korneliussen added a comment - Committed revision 413877.
        Andreas Korneliussen made changes -
        Priority Minor [ 4 ] Major [ 3 ]
        Description The new features introduced in DERBY-690, DERBY-231, DERBY-775 and DERBY-100 should be documented in the Derby developer guide.

        This includes:
        * updatable cursors do longer need to "FOR UPDATE" clause
        * Scrollable insensitive resultsets can be updatable
        * ResultSet.insertRow()
        The new features introduced in DERBY-690, DERBY-231, DERBY-775 and DERBY-100 should be documented in the Derby documentation.

        This includes:
        * updatable cursors do longer need to "FOR UPDATE" clause
        * Scrollable insensitive resultsets can be updatable
        * ResultSet.insertRow()
        Hide
        Andreas Korneliussen added a comment -

        I intend to commit the patch DERBY-717v4, which includes changes in Derby developer guide, reference guide, tools guide, and admin guide.

        I will make some minor changes before committing (an incorrect reference in one of the documents, and a typo in another document).

        Show
        Andreas Korneliussen added a comment - I intend to commit the patch DERBY-717 v4, which includes changes in Derby developer guide, reference guide, tools guide, and admin guide. I will make some minor changes before committing (an incorrect reference in one of the documents, and a typo in another document).
        Hide
        Andreas Korneliussen added a comment -

        Øystein Grøvlen wrote:
        >Differences between the embedded client and the network client driver
        > - Is it still true that scrollable does not support LOBs?

        On client, I think that this is still true. However updateObject() with nulls, and updateString() on int,decimal, long, etc is supported in client.

        Show
        Andreas Korneliussen added a comment - Øystein Grøvlen wrote: >Differences between the embedded client and the network client driver > - Is it still true that scrollable does not support LOBs? On client, I think that this is still true. However updateObject() with nulls, and updateString() on int,decimal, long, etc is supported in client.
        Andreas Korneliussen made changes -
        Attachment derby-717v4.tar.gz [ 12334893 ]
        Attachment DERBY-717v4.diff [ 12334891 ]
        Attachment DERBY-717v4.stat [ 12334892 ]
        Hide
        Andreas Korneliussen added a comment -

        Attached is a new patch, where I have addressed the comments made by Øystein G. I think all comments have been addressed, including fixing topics not touched by the reviewed patch.
        The patch also covers the admin guide and the tools guide.

        Show
        Andreas Korneliussen added a comment - Attached is a new patch, where I have addressed the comments made by Øystein G. I think all comments have been addressed, including fixing topics not touched by the reviewed patch. The patch also covers the admin guide and the tools guide.
        Hide
        Andreas Korneliussen added a comment -

        > Forward only updatable result sets
        >> - Headings in the Dev. Guide are not consistent with respect to
        >> "ResultSets" vs. "result sets"
        >> - "cursors which can move forward and update rows". Would you
        >> call it a cursor if could not move forward?
        >> - "On cursor held on commit" sounds strange. I suggest "cursors
        >> held open after a commit". This phrase is used in the "Holdable
        >> cursors" chapter. Or maybe you should use result set instead of
        >> cursor here. Here you talk about operations on cursors, what
        >> about operations on result sets?
        >>
        >> Holdable cursors
        >> - For scrollable result sets, I do not think it is true that
        >> next() and close() are the only valid operations after a commit.
        >>
        > You are here commenting on current doc, not the contribution. In this document I only corrected which platforms holdable cursors are supported on.

        I only meant the comments for "Holdable cursors" were for the current doc, the comments on "Forward only updatable result sets" are part of the contribution, and will be addressed when I update the patch.

        Show
        Andreas Korneliussen added a comment - > Forward only updatable result sets >> - Headings in the Dev. Guide are not consistent with respect to >> "ResultSets" vs. "result sets" >> - "cursors which can move forward and update rows". Would you >> call it a cursor if could not move forward? >> - "On cursor held on commit" sounds strange. I suggest "cursors >> held open after a commit". This phrase is used in the "Holdable >> cursors" chapter. Or maybe you should use result set instead of >> cursor here. Here you talk about operations on cursors, what >> about operations on result sets? >> >> Holdable cursors >> - For scrollable result sets, I do not think it is true that >> next() and close() are the only valid operations after a commit. >> > You are here commenting on current doc, not the contribution. In this document I only corrected which platforms holdable cursors are supported on. I only meant the comments for "Holdable cursors" were for the current doc, the comments on "Forward only updatable result sets" are part of the contribution, and will be addressed when I update the patch.
        Hide
        Andreas Korneliussen added a comment -

        Thanks for the reviewing.
        I think I will limit the scope of the first doc patch to the reference guide and the dev.guide, and then do the other manuals after this patch has been committed.

        Before I update the patch, I would like to answer some of the questions you have, and comment to some of the comments:

        > - Is it possible to tune the amount of memory used by
        > scroll-insensitive Result Sets?

        No, I do not think so. I took a brief look at the code, and it seems that the BackingStoreHashTable will attempt to use a maximum of 1% of the available memory in the VM for storing rows in memory (as it is being used from ScrollInsensitiveResultSet). So it is sort of self-tuning.

        > Updatable cursors and result set:
        > - I feel that the doc is not consistent with respect to definition
        > of cursors and result sets. The first page on result sets says:
        > "A cursor provides you with the ability to step through and
        > process the rows in a ResultSet one by one."
        > You say:
        > "Scrollable updatable result sets are based on cursors which
        > can both scroll and update rows."
        > This seems like opposite views or may be circular definition.
        > Is cursors based on result sets or result sets based on cursors?
        > Generally, it is not clear to me if you have any rules for when
        > to talk about result sets and when to talk about cursors.

        I agree this could be improved.
        My view is that ResultSet is a Java programming interface which gives access to a SQL concept (cursor), so result sets are based on cursors, not opposite.

        Some existing docs have the opposite view (cursors are defined in terms of ResultSets).

        In which direction do you propose we should define cursors <-> ResultSets ?

        > - I am not sure everybody will understand the meaning of
        > "ResultSet.updateXXX() + ResultSet.updateRow()". Is this common
        > notation in the docs? I suggest you come up with another way to
        > express this. If you disagree, at least write the '+' in text
        > font and not code font.

        I could use: "Result set update methods", if you think that is better ?

        > - "Both scrollable and forward only cursors can be updatable". I
        > suggest may. Why do you choose to talk about cursors here and
        > not result sets? I would suggest to focus on result sets and
        > only use cursors where you need to talk about SQL cursors (e.g.,
        > WHERE CURRENT OF).

        I think this is a current document, which talks about cursors. I could change it to talk about result sets instead, and only mention cursors where relevant.

        > Forward only updatable result sets
        > - Headings in the Dev. Guide are not consistent with respect to
        > "ResultSets" vs. "result sets"
        > - "cursors which can move forward and update rows". Would you
        > call it a cursor if could not move forward?
        > - "On cursor held on commit" sounds strange. I suggest "cursors
        > held open after a commit". This phrase is used in the "Holdable
        > cursors" chapter. Or maybe you should use result set instead of
        > cursor here. Here you talk about operations on cursors, what
        > about operations on result sets?
        >
        > Holdable cursors
        > - For scrollable result sets, I do not think it is true that
        > next() and close() are the only valid operations after a commit.
        >
        You are here commenting on current doc, not the contribution. In this document I only corrected which platforms holdable cursors are supported on.

        I do not think it is true for forward only result sets either.
        After a commit, you could do next(), and then you may do updateRow() / deleteRow() or any other legal operation on FO result sets.

        > Inserting rows with updatable result sets
        >
        ..
        > - "after the current row". Is it obvious what this means? What
        > defines the ordering here?

        The ordering is by RowLocation, so if the inserted row get a RowLocation with a higher page number or same page number and higher recordid than the current row, it may be seen after insertRow. What current row is, should be quite obvious.

        > - ",i.e if the result set is not fully populated." I would drop
        > ", i.e.". I also wonder whether the meaning of "is not fully
        > populated" will be meaningful to the reader.
        >
        I will remove that bi-sentence.

        > Scrollable updatable result sets
        > - The term "scrollable" is not used in the manual prior to your
        > changes. I think that indicates that a job is needed to make
        > the terminology consistent. Either, you need to keep on using
        > the old terminology, or you need to update the old text to use
        > "scrollable".

        I will change it from "scrollable" to "scroll insensitve", since it is more precise.

        > - Visibility, 4th bullet. "it has been on the last row" sounds a
        > bit strange. I also think you need to define "populated"

        > - Visibility, last bullet. "may return true if ..." Is this not
        > deterministic?

        It is deterministic, so it should be will.

        > - "after they were populated to the result set". I would say it
        > is a result set that is populated, not the rows. Or can someone
        > be populated to a city?

        Maybe "populate" is not a good verb ..? Any better suggestions ?

        > - "columns being changed will be overwritten". I suggest "may
        > be overwritten"

        However they always will be overwritten on successful updates.

        > Extended updatable cursor example
        > - Comment says auto-commit needs to be off. The section
        > "ResultSets and auto-commit" says the opposite. The section
        > "Using auto-commit" also says updatable cursors do not work with
        > auto-commit on. At least one of those must be wrong.

        I cannot see that I have touched any of these documents, so this must be inconsistencies in existing documents.

        >
        > Update locks
        > - Is FOR UPDATE still required to get update locks?
        >
        No.

        Show
        Andreas Korneliussen added a comment - Thanks for the reviewing. I think I will limit the scope of the first doc patch to the reference guide and the dev.guide, and then do the other manuals after this patch has been committed. Before I update the patch, I would like to answer some of the questions you have, and comment to some of the comments: > - Is it possible to tune the amount of memory used by > scroll-insensitive Result Sets? No, I do not think so. I took a brief look at the code, and it seems that the BackingStoreHashTable will attempt to use a maximum of 1% of the available memory in the VM for storing rows in memory (as it is being used from ScrollInsensitiveResultSet). So it is sort of self-tuning. > Updatable cursors and result set: > - I feel that the doc is not consistent with respect to definition > of cursors and result sets. The first page on result sets says: > "A cursor provides you with the ability to step through and > process the rows in a ResultSet one by one." > You say: > "Scrollable updatable result sets are based on cursors which > can both scroll and update rows." > This seems like opposite views or may be circular definition. > Is cursors based on result sets or result sets based on cursors? > Generally, it is not clear to me if you have any rules for when > to talk about result sets and when to talk about cursors. I agree this could be improved. My view is that ResultSet is a Java programming interface which gives access to a SQL concept (cursor), so result sets are based on cursors, not opposite. Some existing docs have the opposite view (cursors are defined in terms of ResultSets). In which direction do you propose we should define cursors <-> ResultSets ? > - I am not sure everybody will understand the meaning of > "ResultSet.updateXXX() + ResultSet.updateRow()". Is this common > notation in the docs? I suggest you come up with another way to > express this. If you disagree, at least write the '+' in text > font and not code font. I could use: "Result set update methods", if you think that is better ? > - "Both scrollable and forward only cursors can be updatable". I > suggest may . Why do you choose to talk about cursors here and > not result sets? I would suggest to focus on result sets and > only use cursors where you need to talk about SQL cursors (e.g., > WHERE CURRENT OF). I think this is a current document, which talks about cursors. I could change it to talk about result sets instead, and only mention cursors where relevant. > Forward only updatable result sets > - Headings in the Dev. Guide are not consistent with respect to > "ResultSets" vs. "result sets" > - "cursors which can move forward and update rows". Would you > call it a cursor if could not move forward? > - "On cursor held on commit" sounds strange. I suggest "cursors > held open after a commit". This phrase is used in the "Holdable > cursors" chapter. Or maybe you should use result set instead of > cursor here. Here you talk about operations on cursors, what > about operations on result sets? > > Holdable cursors > - For scrollable result sets, I do not think it is true that > next() and close() are the only valid operations after a commit. > You are here commenting on current doc, not the contribution. In this document I only corrected which platforms holdable cursors are supported on. I do not think it is true for forward only result sets either. After a commit, you could do next(), and then you may do updateRow() / deleteRow() or any other legal operation on FO result sets. > Inserting rows with updatable result sets > .. > - "after the current row". Is it obvious what this means? What > defines the ordering here? The ordering is by RowLocation, so if the inserted row get a RowLocation with a higher page number or same page number and higher recordid than the current row, it may be seen after insertRow. What current row is, should be quite obvious. > - ",i.e if the result set is not fully populated." I would drop > ", i.e.". I also wonder whether the meaning of "is not fully > populated" will be meaningful to the reader. > I will remove that bi-sentence. > Scrollable updatable result sets > - The term "scrollable" is not used in the manual prior to your > changes. I think that indicates that a job is needed to make > the terminology consistent. Either, you need to keep on using > the old terminology, or you need to update the old text to use > "scrollable". I will change it from "scrollable" to "scroll insensitve", since it is more precise. > - Visibility, 4th bullet. "it has been on the last row" sounds a > bit strange. I also think you need to define "populated" > - Visibility, last bullet. " may return true if ..." Is this not > deterministic? It is deterministic, so it should be will . > - "after they were populated to the result set". I would say it > is a result set that is populated, not the rows. Or can someone > be populated to a city? Maybe "populate" is not a good verb ..? Any better suggestions ? > - "columns being changed will be overwritten". I suggest " may > be overwritten" However they always will be overwritten on successful updates. > Extended updatable cursor example > - Comment says auto-commit needs to be off. The section > "ResultSets and auto-commit" says the opposite. The section > "Using auto-commit" also says updatable cursors do not work with > auto-commit on. At least one of those must be wrong. I cannot see that I have touched any of these documents, so this must be inconsistencies in existing documents. > > Update locks > - Is FOR UPDATE still required to get update locks? > No.
        Hide
        Øystein Grøvlen added a comment -

        Good start, but you have not found all places in the documentation
        that needs to be changed. I suggest doing the following Google
        search, and go through each hit:

        "updatable site:db.apache.org/derby/docs/dev"

        I looked through the first hits and see my comments below for these.
        You should probably do the same for "scroll" and for "FOR UPDATE" too.

        Detailed comments:

        Dev. guide:
        --------------------

        Scrolling insensitive ResultSets:

        • "The materialized rows may be backed to disk". I suggest
          will.
        • Is it possible to tune the amount of memory used by
          scroll-insensitive Result Sets?
        • I think this page should say that both read-only and updatable
          are possible.
        • "all rows become materialized". I suggest will be

        Updatable cursors and result set:

        • I feel that the doc is not consistent with respect to definition
          of cursors and result sets. The first page on result sets says:
          "A cursor provides you with the ability to step through and
          process the rows in a ResultSet one by one."
          You say:
          "Scrollable updatable result sets are based on cursors which
          can both scroll and update rows."
          This seems like opposite views or may be circular definition.
          Is cursors based on result sets or result sets based on cursors?
          Generally, it is not clear to me if you have any rules for when
          to talk about result sets and when to talk about cursors.
        • Spelling: "postioned"
        • It would be a good with a reference to a definition of
          "positioned updates and deletes"
        • I am not sure everybody will understand the meaning of
          "ResultSet.updateXXX() + ResultSet.updateRow()". Is this common
          notation in the docs? I suggest you come up with another way to
          express this. If you disagree, at least write the '+' in text
          font and not code font.
        • "Both scrollable and forward only cursors can be updatable". I
          suggest may. Why do you choose to talk about cursors here and
          not result sets? I would suggest to focus on result sets and
          only use cursors where you need to talk about SQL cursors (e.g.,
          WHERE CURRENT OF).
        • "query producing the cursor" sounds a bit strange to me. I also
          wonder whether one should use "statement" instead of "query"
        • It would be good with a reference to somewhere in the manual
          where it is described how to handle warnings like the one
          described here.
        • "Query compilation fails if the query is not updatable, and
          contains a FOR UPDATE clause." Is the comma correct here?
        • A reference to the definition of "update lock" would be good.
        • "if you need to actually update the rows". I suggest "if you
          actually need to update the rows".
        • "which can both scroll and update rows". Sounds a bit strange
          to me.

        Forward only updatable result sets

        • Headings in the Dev. Guide are not consistent with respect to
          "ResultSets" vs. "result sets"
        • "cursors which can move forward and update rows". Would you
          call it a cursor if could not move forward?
        • "On cursor held on commit" sounds strange. I suggest "cursors
          held open after a commit". This phrase is used in the "Holdable
          cursors" chapter. Or maybe you should use result set instead of
          cursor here. Here you talk about operations on cursors, what
          about operations on result sets?

        Holdable cursors

        • For scrollable result sets, I do not think it is true that
          next() and close() are the only valid operations after a commit.

        Inserting rows with updatable result sets

        • "qualifies to the query condition". How about "satifies the
          query predicate"
        • "after the current row". Is it obvious what this means? What
          defines the ordering here?
        • ",i.e if the result set is not fully populated." I would drop
          ", i.e.". I also wonder whether the meaning of "is not fully
          populated" will be meaningful to the reader.

        Scrollable updatable result sets

        • The term "scrollable" is not used in the manual prior to your
          changes. I think that indicates that a job is needed to make
          the terminology consistent. Either, you need to keep on using
          the old terminology, or you need to update the old text to use
          "scrollable".
        • I think the introduction to the deleteRow example should say
          that it deletes the 5th from last row.
        • Visibility, 2nd bullet. I suggest making this note part of the
          1st bullet.
        • Visibility, 3rd bullet. I suggest "Changes caused by other
          statements and triggers within the same transaction are considered
          as other changes, and are not visible in scroll insensitive
          result sets." I am not sure that you need to mention changes by
          other transaction since that should be obvious. If you think
          that is needed, I suggest adding another statement for that.
        • Visibility, 4th bullet. "it has been on the last row" sounds a
          bit strange. I also think you need to define "populated"
        • Visibility, last bullet. "may return true if ..." Is this not
          deterministic?
        • "after they were populated to the result set". I would say it
          is a result set that is populated, not the rows. Or can someone
          be populated to a city?
        • "columns being changed will be overwritten". I suggest "may
          be overwritten"
        • It would be good to give the SQLSTATE for the warning you get
          when a row has been deleted.
        • I still don't like "held over a commit"
        • "If you use cursors held across commits,". I suggest "For a
          cursor held open after a commit"
        • "held cursors". I think it should be "holdable cursors"

        Extended updatable cursor example

        • Comment says auto-commit needs to be off. The section
          "ResultSets and auto-commit" says the opposite. The section
          "Using auto-commit" also says updatable cursors do not work with
          auto-commit on. At least one of those must be wrong.
        • I think this example should be reworked to use updatable
          ResultSet instead of "WHERE CURRENT OF". It would also be good
          if it used ResultSet.CONCUR_UPDATABLE instead of FOR UPDATE.

        Update locks

        • Is FOR UPDATE still required to get update locks?

        Reference guide:
        --------------------

        For UPDATE clause:

        • "ResultSet" => "JDBC ResultSet"

        SELECT statement:

        • Suggest rephrasing third paragraph to:
          "In order to get an updatable JDBC ResultSet, you do not need
          to include a FOR UPDATE clause. Instead, you can specify
          concurrency mode ResultSet.CONCUR_UPDATABLE when creating the
          statement."
        • Suggest putting the heading "Requirements for updatable cursors
          ..." above the preceding paragraph.
        • Do we need to specify the whole truth here? Maybe it would be
          better to focus on the use of CONCUR_UPDATABLE for ResultSets
          and mention FOR UPDATE only in the context of SQL cursors?
        • "Cursors are read-only by default." I suggest moving this to
          the start of the third paragraph.

        SQLState and error message reference

        • 01J03 "Scroll sensitive and scroll insensitive updatable
          ResultSets are not currently implemented." Hopefully, this
          error text has been changed.

        java.sql.Connection

        • "you can only request an updatable ResultSet that has a
          TYPE_FORWARD_ONLY scrolling type" !!!

        Admin. guide:
        --------------------

        Updatable Result Sets:

        • Any changes to what is supported?

        Differences between the embedded client and the network client driver

        • Is it still true that scrollable does not support LOBs?

        Tools guide:
        --------------------

        Get Scroll Insensitive Cursor

        • "Scroll insensitive cursors are not updatable."
        Show
        Øystein Grøvlen added a comment - Good start, but you have not found all places in the documentation that needs to be changed. I suggest doing the following Google search, and go through each hit: "updatable site:db.apache.org/derby/docs/dev" I looked through the first hits and see my comments below for these. You should probably do the same for "scroll" and for "FOR UPDATE" too. Detailed comments: Dev. guide: -------------------- Scrolling insensitive ResultSets: "The materialized rows may be backed to disk". I suggest will . Is it possible to tune the amount of memory used by scroll-insensitive Result Sets? I think this page should say that both read-only and updatable are possible. "all rows become materialized". I suggest will be Updatable cursors and result set: I feel that the doc is not consistent with respect to definition of cursors and result sets. The first page on result sets says: "A cursor provides you with the ability to step through and process the rows in a ResultSet one by one." You say: "Scrollable updatable result sets are based on cursors which can both scroll and update rows." This seems like opposite views or may be circular definition. Is cursors based on result sets or result sets based on cursors? Generally, it is not clear to me if you have any rules for when to talk about result sets and when to talk about cursors. Spelling: "postioned" It would be a good with a reference to a definition of "positioned updates and deletes" I am not sure everybody will understand the meaning of "ResultSet.updateXXX() + ResultSet.updateRow()". Is this common notation in the docs? I suggest you come up with another way to express this. If you disagree, at least write the '+' in text font and not code font. "Both scrollable and forward only cursors can be updatable". I suggest may . Why do you choose to talk about cursors here and not result sets? I would suggest to focus on result sets and only use cursors where you need to talk about SQL cursors (e.g., WHERE CURRENT OF). "query producing the cursor" sounds a bit strange to me. I also wonder whether one should use "statement" instead of "query" It would be good with a reference to somewhere in the manual where it is described how to handle warnings like the one described here. "Query compilation fails if the query is not updatable, and contains a FOR UPDATE clause." Is the comma correct here? A reference to the definition of "update lock" would be good. "if you need to actually update the rows". I suggest "if you actually need to update the rows". "which can both scroll and update rows". Sounds a bit strange to me. Forward only updatable result sets Headings in the Dev. Guide are not consistent with respect to "ResultSets" vs. "result sets" "cursors which can move forward and update rows". Would you call it a cursor if could not move forward? "On cursor held on commit" sounds strange. I suggest "cursors held open after a commit". This phrase is used in the "Holdable cursors" chapter. Or maybe you should use result set instead of cursor here. Here you talk about operations on cursors, what about operations on result sets? Holdable cursors For scrollable result sets, I do not think it is true that next() and close() are the only valid operations after a commit. Inserting rows with updatable result sets "qualifies to the query condition". How about "satifies the query predicate" "after the current row". Is it obvious what this means? What defines the ordering here? ",i.e if the result set is not fully populated." I would drop ", i.e.". I also wonder whether the meaning of "is not fully populated" will be meaningful to the reader. Scrollable updatable result sets The term "scrollable" is not used in the manual prior to your changes. I think that indicates that a job is needed to make the terminology consistent. Either, you need to keep on using the old terminology, or you need to update the old text to use "scrollable". I think the introduction to the deleteRow example should say that it deletes the 5th from last row. Visibility, 2nd bullet. I suggest making this note part of the 1st bullet. Visibility, 3rd bullet. I suggest "Changes caused by other statements and triggers within the same transaction are considered as other changes, and are not visible in scroll insensitive result sets." I am not sure that you need to mention changes by other transaction since that should be obvious. If you think that is needed, I suggest adding another statement for that. Visibility, 4th bullet. "it has been on the last row" sounds a bit strange. I also think you need to define "populated" Visibility, last bullet. " may return true if ..." Is this not deterministic? "after they were populated to the result set". I would say it is a result set that is populated, not the rows. Or can someone be populated to a city? "columns being changed will be overwritten". I suggest " may be overwritten" It would be good to give the SQLSTATE for the warning you get when a row has been deleted. I still don't like "held over a commit" "If you use cursors held across commits,". I suggest "For a cursor held open after a commit" "held cursors". I think it should be "holdable cursors" Extended updatable cursor example Comment says auto-commit needs to be off. The section "ResultSets and auto-commit" says the opposite. The section "Using auto-commit" also says updatable cursors do not work with auto-commit on. At least one of those must be wrong. I think this example should be reworked to use updatable ResultSet instead of "WHERE CURRENT OF". It would also be good if it used ResultSet.CONCUR_UPDATABLE instead of FOR UPDATE. Update locks Is FOR UPDATE still required to get update locks? Reference guide: -------------------- For UPDATE clause: "ResultSet" => "JDBC ResultSet" SELECT statement: Suggest rephrasing third paragraph to: "In order to get an updatable JDBC ResultSet, you do not need to include a FOR UPDATE clause. Instead, you can specify concurrency mode ResultSet.CONCUR_UPDATABLE when creating the statement." Suggest putting the heading "Requirements for updatable cursors ..." above the preceding paragraph. Do we need to specify the whole truth here? Maybe it would be better to focus on the use of CONCUR_UPDATABLE for ResultSets and mention FOR UPDATE only in the context of SQL cursors? "Cursors are read-only by default." I suggest moving this to the start of the third paragraph. SQLState and error message reference 01J03 "Scroll sensitive and scroll insensitive updatable ResultSets are not currently implemented." Hopefully, this error text has been changed. java.sql.Connection "you can only request an updatable ResultSet that has a TYPE_FORWARD_ONLY scrolling type" !!! Admin. guide: -------------------- Updatable Result Sets: Any changes to what is supported? Differences between the embedded client and the network client driver Is it still true that scrollable does not support LOBs? Tools guide: -------------------- Get Scroll Insensitive Cursor "Scroll insensitive cursors are not updatable."
        Andreas Korneliussen made changes -
        Attachment DERBY-717v3.stat [ 12326522 ]
        Attachment derby-717v3.tar.gz [ 12326523 ]
        Attachment DERBY-717v3.diff [ 12326521 ]
        Hide
        Andreas Korneliussen added a comment -

        The attached files (DERBY-717v3.*) now also contains updates to the Derby reference manual w.r.t. the updatable cursor features.
        Also changed some minor issues found in the first diff.

        Show
        Andreas Korneliussen added a comment - The attached files ( DERBY-717 v3.*) now also contains updates to the Derby reference manual w.r.t. the updatable cursor features. Also changed some minor issues found in the first diff.
        Andreas Korneliussen made changes -
        Attachment DERBY-717v2.diff [ 12325620 ]
        Hide
        Andreas Korneliussen added a comment -

        Minor change: some of the example code incorrectly referred to the resultset reference as rs instead of uprs. Fixed in DERBY-717v2.diff. Same stat file.

        Show
        Andreas Korneliussen added a comment - Minor change: some of the example code incorrectly referred to the resultset reference as rs instead of uprs. Fixed in DERBY-717 v2.diff. Same stat file.
        Andreas Korneliussen made changes -
        Derby Info [Patch Available]
        Andreas Korneliussen made changes -
        Attachment derby-717.tar.gz [ 12325617 ]
        Attachment DERBY-717.diff [ 12325615 ]
        Attachment DERBY-717.stat [ 12325616 ]
        Hide
        Andreas Korneliussen added a comment -

        The patch DERBY-717.diff has the following new topics:

        rdevconceptssur: describes scrollable updatable resultsets
        rdevconceptsfor: describes forward only updatable resultsets
        rdevconceptsinsertrow: describes ResultSet.insertRow()
        derbydev.ditamap: new topics included

        The patch also has the following changes:
        cdevconcepts22641: desription on materialization of scrollabel resultsets, and fixed example code
        cdevconcepts28351: added more description on updatable cursors
        rdevconceptsholdablecursors: modified text about holdable cursor only valid in java 1.4

        Attached is also html output (derby-717.tar.gz), for reviewers.

        Show
        Andreas Korneliussen added a comment - The patch DERBY-717 .diff has the following new topics: rdevconceptssur: describes scrollable updatable resultsets rdevconceptsfor: describes forward only updatable resultsets rdevconceptsinsertrow: describes ResultSet.insertRow() derbydev.ditamap: new topics included The patch also has the following changes: cdevconcepts22641: desription on materialization of scrollabel resultsets, and fixed example code cdevconcepts28351: added more description on updatable cursors rdevconceptsholdablecursors: modified text about holdable cursor only valid in java 1.4 Attached is also html output (derby-717.tar.gz), for reviewers.
        Andreas Korneliussen made changes -
        Description The new features introduced in DERBY-690, DERBY-231, DERBY-775 and DERBY-100 should be documented in the Derby reference manual.

        This includes:
        * updatable cursors do longer need to "FOR UPDATE" clause
        * Scrollable insensitive resultsets can be updatable
        * insertRow
        The new features introduced in DERBY-690, DERBY-231, DERBY-775 and DERBY-100 should be documented in the Derby developer guide.

        This includes:
        * updatable cursors do longer need to "FOR UPDATE" clause
        * Scrollable insensitive resultsets can be updatable
        * ResultSet.insertRow()
        Andreas Korneliussen made changes -
        Description The new features introduced in DERBY-690, DERBY-231, and DERBY-775 should be documented in the Derby reference manual.

        This includes:
        * updatable cursors do longer need to "FOR UPDATE" clause
        * Scrollable insensitive resultsets can be updatable
        The new features introduced in DERBY-690, DERBY-231, DERBY-775 and DERBY-100 should be documented in the Derby reference manual.

        This includes:
        * updatable cursors do longer need to "FOR UPDATE" clause
        * Scrollable insensitive resultsets can be updatable
        * insertRow
        Andreas Korneliussen made changes -
        Description The new features introduced in DERBY-695, DERBY-231, and DERBY-775 should be documented in the Derby reference manual.

        This includes:
        * updatable cursors do longer need to "FOR UPDATE" clause
        * Scrollable insensitive resultsets can be updatable
        The new features introduced in DERBY-690, DERBY-231, and DERBY-775 should be documented in the Derby reference manual.

        This includes:
        * updatable cursors do longer need to "FOR UPDATE" clause
        * Scrollable insensitive resultsets can be updatable
        Andreas Korneliussen made changes -
        Field Original Value New Value
        Description The following section in the Derby reference manual should be changed from:

        Cursors are read-only by default. For a cursor to be updatable, you must specify FOR UPDATE in the FOR clause (see FOR UPDATE clause ).

        to:

        Cursors are read-only by default. For a cursor to be updatable, you must specify FOR UPDATE in the FOR clause (see FOR UPDATE clause ), or use concurrency mode ResultSet.CONCUR_UPDATABLE for the statement.

        The change is necessary due to implementation of JIRA-231.
        The new features introduced in DERBY-695, DERBY-231, and DERBY-775 should be documented in the Derby reference manual.

        This includes:
        * updatable cursors do longer need to "FOR UPDATE" clause
        * Scrollable insensitive resultsets can be updatable
        Andreas Korneliussen created issue -

          People

          • Assignee:
            Andreas Korneliussen
            Reporter:
            Andreas Korneliussen
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development