JDK, Railo, Derby

Installing JDK, Railo, and Derby for local ColdFusion development

Shop for web design and development books here.

This article covers installation of Railo Server 3 (with Resin), MS SQL Server 2005 Express, SQL Server 2005 Management Studio Express, Sava CMS, Java Development Kit 6 and Java DB (Apache Derby); in a local XP-Pro machine, for ColdFusion development purposes.

Want to learn, or just try, CFML without the fat price tag? Need a total Java-based solution that doesn’t rely on expensive CFML and DBMS servers? I did, so a while back I started poking around for solutions. Here’s what I found.

The reader should have prior experience installing development servers in Windows XP, such as XAMPP or Apache2Triad. However, this isn’t quite that easy—no one has made a free package of CFML server stuff that installs everything with a click, so we need to install and configure several items, in the right order, to get from 0-60 in less than 30 hours…

Disclaimer: What I used, and did, works well, but may not be the best stuff or the best way. I’m brand-new with CFML and Java, so can only write this from that perspective. Trade names: Various software names used herein are trademarks of their respective owners, and are used herein only as convenient references, not endorsements.

Cold Fusion Markup Language Server

First, we need a local ColdFusion-compatible server. There are at least three free ones: Railo, Blue Dragon, and Smith. Several reviewers seemed to like Railo the best, for ease of installation and best ColdFusion-8 compatibility. I downloaded Railo Server (Develop Edition) with Resin. Resin is a Java-based web server included in Railo, and Railo is the Java-based CFML layer (don’t search now, the links and proper installation order are well below). Obviously, we need JRE or JDK (currently (Mar. ’09) at v. 6_12) installed to run Java.

Railo installation was simple—just make a c:\railo folder and unzip the contents of the download into it. Run httpd.exe, and point the browser at /localhost:8600. The included index.cfm runs and displays a bunch of tests, sorta like phpinfo(), indicating that JRE is running Resin and Railo. The start page has a link the Railo Admin. Congrats—we now have a free CF web server. That’s the easiest part, as we’ll soon see.

If not already running a web server on port 80, you can change Resin to use it and dispense with the 8600 port designator. See port, around line 62, in C:\Railo\conf\resin.conf.

Databse Server

Second, we need a database server. Railo can use a bunch of them. I’ve used Access extensively, and MySql a little, but someone recently asked if I knew “how to write stored procedures for MS-SQL Server,” and I didn’t, so I downloaded SQL Server 2005 Express (free) from Microsoft. I also installed SQL Server Management Studio Express.

Fourteen hours and 150,000 dialog-box clicks later, I had a basic grasp on how to manage MS-SQL, create databases and schemas, and write basic stored procedures…

Notes:

At this time (March 2009), the MS-SQL 2008 Express download is corrupted and will botch/fail the install, so drop back and look for 2005 before you waste a bunch of time. Or try it, maybe it’s fixed now.
Installing MS-SQL will suck in the .NET 2.0, 3.0, and 3.5 frameworks—more bloat-ware to cumber the registry and clutter the hard drive.
If you don’t need MS-SQL, install MySQL and MySQL Workbench (or PhpMyAdmin, if you have php installed).
If you already have a WAMP installed, just fire up its MySQL server.
If you want to stay all-Java, and run an embedded RDBMS without the need of a server, use the Java DB (Apache Derby) included in the Sun JDK, or try SQLite.

Get a CF Application to Study

Third, we need a substantial CF application to play with, so I located, downloaded, and installed Sava CMS in a sub-folder of Railo’s root (c:\railo\webapps\Root\Sava\ — Hint: to put Sava in a subdirectory, you need to set the “context” variable in settings.ini.cfm to /foldername with no trailing slash). Setting up Sava needs a little editing of its config file (what to put, noob?), and it also needs a database. I used Management Studio and created a database for Sava, then ran the provided SQL script on it to build the schema.

It took a few more hours to figure out how to set various permissions on the MS-SQL server, and the database, to get Sava to connect to it. Why so long? Typical MS wrong defaults and confusing dialog boxes. I could have hand-written 10 server configuration files in Linux in less time!

There are at least three issues with SQL Server 2005 Express:

