<section>
<name filename="servletmode">BshServlet and Servlet Mode Scripting</name>

<img src="servletmode.gif"/>
<br CLEAR="ALL"/>

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.
<p/>

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.
<p/>

<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.
</tip>

<h2>Deploying BshServlet</h2>

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

<ul>
<li><a href="http://www.beanshell.org/bshservlet.war">
http://www.beanshell.org/bshservlet.war</a></li>
<li>
<a href="http://www.beanshell.org/bshservlet-wbsh.war">
http://www.beanshell.org/bshservlet-wbsh.war</a> 
<em>Rename this file to "bshservlet.war" for use.</em>
</li>
</ul>

<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.
</tip>

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 <a href="weblogic.html">Upgrading BeanShell in Weblogic</a>
(http://www.beanshell.org/weblogic.html).
</note>

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 <a href="weblogic.html">Upgrading BeanShell in Weblogic</a>.
(http://www.beanshell.org/weblogic.html).
</note>

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:

<example><![CDATA[ 
<?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>
]]></example>

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:

<example>
http://localhost/myapp/eval
</example>

<h2>Running Scripts</h2>

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

<example>
http://localhost/bshservlet/eval
</example>

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.  

<example>
  java bsh.Remote http://localhost/bshservlet/eval test1.bsh
</example>

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

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

<h2>The Script Environment</h2>

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

<ul>
<li>bsh.httpServletRequest</li>
<li>bsh.httpServletResponse</li>
</ul>

which are the standard servlet request and response objects, respectively.
<p/>

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:

<example><![CDATA[ 
// 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>");
]]></example>

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.

<h2>BshServlet Parameters</h2>

The following parameters are recognized by BshServlet:

<table border="1" cellpadding="5">
<tr><td>Parameter</td><td>Value</td></tr>
<tr><td><strong>bsh.script</strong></td><td>The BeanShell Script</td></tr>
<tr><td><strong>bsh.servlet.captureOutErr</strong></td><td>"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.
</td></tr>
<tr><td><strong>bsh.servlet.output</strong></td><td>"raw" - Do not generate
the servlet HTML result page.  Instead rely on the script to generate the
complete result using the servlet response.
<tr><td><strong>bsh.client</strong></td><td>"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.</td></tr>
</td></tr>
</table>

</section>
