IKanServe – an Ioke web framework

The last few days I’ve cobbled together IKanServe, which could be called a web framework, if you’re really generous about the meaning of the words. It doesn’t really do that much right now. But it does allow you to serve dynamic web pages using Ioke.

Much of the hard parts in the Ioke servlet was totally cribbed from Nick Sieger’s JRuby-rack, which is a very well-engineered project.

IKanServe is basically three different parts. First and most importantly, it’s an IokeServlet, that takes care of starting runtimes and pooling them. The second part is the Ioke parts of dispatching, that will turn headers and parameters into a dict, and then find matching actions and dispatch them. The third part is a very small builder library that lets you create HTML with Ioke code. In fact, the code for the html builder could be quite interesting, so let’s start with that. It’s very small, promise!

IKanServe HtmlBuilder = BlankSlate create(fn(bs,
    bs pass = method(+args, +:attrs,
      args "<%s%:[ %s=\"%s\"%]>%[%s%]</%s>\n" format(
        currentMessage name, attrs, args, currentMessage name))))

As you can see, we use a blank_slate library, that is part of the standard library of Ioke. If you’re familiar with Ruby, you know what a blank slate is. Ioke’s blank slate is a bit more blank than the Ruby equivalent, though. To create a blank slate, we call the create method, and then send in a lexical block where we can set up anything we want to have on the blank slate. After create is finished, it will be impossible to add new stuff to the blank slate, so this is the only place we can do that. What we do here is to add a “pass” method. Pass is mostly the same as method_missing in Ruby. That method will create a tag from the method name, add all keyword arguments as attributes, then add all the content inside the tag and finally close the tag. The funky looking syntax in the Text literal is mostly the same as the % or sprintf methods in Ruby.

There is some subtle things going on in this method, but to go into them would derail this whole post. Before abandoning the HTML stuff, you might want to know how to use it. This is how:

h = IKanServe HtmlBuilder
title = "I kan serve HTML!"
h html(
  h head(h title(title)),
  h body(
    h h1(
      style: "font-size: 1.5em",
      "Isn't this cool?"

HtmlBuilder doesn’t have any state, so you just use it immediately. I alias it as “h” to make it easier on the eyes. That means that every call to the “h” object will return html. That’s how I can differentiate between creating the tag “title” and referring to the variable “title”. This is very easy stuff, but it seems to work well for smaller cases.

OK. Let’s get back to the rest of IKanServe. What do you need to use it? In your WEB-INF, you need to have three files in the “lib” directory – namely “ioke.jar”, “ioke-lib.jar” and “ikanserve.jar”. Since Ioke is inbetween releases you will have to build these yourselves, but it’s pretty simple. You can build the first two using the target “jar-lib” in the Ioke source. The third can be created by checking out ikanserve from Github: http://github.com/olabini/ikanserve, and then building it with ant.

Once you have those in your WEB-INF, you also need a web.xml file. It should look something like this:

<?xml version="1.0" encoding="utf-8"?>
  "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"





Nothing spectacular, just set up the number of runtimes, the servlet and a servlet context listener.

And that’s it. Now you can build a war file and it will be ready to serve. Of course, if you deploy it and try to go to any URL, you will get a message that says: “Couldn’t find any action corresponding to your request. Sorry!”. That’s the default 404 action.

To actually create some code that does something, you need to create a file called iks_application.ik. This file should be places in WEB-INF/classes. Any other Ioke files you want to use should be on the classpath, and you can just use “use” to load those files. What can you do in IKanServe then? Well, basically you can bind actions to urls. Right now there is only one way to bind urls, and that is with regular expressions. A typical small action can be bound like this:

IKanServe actionForPath(#r[^/bar],
  method("you requested this: #{request pathInfo}"))

Here we bind any URL that starts with /bar to the method sent in. At the moment you have access to a request object, and the return value of the method will be rendered as the result. And that’s basically it. As mentioned above, it’s not so much a framework as the initial skeleton for one – but it still works quite well.

If you want to try this out in the easiest way possible, you can do “ant example-app” in the ikanserve source tree, then do “cd jetty” and finally do “java -jar start.jar”. This will build and deploy an example application and then start a Jetty instance to serve it. Go to localhost:8080 and try /foo, /bar or any other URL, and see it in action. You can see the code for this small app in web/WEB-INF/classes/iks_application.ik.

And that’s all for this time. Have fun.

4 Comments, Comment or Ping

  1. Fantastic! Thank you.

    March 21st, 2009

  2. :D this is so circus …. when you started that html builder part of code i was hearing playing in mind, that song from the circus/circus related … who’s name i never know.

    Truly fantastic to quote the above.

    March 23rd, 2009

  3. I’d like to play with this on a Macintosh PowerPC machine. But on that machine, which is not particularly slow (1.33 GHz), ioke takes more than half a minute to load:

    > time bin/ioke -e “”
    37.56 real 19.15 user 0.95 sys

    This is with java version 1.5.0_16.

    Any advice?


    April 3rd, 2009

Reply to “IKanServe – an Ioke web framework”