[ http://issues.apache.org/jira/browse/DERBY-373?page=all ]
Jeff Levitt updated DERBY-373:
------------------------------
Attachment: derby373modified.diff
Attached patch takes Army's feedback in:
http://mail-archives.apache.org/mod_mbox/db-derby-dev/200506.mbox/[EMAIL
PROTECTED]
into account. Please once again view the output at:
http://derby.mylevita.com/adminguide/
http://derby.mylevita.com/adminguide/derbyadmin.pdf
> 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: 10.1.1.0
> Reporter: A B
> Fix For: 10.1.1.0
> Attachments: derby373modified.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:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
