db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Jeff Levitt (JIRA)" <derby-...@db.apache.org>
Subject [jira] Updated: (DERBY-373) Documentation errors in "Server/Admin" Guide.
Date Tue, 21 Jun 2005 00:25:18 GMT
     [ http://issues.apache.org/jira/browse/DERBY-373?page=all ]

Jeff Levitt updated DERBY-373:

    Attachment: derby373.diff

Attached is a patch for this issue.  Since this patch affected so many files, I decided to
just create sample output on my own site for review.  Navigate to:

HTML files:  http://derby.mylevita.com/adminguide/
PDF file: http://derby.mylevita.com/adminguide/derbyadmin.pdf

Here are my notes on the changes, numbered according to the numbering used in this JIRA issue:

1.  Added lines to the Starting the Network Server pages that warn users to shut down the
Network server, and moved the shutting down the network server topics to directly after the
starting up pages.
2.  Fixed, and false reminder is removed.
3. Fixed as requested
4. Fixed as requested
5.  Changed domain to samplehost.sampledomain.com (let me know if thats hanging too!)
6.  Added that the two jar files are needed in the classpath to use the driver.
7.  Fixed as requested
8.  Fixed as requested
9.  Fixes as requested
10. fixed as requested
11. Fixed as requested
12. Fixed as requested
13. Fixed as requested
14. Fixed as requested; page removed
15. Fixed as requested
16.  Fixed as requested
17. Fixed as requested
18. Fixed as requested

> Documentation errors in "Server/Admin" Guide.
> ---------------------------------------------
>          Key: DERBY-373
>          URL: http://issues.apache.org/jira/browse/DERBY-373
>      Project: Derby
>         Type: Bug
>   Components: Documentation
>     Versions:
>     Reporter: A B
>      Fix For:
>  Attachments: derby373.diff
> I took some time to read through the Derby server/admin manual and to try out the various
examples/scenarios that are described there.  In doing so, I discovered several documentation
errors as well as two bugs within the server/client code.  Below are the documentation errors
I found, several of which (esp. 3 and 4) are rather signficant.  I'll be filing separate JIRA
entries for the two server/client bugs that I found.
> All page/section references are w.r.t to the PDF form of the manual, as downloaded from
the Derby website "Manuals" tab.  The page numbers I use correspond to the page numbers used
in the manual--i.e. they do not count the two cover pages of that manual (so page 5 means
the page labelled "5", not the fifth page in the overall document).
> 1) pp. 10-11: "Starting the Network Server"
> I think there should be a "NOTE" immediately following this header that warns a user
to ALWAYS PROPERLY SHUTDOWN the server after starting it, especially when starting it from
within a Java application.  Otherwise, if the user is like me and just following the examples,
s/he might write code to start the server in some program (like in the examples) but not include
code to shut it down.  Doing this can lead to situations where, upon completion of the program,
the port on which the server started becomes "blocked" and only a reboot of the machine can
"free" it up again.  I know because port 1527 on my machine was blocked for 2 days (I didn't
want to reboot my machine ;)
> Which brings up another issue: the section describing _how_ to shutdown the server doesn't
appear until page 30!! Either that section should be moved up to an earlier place in the manual,
or at the very least a link to that section should be included after the "NOTE" that I suggested
above (i.e. right at the beginning of the section on how to start the server).
> Even better: combine the starting and shutdown sections into a single section and include
BOTH pieces in all of the example code.  Then any users who are copying/referencing the example
code (like I did) will have the proper shutdown code, too.
> 2) p. 12: "Starting the Network Server from a Java application"
> The example for #2 shows the creation of a NetworkServerControl object using a constructor
that takes a single "null" value:
> NetworkServerControl server = new NetworkServerControl(null);
> This isn't correct--no such constructor exists.  Instead, the constructor should take
NO arguments:
> NetworkServerControl server = new NetworkServerControl();
> A similar example is correct on page 13, but this particular example on page 12 is wrong.
> Also, this section says "Remember: The NetworkServerControl.start method does not return
until the server is shut down", and yet it seems to be returning just fine in my test program.
 Am I missing something or is this documentation incorrect/misleading?
