Speak your own programming language with Web scripting

An introduction to JSR 223's Web scripting framework

By Chaur Wu, JavaWorld.com, 05/22/06

The Web scripting capability of Java Specification Request (JSR) 223, Scripting for the Java Platform, specifies what a script engine must implement so that code written in the script language can run in a servlet container. In this article, we will equip BoolScript, a simple Boolean language I introduced in my previous JavaWorld article, "Build Your Own Scripting Language for Java," with Web scripting. If we draw an analogy between BoolScript and JavaServer Pages (JSP) in regards to Web scripting, we can see that essentially what we will be doing in this article is turning our BoolScript engine into something like a JSP engine. A JSP engine allows JSP code to run in a servlet container. Similarly, a BoolScript engine allows BoolScript code to run in a servlet container.

Before we begin, a word of caution is in order: JSR 223 implementation is still a work in progress. The implementation of Web scripting is not yet included in Java Platform, Standard Edition 6 beta build 80 (Java SE is Sun's new name for J2SE), the latest build as of this writing. Besides the Java SE beta, another source we can turn to for a JSR 223 implementation is the reference implementation. However, this reference implementation is dated to the extent that it is broken if you use it with build 80. In the article's example code, I spent minimum effort fixing those issues since they are temporarily due to the beta quality of the Java SE build. Although I can't speak for the Java SE development community, I believe the implementation and specification will undergo some changes, but the concepts and overall structure will remain. And in the production release of Java SE 6, the temporary issues will all be fixed. For now, think of my temporary fixes as an opportunity to see how things work behind the scenes.

This article doesn't require much knowledge of Java servlets. If you know the use of a servlet context in a servlet and the basics of deploying a servlet in a servlet container, you know enough to proceed.

Set up the example code

To set up the environment for this article's example code, you need three things:

Java SE 6 beta build 80. You can download it from java.net.
A servlet container. In this article, I use Tomcat 5.5 as an example. You can download Tomcat 5.5 from Apache Tomcat.
The JSR 223 reference implementation. You can download that from the JSR 223 Webpage.

The article's code example, which can be downloaded from Resources, comes in two files:

BoolScript-src.zip contains the source code of the BoolScript engine
BoolScript-binary.zip contains the binary of the BoolScript engine and some other files that we'll look at in detail in this article's "Configurations" section

After you download all the required software, you must perform the following steps to set up and run the example code.

Install Java SE 6 beta build 80 and Tomcat 5.5. Following Tomcat conventions, I use {CATALINA_HOME} to refer to the folder where Tomcat is installed.
Extract the contents of BoolScript-binary.zip into {CATALINA_HOME}\webapps. If you use a different servlet container, you must extract BoolScript-binary.zip into the folder where you would deploy a Web application.
Extract the contents of the JSR 223 reference implementation into a temporary folder and copy the file jars\script.jar into {CATALINA_HOME}\webapps\BoolScript\WEB_INF\lib.

Open the file {CATALINA_HOME}\conf\server.xml and add a context entry like this:

 <Server>
  ...
  <Service>
    ...
    <Engine>
      ...
<Host>
        ...
  <Context path="/BoolScript" docBase="BoolScript" 
debug="0" reloadable="true" />
        ...
      </Host>
    </Engine>
  </Service>
</Server>

Now you are ready to test the example. Ensure the Tomcat server is up and running. Open a Web browser and type in this URL: http://localhost:8080/BoolScript/logic.bool. If everything is set up correctly, the result you will see should look like this: [true, false, true].

The figure below and subsequent list describe the sequence of events that occur when you run the above test. The rest of the article explains the various parts of this figure in detail.

Overview of example. Click on thumbnail to view full-sized image.

Web browser sends an HTTP request to Web server
Servlet container dispatches the HTTP request to our script servlet
The script servlet calls the getScriptSource() method on the HTTP script context to get the script source file logic.bool
HTTP script context locates logic.bool
HTTP script context reads in the file logic.bool
HTTP script context returns the contents of logic.bool back to the script servlet
The script servlet passes the contents to the script engine for evaluation
The script engine returns the result of evaluation back to the script servlet
The script servlet returns the result back to the servlet container
Web server returns the result back to the Web browser

From the figure and the list above, you can see that the script servlet and the HTTP script context are the key components that carry out script evaluation in a servlet container. Let's first look at the script servlet in detail. Then I'll explain the HTTP script context and its functionalities. After those discussions, we will look at the configurations that glue together all the parties depicted in the figure above.

Script servlet

JSR 223's Web scripting framework consists of mainly three items: script servlet, HTTP script context, and configurations. (Note: Though these are not standard terms, they prove helpful for our discussion.) Let's discuss them one-by-one, starting with the script servlet. A script servlet is really just a servlet (i.e., an instance of GenericServlet). A servlet performs its tasks in its service() method and so does a script servlet. Like a typical servlet, a script servlet performs in its service() method tasks such as processing an HTTP request and stuffing Web contents in an HTTP response. Unlike a typical servlet, a script servlet, while performing its tasks, runs script code in one or more script engines.

Now that I've explained a script servlet at a conceptual level, let's talk about the code. A servlet must directly or indirectly derive from javax.servlet.GenericServlet. In this article's example code, we implement a script servlet class called BoolScriptServlet. It inherits GenericHttpScriptServlet, which in turn inherits GenericServlet. From this, we confirm that our script servlet is a bona fide servlet as I claimed it must be.