db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Øystein Grøvlen <Oystein.Grov...@Sun.COM>
Subject Re: [jira] Commented: (DERBY-717) update doc on updatable cursors
Date Thu, 25 May 2006 22:54:02 GMT
Andreas Korneliussen (JIRA) wrote:

>>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 propose that we focus on ResultSet and only mention cursors in the 
context of positioned updates/deletes.  For the definition of cursors, I 
think we can borrow that from the glossary in the JDBC tutorial.

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

Yes, I think it 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.

Good suggestion.

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

Will you fix this, or should I file a doc bug?

> 
>>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 do not have the doc in front of me, but I think this was about 
visibility of inserts.  Since the doc does not discuss what gives the 
ordering in a result set, I do not think you should into details here 
either, but just say that inserts may be visible.

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

I think some places "scrolling" is used instead of "scroll".

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

How about fetched?

>>    - "columns being changed _will_ be overwritten".  I suggest "_may_
>>      be overwritten"
> 
> 
> However they always _will_ be overwritten on successful updates. 

Depends on whether there are other concurrent operations and the 
ordering of those operations.

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

OK.  I should file bug report for this.

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

So this needs to be changed.

--
Øystein


Mime
View raw message