db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Daniel John Debrunner <...@apache.org>
Subject Holistic getting started approach
Date Thu, 02 Feb 2006 22:14:59 GMT

Looking at Stan's WMD, sorry WWD document in DERBY-913 I want to promote
 a holistic approach to making getting started on Derby easier. Thus by
improving various areas such as documentation, web-site, product,
tutorials, FAQ etc. together we can gain a bigger benefit than by
increasing individual items to make up for deficiencies in other areas.
This echoes something Bryan (I think) said a couple of days ago, that
just don't assume fixing the getting started guide is the only or best

Stan's WWD tutorial looks like a great project and I'm sure will benefit
people getting up to speed on Derby.

What really jumped out at me was the very first things a user has to do
is understand and set classpaths. Something that causes the most
problems and is tricky to get right in a manual way, is the first thing
we hit users with. To my mind seems like a very good way to lose users
at the first step, either because they want to issue some SQL right away
but we make them setup environment variables first, or they get
frustrated by ClassNotFoundExceptions due to minor typos.

Now I understand where Stan is coming from, he's once supported this
product and saw the endless class path issues, so why not explain it up

I would take a different approach, start out with something that works
and get users into executing SQL through ij as soon as possible. As the
tutorial moves on, explain class paths later, once they have seen all
the powers of Derby.

Note that what I'm talking about is maybe 2% of Stan's proposed
tutorial, but it's the first 2% where one stands the greatest risk to
lose the most people.

I see the requirement to set classpath as a weakness in the product,
which the tutorial is trying to work around. So what could be done
better in the product that would help this tutorial?

Having installed Derby there needs to be something simple that gets you
into ij. Some very easy step that gets you to a successful session like:

ij version 10.2
ij> connect 'MYDB;create=true';
ij> create table t (i int );
insert into t values 1;
0 rows inserted/updated/deleted
ij> 1 row inserted/updated/deleted
ij> select * from t;

1 row selected

Note that I intentionally have a connect statement without
'jdbc:derby:', I'm trying to make it simple, then as one progresses
through the tutorial one unwraps the layers to expose the full story.
E.g. some section that said, what was really going on with the 'connect
MYDB', then explain it's being mapped in jdbc:derby:MYDB and so on.

Maybe the simple command to get things going is based upon the current
ij shell or batch scripts in the frameworks directory. They could be
improved so that they were more visible and were a single step.  If I
can't run this scripts right away after an installation they will turn
people off.

Maybe we could provide additional jar files the execute the tools, I
created a simple ij.jar containing only this manifest (no classes etc.):

Manifest-Version: 1.0
Ant-Version: Apache Ant 1.6.2
Created-By: 1.4.2 (IBM Corporation)
Main-Class: org.apache.derby.tools.ij
Class-Path: derbytools.jar derby.jar

Then I can execute

java -jar jars/sane/ij.jar
ij version 10.2

To set the default JDBC protocol a simple java class would be needed in
ij.jar as its main class to set the ij.protocol property and then call ij.

Can these jars be executed directly, I thought on windows one could
double-click a jar file and have it run right away, doesn't seem to
happen on my machine though?

So that's just one example where hopefully addressing something in the
product would make the tutorial better and lead to more happy Derby
users. I would encourage others to think along similar lines when
looking at the tutorial, manual or anything else that's aimed at making
Derby easier, namely to see if some other piece would make it even easier.


View raw message