Dev guide: sections - upgrades to controlling derby application behavior.

[Sunitha Kambhampati <ks...@gmail.com>]

I reviewed some sections from the developer guide and I am posting my 
comments here:
Note: the page number is the pdf page number that is printed on the page.

I'll update the wiki with the link to this mail, after it hits the archives.

(1)Section 'Preparing to Upgrade' , pg 7:
We talk about soft upgrade before introducing soft upgrade.  

(2)Section 'Soft Upgrade' pg 8:
Incorrect procedure name
SYSCS_UTIL.SYSCS_ONLINE_BACKUP_DATABASE_NOWAIT and
Change to SYSCS_UTIL.SYSCS_BACKUP_DATABASE_NOWAIT

(3)Page 10, Section Derby JDBC Driver
Remove this line 'See also javadoc for org.apache.derby.util.DriverUtil.'
I cannot find this file in the derby source.

(4)Figure1: does not show up in the pdf file 
(http://db.apache.org/derby/docs/10.2/devguide/derbydev.pdf)

(5) derby.service property is referenced in below three cases,whereas 
this property is not described in tuning guide.
I sent mail to derby-dev with title 'derby.service property references 
in dev guide, should these be cleaned up ?'

[pg11: section 'Derby system'
"You can use a property (see "derby.service" in Tuning Derby) to include 
databases in other directories
or in subdirectories of the system directory in the current system when 
you start it up."

pg17:
towards the end of the page, remove this line.
"You must specify a path for a database in a directory other than the 
system directory
even if you have defined the derby.service property to have Derby boot the
database automatically (see "derby.service" in Tuning Derby )."

pg31 (section - Accessing a read-only database in a zip/jar file)
Databases in a jar or zip file are not booted automatically when Derby 
is started, unless
they are explicitly listed as derby.service properties.
]

(6) pg11 - section 'Booting databases'
When Derby boots a database, it prints a message in the error log:
2005-06-10 03:54:06.196 GMT: Booting Derby version Apache Derby
- 10.0.0.1 - (29612): instance c013800d-00fd-0cb0-e736-ffffd1025a25 on
database directory sample

Here the example has version 10.0.0.1, since this is 10.2, should we 
update this message.
Or maybe better to just add a statement to say something like  --
the message will contain the derby version with which the database was 
booted.

(7)
pg12:
Add the property name here.
"Typically, Derby writes this information to a log called derby.log in 
the system directory,
although you can also have Derby send messages to a stream, using a 
property."
to
"Typically, Derby writes this information to a log called derby.log in 
the system directory,
although you can also have Derby send messages to a stream, using 
derby.stream.error.method property."

(8)
pg12: - section 'derby.properties'
In the last line on the page.
"For more information about properties and the Derby.properties file, 
see Tuning Derby"
The casing for the derby.properties should be 'derby.properties' instead 
of 'Derby.properties'.

(9)
pg33. Section 'Class Loading overview'
This line seems out of place. 'Include the class files and resources 
needed for your application.'

(10)
pg56- Section - Scope of Locks-> single-row-locks.  see DERBY-1683.

(11)
pg59-Section debugging deadlocks.
Casing for derby.log is incorrect in this statement. "...dump additional 
information to the Derby.log file
about any deadlocks that occur on your system. "

(12)
pg63: Section 'Information provided in SQLExceptions"
I dont think we want to document this. I have brought this issue on the 
list. see
thread 'Info provided in SQLException & ExceptionSeverity.'
"The severity levels are described 
inorg.apache.derby.types.ExceptionSeverity". Note this derby class is not
as part of the published api at 
http://db.apache.org/derby/javadoc/publishedapi/jdbc4/

(13)
general comments:
Figures dont show up in the pdf books.
Lots of places,there is a bulleted list whereas the list has only one 
element.
There is something like "1. ...."  It looks odd to number it as 1. see 
for an example -pg 22