TCP/IP is not enabled for the server. The default is Network. We need to enable TCP/IP before a web application can talk to it. In the Microsoft SQL Server Configuration Manager (not Management Studio), open the network configuration tree, click Protocols, r-click TCP/IP, and click Enable; r-click it again and click Properties; click IP Addresses tab and make sure all listed addresses have (a) TCP/IP Dynamic Ports is blank, and (b) TCP/IP Port is set to 1433. Also enable Named Pipes. In the left pane, click services, click the server in the right pane, and stop and restart the service.
SQL authentication is not enabled. The default is Windows authentication. Look in Management Studio, r-click the server name (top of left pane), click Server Properties, Security page, and change that to “SQL Server and Windows Authentication mode.”
SQL Server 2005 Express would not let me create a system DSN to it in Control Panel, OBDC. After much googling, I had to use Management Express again to create myself (my xp login) as an MS-SQL sysadmin. Create a new user, called YOURMACHINE\Yourloginname, and set him to the role of sysAdmin, else you can’t create a DSN (to MS-SQL) in Control Panel, OBDC. Where? Security, Logins, r-click, Add, etc. Make sure that’s Security for the server, not one of the databases, in the tree. Then you can create system DSNs to the SQL server.
We also need to create a user that our web apps will use to connect. I made one called root, gave him a password, and assigned him to all roles and all databases. That way I can just use the same username and password in whatever CF apps I install in the Railo server, and they’ll have full control of the db server, via SQL connects, without complaining.

Then POOF! it let me create a DSN and Sava connected. I created a couple of pages in it. That’s some nice open-source CMS!

Now, if all this sounds quick and easy, bear in mind that we’re now at the 22 continuous hours mark. Why? Most of it was spent getting the MS-SQL server un-bugged, and searching for answers revealed sketchy and scattered info.

Installing Apache Derby / Java DB

After a 14-hour nap, I decided it was time to start learning some CFML. I googled up a nice online tutorial that wanted me to create an Apache Derby database. Went to Railo admin, Datasources, and Derby isn’t a choice. It is in Adobe ColdFusion, and Derby is free, so why isn’t it in Railo? (Answer: it comes with JDK!)

What’s Derby? Originally made by IBM, it’s now an open-source, all-Java RDBMS, known as Apache Derby and Sun Java DB. The two are essentially identical. It runs like any Java—in a JVM—and can run as a server (multi-connections, runs in its own JVM), or Embedded (runs in the JVM of the app that calls it). How it runs depends on how you connect to it from the web app. For single-user development, run it embedded. For production, obviously, run it as a server.

More searching and research. No one has a page on installing Derby in Railo. I went to the Apache Derby site and downloaded it. The included docs are sketchy in the installation section, but I finally figured out I just needed to make a folder (c:\railo\derby\) and unzip it there, then configure it to run in embedded mode. I like that—I won’t need MS-SQL or any other massive DB server running in the background as a service.

Oops! The included Derby tutorials want us to install JDK (Sun Java Development Environment), and so far everything (Resin, Railo, Sava, Derby, etc.) is running fine with only the usual JRE (Sun Java Runtime Environment) installed.

Installing JDK, Railo, and Other Stuff

Ok, download and install the Sun JDK. HEY! It includes Derby! So now I don’t need the one I installed? No! Will the one in JDK run in embedded mode? Yes! Delete the one I installed in Railo.

We’re now at 42 hours… So I did it all backwards! Stop laughing! I’m saving you a couple DAYS here!

Commence Your Doin’s Here

So to do it forwards, we need to install in this order:

Sun JDK 6 from http://java.sun.com/javase/downloads/index.jsp (77 MB). Note that JDK also contains JRE and Derby (which Sun calls Java DB), so you won’t need JRE or Derby. The Java DB (Derby) included in the Sun JDK installation is identical to the Derby download from Apache, except that the docs are “Sun-ized” a little bit.
Railo-3.0.2.001-resin-3.1.2-without-jre.zip (find latest version) from http://www.railo-technologies.com/ (see downloads page). Don’t get the -with-jre version—not needed—we got that with JDK.
Any other database server you might need to use or learn, such as MS-SQL Express or MySQL, and the management and development front-ends for them.
Any open-source framework, CMS, blog, and tutorials for ColdFusion-type development.

Exploring and Configuring Java DB / Derby

Installing Sun JDK (in Windows) adds no shortcuts, so we go to its installation folders and look for docs. In Windows, the parts are located:

