db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "David W. Van Couvering" <David.Vancouver...@Sun.COM>
Subject Re: Holistic getting started approach
Date Thu, 02 Feb 2006 22:50:26 GMT
Solving the classpath issue would be a great win.  Not only could we fix 
ij this way, we could provide guidance to users so they can set up an 
executable application jar that includes derby.jar so that Derby 
application users also don't have to deal with classpath.

David

Daniel John Debrunner wrote:
> 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
> approach.
> 
> 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
> front.
> 
> 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;
> I
> -----------
> 1
> 
> 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
> ij>
> 
> 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.
> 
> Dan.
> 
> 
> 
> 
> 
> 

Mime
View raw message