SimpleXist

Over the last few weeks I’ve been looking at introducing the joys of the XRX world using eXist as we look to move away from Cocoon. One problem I’ve found is that eXist defaults to presenting, not only the eXist database, but a cornucopia of XML technologies. It’s an excellent showcase of things like XProc and not one, but two XForms implementations as well as concepts such as having the code and data in the database. But, if you’re used to putting code in a folder it can be tricky to know where to start and this gets in the way of the goal: learning about XQuery, XForms, and the database.

So, I’ve set up a simpler version called SimpleXist that either hides or removes most of the harder topics. The key things I’ve gone for are:

• Minimal servlets, only XQuery, REST (optional) and XML-RPC (for the client)
• XQueries run from the disk rather than the database.
• No URL-Rewriting.
• Can be locally deployed to a workstation but will work on a server.

I’ve written up the configuration below, but if you want to just download it then here you go. I’ve purposely not taken the route of repackaging jars or reducing their number. Everything is there, just not turned on. It’s all done with configuration and thus saves me embarrassing myself with my limited java skills.

Dear eXist gurus, I know there are other options, you can do a minimal recompile etc, etc. I’ve taken this route as it fits in with what we need, it’s easy to maintain and fits into the deployment and development methods we use. 

Jetty Minimal

First step was a minimal Jetty. It’s not critical to use Jetty but it gives a nice small container to run eXist that works on a desktop. I’ve used a download of Jetty 6 (6.1.26)  as the start point. Put Jetty somewhere; we only need a few files from it and then create a a folder for SimpleXist. In that folder make subfolders for /etc, /lib and /webapps. In the /webapps directory create a subfolder called /ROOT and in that create a folder /WEB-INF. Lastly in that folder create a folder /data.

Keep an eye on the folder structure shown on the left. This is what you’re heading towards.

Now, copy start.jar from Jetty to the SimpleXist folder. Next, Put jetty-6.1.26.jar, jetty-util-6.1.26.jar and servlet-api-2.5-20081211.jar into /lib. Lastly, in /etc put this jetty.xml file.

This is enough to set up a simple server on port 8080, which will run any webapp deployed in /webapps – in our case the default ROOT webapp. This is one of many reasons to love Jetty.

You can try it out with the command  java -jar start.jar . Point your browser to http://localhost:8080. It won’t be interesting or pretty but it should work.

Now we need to set up a simplified eXist to run in our container.

eXist Install

As with Jetty, download a copy of eXist. In this case I used the setup jar so I had a working install of the full system as a start point. Next, in the eXist root directory, run build dist-webapp which will create a .war file in the eXist /dist directory. I’m using war format because a) I like all my lib files in one directory and b) because it makes the app easy to move to something like Tomcat, which we use for production, later on.

Open up the .war with your favorite unzip utility and from it’s WEB-INF folder copy conf.xml and the /lib folder into /ROOT/WEB-INF.  Next,  download this web.xml into WEB-INF

Web.xml is the meat of the system. It sets up:

• The eXist XQuery servlet to handle anything ending .xqy or .xql
• The XML-RPC servlet to handle the eXist client connection at /xmlrpc.
• The eXist Servlet to start the database and respond to the REST commands at /rest
• The default servlet to handle resources i.e. a catchall servlet for anything else. Note this is Jetty specific.
• Lastly it looks for index.xql for the welcome file if nothing is requested at all.

Finally, we’ll create the ubiquitous Hello World to test it all out. Make an index.xql file in /ROOT with the following content:

xquery version "1.0";
declare option exist:serialize "method=html media-type=text/html";
let $hello := 'Hello World!'
return
<html>
<body>{$hello}</body>
</html>

That’s it. You can now run java -jar start.jar and you should see the famous message at localhost:8080. The Jetty container will complain a bit about logging, there isn’t a client and a couple of things need tidying up, but basically we’re there. Next time for those bits and some development examples.