Home | Back | Contents | Next

# BshServlet and Servlet Mode Scripting

BshServlet is a simple servlet that can be used to evaluate BeanShell scripts inside of an application server or servlet container. BshServlet accepts BeanShell scripts via the POST method, evaluates them capturing output (optionally including standard out and standard error) and returns the results.

BshServlet has a simple form based interface for interactive experimentation (analogous to the remote server mode). But more generally you can send standalone BeanShell scripts from the command line to the BshServlet for evaluation using the bsh.Remote launcher. bsh.Remote complements bsh.Interpreter and bsh.Console as a launch point for BeanShell.

Tip: You may find BshServlet useful for writing unit tests that must run inside an application server environment. In this mode BshServlet can be used in the same way as or in combination with the Jakarta project's cactus.

## Deploying BshServlet

To test drive BshServlet you can grab one of the following sample application WAR files here:

- http://www.beanshell.org/bshservlet.war
- http://www.beanshell.org/bshservlet-wbsh.war Rename this file to "bshservlet.war" for use.

Tip: A WAR file is a Web Application Archive. It is a JAR file containing HTML, images, servlets, and configuration files comprising a complete web application. Web applications can usually be deployed to a servlet container by simply dropping the WAR file into a special directory.

The first file, bshservlet.war, assumes that BeanShell has been installed in your application server's classpath. It includes only the web.xml file necessary to deploy an instance of the test servlet and an index.html README file.

Note: To install BeanShell in the Tomcat server classpath place the bsh.jar file in common/lib. To use BeanShell in Weblogic you must upgrade its version of the package. See Upgrading BeanShell in Weblogic (http://www.beanshell.org/weblogic.html).

The second WAR, bshservlet-wbsh.war, includes a copy of the BeanShell application bsh.jar inside the WAR's lib directory. This WAR includes everything you need to just drop the WAR into an application server.

Note: Using bshservlet-wbsh.war will still *not* work in Weblogic 6.x unless you upgrade Weblogic's internal version of BeanShell first. See Upgrading BeanShell in Weblogic. (http://www.beanshell.org/weblogic.html).

To use the servlet for testing your own applications you will probably want to deploy an instance of the test servlet in your WAR file. This will allow the test servlet to to share a classloader with your webapp so that you can test things like application classes and EJB local homes. Since the servlet is included in the standard BeanShell distribution, all that is necessary to do this is to include bsh.jar and add an entry to your wegapp's web.xml file. Here is an example:

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <!DOCTYPE web-app
        PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
        "http://java.sun.com/dtd/web-app_2_3.dtd">

    <web-app>
        <servlet>
            <servlet-name>bshservlet</servlet-name>
            <servlet-class>bsh.servlet.BshServlet</servlet-class>
        </servlet>

        <servlet-mapping>
            <servlet-name>bshservlet</servlet-name>
            <url-pattern>/eval</url-pattern>
        </servlet-mapping>

    </web-app>

The above example deploys an instance of BshServlet under the name "/eval". The full path to the servlet will then depend on the name given to the webapp WAR file. For example if the above appears in a WAR file named "myapp.war" then the path would be:

    http://localhost/myapp/eval

## Running Scripts

After deploying the servlet, test it by fetching the default page with your web browser.

    http://localhost/bshservlet/eval

You can use the servlet interactively through the form that it generates, or, more importantly, through the command line launcher bsh.Remote. bsh.Remote accepts a URL for a target bsh interpreter and one or more file names to send to that server, printing the results.

      java bsh.Remote http://localhost/bshservlet/eval test1.bsh

You can execute remote scripts programmatically using the static method bsh.Remote.eval().

If bsh.Remote can parse the retun value as an integer it will return it as the exit status to the command line.

## The Script Environment

Scripts have access to the servlet environment through two predefined variables:

- bsh.httpServletRequest
- bsh.httpServletResponse

which are the standard servlet request and response objects, respectively.

When set to "raw" output mode via the forms interface or servlet parameter (described in the next section) the script is expected to generate the complete response using the httpServletResponse object. This means that you can have your script generate HTML or other output to be consumed by the client. For example:

    // Server side script generates HTML response page
    bsh.httpServletResponse.setContentType("text/html");
    out = bsh.httpServletResponse.getWriter();
    out.println("<html><body><h1>Hello World!</h1></body></html>");

More generally, you can use the httpServletRequest to get access to the server environment such as the servlet session object. You can also access all of the standard Java tools such as JNDI to fetch EJB homes, etc. and perform testing or script activities.

## BshServlet Parameters

The following parameters are recognized by BshServlet:

Parameter | Value
bsh.script | The BeanShell Script
bsh.servlet.captureOutErr | "true" - capture standard out and standard error during the evaluation of the script. Note: this is inherently non-thread safe. All output from the VM will be captured.
bsh.servlet.output | "raw" - Do not generate the servlet HTML result page. Instead rely on the script to generate the complete result using the servlet response.
bsh.client | "remote" - set by the bsh.Remote launcher to indicate that results should be raw and the return value should be encoded for transport back to the client.

Home | Back | Contents | Next