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 Re: [jira] Commented: (DERBY-2390) DOCS - Merge Working with Derby and Getting Started Guide
Date Thu, 31 May 2007 02:10:17 GMT
Kim Haase (JIRA) wrote:
>     [ https://issues.apache.org/jira/browse/DERBY-2390?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12498750
> Kim Haase commented on DERBY-2390:
> ----------------------------------
> This is a terrific job, Laura -- I think you've done a great job merging the manuals.
These comments are on the individual sections. I don't think these answer every question you
had, though. Let me see -- question 5 -- I think it would be good to update the output to
10.3 if possible, but getting the svn version right is probably not possible since code hasn't
frozen. Question 7 -- I believe both "mode" and "environment" are used but in slightly different
situations -- it might be worth adding the mention of "mode" to the Terminology section? I
think "configuration" is used only in "Deployment options" -- not sure.
   = = = =  SNIP  ===  Stan's comments:
Hi Laura -
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.  The document looks good but I think it would be clearer to 
novice users to provide the following information / clarifications (in 
not particular order):

1) It looks like Kim has flagged the references to JDK 1.3 which is no 
longer supported in this release.  The info from the WIKI states:
10.3 Platforms : Minimum JDK support will change to JDK 1.4.2 for J2SE & 
CDC/Foundation 1.1 for J2ME. (Removes support for JDK 1.3 and 
J2ME/CDC/Foundation 1.0)   -> DERBY-1982

o) Laura is correct raising issue 6:  "I don't think that we do a good 
job of describing what the Network Server is."  And I agree with Kim's 
suggestion: "Deployment options - Here, probably, is where "Network 
Server" needs to be defined."   IMHO the Deployment options section of 
the Getting Started Guide has never been right.  The GS should only 
introduce the two basic options: Embedded and Server / Network Server.  
Any more gets you into the deep weeds really quickly.  Here's a basic 
'Getting Started' replacement for this section:

====  Begin of Replacement ===============
Before you install Derby, you should understand the system requirements 
and two basic
frameworks provided.

    Basic Frameworks Provided

The Derby software distribution provides two basic frameworks (also 
referred to as 'deployment options').  The simple embedded framework and 
the Derby Network Server framework.

 o Embedded is used to refer to Derby being started by a simple 
single-user Java application.  In this framework Derby runs in the same 
Java virtual machine (JVM) as the application.  Derby can be almost 
invisible to the end user because it is started and stopped by the 
application and often requires no administration.

 o Server (or Server based) is used to refer to Derby being started by 
an application that provides multi-user connectivity to Derby across a 
network.  In this framework Derby runs in the Java virtual machine (JVM) 
that hosts the Server and applications connect to the Server from 
different JVMs in order to access the database(s).  The Derby Network 
Server is part of the Derby software distribution and provides this type 
of framework for Derby.  Derby also works well with other, independently 
developed Server applications. 

==========  END =============

o) The document would benefit from clarifying the three different 
'command styles' shown in the 'Using the Derby tools and setup 
utilities'.  Adding information to the 'Choose a method to run the Derby 
tools and startup utilities' seems like where this is needed.  Also, for 
clarity and use the text provided below you will need to perform the 
following global changes on two of the three 'Method' columns in each table:
Replace Method:
  Run the tools as standalone commands
 Run the tools using the command scripts

Replace Method:
Run the tools using the jar files that are located in the directory 
where the tools reside.
Run the tools using the derbyrun.jar archive

Intro Replacement suggestion [NOTE: you could instead add the three 
'People/Programmers ... interested/have' sentences below to the 'When to 
Use' section of the table]
There are several ways that you can run the Derby tools and startup 
 This section discusses how to setup the system environment variables 
needed to run the Derby tools and utilities presented in the next 
section.  Three ways to run each tools and utilities are shown.  Choose 
the method that best fits your own personal needs and interests.  Java 
programmers will probably be interested in learning the full command 
syntax show by the methods: '...using java command'.  People who have a 
full Derby 'bin' distribution available, want to do a minimal amount of 
typing when running the tools and don't mind setting up a few 
environment variables upfront will like using the method '...shell 
scripts provided'.  People interested in performing the minimum amount 
of environment setup and being able to run the tools when only the derby 
jarfiles are available will want to use the method: '...using the 
derbyrun.jar archive'.

  Choose the method that you want to use:Choose the method that you want 
to use:
  Use the following table to identify the setting required for the 
method which is right for you. 

In the first table itself, the second row (derbyrun) remove the following:
  Col 2:  • Do not run the tools often  - (this is not a good 
recommendation, see text above)
  Col 3: JAVA_HOME  - ( with JAVA in your PATH there is no reason to 
have JAVA_HOME set)

--- I hope you find this helpful.  I think these changes, though 
longish, will provide the intro needed to guide new users through the 
rest of the document.  I will provide additional input tomorrow but I 
think this is the bulk of it. 

View raw message