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
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
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?