db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Susan Cline (JIRA)" <derby-...@db.apache.org>
Subject [jira] Commented: (DERBY-380) Doc Review: Derby Developer's Guide
Date Tue, 21 Jun 2005 16:03:23 GMT
    [ 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


Mime
View raw message