Thanks for approaching the docs from this perspective, Bryan. I am sure
you are not the first to be puzzled by this material. More inline...
On 1/13/19 10:02 AM, Bryan Pendleton wrote:
Hi Rick,
I tried to take a "beginner's mind" and explore the Getting Started
guide with 10.15.
I stumbled a bit, and I'm wondering if we could do a bit of
smoothening and path-straightening prior to release.
First of all, I searched and didn't find a simple "one-pager"
describing CLASSPATH versus MODULEPATH, why it matters, how I would go
about choosing which configuration approach to use, what the
restrictions are on switching back-and-forth, etc.
Perhaps we could put something like that up at the very beginning, in
either "Deployment Options" or "System requirements"?
That's a good suggestion. I will give it some thought.
Secondly, is it true that if I use either "java -jar derbyrun.jar" or
the scripts in the bin/ directory, then I'm going to be using only
CLASSPATH, not MODULEPATH?
The set* scripts (the ones which merely set environment variables) set
both CLASSPATH and MODULEPATH. So they are agnostic. The other scripts
(the ones which actually run programs) merely run the programs with a
classpath. They DON'T run the programs with a modulepath. Maybe we need
another set of scripts. Maybe we need a command line argument which
causes the scripts to use a modulepath. Maybe we should stop documenting
these scripts and settle on a single, simple scheme for booting Derby
tools and the server.
The "java -jar" pattern always boots the JVM with a classpath. The
reasoning was explained to me by Alan Bateman from the Oracle corelibs
group. I moused his explanation into the following JIRA comment:
https://issues.apache.org/jira/browse/DERBY-7016?focusedCommentId=16697394&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-16697394
Maybe there is some simple command line which can be used to boot the
JVM with a modulepath.
I couldn't figure out how MODULEPATH would
have any interactions with either of those methods. If this is the
case, then maybe a sentence at the start of "Choosing a method to run
the Derby tools and startup utilities" describing this would help.
Yes, that sounds good.
Lastly, I think this might be just an oversight from some time in the
past, but with my "beginner's mind" I was struck by how awkwardly we
introduce the NetworkServer in the Getting Started manual. For example
"Using the Derby tools and startup utilities" starts out by saying
"The tools that are included with Derby are dblook, ij, and sysinfo."
Then about in the middle of the page it suddenly dumps
"NetworkServerControl" into the mix. And nowhere in the entire Getting
Started manual do I find anything at all about the startNetworkServer
and stopNetworkServer scripts in the bin/ directory. Instead, the
"Activity 4" section just tells you to use "java -jar derbyrun.jar" to
start and stop the Network Server, which is awkward as heck if you
chose to use the bin/ scripts when you launched into "Getting Started
with Derby".
Maybe we should step back and clean this all up before we release 10.15.
I think that derbyrun and the startup scripts are two different
approaches to the same problem. A Getting Started Guide should recommend
a single best practice, I think.
Anyway, I realise that nearly all of this pre-dates the modularization
work that you did, but I thought it was worth sharing the feedback
regardless.
Oh, and BTW, all my testing continues to go well, haven't found any
actual code problems to note yet.
thanks,
bryan
