[ http://issues.apache.org/jira/browse/DERBY-1271?page=all ]
Jean T. Anderson updated DERBY-1271:
------------------------------------
Attachment: JWarn-ref-src-1.diff
JWarn-ref-review-1.zip
This adds the JDBC 4.0 warning to files in the Reference Guide:
JWarn-ref-src-1.diff - patch to DITA source
JWarn-ref-review-1.zip - changed html pages, refderby.pdf, ref-single.html
My approach was to update any file that had already been updated as part
of DERBY-1271, but only update it if the file actually references JDK 1.6 or
JDBC 4.0. Eleven files get the disclaimer. The files listed below don't get
the disclaimer because they either just link to the JDBC 4.0 summary page or
don't mention either JDK 1.6 or JDBC 4.0 (they got updated for some other
reason). Also, I also didn't update the error message pages.
src/ref/rrefcrsrgpc1.dita
src/ref/rrefjdbc40794.dita
src/ref/crefjavccns.dita
src/ref/rrefexcept16677.dita (error messages)
In the pdf and single html book, updating even these many files looks like
"over communicating" the issue, but the singleton pages don't have that
surrounding context. That's why included all three product types in that
zip file for review.
At any rate, here's how adding the warning works, and it will make it easy to
update the message itself, and to plug it in (or pull out) wherever we see fit.
The refconrefs.dita file stores the text for the warning in a "jdbc4disclaimer"
variable, which the other files reference with this syntax:
<section><p><ph
conref="refconrefs.dita#vers/jdbc4disclaimer"></ph></p></section>
Incidently, DITA processing complains about the <note> element in the variable,
but it does get processed correctly.
Everything works pretty nicely in the Reference Guide and in the Tools Guide,
which has just one topic updated, but there are formatting problems in
the Admin Guide and in Developers Guide, that fortunately gets exhibited
by one page in the Reference Guide, so I can describe it here.
The online DITA instructions at
http://db.apache.org/derby/manuals/dita.html mention the three file types:
concepts, tasks, and reference. I found it pretty easy to update the
reference pages in the Reference Guide pages because content seems to go
entirely within a <refbody> element. But I'm grappling with updating concept
files, such as src/ref/crefjdbc12657.dita, which puts content both outside
and inside a <conbody> element. If you put the disclaimer within the conbody,
the placement is after the "short description" which is declared outside the
conbody. If you put the disclaimer in a section before the conbody, it causes
weird indents to the left.
pdf page 199 of Ref Guide "JDBC Reference" shows what the problem looks like.
If any of you who know DITA could look at the source and suggest what
would produce better output, I'd be grateful and that would help me add
the notice to the Admin and Dev guides which have lots more of those "c"
type files.
I know now vastly more about DITA than I did two days ago.
> Release documentation for JDBC4 release
> ---------------------------------------
>
> Key: DERBY-1271
> URL: http://issues.apache.org/jira/browse/DERBY-1271
> Project: Derby
> Issue Type: Improvement
> Components: Documentation, JDBC
> Affects Versions: 10.2.1.0
> Reporter: Rick Hillegas
> Assigned To: Jean T. Anderson
> Fix For: 10.2.1.0
>
> Attachments: adminGuide_v01.tar, derby-1271_adminGuide_v01.diff,
> derby-1271_copyrights.diff, derby-1271_copyrights_v02.diff,
> derby-1271_devGuide_v01.diff, derby-1271_refGuide_v01.diff,
> derby-1271_refGuide_v01.tar, derby-1271_toolsGuide_v01.diff,
> derby1271-2-html.zip, derby1271-2.diff, derby1271-3-html.zip,
> derby1271-3.diff, devGuide_v01.tar, JWarn-ref-review-1.zip,
> JWarn-ref-src-1.diff, toolsGuide_v01.tar
>
>
> We can't check in any of this work until we understand how our release trains
> line up. However, the JDBC4-bearing release will need the following
> documentation:
> 1) Changes to the user guides. These need to be understood. We can analyze
> the scope of these changes without checking anything in yet.
> 2) Summary page which explains what pieces of JDBC4 we tackled and what we
> passed over.
> 3) Verbiage for the Release Notes.
> USER GUIDES
> Admin Guide
> Part One...How to start an embedded server from an application
> For JDBC4, we can omit the Class.forName() line because
> of Driver autoloading.
> Part One...Embedded server example
> For JDBC4, we can omit the Class.forName() line because
> of Driver autoloading.
> Part One...Network client driver examples
> For JDBC4, we can omit the Class.forName() line because
> of Driver autoloading.
> Part One...Accessing the Network Server by using a DataSource
> For JDBC4, we have different DataSources: ClientDateSource40
> and ClientConnectionPoolDataSource40.
> Part One...Using the Derby ij tool with the Network Server
> In case the DRIVER command ends up being needed pre-JDBC4,
> we should note that you don't need it under JDBC4 because
> of Driver autoloading.
> Part One...The NsSample sample program
> Change NsSample to demonstrate driver autoloading under JDBC4.
> Part One...Overview of the SimpleNetworkServerSample program
> Change SimpleNetworkServerSample to demonstrate driver autoloading under
> JDBC4.
> Part One...Connecting a client to the Network Server with the
> SimpleNetworkClientSample program
> Change SimpleNetworkClientSample to demonstrate driver autoloading under
> JDBC4.
> Developer's Guide
> JDBC applications and Derby basics
> Derby embedded basics
> Derby JDBC driver
> Note that you don't need Class.forName() in JDBC4.
> Derby embedded basics
> Embedded Derby JDBC driver
> Note that you don't need Class.forName() in JDBC4.
> Starting Derby as an embedded database
> Note that you don't need Class.forName() or the jdbc.drivers property
> in JDBC4.
> Controlling Derby application behavior
> Working with Derby SQLExceptions in an application
> Note that with JDBC4, these are refined subclasses
> Example of processing SQLExceptions
> Say something about SQLException.getCause()
> Using Derby as a J2EE resource manager
> Classes that pertain to resource managers
> Mention the JDBC4 variants of these classes.
> Getting a DataSource
> Include example using JDBC4 variants of these classes.
> Shutting down or creating a database
> Include example using JDBC4 variants of these classes.
> Getting Started Guide
> No changes necessary.
> Reference Guide
> Derby exception messages and SQL states
> Describe SQLFeatureNotSupportedException and its SQLStates.
> SQLState and error message reference
> Mention new unimplementedFeature exceptions.
> What to do about new SQLStates.
> JDBC Reference
> "conforms to the JDBC 2.0 and 3.0 APIs"
> ->
> "conforms to the JDBC 2.0, 3.0, and 4.0 APIs"
> java.sql.Driver
> Amend this to note driver autoloading for JDBC4.
> java.sql.Connection
> Connection functionality not supported
> List unsupported Connection methods.
> java.sql.DatabaseMetaData
> Columns in the ResultSet returned by getProcedureColumns
> Add new columns added by JDBC4
> java.sql.Statement
> Note that Derby does not support the execute() and
> executeQuery() overloads which return autogenerated keys.
> Prepared statements and streaming columns
> Note that with JDBC4, you can specify length as a long
> or even omit the length when setting LOB streams.
> java.sql.ResultSetMetaData
> Waiting for feedback from Dag on whether we still don't
> support isDefinitelyWritable(), isReadOnly(), and
> isWritable().
> java.sql.Blob and java.sql.Clob
> Right now this section says that Derby supports the methods in
> the Blob and Clob interfaces. This is not true. We should
> describe the discrepancies, including any additional methods added
> by JDBC4.
> JDBC 4.0-only features
> Add this new section, with a subsection for each SQL interface
> that changed in JDBC4. The subsections should list new methods
> that were added.
> Derby API
> JDBC implementation classes
> Data Source Classes
> List the JDBC4 versions of these classes
> Tools Guide
> Using ij
> Getting started with ij
> Running ij scripts
> You don't need to specify the Derby drivers
> on the command line even under JDBC2.
> ij properties reference
> ij.dataSource
> This is the DataSource for embedded JDBC3. Note that
> this would be different if you are running under
> JDBC4.
> Tuning Guide
> No changes necessary.
> Working With Derby Guide
> Activity 3: Run a JDBC program using the Embedded driver
> The WwdEmbedded program
> Start the Derby engine
> Note that this step (Class.forName() on the embedded driver)
> is not necessary if you are running on jdk 1.6 or higher.
--
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
