You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-dev@db.apache.org by "Andreas Korneliussen (JIRA)" <de...@db.apache.org> on 2005/11/18 15:34:41 UTC
[jira] Created: (DERBY-717) update doc on updatable cursors
update doc on updatable cursors
-------------------------------
Key: DERBY-717
URL: http://issues.apache.org/jira/browse/DERBY-717
Project: Derby
Type: Improvement
Components: Documentation
Versions: 10.2.0.0
Reporter: Andreas Korneliussen
Assigned to: Andreas Korneliussen
Priority: Minor
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.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Updated: (DERBY-717) update doc on updatable cursors
Posted by "Andreas Korneliussen (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-717?page=all ]
Andreas Korneliussen updated DERBY-717:
---------------------------------------
Attachment: DERBY-717v3.diff
DERBY-717v3.stat
derby-717v3.tar.gz
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.
> update doc on updatable cursors
> -------------------------------
>
> Key: DERBY-717
> URL: http://issues.apache.org/jira/browse/DERBY-717
> Project: Derby
> Type: Improvement
> Components: Documentation
> Versions: 10.2.0.0
> Reporter: Andreas Korneliussen
> Assignee: Andreas Korneliussen
> Priority: Minor
> Attachments: DERBY-717.diff, DERBY-717.stat, DERBY-717v2.diff, DERBY-717v3.diff, DERBY-717v3.stat, derby-717.tar.gz, derby-717v3.tar.gz
>
> 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()
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Updated: (DERBY-717) update doc on updatable cursors
Posted by "Andreas Korneliussen (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-717?page=all ]
Andreas Korneliussen updated DERBY-717:
---------------------------------------
Attachment: DERBY-717.diff
DERBY-717.stat
derby-717.tar.gz
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.
> update doc on updatable cursors
> -------------------------------
>
> Key: DERBY-717
> URL: http://issues.apache.org/jira/browse/DERBY-717
> Project: Derby
> Type: Improvement
> Components: Documentation
> Versions: 10.2.0.0
> Reporter: Andreas Korneliussen
> Assignee: Andreas Korneliussen
> Priority: Minor
> Attachments: DERBY-717.diff, DERBY-717.stat, derby-717.tar.gz
>
> 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()
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Updated: (DERBY-717) update doc on updatable cursors
Posted by "Andreas Korneliussen (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-717?page=all ]
Andreas Korneliussen updated DERBY-717:
---------------------------------------
Attachment: DERBY-717v2.diff
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.
> update doc on updatable cursors
> -------------------------------
>
> Key: DERBY-717
> URL: http://issues.apache.org/jira/browse/DERBY-717
> Project: Derby
> Type: Improvement
> Components: Documentation
> Versions: 10.2.0.0
> Reporter: Andreas Korneliussen
> Assignee: Andreas Korneliussen
> Priority: Minor
> Attachments: DERBY-717.diff, DERBY-717.stat, DERBY-717v2.diff, derby-717.tar.gz
>
> 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()
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Updated: (DERBY-717) update doc on updatable cursors
Posted by "Andreas Korneliussen (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-717?page=all ]
Andreas Korneliussen updated DERBY-717:
---------------------------------------
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()
was:
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
> update doc on updatable cursors
> -------------------------------
>
> Key: DERBY-717
> URL: http://issues.apache.org/jira/browse/DERBY-717
> Project: Derby
> Type: Improvement
> Components: Documentation
> Versions: 10.2.0.0
> Reporter: Andreas Korneliussen
> Assignee: Andreas Korneliussen
> Priority: Minor
>
> 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()
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Closed: (DERBY-717) update doc on updatable cursors
Posted by "Andreas Korneliussen (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-717?page=all ]
Andreas Korneliussen closed DERBY-717:
--------------------------------------
> update doc on updatable cursors
> -------------------------------
>
> Key: DERBY-717
> URL: http://issues.apache.org/jira/browse/DERBY-717
> Project: Derby
> Type: Improvement
> Components: Documentation
> Versions: 10.2.0.0
> Reporter: Andreas Korneliussen
> Assignee: Andreas Korneliussen
> Fix For: 10.2.0.0
> Attachments: DERBY-717.diff, DERBY-717.stat, DERBY-717v2.diff, DERBY-717v3.diff, DERBY-717v3.stat, DERBY-717v4.diff, DERBY-717v4.stat, derby-717.tar.gz, derby-717v3.tar.gz, derby-717v4.tar.gz
>
> 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()
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Updated: (DERBY-717) update doc on updatable cursors
Posted by "Andreas Korneliussen (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-717?page=all ]
Andreas Korneliussen updated DERBY-717:
---------------------------------------
Derby Info: [Patch Available]
> update doc on updatable cursors
> -------------------------------
>
> Key: DERBY-717
> URL: http://issues.apache.org/jira/browse/DERBY-717
> Project: Derby
> Type: Improvement
> Components: Documentation
> Versions: 10.2.0.0
> Reporter: Andreas Korneliussen
> Assignee: Andreas Korneliussen
> Priority: Minor
> Attachments: DERBY-717.diff, DERBY-717.stat, derby-717.tar.gz
>
> 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()
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-717) update doc on updatable cursors
Posted by "Øystein Grøvlen (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-717?page=comments#action_12412758 ]
Øystein Grøvlen commented on DERBY-717:
---------------------------------------
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."
> update doc on updatable cursors
> -------------------------------
>
> Key: DERBY-717
> URL: http://issues.apache.org/jira/browse/DERBY-717
> Project: Derby
> Type: Improvement
> Components: Documentation
> Versions: 10.2.0.0
> Reporter: Andreas Korneliussen
> Assignee: Andreas Korneliussen
> Priority: Minor
> Attachments: DERBY-717.diff, DERBY-717.stat, DERBY-717v2.diff, DERBY-717v3.diff, DERBY-717v3.stat, derby-717.tar.gz, derby-717v3.tar.gz
>
> 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()
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Updated: (DERBY-717) update doc on updatable cursors
Posted by "Andreas Korneliussen (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-717?page=all ]
Andreas Korneliussen updated DERBY-717:
---------------------------------------
Attachment: DERBY-717v4.diff
DERBY-717v4.stat
derby-717v4.tar.gz
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.
> update doc on updatable cursors
> -------------------------------
>
> Key: DERBY-717
> URL: http://issues.apache.org/jira/browse/DERBY-717
> Project: Derby
> Type: Improvement
> Components: Documentation
> Versions: 10.2.0.0
> Reporter: Andreas Korneliussen
> Assignee: Andreas Korneliussen
> Priority: Minor
> Attachments: DERBY-717.diff, DERBY-717.stat, DERBY-717v2.diff, DERBY-717v3.diff, DERBY-717v3.stat, DERBY-717v4.diff, DERBY-717v4.stat, derby-717.tar.gz, derby-717v3.tar.gz, derby-717v4.tar.gz
>
> 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()
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Updated: (DERBY-717) update doc on updatable cursors
Posted by "Andreas Korneliussen (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-717?page=all ]
Andreas Korneliussen updated DERBY-717:
---------------------------------------
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
was:
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
> update doc on updatable cursors
> -------------------------------
>
> Key: DERBY-717
> URL: http://issues.apache.org/jira/browse/DERBY-717
> Project: Derby
> Type: Improvement
> Components: Documentation
> Versions: 10.2.0.0
> Reporter: Andreas Korneliussen
> Assignee: Andreas Korneliussen
> Priority: Minor
>
> 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
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-717) update doc on updatable cursors
Posted by "Andreas Korneliussen (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-717?page=comments#action_12414242 ]
Andreas Korneliussen commented on DERBY-717:
--------------------------------------------
Ø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.
> update doc on updatable cursors
> -------------------------------
>
> Key: DERBY-717
> URL: http://issues.apache.org/jira/browse/DERBY-717
> Project: Derby
> Type: Improvement
> Components: Documentation
> Versions: 10.2.0.0
> Reporter: Andreas Korneliussen
> Assignee: Andreas Korneliussen
> Priority: Minor
> Attachments: DERBY-717.diff, DERBY-717.stat, DERBY-717v2.diff, DERBY-717v3.diff, DERBY-717v3.stat, DERBY-717v4.diff, DERBY-717v4.stat, derby-717.tar.gz, derby-717v3.tar.gz, derby-717v4.tar.gz
>
> 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()
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Updated: (DERBY-717) update doc on updatable cursors
Posted by "Andreas Korneliussen (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-717?page=all ]
Andreas Korneliussen updated DERBY-717:
---------------------------------------
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
was:
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
> update doc on updatable cursors
> -------------------------------
>
> Key: DERBY-717
> URL: http://issues.apache.org/jira/browse/DERBY-717
> Project: Derby
> Type: Improvement
> Components: Documentation
> Versions: 10.2.0.0
> Reporter: Andreas Korneliussen
> Assignee: Andreas Korneliussen
> Priority: Minor
>
> 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
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Resolved: (DERBY-717) update doc on updatable cursors
Posted by "Andreas Korneliussen (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-717?page=all ]
Andreas Korneliussen resolved DERBY-717:
----------------------------------------
Fix Version: 10.2.0.0
Resolution: Fixed
Derby Info: (was: [Patch Available])
Committed revision 413877.
> update doc on updatable cursors
> -------------------------------
>
> Key: DERBY-717
> URL: http://issues.apache.org/jira/browse/DERBY-717
> Project: Derby
> Type: Improvement
> Components: Documentation
> Versions: 10.2.0.0
> Reporter: Andreas Korneliussen
> Assignee: Andreas Korneliussen
> Fix For: 10.2.0.0
> Attachments: DERBY-717.diff, DERBY-717.stat, DERBY-717v2.diff, DERBY-717v3.diff, DERBY-717v3.stat, DERBY-717v4.diff, DERBY-717v4.stat, derby-717.tar.gz, derby-717v3.tar.gz, derby-717v4.tar.gz
>
> 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()
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Updated: (DERBY-717) update doc on updatable cursors
Posted by "Andreas Korneliussen (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-717?page=all ]
Andreas Korneliussen updated DERBY-717:
---------------------------------------
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()
was:
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()
Priority: Major (was: Minor)
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).
> update doc on updatable cursors
> -------------------------------
>
> Key: DERBY-717
> URL: http://issues.apache.org/jira/browse/DERBY-717
> Project: Derby
> Type: Improvement
> Components: Documentation
> Versions: 10.2.0.0
> Reporter: Andreas Korneliussen
> Assignee: Andreas Korneliussen
> Attachments: DERBY-717.diff, DERBY-717.stat, DERBY-717v2.diff, DERBY-717v3.diff, DERBY-717v3.stat, DERBY-717v4.diff, DERBY-717v4.stat, derby-717.tar.gz, derby-717v3.tar.gz, derby-717v4.tar.gz
>
> 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()
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
Re: [jira] Commented: (DERBY-717) update doc on updatable cursors
Posted by Andreas Korneliussen <An...@Sun.COM>.
>> 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.
>
Ok.
..
>>> 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 thinking about it, I think "scrollable resultset" is much better
language than "scrolling resultset". Scrollable covers both resultsets
of type "ResultSet.TYPE_SCROLL_INSENSITIVE and
ResultSet.TYPE_SCROLL_SENSITIVE". In JDBC tutorials, I found that they
used the terms scrollable this way, and sometimes referred to resultsets
of type ResultSet.TYPE_FORWARD_ONLY as non-scrollable.
I will modify the current language in the docs which I touch (and maybe
the other docs as well) to make this consistent.
>>> - "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?
>
Thanks, I think I can use fetched instead.
>>> 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.
>
Yes.
Andreas
Re: [jira] Commented: (DERBY-717) update doc on updatable cursors
Posted by Øystein Grøvlen <Oy...@Sun.COM>.
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
[jira] Commented: (DERBY-717) update doc on updatable cursors
Posted by "Andreas Korneliussen (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-717?page=comments#action_12413092 ]
Andreas Korneliussen commented on DERBY-717:
--------------------------------------------
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.
> update doc on updatable cursors
> -------------------------------
>
> Key: DERBY-717
> URL: http://issues.apache.org/jira/browse/DERBY-717
> Project: Derby
> Type: Improvement
> Components: Documentation
> Versions: 10.2.0.0
> Reporter: Andreas Korneliussen
> Assignee: Andreas Korneliussen
> Priority: Minor
> Attachments: DERBY-717.diff, DERBY-717.stat, DERBY-717v2.diff, DERBY-717v3.diff, DERBY-717v3.stat, derby-717.tar.gz, derby-717v3.tar.gz
>
> 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()
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Updated: (DERBY-717) update doc on updatable cursors
Posted by "Andreas Korneliussen (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-717?page=all ]
Andreas Korneliussen updated DERBY-717:
---------------------------------------
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
was:
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.
> update doc on updatable cursors
> -------------------------------
>
> Key: DERBY-717
> URL: http://issues.apache.org/jira/browse/DERBY-717
> Project: Derby
> Type: Improvement
> Components: Documentation
> Versions: 10.2.0.0
> Reporter: Andreas Korneliussen
> Assignee: Andreas Korneliussen
> Priority: Minor
>
> 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
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Commented: (DERBY-717) update doc on updatable cursors
Posted by "Andreas Korneliussen (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-717?page=comments#action_12413095 ]
Andreas Korneliussen commented on DERBY-717:
--------------------------------------------
> 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.
> update doc on updatable cursors
> -------------------------------
>
> Key: DERBY-717
> URL: http://issues.apache.org/jira/browse/DERBY-717
> Project: Derby
> Type: Improvement
> Components: Documentation
> Versions: 10.2.0.0
> Reporter: Andreas Korneliussen
> Assignee: Andreas Korneliussen
> Priority: Minor
> Attachments: DERBY-717.diff, DERBY-717.stat, DERBY-717v2.diff, DERBY-717v3.diff, DERBY-717v3.stat, derby-717.tar.gz, derby-717v3.tar.gz
>
> 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()
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira