a web-framework using Armed Bear Common Lisp as a Java Servlet
This tutorial is currently the only source of information about abcl-web installation process. Detailed component description and feature overview can be found here. This tutorial will explain how to install, which files to download, how to work with it, etc.
In theory, you can just deploy ABCL-web application as a standard Java web application, but currently it's not always goes so smooth. Also, you'll need some stuff to set up if you want to develop and debug web applications.
At minimum, you'll need to install Java and some Servlet Container (Apache Tomcat). For development environment, you'll need Emacs/XEmacs (or something of emacs kind) and SLIME (see notes about SLIME and abcl-web).
You can first try to deploy a web application archive -- that's simple, almost one-click, but possibly in some cases you'll need to build web-application from parts youself.
If you'll have problems, check configure section.
After web application is deployed, you can check it's running and check development and debugging environment.
In theory, it can work with any platform supporting Java and Servlets. Currently it's tested on Win32 (Windows XP Pro), Solaris 10, Debian Etch and FreeBSD 6.1. It's up to you to get Java (1.4.2 or 1.5 or higher version), preferably with a compiler (jikes), and a Servlet Container like Apache Tomcat 4 or 5+.
You can get web application archive (WAR) file for test application here, and easily deploy it into servlet container -- if you're using Tomcat's Manager HTML interface, just use upload form with a 'Deploy' button. If it goes OK, you can proceed to testing it. Otherwise, please check what does servlet container writes, and what you see in the logs. As a obvious problem, you should allow servlet container to write to webapps folder. If it doesn't help, check configure section.
Note that you can unpack WAR and run console ABCL interpreter -- it is in WEB-INF/lib/abcl.jar.
First you need to get ABCL. You can either get pre-built binaries (build from current (30.07.2006) ABCL sources on Linux using JDK 1.4.2/jikes. Or you can get sources from ABCL site and build it youself. Please note that binaries build with JDK 1.5 won't work with 1.4.2 JRE/JDK!
Once you have abcl.jar, you can run "java -jar abcl.jar" in shell and get lisp promt. You can also run a j.jar, it's a bit harder.
Then you can get Java and Lisp files of lispwebapp, and put abcl.jar into WEB-INF/lib directory, and then deploy it into servlet container according to it's documentation (for Tomcat, you can unpack it to /var/lib/tomcat5/webapps/lispwebapp (or whatever home of tomcat is called) and access url http://localhost:8180/manager/deploy?path=/lispwebapp)
If you want to try RDF stuff, you'll also need to download Jena binaries and place them into lib directory. Minimum set of Jena JARs is: jena.jar, arq.jar, concurrent.jar.
If you don't have Emacs (or XEmacs, or other flavour) and SLIME working, you'd better learn them first!
It's quite straightforward to configure SLIME to work with ABCL -- (define-slime-dialect abcl "abcl"),
but there can be some problems when you are using SLIME to work with ABCL that is in servlet container.
ABCL-web loads SLIME that bundled into a package. If you have locally-installed SLIME, you should ensure that same
versions are used on abcl-web and emacs side. Note that bundled version is configured via slime/site-init.lisp
(i/o redirection and global debugger), and also fasl output is redirected into slime/fasl directory.
Currently remote debugging works fine in default configuratin on Debian Etch -- actually i don't know why it's accessible if sockets are bound to the address 127.0.0.1, but it somehow works.. This might open a security hole in your machine, please check stuff, configure firewall as needed etc.
If application is not launched, check what happens in the tomcat logs. ABCL-web informs you about checkpoints it passes -- so at least you should see messages like "initializing lisp debugger servlet", "creating interpreter" etc. In case of failure you'll most likely need to restart the whole Tomcat server to ensure no artifacts are left from the previous run (for example, SLIME debugger can leave port open, so it won't be possible to initialize it second time). It might be a slow process, but unfortunately this part is hard to debug efficiently.
Here is a list of typical configuration problems:
Additionally, current version of ABCL does not work well with hardware SMP (multiple cores, hyperthreading) -- it breaks if CLOS code is executed simultaneously on multiple processors. Thus, you should disable SMP or set tomcat's process affinity to a single CPU.
At this point, we assume that you have successfully deployed the lispwebapp. First check that it's indeed deployed
-- open url http://localhost:8180/lispwebapp/ (port and host might differ on your system). You should see two links -- debug and exec --
if you don't, it's not deployed. This links lead to two servlets -- LspDebug and LspExec.
First try to access LspDebug. For the first time, it will try to compile SLIME on your system, it can take significant amount of time!
If you see that disk activity stopped, but no result is delivered (a debugger form should appear in case of success), something is wrong.
Please go to configure section for trouble-shooting.
If you see a form, lisp interpreter is running (congratulations!), you can try to execute forms like (+ 2 2) to see it's really alive.
Then you can proceed running the servlet code (/lispwebapp/servlet/LspExec). As with debugger, it will compile JFLI-ABCL and LML2 on first run, so you should be patient. It's easier to detect problems in the servlet itself, because you can attach a SLIME debugger, but sometimes it can break weirdly. Once you see web-application page running, you've completed installation process.
Note: you should NOT leave LspDebug accessible to public, since it's a security hole. Please remove it, or restrict access to it when running public web server. (Being alpha, other parts of ABCL-web are not guaranteed to be safe, but at least there are no obvious holes).
So, we assume you have running ABCL-web -- you see both debugger and sample lispwebapp pages. Let's now check debugging process
If all is well, and you running ABCL-web on the same machine you have Emacs, just open Emacs do M-x slime-connect -- and connect to 127.0.0.1, port 4005. If all is well, you'll see a ABCL-web's lisp prompt. You can check now that it's working and functional. Normally, you should start debugger before loading application if you do development -- first lauchd LspDebug servlet accessing it, or setting autostart so it will launch on tomcat's launch; then load Emacs and connect to it, and only then start loading application code. If you'll have errors loading code (you've saved dirty files last time), you'll break into SLIME debugger, so you can diagnose error, fix it, save files, and restart loading that file.
You can also do just-in-time debugging -- if request leads to error, you can break into the debugger, fix the error and retry processing request. Data will be sent to browser only when you continue.
Development is really dynamic -- you can write function in the Emacs, execute it or compile -- and it's instantly available to a web-server!
You can find (C-x C-f) web-application source file /lispwebapp/WEB-INF/lisp/app.lisp in Emacs. You'll need to set current package to SERVLET1 both in REPL and in file being edited, then you can modify functions, and after you evaluate defun (M-C-x), it will be instantly available to a web-server.
The demo application bundled with lispwebapp is written using 'web-engine.lisp' that enables manual continuation-style programming. You can find more information on it here.