db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Dag H. Wanvik (JIRA)" <j...@apache.org>
Subject [jira] Commented: (DERBY-3668) Remove JDBC 3.0-specific topics from Reference Manual and merge implementation notes as needed
Date Thu, 22 May 2008 22:57:55 GMT

    [ https://issues.apache.org/jira/browse/DERBY-3668?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12599231#action_12599231
] 

Dag H. Wanvik commented on DERBY-3668:
--------------------------------------

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
> DERBY-3568 uses SQL SAVEPOINT and RELEASE statements -- these aren't
> 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 :)


> Remove JDBC 3.0-specific topics from Reference Manual and merge implementation notes
as needed
> ----------------------------------------------------------------------------------------------
>
>                 Key: DERBY-3668
>                 URL: https://issues.apache.org/jira/browse/DERBY-3668
>             Project: Derby
>          Issue Type: Sub-task
>          Components: Documentation
>    Affects Versions: 10.4.1.3
>            Reporter: Kim Haase
>            Assignee: Kim Haase
>            Priority: Minor
>         Attachments: DERBY-3668-2.diff, DERBY-3668-2.stat, DERBY-3668-2.zip, DERBY-3668.diff,
DERBY-3668.stat, DERBY-3668.zip
>
>
> The following files should be removed and their contents merged, where appropriate, with
the main files for the interfaces concerned. If implementation notes in the JDBC 3.0 topics
are identical to the javadoc (i.e. they are not really implementation notes), they can be
dropped.
> rrefjdbc32593.html ("JDBC 3.0 features"): remove.
> rrefjdbcjavasqlconnection30.html ("java.sql.Connection interface: supported JDBC 3.0
methods"): remove and merge implementation notes with rrefjdbc27734.html ("java.sql.Connection
interface") as needed. Only the last two items in the table contain implementation-specific
information.
> rrefjdbcdatabasemetadata30.html ("java.sql.DatabaseMetaData interface: supported JDBC
3.0 methods"): remove and merge implementation notes with rrefjdbc15905.html ("java.sql.DatabaseMetaData
interface") as needed. Only the last item in the table contains implementation-specific information.
> rrefjdbcparametermetadata30.html ("java.sql.ParameterMetaData interface: supported JDBC
3.0 methods"): remove. No need to create a topic for this interface in the general JDBC reference,
since there is no implementation-specific information for it.
> rrefjdbcjavasqlpreparedstatement30.html ("java.sql.PreparedStatement interface: supported
JDBC 3.0 methods"): remove. No implementation-specific information to merge.
> rrefjdbcjavasqlsavepoint.html ("java.sql.Savepoint interface") and its subtopics: This
is a somewhat complicated case. There is information in here that really belongs in the Developer's
Guide, I believe. I think this topic file should be moved up to the main JDBC reference section,
but its only contents should be the two Derby-specific restrictions described in rrefjavsaverestrict.html
("Restrictions on savepoints"). The topic rrefjavsaverestrict.html should then be removed,
since the rest of its contents are not implementation-specific. The substantive contents of
rrefjdbcjavasqlsavepoint.html ("java.sql.Savepoint interface"), crefjavsavesetroll.html ("Setting
and rolling back to a savepoint"), crefjavsaverel.html ("Releasing a savepoint"), and crefjavsaverules.html
("Rules for savepoints") could be combined into one topic and added to the Developer's Guide,
probably as an additional subtopic of "Transactions" under "The JDBC Connection and Transaction
Model", if that would make sense.
> rrefjdbcjavasqlstatement30.html ("java.sql.Statement interface: supported JDBC 3.0 methods"):
remove and merge implementation notes with rrefjdbc40794.html ("java.sql.Statement interface")
as needed. The subtopic crefjavstateautogen.html ("Autogenerated keys") should be made a subtopic
of rrefjdbc40794.html ("java.sql.Statement interface"), after the "ResultSet objects" topic.

-- 
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.


Mime
View raw message