db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stanley Bradbury <Stan.Bradb...@gmail.com>
Subject Review - second installment: (DERBY-2390) DOCS - Merge Working with Derby and Getting Started Guide
Date Fri, 01 Jun 2007 18:55:14 GMT
Hi -
This is the second installment of my review of the new Getting Started 
Guide.  Again I'm posting these comments to the email thread but NOT 
adding a comment to the JIRA issue.  You can add this message to 
DERBY-2390 if you like or simply summarize relevant points based on your 
decisions about the suggestions.

Background and General recommendations:
Thanks to Andrew's improvements of the scripts (.bat and .sh: 
Derby-1032, v 10.2.1) the scripts no longer require that JAVA_HOME be 
set and, though the scripts will now figure out the proper setting for 
DERBY_HOME (assuming the scripts have not been moved from 
DERBY_HOME\bin) I recommend we still document that DERBY_HOME be set for 
ALL methods of execution.  With regard to the scripts; having DERBY_HOME 
set allows the discussion of adding the scripts directory to the PATH 
environment variable can reference DERBY_HOME\bin.  In addition the 
changes I suggest below count on java being in the system/user PATH.  
All the examples shown require the 'java.exe' be in the system/user PATH 
and this should be clearly stated and a check added to replace that of 
JAVA_HOME.  I recommend something like this:

    ======   Related Text substitutions  ====== 
 >> Section: To check the Derby system configuration
Change item 1
  ... Replace: 
1. Verify that the JAVA_HOME environment variable is set and points to a 
JDK version 1.3 or higher.
Open a command window and run the command java -version
   [ SYSTEM SYNTAX TABLE: Unix and Windows]
 ... With:
1. Verify that the java executable, version 1.4.2 or, higher is in your 
command execution PATH by opening a command window and running the 
command <CODE> java -version </code>
[NOTE TO AUTHOR: this command is the same on all platforms so the SYSTEM 
SYNTAX TABLE can be removed.  The example of output presented is fine,  
just change the reference to 1.3 (and all other references) which 
follows, as mentioned previously.

 >> Section: Setting the environment variables
  ... Replace: 
 item: 3. Set the JAVA_HOME environment ...
 ... With:
 3. Be sure the java executable is in your command execution PATH
   OR .. just remove item #3 altogether...
 
 >> NOTES TO AUTHOR:
Be sure to search for and REMOVE other reference to setting/checking 
JAVA_HOME in the document. 

The first table in the document, 'Choosing a method to run the Derby 
tools and startup utilities' is key to the information presented later.  
Since many of my suggestions (both first and second installments) change 
or augment the information presented in the table, I thought I would 
provide a rough rewrite for it.  Of course, I am not the author nor a 
good wordsmith so please use this as a guide and clean things up:

======  BEGIN of TABLE Suggestion =========
  ++ COLUMN 1: Method
  ROW 1
Run the tools using the shell scripts provided
  ROW 2
Run the tools using the derbyrun.jar archive
  ROW 3
Run the tools using complete java command syntax or use Derby in a Java 
program

  ++ COLUMN 2: When to Use
  ROW 1
When you want to execute the tools with the least amount of typing and 
have a full Derby 'bin' software distribution available.
  ROW 2
When you only have the derby jarfile set available or you do not want to 
use the scripts provided.
  ROW 3
When you do not have the scripts and derbyrun.jar archive available or 
when you are interested in learning the full syntax of each command and 
understanding the details of setting up the execution environment.  
Also, anyone who will be programming with Derby will need to meet the 
requirements listed for this method.

  ++ COLUMN 3: Requirements
  ROW 1
To use the examples in this book, the DERBY_HOME environment variable  
must be set and both the java executable and the Derby scripts directory 
(DERBY_HOME\bin) must be in your command execution PATH.  
  ROW 2
To use the examples in this book, the DERBY_HOME environment variable 
must be set and the java executable must be in your command execution 
PATH.  The derbyrun.jar file must be in the same folder as the other 
Derby jarfiles.

For more information see the syntax for the derbyrun.jar file.
  ROW 3
To use the examples in this book, the DERBY_HOME environment variable  
must be set and the java executable must be in your command execution 
PATH.  You will need to know the full package name for the java class 
supporting the tool and the CLASSPATH environment variable must be set 
to include the required jarfiles.

For details on setting the CLASSPATH, see Manually setting the 
CLASSPATH  environment variable.

============= END OF TABLE  =========================
    - - - - END: Related Text substitutions - - - -

INCORRECT INFORMATION [note: derbyrun.jar does NOT need to be in CLASSPATH]:
 >> SECTION:Syntax for the derbyrun.jar file
  .. Replace:
Adding the derbyrun.jar file to your CLASSPATH is equivalent to adding 
all of the
Derby jar files to your CLASSPATH
  .. With:
The derbyrun.jar file is a special jarfile archive that greatly 
simplifies invoking the Derby tools and Network Server.  It allows these 
programs to be executing using shortened names and without having to set 
the java CLASSAPATH environment variable.  To use derbyrun.jar the file 
must be in the same folder as the other Derby jarfiles.

NOTE TO AUTHOR:  It would be appropriate to add "Manually setting the 
CLASSPATH environment variable" to this section as it is an environment 
variable.  It seems odd that it is in the section: 'Using the Derby 
tools and startup utilities'.  My suggestions below include CLASSPATH 
and so will need tweaking if you do not want to cover CLASSPATH here.

 >> SECTION: Setting the environment variables
  .. Replace:
If you set several environment variables, the scripts that are included 
with the Derby bin distribution will be easier to run.
  .. With:
This section shows how to setup the environment variables required to 
support the execution method you select for using the Derby tools.  As 
stated in the table "Choosing a method to run the Derby tools and 
startup utilities", the environment variable DERBY_HOME needs to be set 
to use the command examples presented in this manual.  In addition 
adding the Derby scripts directory to your execution path makes the 
scripts easier to use and is also required to use the script examples 
presented.  The CLASSPATH environment variable must be set if you will 
be using Derby in a Java program or executing the tools using the java 
command.

NOTE TO AUTHOR:  I think with the above lead in you can remove this 
sentence that only talks about the scripts.  Or maybe incorporate some 
of it in the above??
  ... Seems not to be needed
The Derby scripts run the Derby tools and utilities. If you decide not 
to setup the
environment variables, you will need to run the Derby tools manually.

NOTE TO AUTHOR:  The following two notes appear in the document and 
should either be removed or clarifying text added.  New windows need to 
be opened only after making changes using the Control Panel.   Control 
Panel changes only effect windows opened after the edits have been 
saved.  If the variables are set manually in a window then they are in 
effect ONLY in that window - you will NOT be able to check settings done 
this way in another window.

 .. Note: You will need to open a new command window to verify that the
DERBY_HOME environment variable is set.
  .. Note: On Windows, you will need to open a new command window to 
very the
settings for these environment variables.



Mime
View raw message