[ http://issues.apache.org/jira/browse/DERBY-380?page=comments#action_12314152 ]
Susan Cline commented on DERBY-380: ----------------------------------- I've reviewed the following sections in the html version of the Developer's Guide: Controlling Derby Application Behavior Using Derby as a J2EE resource manager Derby and Security Developing Tools and Using Derby with an IDE Here are my suggestions for clarifications and corrections: 1) Page: http://incubator.apache.org/derby/docs/devguide/cdevconcepts14433.html The second sentence of the third paragraph has the words IBM Derby Reference Manual. Change to 'See the Derby Reference Manual ...' 2) Page: http://incubator.apache.org/derby/docs/devguide/rdevconcepts88082.html The code snippet has a typo in it: ResultSet rs = s.executeQuery( "SELECT empno, firstnme, lastname, salary, bonus, comm " + 12 "FROM samp.employee"); It should be: ResultSet rs = s.executeQuery( "SELECT empno, firstnme, lastname, salary, bonus, comm " + "FROM samp.employee"); 3) Page: http://incubator.apache.org/derby/docs/devguide/tdevconcepts41704.html The code snippet is a little confusing. Later, when I looked at the extended example I figured out it was okay, but I recommend changing the code snippet from this: Statement s3 = conn.createStatement(); // name the statement so we can reference the result set // it generates s3.setCursorName("UPDATABLESTATEMENT"); // we will be able to use the following statement later //to access the current row of the cursor PreparedStatement ps2 = conn.prepareStatement( "UPDATE FlightBookings SET number_seats = ? " + "WHERE CURRENT OF UPDATABLESTATEMENT"); To this: Statement s3 = conn.createStatement(); // name the statement so we can reference the result set // it generates s3.setCursorName("UPDATABLESTATEMENT"); // we will be able to use the following statement later // to access the current row of the cursor // a result set needs to be obtained prior to using the // WHERE CURRENT syntax ResultSet rs = s3.executeQuery("select * from FlightBookings FOR UPDATE of number_seats"); PreparedStatement ps2 = conn.prepareStatement( "UPDATE FlightBookings SET number_seats = ? " + "WHERE CURRENT OF UPDATABLESTATEMENT"); 4) Page: http://incubator.apache.org/derby/docs/devguide/cdevconcepts22641.html The code on this page throws an exception since the transaction was not committed. To prevent this, add conn.commit() after s4.close() and before conn.close(): scroller.close(); s4.close(); conn.commit(); <-- new line conn.close(); System.out.println("Closed connection"); 5) Page: http://incubator.apache.org/derby/docs/devguide/cdevconcepts16400.html The color of the arrows and in one instance the length of the bars in these examples is incorrect. Figure 1: The arrow on the time line should be yellow, not orange. The arrow under the text 'Transactions are never aborted ...', should be orange, and not yellow. So in effect, the colors of the arrows is exactly opposite to what it should be. Figure 2: Again, the color of the arrows is exactly in reverse. The first arrow should be yellow, the second arrow should be orange. Figure 3: The color of the arrows is incorrect, but the length of the bars are incorrect. Since locksWaitTimeout is at 50 seconds, it should be smaller in length then the deadlockTimeout bar, which is 60 seconds. So the picture should look something like this: |locksWaitTimeout= 50 | __ | deadlockTimeout = 60 | \/ No deadlock .... I've been waiting 50 seconds Abort me (I'll try again later). __ \/ (orange) 6) Page: http://incubator.apache.org/derby/docs/devguide/cdevconcepts32861.html The code snippet has an error: try { s6.executeUpdate( "UPDATE employee " + "SET bonus = 625 " + 91 "WHERE empno='000150'"); s6.executeUpdate("UPDATE project " + "SET respemp = '000150' " + "WHERE projno='IF1000'"); } Change to: try { s6.executeUpdate( "UPDATE employee " + "SET bonus = 625 " "WHERE empno='000150'"); s6.executeUpdate("UPDATE project " + "SET respemp = '000150' " + "WHERE projno='IF1000'"); } 7) Page: http://incubator.apache.org/derby/docs/devguide/rdevconcepts713.html The table has a vestige of IBM license stuff under the Connection mode column, Multi-Connection row: Multi-Connection >From an application, using multiple connections to a Derby database and >issuing requests against those connections on multiple threads. (You must have a multi-user license to have more than one connection to Derby.) Remove the: You must have a multi-user license to have more than one connection to Derby. 8) Page: http://incubator.apache.org/derby/docs/devguide/cdevcsecure30032.html A typo in the 3rd paragraph, 2nd sentence. For example, you can hook Derby up to an external directory service elsewhere in your enterprise, create your own, use Derby's simple mechanism for creating a built-in repository of users. The word 'or' should be added to make the sentence like this: For example, you can hook Derby up to an external directory service elsewhere in your enterprise, create your own, or use Derby's simple mechanism for creating a built-in repository of users. 9) Page: http://incubator.apache.org/derby/docs/devguide/rdevcsecure608.html The last paragraph cites a non-existent URL. Derby does not provide these libraries; they are available from Sun on the JNDI page at Use the 1.1.x versions of these libraries, not the 1.2.x versions. I tried to find the 1.1 versions of the libraries at Sun and could not find them. I think it would be better just to say they are available at Sun, and not try to cite a URL. Therefore this sentence could be changed to: Derby does not provide these libraries; they are available from Sun on the JNDI page. Use the 1.1.x versions of these libraries, not the 1.2.x versions. 10) Page: http://incubator.apache.org/derby/docs/devguide/cdevcsecure876908.html 4th paragraph: Typically, the user knows only a simple user name (e.g., the first part of the DN above, WilliamS). The DN above has a name of mary, not WilliamS. Therefore this sentence should be changed to: Typically, the user knows only a simple user name (e.g., the first part of the DN above, mary). 11) http://incubator.apache.org/derby/docs/devguide/rdevcsecure13713.html The first three examples of calling the SYSCS_UTIL procedures on this page are missing the CALL command. Change this: SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY( 'derby.connection.requireAuthentication', 'true') SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY( 'derby.authentication.provider', 'BUILTIN') SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY( 'derby.user.enduser', 'red29PlaNe') CALL SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY( 'derby.database.propertiesOnly', true') to this: CALL SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY( 'derby.connection.requireAuthentication', 'true') CALL SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY( 'derby.authentication.provider', 'BUILTIN') CALL SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY( 'derby.user.enduser', 'red29PlaNe') CALL SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY( 'derby.database.propertiesOnly', true') Susan > Doc Review: Derby Developer's Guide > ----------------------------------- > > Key: DERBY-380 > URL: http://issues.apache.org/jira/browse/DERBY-380 > Project: Derby > Type: Improvement > Components: Documentation > Environment: all > Reporter: Jeff Levitt > Priority: Minor > Fix For: 10.1.1.0 > > This issue tracks comments for the Derby Developer's Guide. The deadline for > posting comments isTuesday, June 28, noon Pacific time. > Some guidelines to follow when posting comments to this issue are: > - Try to make clear and concise comments about what you want changed whenever > possible. Provide concrete comments that say "Please change <original> to > <modified>" instead of generic comments like "This section needs to be > rewritten." > - If you're reviewing the HTML Files copy, include the URL for the page in > the review comment. Obtain the URL like this: > * highlight the topic in the left frame > * right click > * choose "Properties" > * copy and paste the address in the pop up box. > - If you're reviewing the PDF copy, in the review comment: > * Include the page number for the PDF, and indicate whether the number is > the PDF sheet number or the printed page number. > * Include the title of the section that the problem occurs in. If it's in > a subsection, try to include the hierarchy of titles. > - Please don't review the HTML Book copy -- it'll be time consuming to match > up that copy with the underlying DITA source. -- 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
