[
https://issues.apache.org/jira/browse/DERBY-2390?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12504659
]
John H. Embretsen commented on DERBY-2390:
------------------------------------------
Laura, thanks for committing the new version of the getting started guide,
great work :)
Regarding the "Installing Derby" section and the description of the
distributions/packages:
I see now that this was added as part of DERBY-1223. It seems that the wording
in the patch for that issue is slightly different from Andrew's original
proposal - and different enough to change meaning:
Original proposal: "The bin distribution contains scripts, demonstration
programs, documentation and the optimized jars available in the lib
distribution."
Patch/committed wording: "The bin distribution contains scripts, demonstration
programs, and documentation. The optimized jar files are available in the lib
distribution. "
The so-called optimized jars (i.e. the non-debug jars, without extra line
number information) are part of both the lib and the bin distributions. The
non-optimized (debug) jars are in the lib-debug distribution only. I've tried
to make this more clear with the following wording for the bin distribution:
"The bin distribution contains scripts, demonstration programs, documentation
and the same set of jar files as the lib distribution."
Would this work for everyone?
Regarding my second issue, (Activity 3) shutting down the database, I cannot
see that it has been addressed. I see the comments in Activity 4 about not
shutting down the database from the client application, but my issue was
regarding the application using the embedded driver, with a separate section
with the title "Shut down the database" (under "The gsEmbedded program"), page
number 29-30 in the pdf.
The current manual says:
"If an application starts the Derby engine, the application should shut down
all databases before exiting. The attribute ;shutdown=true in the Derby
connection URL performs the shutdown."
Here I think it is important to include a sentence about the difference between
shutting down the engine and a single database. This is described in the
Developers guide
(http://db.apache.org/derby/docs/dev/devguide/tdevdvlp40464.html), but I think
saying something like this in the Getting started guide would be appropriate:
"If an application starts the Derby engine, the application should shut it down
before exiting. The attribute ;shutdown=true in the Derby connection URL
performs the shutdown. When shutting down the Derby engine, all booted
databases will automatically shut down. It is also possible to shut down
individual databases without shutting down the engine, by including the
database name in the connection URL."
Alternatively we could possibly cut down on the text and rather refer to the
Developers guide, but I think the sentences I added/modified above would be
useful.
Later, the manual says:
"This section verifies that the embedded driver is being used, then issues the
shutdown command and catches the shutdown exception to confirm that the
database shut down cleanly."
This is inaccurate, because the shutdown command shown in the example shuts
down the Derby engine, not the individual database (although this happens as a
side-effect). I suggest changing to:
"This section verifies that the embedded driver is being used, then issues the
shutdown command and catches the shutdown exception to confirm that the Derby
engine shut down cleanly."
After the code example, the manual says:
"> Important: The XJ015 error is the only exception thrown by Derby that
indicates that an operation succeeded. All other exceptions indicate that an
operation failed."
This is wrong, because if you shut down an individual database instead of the
engine, you will get the 08006 - "Database '<databaseName>' shutdown" error
message instead, i.e. another exception indicating that an operation succeeded.
As far as I know there are no other exceptions indicating success, so perhaps
something like this would suffice:
"> Important: The XJ015 error (successful shutdown of the Derby engine) and the
08006 error (successful shutdown of a single database) are the only exceptions
thrown by Derby that may indicate that an operation succeeded. All other
exceptions indicate that an operation failed."
I included "may indicate" because the 08006 error could also mean something
else (see http://db.apache.org/derby/docs/dev/ref/rrefexcept71493.html), so the
user would have to check the error message text to be sure (I think).
> DOCS - Merge Working with Derby and Getting Started Guide
> ---------------------------------------------------------
>
> Key: DERBY-2390
> URL: https://issues.apache.org/jira/browse/DERBY-2390
> Project: Derby
> Issue Type: Improvement
> Components: Documentation
> Reporter: Laura Stewart
> Assignee: Laura Stewart
> Fix For: 10.3.0.0
>
> Attachments: cgsintro.html, derby2390_1.diff, getstartderby.pdf,
> rgsdocs17307.html
>
>
> The activities in the Working with Derby guide should be merged into the
> Getting Started Guide.
> Review Getting Started Guide for any reference info that should be either
> "shared" with another guide
> or moved to another guide. For example, the SQL Syntax section in the Getting
> Started Guide should
> be moved to the Reference Manual.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