> 3) p. 14: "Accessing the Network Server by using the Network Client driver"
> The first paragraph under this heading states that user/password need to be specified
to connect to the server--but that's only true for JCC.  The Derby client only requires user/password
IF authentication is being used (so the paragraph should be changed to say that).
> Also, the syntax for the URL is wrong.  The colon is no longer valid in the client URL
(that's only for JCC), and embedded/client attributes can be interspersed.  The new syntax
should be something like:
> jdbc:derby://<server>[:port]/<databaseName>[;<URL attribute>=<value>[;
... ]]
> where "URL attribute" can be any of the attributes for Derby embedded or for the Derby
Client (which are shown in the tables on the subsequent pages).
> Finally, the paragraph starting with "The syntax for connection to the Network Server
differs..." can be removed from this section entirely, as it doesn't apply to the Derby Client
(only to JCC).
> 4) p. 18: "Network Client driver examples"
> The URLs used in Examples 1, 2, and 3 are wrong. They all specify a colon before the
user/password, which is not valid syntax for the Network Client (per #3 above).
> As further motivation to correct this, attempts to use the URLs as they are currently
shown in the documentation (i.e. with a colon before the user/password) will cause a protocol
exception at connection time.  This is a bug against the server/client, and I will file a
separate JIRA entry for it.  But in the meantime, the examples should be changed to replace
the colon with a semicolon.
> As for example 3, the documentation states that when the target database is specified
using a full path, double quotes are needed and "you cannot specify Derby attributes on the
URL."  But that's only true for JCC--for the Derby Client, double quotes are no longer required
and Derby attributes ARE allowed, so that statement should be removed.  Further, the double
quotes should be removed from example 3--not only are they not required, but their presence
causes a protocol exception at connection time (that's another JIRA issue that I'm going to
have to file--but in the meantime, it'd be good to change the documentation ;).
> 5) p. 17: "Changing default trace level"
> The example URL uses the domain "myhost.mydomain.com:1528", but that domain actually
exists and apparently there's something listening on that port.  The result is that attempts
to connect to that particular host will cause a hang in the client.  This isn't really a bug
with the client (client can't control who's listening on the port it uses), but the documentation
should be changed to use a different hostname so that users who blindly copy/paste the examples
(like me ;) don't end up getting a hang.
> 6) pp. 18-20: "Accessing the Network Server by using the DB2 Universal Driver"
> All of these examples for using JCC are given, but the documentation doesn't say what
jars the user needs in his/her classpath in order to use JCC.  Granted, most users are probably
more likely to use the Derby Network Client over the JCC client, but nonetheless, if we're
going to bother documenting how to connect to the server with JCC, we should mention what
the user has to have in his/her classpath in order to do so.
> 7) p. 21: "XA and the Network Server"
> The example code for using XA needs to be cleaned up; it doesn't compile as it currently
is written.  In particular:
> -- The code should either include the proper imports or else use the full names of the
following two classes, in order to be consistent with the other examples in the doc:
> 	org.apache.derby.jdbc.ClientXADataSource
> 	javax.sql.XAConnection
> -- The "dbname" variable isn't defined; it should be replaced with some example database
name, such as "sample".
> -- The left side of the final assignment statement should be "conn", not "connection".
> -- Indentation should be cleaned up.
> 8) p. 22: "Using the Derby dblook tool with the Network Server"
> The example of how to use dblook needs a space after the "-d" (before the opening single
quote).  Also, in all the other examples we specify some dummy user/password; for consistency
sake, seems like we should specify them for this command, too (esp. since we're already giving
an example database name).
> This example also uses a colon in the connection URL before the user/password, which
is not valid syntax (per #3 above).  The colon should be replaced with a semicolon.
> 9) p. 22: "Differences between running Derby in embedded mode and using the network server"
> This header should capitalize Network Server in order to be consistent with the rest
of the document.
> 10) p. 24: "Encrypted user id and password"
> The second paragraph of #3 in this section says to "use the dbshutdown option to shut
down the database".  I think "dbshutdown" should be replaced with "shutdown=true", since I
don't think there is such a thing as "dbshutdown" in Derby (at least, not that I know of).
> 11) p. 25: "Using the NeworkServerControl API"
> The examples of how to use NetworkServerControl() have "new" mistyped as "nwe", and are
missing the semicolon at the end of the line.
> 12) pp. 26-27: "Setting Network Server properties"
> There are several minor inconsistencies in the way the different properties are presented.
 For example, some of the properties define what it means to be "static" or "dynamic", others
do not; some have the syntax for the property enclosed in braces ("<" and ">"), others
do not; some have an extra end-of-line character in them (at least, in the PDF form) while
others do not.
> 13) p. 30: "Verifying Startup"
> The example for pinging the server from the command line has an extra brace ("<")
at the beginning.
> Also, the example method "isServerStarted" should be returning "true" as the last line,
not "false".
> 14) p. 32: "Test Connection"
> This "Test Connection" section talks about a page that doesn't exist in the servlet.
 This section should be removed entirely.
> 15) p. 36: "Controlling tracing by using the trace facility"
> Syntax for the command to turn tracing on is incorrect:
> 	[<connection number>]
> should be
> 	[-s <connection number>]
> Also, this section makes it look you have to do steps 1 AND 2 in order to turn tracing
on, when in fact those are two different options.  And finally, it would be good to note here
that if the "derby.drda.traceAll" property is set, then subsquent attempts to turn tracing
off using the NetworkServerControl will NOT work (traceAll takes precedence)--unless of course
that's accidental, in which case this is a bug against the server...?
> 16) p. 45: "Using operating system commands with the freeze and unfreeze system procedures"
> -- There are a couple of references to SYSCS_FREEZE where SYSCS_UNFREEZE should be used.
> -- The example program fragments on this page use a "JCalendar" class that isn't part
of the Java API; in fact, I'm not sure where it comes from.  The examples should either use
a calendar class that's part of the Java API, or else get rid of this altogether and replace
it with something else (so that the code compiles).
> -- The example using freeze/unfreeze doesn't have "conn" declared anywhere; for the sake
of consistency with other examples, "conn" should either be declared or passed in as a param
to a sample method.  Also, the sample code is missing the closing quote and paren on the two
"executeUpdate" calls, so it won't compile.
> -- The following warning appears twice on this page, but the "workaround" that it refers
to either doesn't exist or else isn't obvious: "Note: If you are doing this through the Network
Server, refer to the workaround in 'Differences between ... '"
> 17) p. 46: "Restoring a database from a backup copy"
> The example in this section specifies the "createFrom" attribute when it should specify
the "restoreFrom".
> 18) p. 46: "Creating a database from a backup copy"
> The example in this section has a period in the URL where a colon is supposed to be (between
"derby" and "sample").

This message is automatically generated by JIRA.
If you think it was sent incorrectly contact one of the administrators:
For more information on JIRA, see:

View raw message