You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-dev@db.apache.org by "A B (JIRA)" <de...@db.apache.org> on 2005/06/19 08:51:17 UTC
[jira] Created: (DERBY-373) Documentation errors in "Server/Admin" Guide.
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
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
Re: [jira] Updated: (DERBY-373) Documentation errors in "Server/Admin"
Guide.
Posted by Army <qo...@sbcglobal.net>.
Jeff Levitt (JIRA) wrote:
> [ 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.
Hi Jeff,
Thanks for looking at this so quickly. A couple of minor changes are still
needed (most of which are my fault because I told you the wrong thing...*sorry*)
1 -- Top of p. 11: "Starting the Network Server"
Capitalization of ALWAYS in the new "NOTE" probably isn't necessary, although
that's how I wrote it in my original comments (oops). Also, it might be better
to make this slightly more general since we don't really know what all of the
effects of not shutting down the server might be (we just know that port block
is for sure one of them). For example, something like:
Note that you should always properly shut down the
Network Server after use, because failure to do so
may result in unpredictable side effects, such as
blocked ports on the server.
2 -- Top of p. 12: "Starting the Network Server from a Java application"
Same comment as #1 above.
3 -- pp. 31-32: "Verifying Startup"
Ooops, I told you the wrong thing here. In my earlier comments I said that the
the last line of the isServerStarted() method should return TRUE, not FALSE--but
that was a mistake. The code was right in its original form--i.e. the last line
should be returning FALSE, not TRUE. Sorry for the confusion there.
4 -- p. 37: "Turning on the trace facility"
I asked you to add the line starting with "Note that if the derby.drda.traceAll
property...", but after discussing with Kathey Marsden about this behavior, I've
decided that this line should be removed and I should instead file this as a
code bug (if anyone wants a transcript from the chat I had with Kathey, I can
send it).
Also, there should be a "-s" in front of connection number for turning trace off:
java org.apache.derby.drda.NetworkServerControl trace off [-s <connection
number>] [-h <hostname>] [-p <portnumber>]
5 -- p. 46: "Using the backup procedure"
That "workaround" text is still on this page, and I still don't know what it
means. I think it can be removed?
6 -- p. 47: "Creating a database from a backup copy"
In the example, the period between "derby" and "sample" was changed to a
semi-colon, but it was supposed to be changed to a COLON:
jdbc:derby:sample;createFrom=c:\mybackups\sample
I think that's it; thanks for your patience, and sorry again for my
incorrect/incomplete comments the first time around...
Army
[jira] Updated: (DERBY-373) Documentation errors in "Server/Admin" Guide.
Posted by "Jeff Levitt (JIRA)" <de...@db.apache.org>.
[ 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: 10.1.1.0
> Reporter: A B
> Fix For: 10.1.1.0
> 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:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
[jira] Closed: (DERBY-373) Documentation errors in "Server/Admin" Guide.
Posted by "Jean T. Anderson (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-373?page=all ]
Jean T. Anderson closed DERBY-373:
----------------------------------
Resolution: Fixed
Committed, revision 191746, Jeff Levitt's patch that fixes documentation errors in the Server/Admin Guide. Modified files:
$ svn status
M src/adminguide/radminconfigportnumber.dita
M src/adminguide/radmindrdaminthreads.dita
M src/adminguide/radmindrdamaxthreads.dita
M src/adminguide/radminconfigdb2jdrdalogconnections.dita
M src/adminguide/radmindrdahost.dita
M src/adminguide/radminservlet810850.dita
M src/adminguide/tadminhubbkup44.dita
M src/adminguide/cadminappsxawthdriver.dita
M src/adminguide/tadmincbdjhhfd.dita
M src/adminguide/cadminhubbkup75469.dita
M src/adminguide/radminconfigdb2jdrdatracedirectory.dita
M src/adminguide/tadminadv804451.dita
M src/adminguide/radminconfigstartnetworkserver.dita
M src/adminguide/tadminapps811345.dita
M src/adminguide/tadminconfigverifyingstartup.dita
M src/adminguide/derbyadmin.ditamap
M src/adminguide/tadminconfig814963.dita
M src/adminguide/tadminadv804410.dita
M src/adminguide/radminconfig.dita
M src/adminguide/radmindrdatimeslice.dita
M src/adminguide/cadminhubbkup01.dita
M src/adminguide/tadminconfigsettingnetwrokserverproperties.dita
M src/adminguide/cadminapps.dita
M src/adminguide/radminappsclientxmp.dita
M src/adminguide/cadminappsclienttracing.dita
M src/adminguide/tadminapps811695.dita
M src/adminguide/tadminconfig813694.dita
M src/adminguide/cadminapps810777.dita
M src/adminguide/tadmincrtdbbkup.dita
M src/adminguide/cadminappsclient.dita
> 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
Re: [jira] Updated: (DERBY-373) Documentation errors in "Server/Admin"
Guide.
Posted by Army <qo...@sbcglobal.net>.
Jeff Levitt (JIRA) wrote:
> [ 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:
Looks like all of the issues mentioned in the description for this bug have been
handled now, so I give this a +1 to be committed...
Army
[jira] Updated: (DERBY-373) Documentation errors in "Server/Admin" Guide.
Posted by "Jeff Levitt (JIRA)" <de...@db.apache.org>.
[ 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/%3c42B88193.6040509@sbcglobal.net%3e
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