db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "John H. Embretsen (JIRA)" <j...@apache.org>
Subject [jira] Commented: (DERBY-2390) DOCS - Merge Working with Derby and Getting Started Guide
Date Thu, 14 Jun 2007 11:08:26 GMT

    [ 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.


Mime
View raw message