Details
-
Bug
-
Status: Closed
-
Major
-
Resolution: Fixed
-
10.1.1.0
-
None
Description
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 3not 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").