|
A few more changes need to be made:
crefjdbc12657.html ("JDBC reference"): change "JDBC 2.0, 3.0 and 4.0 APIs" to "JDBC 3.0 and 4.0 APIs". crefjdbc25142.html ("Core JDBC java.sql classes, interfaces, and methods"): Add the new savepoint topic. Also, remove the reference to rrefjdbc34954.html ("java.sql.Driver.getPropertyInfo method"), since it is now under the java.sql.Driver topic, and this list includes only the top-level topics. This topic seems completely redundant unless you are looking at the HTML single or PDF version, in which the parent topic doesn't automatically list all the subtopics. The ordering is not the same as in the TOC, but it is in some ways better than the TOC order, so I'll save any changes in the order for the next step in the Attaching
I have one additional question: In http://db.apache.org/derby/docs/dev/devguide/cdevconcepts29416.html ("Using auto-commit"), should a table entry be added for savepoints? I would guess they are akin to updatable cursors -- that is, they don't work when auto-commit is on. Is that true? Many thanks to anyone who can review these. Re the devguide's "Using savepoints" and nested savepoints:
I am not sure of the status here, but see Kathey's comment on client driver does not support this? > A savepoint can be reused after it has been released explicitly (by issuing a release of the savepoint) or implicitly (by issuing a connection commit/rollback). Or , possibly, if a savepoint has been made invalid due to rolling back to a savepoint declared earlier than that savepoint? (I didnt test it....) Re "Derby and standards":
> Derby adheres to SQL99 standards wherever possible. This section describes those features currently in Derby that are not standard; these features are currently being evaluated and might be removed in future releases. This is a bit misleading in that SQL2003 is also used as a guide. Perhaps it would be better to say: Derby adheres to SQL99 or newer SQL standards wherever possible. > Unique constraints and nulls This paragraph is now out of date, cf. the new feature: UNIQUE constraint on nullable columns ( > should a table entry be added for savepoints? I would guess they are akin to updatable cursors -- that is, they don't work when auto-commit is on. Is that true?
+1 But the statement that updatable cursors don't work under autocommit isnt quite right. If holdable cursors are used, forward only cursors just need a repositioning to work again; scrollable insensitive result sets/cursors dont even need that.. Thanks very much, Dag, for these comments. I hope I'm addressing them all right with these new files:
About nested savepoints: I added a sentence to "Using savepoints" to say that nested savepoints are permitted, but only in an embedded environment. Will that be enough? About the following: > A savepoint can be reused after it has been released explicitly (by issuing a release of the savepoint) or implicitly (by issuing a connection commit/rollback). Or, possibly, if a savepoint has been made invalid due to rolling back to a savepoint declared earlier than that savepoint? (I didnt test it....) I think that "implicitly" may cover this situation. However, maybe it is clearer if the sentence says "implicitly (by issuing a connection commit/rollback to that savepoint or to a savepoint declared earlier than that savepoint)." About the "Derby and standards" topic: these corrections are off the JDBC 3.0 topic and in theory ought to have a separate JIRA -- but it is simpler just to make the corrections now, so I'm doing that. I added "or newer" to the first sentence and removed the list item "Unique constraints and nulls". About "Using auto-commit" and its table: I'm ignorant about cursors so I need a sanity check here. You say, "But the statement that updatable cursors don't work under autocommit isnt quite right. If holdable cursors are used, forward only cursors just need a repositioning to work again; scrollable insensitive result sets/cursors dont even need that." The topic currently says, "A cursor declared to be held across commit can execute updates and issue multiple commits before closing the cursor, but the cursor must be repositioned before any statement following the commit. If this is attempted with auto-commit on, an error is generated." So I think you're saying that the last sentence here is not correct; so I've removed it. And it looks as if the previous sentence would work if I change it as follows (it's kind of long so I'm breaking it into two sentences): "A cursor declared to be held across commit can execute updates and issue multiple commits before closing the cursor. A holdable forward-only cursor must be repositioned before any statement following the commit." Would that be right? And in the table I changed "Does not work" to say "Works for holdable cursors; does not work for non-holdable cursors." I noticed that the SavepointJdbc30Test.java file mentioned in Thanks for your work on this Kim! The HTML pages look good.
In table 1 in devguide/cdevconcepts29416.html, for entry "Updatable ResultSets" and "Auto-commit off", I see: "Works. Not required by the JDBC program." The last sentence seems pointless. It is probably intended for the entry "Updatable cursors" and "Auto-commit off". Since JDBC has updatable ResultSets, explicit cursors are not really needed. As for your comments: > About nested savepoints: I added a sentence to "Using savepoints" to > say that nested savepoints are permitted, but only in an embedded > environment. Will that be enough? I guess so. I filed a new JIRA, DERBY-3687 for improving this for the client. > About the following: > > > A savepoint can be reused after it has been released explicitly (by > issuing a release of the savepoint) or implicitly (by issuing a > connection commit/rollback). > > Or, possibly, if a savepoint has been made invalid due to rolling back > to a savepoint declared earlier than that savepoint? (I didnt test > it....) > > I think that "implicitly" may cover this situation. However, maybe it > is clearer if the sentence says "implicitly (by issuing a connection > commit/rollback to that savepoint or to a savepoint declared earlier > than that savepoint)." Seems good to me. > About "Using auto-commit" and its table: I'm ignorant about cursors so > I need a sanity check here. You say, "But the statement that updatable > cursors don't work under autocommit isnt quite right. If holdable > cursors are used, forward only cursors just need a repositioning to > work again; scrollable insensitive result sets/cursors dont even need > that." > > The topic currently says, "A cursor declared to be held across commit > can execute updates and issue multiple commits before closing the > cursor, but the cursor must be repositioned before any statement > following the commit. If this is attempted with auto-commit on, an > error is generated." > > So I think you're saying that the last sentence here is not correct; > so I've removed it. And it looks as if the previous sentence would > work if I change it as follows (it's kind of long so I'm breaking it > into two sentences): > "A cursor declared to be held across commit can Yes, but I would say "An updatable cursor..." just to be precise. > execute updates and issue multiple commits before closing the > cursor. A holdable forward-only cursor must be repositioned before any > statement following the commit." Would that be right? Yes, except "any statement" is a bit vague. The only legal ones after a commit would be close and next, since the cursor is not positioned. > > And in the table I changed "Does not work" to say "Works for holdable > cursors; does not work for non-holdable cursors." OK. > > > I noticed that the SavepointJdbc30Test.java file mentioned in > > documented in the Derby Reference Manual. Neither are COMMIT and > ROLLBACK, for that matter. Is that omission deliberate? There's no > JIRA for them. I don't know. It seems the client uses the SQL level savepoint syntax for its implementation. Possible it was omitted from the docs to encourage use of the JDBC constructs (instead of the SQL syntax); which allow nesting although only in the embedded driver. Does anyone know? I think we should document this syntax since it is there. If we want we can add suitable deprecatory noise :) Thanks again, Dag, for the great comments. I have done some more work on that one topic ("Using auto-commit, cdevconcepts29416.dita) and attached
"The last sentence seems pointless. It is probably intended for the entry "Updatable cursors" and "Auto-commit off". Since JDBC has updatable ResultSets, explicit cursors are not really needed." So would it make sense to move "Not required by the JDBC program" to the "Updatable cursors" row of the table? Or just to drop it entirely? It doesn't seem like very helpful information. I've dropped it -- let me know if it should be added to the other row. Thanks for the info about nested savepoints. I will keep an eye on DERBY-3687. I have changed "A cursor declared to be held across commit" to "An updatable cursor declared to be held across commit". And I have changed "A holdable forward-only cursor must be repositioned before any statement following the commit." to "A holdable forward-only cursor must be repositioned before the close or next method call that follows the commit." I hope that works? I was also confused by the references to the "close cursors on commit option", because that seemed like odd terminology for JDBC. It appears to refer to specifying ResultSet.CLOSE_CURSORS_AT_COMMIT as the third argument (resultSetHoldability) in a Connection.createStatement, Connection.prepareCall, or Connection.prepareStatement method call. I've tidied up this language a little. I also mention that ResultSet.HOLD_CURSORS_OVER_COMMIT is the default value (this is stated in the Reference Manual topic on the java.sql.DatabaseMetaData interface). I hope this is all correct. I will file a JIRA for documenting the SAVEPOINT, RELEASE, COMMIT, and ROLLBACK statements. Then perhaps we can get some discussion about whether this is a good idea. > It doesn't seem like very helpful information. I've dropped it
+1 > And I have changed > > "A holdable forward-only cursor must be repositioned before any > statement following the commit." > > to > > "A holdable forward-only cursor must be repositioned before the close > or next method call that follows the commit." Mmm, that came out a bit wrong, sorry if I was unclear. Maybe: "After an explicit or implicit commit, a holdable forward-only cursor must be repositioned with a call to next before it can accessed again. In this state, the only other legal operation besides calling next is calling close." .. or some such.... > > I hope that works? > > I was also confused by the references to the "close cursors on commit > option", because that seemed like odd terminology for JDBC. It appears > to refer to specifying ResultSet.CLOSE_CURSORS_AT_COMMIT as the third > argument (resultSetHoldability) in a Connection.createStatement, > Connection.prepareCall, or Connection.prepareStatement method > call. I've tidied up this language a little. I also mention that > ResultSet.HOLD_CURSORS_OVER_COMMIT is the default value (this is > stated in the Reference Manual topic on the java.sql.DatabaseMetaData > interface). I hope this is all correct. Yes. > I will file a JIRA for documenting the SAVEPOINT, RELEASE, COMMIT, and > ROLLBACK statements. Then perhaps we can get some discussion about > whether this is a good idea. Great! The new issue for documenting SAVEPOINT, RELEASE, COMMIT, and ROLLBACK statements is DERBY-3691.
Thanks very much, Dag, for the correction. I have made the fix you suggest (plus a few font changes to be consistent with other parts of the topic).
Feeling very ignorant about cursors, I started reading about them in other parts of the Dev Guide, and came upon a reference to JDBC 2.0 that I had previously missed, in "Scrollable result sets" (cdevconcepts22641.dita). Rather than reopen I'm attaching Lance Andersen has provided some helpful offline feedback that resulted in the following changes:
cdevconcepts22641.dita (Scrollable result sets): This sentence contained a circular definition: "Insensitive result sets, in contrast to sensitive result sets, are insensitive to changes made by others on the rows ..." I changed "are insensitive to" to "cannot see". cdevconcepts29416.dita (Using auto-commit): "Commit() or rollback() begins a transaction" is misleading -- changed "begins" to "completes". cdevstandardsxml.dita (XML data types and operators), whose first paragraph appears in cdevstandards806118.dita (Derby and standards) and is misleadingly incomplete: Changed "Derby supports the XML data type and a set of operators that work with the XML data type." to "Derby supports the XML data type and a set of operators that work with the XML data type, but does not provide JDBC support for the XML data type." I'm attaching I'll commit this latest patch in a few days if no one suggests further changes. Committed
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
 |
|
Sub-task
Closed
Minor
cdevconcepts14433.html ("Statement versus transaction runtime rollback") currently refers the reader to the Reference Manual for information on savepoints, but should now point to the new Developer's Guide topic on savepoints (which will be placed immediately after it in the Developer's Guide).
cdevstandards806118.html ("Derby and standards") refers specifically to JDBC 3.0; this is no longer necessary.
rdevconceptsholdablecursors.html ("Holdable result sets") refers specifically both to JDBC 3 and to J2SE 1.4; both of these references can be removed.