JDK: C:\Program Files\Java\jdk1.6.0_12\ (or current version number)
Java DB (Derby): C:\Program Files\Sun\JavaDB\
JDK Docs: Online at http://java.sun.com/javase/6/docs/, and are also downloadable (scroll down to Java SE 6 Documentation)—a mere 56 megs, zipped.
Java DB Docs: C:\Program Files\Sun\JavaDB\docs\, in HTML and PDF flavors. These are essentially the same as the online docs at http://db.apache.org/derby/manuals/.

The JDK comes with no fancy front-end, unless you install JavaBeans IDE, so everything is run from the command prompt. The console can be cmd, powerconsole, bash, or sh. Most everything runs from jar (Java Archive) files, which are started with java:

java -jar some-jar-file.jar

And then you’ll get errors like: Unable to access jarfile some-jar-file.jar and Failed to load Main-Class manifest attribute from some-jar-file.jar.

Setting Environment Variables: All at Once

The JDK installation is pretty generic, so it doesn’t tailor your system. We need to go to Control Panel, System Properties, Advanced (tab), Environment Variables (button), and set a few of them. Both JDK and Derby need some environment variables, unless you like typing full paths every time you run a command. Derby will certainly need them if you plan to connect a web application to a Derby database.

I’m gonna save you a bunch of time by combining instructions from two documents: Ref: http://java.sun.com/javase/6/webnotes/install/ and click your OS, see installation page; and Ref: http://db.apache.org/derby/docs/dev/getstart/ and read the “Setting Up Your Environment” section.

Adding both JDK and Derby /bin folders to the system path:

In the lower part of the Environment Variables dialog, called System Variables, locate Path, select and edit it, adding:
;C:\Program Files\Java\1.6.0_12\bin;%DERBY_HOME%\bin
to the end of the existing path. Substitute your version numbers as needed. OK the edit box, but don’t close the Environment Variables dialog; we’re not done with them yet. Now both JDK and Derby will be able to locate their executables from any folder.

Adding the two main variables for Derby:

Now let’s set up the environment variables that Derby needs: DERBY_HOME and CLASSPATH. In the System Variables box, click New, and put:
Variable Name: DERBY_HOME
Variable Value: C:\Progra~1\Sun\JavaDB (your OS may vary)
…and OK the edit box.

NOTE! The Derby and Sun docs don’t tell you this, but if you put “Program Files” in it, every derby command will break at the space, and fail to run. Make sure you use the DOS short-hand version of the name: truncate the long name to 6 characters and add ~1.

Helpful: Navigate your file manager to the JavaDB\lib folder (C:\Program Files\Sun\JavaDB\lib\ in XP), then Alt-Tab the Environment Variables dialog to the foreground and position it so you can see the names of the jar files in the file manager. Again click New, and put:
Variable Name: CLASSPATH
Variable Value:
%DERBY_HOME%\lib\derby.jar; %DERBY_HOME%\lib\derbyclient.jar; %DERBY_HOME%\lib\derbynet.jar; %DERBY_HOME%\lib\derbyrun.jar; %DERBY_HOME%\lib\derbytools.jar
…like that but all on one line, five of them, each separated with a semicolon. OK the edit box.

Then OK the Environment and System dialogs. Now Derby can find itself from anywhere.

There are a bunch of shell scripts and batch files in C:\Program Files\Sun\JavaDB\bin\, and these may be used to start various Derby things. They will set environment variables as needed, but only on a per-instance basis. Putting all the vars in the system environment will save a bunch of trouble when you start calling Derby from web scripts.

To test the environment settings, start a shell/cmd prompt and enter echo %path% and also echo the other variable we made and see if they are all right.

Now try java -jar %DERBY_HOME%\lib\derbyrun.jar sysinfo . It should gin out a couple screens of JVM and Derby info. If not, make sure that java will run: enter java -version and if that’s okay, echo %derby_home% and make sure that’s okay.

There are three ways to run the derby tools:

With the batch files in javadb\bin,
With the java -jar %derby_home%\lib\toolname.jar syntax, and
With the java org.apache.derby.tools.toolname syntax.

Note that, unfortunately, having the tools in classpath does not mean they’ll run with syntax #2 without the full path to the tool jar. Classpath only helps the syntax #3-type commands, which is the one you’ll use for connects and such from web apps.

What’s Next

Once I got it all working, I quickly lost interest in CFML, and have been messing with jQuery for a while. Maybe I’ll write a noob article on that pretty soon.

◄— CSS White-space Nowrap — CKeditor Tips —►