| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| |
| <!-- Content Stylesheet for Site --> |
| |
| |
| <!-- start the processing --> |
| <html> |
| <!-- GENERATED FILE, DO NOT EDIT, EDIT THE XML FILE IN xdocs INSTEAD! --> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/> |
| |
| <meta name="author" value="Victor Orlikowski"> |
| <meta name="email" value="victor.j.orlikowski@alumni.duke.edu"> |
| <meta name="author" value="Chuck Murcko"> |
| <meta name="email" value="chuck@topsail.org"> |
| |
| <title>Jakarta BSF - BSF Documentation</title> |
| </head> |
| |
| <body bgcolor="#ffffff" text="#000000" link="#525D76"> |
| <table border="0" width="100%" cellspacing="0"> |
| <!-- TOP IMAGE --> |
| <tr> |
| <td align="left"> |
| <a href="http://jakarta.apache.org"><img src="images/jakarta-logo.gif" border="0"/></a> |
| </td> |
| <td align="right"> |
| <a href="http://jakarta.apache.org/bsf/"><img src="./images/bsf_logo.jpg" alt="Jakarta BSF" border="0"/></a> |
| </td> |
| </tr> |
| </table> |
| <table border="0" width="100%" cellspacing="4"> |
| <tr><td colspan="2"> |
| <hr noshade="" size="1"/> |
| </td></tr> |
| |
| <tr> |
| <!-- LEFT SIDE NAVIGATION --> |
| <td valign="top" nowrap="true"> |
| <p><strong>BSF Essentials</strong></p> |
| <ul> |
| <li> <a href="./index.html">Front Page</a> |
| </li> |
| <li> <a href="./bsfnews.html">News</a> |
| </li> |
| <li> <a href="./manual.html">Documentation</a> |
| </li> |
| <li> <a href="./projects.html">Related Projects</a> |
| </li> |
| <li> <a href="./resources.html">Resources</a> |
| </li> |
| <li> <a href="./faq.html">BSF FAQ</a> |
| </li> |
| <li> <a href="./problems.html">Having Problems?</a> |
| </li> |
| </ul> |
| <p><strong>Download</strong></p> |
| <ul> |
| <li> <a href="http://jakarta.apache.org/site/downloads/downloads_bsf.cgi">Binaries</a> |
| </li> |
| <li> <a href="http://jakarta.apache.org/site/downloads/downloads_bsf.cgi">Source Code</a> |
| </li> |
| </ul> |
| <p><strong>Jakarta</strong></p> |
| <ul> |
| <li> <a href="http://jakarta.apache.org/site/news.html">News & Status</a> |
| </li> |
| <li> <a href="http://jakarta.apache.org/site/mission.html">Mission</a> |
| </li> |
| <li> <a href="http://jakarta.apache.org/site/guidelines.html">Guidelines Notes</a> |
| </li> |
| <li> <a href="http://jakarta.apache.org/site/faqs.html">FAQs</a> |
| </li> |
| </ul> |
| <p><strong>Get Involved</strong></p> |
| <ul> |
| <li> <a href="http://jakarta.apache.org/site/getinvolved.html">Overview</a> |
| </li> |
| <li> <a href="http://jakarta.apache.org/site/cvsindex.html">Source Repositories</a> |
| </li> |
| <li> <a href="http://www.faqs.org/rfcs/rfc1855.html">Netiquette</a> |
| </li> |
| <li> <a href="http://jakarta.apache.org/site/mail.html">Mailing Lists</a> |
| </li> |
| <li> <a href="http://jakarta.apache.org/site/library.html">Reference Library</a> |
| </li> |
| <li> <a href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=BSF">Bug Database</a> |
| </li> |
| <li> <a href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=BSF&bug_severity=Enhancement">Enhancement Requests</a> |
| </li> |
| <li> <a href="http://issues.apache.org/bugzilla/buglist.cgi?bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&email1=&emailtype1=substring&emailassigned_to1=1&email2=&emailtype2=substring&emailreporter2=1&bugidtype=include&bug_id=&changedin=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&product=BSF&short_desc=%5BPATCH%5D&short_desc_type=allwordssubstr&long_desc=&long_desc_type=allwordssubstr&bug_file_loc=&bug_file_loc_type=allwordssubstr&keywords=&keywords_type=anywords&field0-0-0=noop&type0-0-0=noop&value0-0-0=&cmdtype=doit&order=Reuse+same+sort+as+last+time">Patch Queue</a> |
| </li> |
| </ul> |
| </td> |
| <td align="left" valign="top"> |
| <table border="0" cellspacing="0" cellpadding="2" width="100%"> |
| <tr><td bgcolor="#525D76"> |
| <font color="#ffffff" face="arial,helvetica,sanserif"> |
| <a name="Bean Scripting Framework"><strong>Bean Scripting Framework</strong></a> |
| </font> |
| </td></tr> |
| <tr><td> |
| <blockquote> |
| <p> |
| Bean Scripting Framework (BSF) is a set of Java classes which provides |
| scripting language support within Java applications, and |
| access to Java objects and methods from scripting languages. |
| </p> |
| </blockquote> |
| </td></tr> |
| </table> |
| <table border="0" cellspacing="0" cellpadding="2" width="100%"> |
| <tr><td bgcolor="#525D76"> |
| <font color="#ffffff" face="arial,helvetica,sanserif"> |
| <a name="BSF Architectural Overview"><strong>BSF Architectural Overview</strong></a> |
| </font> |
| </td></tr> |
| <tr><td> |
| <blockquote> |
| <p> |
| The two primary components of BSF are the <code>BSFManager</code> |
| and the <code>BSFEngine</code>. |
| </p> |
| <p> |
| The <code>BSFManager</code> handles all scripting execution engines |
| running under its control, and maintains the object registry that permits |
| scripts access to Java objects. By creating an instance of the |
| <code>BSFManager</code> class, a Java application can gain access to |
| scripting services. |
| </p> |
| <p> |
| The <code>BSFEngine</code> provides an interface that must be |
| implemented for a language to be used by BSF. This interface provides |
| an abstraction of the scripting language's capabilities that permits |
| generic handling of script execution and object registration within |
| the execution context of the scripting language engine. |
| </p> |
| <p> |
| An application can instantiate a single <code>BSFManager</code>, |
| and execute several different scripting languages identically via the |
| <code>BSFEngine</code> interface. Furthermore, all of the scripting |
| languages handled by the <code>BSFManager</code> are aware of the |
| objects registered with that <code>BSFManager</code>, and the execution |
| state of those scripting languages is maintained for the lifetime of |
| the <code>BSFManager</code>. |
| </p> |
| </blockquote> |
| </td></tr> |
| </table> |
| <table border="0" cellspacing="0" cellpadding="2" width="100%"> |
| <tr><td bgcolor="#525D76"> |
| <font color="#ffffff" face="arial,helvetica,sanserif"> |
| <a name="Installation"><strong>Installation</strong></a> |
| </font> |
| </td></tr> |
| <tr><td> |
| <blockquote> |
| <p> |
| BSF can be used standalone, as a class library, or as part of an |
| application server. In order to be used as a class library or as |
| a standalone system, you simply download a copy of the bsf.jar |
| file from the |
| <a href="http://jakarta.apache.org/bsf/index.html">BSF web site</a> |
| and include it in your classpath, along with any required classes |
| or jar files for desired languages. |
| </p> |
| <p> |
| In order to use BSF as part of the |
| <a href="http://jakarta.apache.org/tomcat/">Tomcat</a> |
| servlet engine, you must currently download patches from the BSF |
| web site that permit Jasper to call BSF. Instructions for this will be |
| posted on the website, and will soon be accompanied by prebuilt binaries. |
| We hope that these changes will be merged into Tomcat in the near |
| future. |
| </p> |
| </blockquote> |
| </td></tr> |
| </table> |
| <table border="0" cellspacing="0" cellpadding="2" width="100%"> |
| <tr><td bgcolor="#525D76"> |
| <font color="#ffffff" face="arial,helvetica,sanserif"> |
| <a name="Using BSF"><strong>Using BSF</strong></a> |
| </font> |
| </td></tr> |
| <tr><td> |
| <blockquote> |
| <table border="0" cellspacing="0" cellpadding="2" width="100%"> |
| <tr><td bgcolor="#828DA6"> |
| <font color="#ffffff" face="arial,helvetica,sanserif"> |
| <a name="BSF and JSPs"><strong>BSF and JSPs</strong></a> |
| </font> |
| </td></tr> |
| <tr><td> |
| <blockquote> |
| <p> |
| After you set up an application server that is BSF enabled, you can write |
| JSPs using any of the supported scripting languages. JSPs using scripting |
| languages differ only slightly from those using Java. |
| </p> |
| <p> |
| First, you must set the language attribute of the page directive |
| in the JSP to the desired language. For example, |
| |
| <p> |
| <code> |
| <%@ page language="javascript" %> |
| </code> |
| </p> |
| |
| sets the language used for the JSP to Javascript; any |
| <code>scriptlet</code>s or <code>expressions</code> within the JSP |
| will be handed off to BSF, which will in turn hand the code over to |
| Rhino for execution. |
| </p> |
| <p> |
| The standard set of JSP implicit objects is available within BSF. |
| These implicit objects must be used for input and output with respect |
| to the generated page, since the scripting languages do not have any |
| awareness of having been called within a JSP. For example, in order to |
| print a line of text into the page generated by the JSP, one must use the |
| <code>println()</code> method of the <code>out</code> implicit object. |
| </p> |
| <p> |
| Multiple languages can be supported within a given JSP; this is |
| accomplished by using the BSF taglibs, which are available from the |
| <a href="http://jakarta.apache.org/taglibs/index.html">Jakarta Taglibs</a> |
| project. BSF taglib provides two tags: <code>scriptlet</code> and |
| <code>expression</code>. Both of these have a required language attribute, |
| which is used to specify the language used on a per <code>scriptlet</code> |
| or <code>expression</code> basis. |
| </p> |
| </blockquote> |
| </td></tr> |
| </table> |
| <table border="0" cellspacing="0" cellpadding="2" width="100%"> |
| <tr><td bgcolor="#828DA6"> |
| <font color="#ffffff" face="arial,helvetica,sanserif"> |
| <a name="Servlets and Other Applications"><strong>Servlets and Other Applications</strong></a> |
| </font> |
| </td></tr> |
| <tr><td> |
| <blockquote> |
| <p> |
| Using BSF in servlets or applications is also quite simple. In order |
| to provide an application with scripting support, you need to |
| import the BSF class hierarchy and instantiate a <code>BSFManager</code> |
| object. After instantiating the <code>BSFManager</code>, you |
| register or declare any Java objects to be made available within the |
| scripting engine. Then call either one of the <code>eval()</code> |
| or <code>exec() BSFManager</code> methods (depending on whether you want to |
| evaluate a script and have the value of the evaluation returned, or |
| execute a script). Alternatively, you can call the |
| <code>loadScriptingEngine()</code> method in order to get an object |
| implementing the <code>BSFEngine</code> interface for the desired |
| scripting language. You can then call the <code>exec()</code> or |
| <code>eval()</code> methods of <code>BSFEngine</code> to run the script. |
| </p> |
| <p> |
| Additionally, BSF declares an object named <code>bsf</code> within a |
| scripting engine's execution context, which represents the |
| <code>BSFManager</code> that is associated with the scripting engine. |
| This object provides all of the methods and properties |
| associated with the <code>BSFManager</code> to the script. |
| However, the most used method within scripts is usually |
| <code>lookupBean()</code>, which is used to access objects |
| in BSF's object registry. |
| </p> |
| <p> |
| The most important methods within the <code>BSFManager</code> are: |
| |
| <ul> |
| <li><code>BSFManager</code>() - the <code>BSFManager</code> |
| constructor</li> |
| |
| <li><code>eval()</code> - used to evaluate a script and return |
| its value</li> |
| |
| <li><code>exec()</code> - used to execute a script </li> |
| |
| <li><code>loadScriptingEngine()</code> - used to return a |
| <code>BSFEngine</code> for the desired scripting language</li> |
| |
| <li><code>registerBean()</code> - adds an object to BSF's object |
| registry</li> |
| |
| <li><code>lookupBean()</code> - retrieves an object from BSF's |
| object registry</li> |
| |
| <li><code>declareBean()</code> - creates an implicit object in |
| the context of any loaded scripting language, which does not have |
| to be accessed via <code>lookupBean()</code></li> |
| </ul> |
| </p> |
| <p> |
| Other, less often used methods within the <code>BSFManager</code> are: |
| |
| <ul> |
| <li><code>apply()</code> - used to call anonymous functions</li> |
| |
| <li><code>compileExpr()</code> - used to compile an expression into a |
| <code>CodeBuffer</code> object</li> |
| |
| <li><code>compileScript()</code> - similar to compile expression, used to |
| compile scripts into <code>CodeBuffer</code> objects</li> |
| |
| <li><code>compileApply()</code> - similar to both of the above - used to |
| compile anonymous functions into <code>CodeBuffer</code> objects</li> |
| </ul> |
| </p> |
| <p> |
| For the curious, the <code>CodeBuffer</code> is a class provided by BSF for |
| storing generated Java code. |
| </p> |
| <p> |
| The <code>BSFManager</code> <code>exec()</code>, <code>eval()</code>, |
| and <code>apply()</code> methods (as well as their compile counterparts) |
| are wrappers over the equivalent methods presented by the |
| <code>BSFEngine</code> interface. If the programmer explicitly |
| loads a scripting engine via <code>loadScriptingEngine()</code>, they |
| can use the <code>exec()</code> or <code>eval()</code> methods of the |
| resulting <code>BSFEngine</code> as appropriate. |
| </p> |
| </blockquote> |
| </td></tr> |
| </table> |
| </blockquote> |
| </td></tr> |
| </table> |
| <table border="0" cellspacing="0" cellpadding="2" width="100%"> |
| <tr><td bgcolor="#525D76"> |
| <font color="#ffffff" face="arial,helvetica,sanserif"> |
| <a name="Adding BSF Support for a Scripting Language"><strong>Adding BSF Support for a Scripting Language</strong></a> |
| </font> |
| </td></tr> |
| <tr><td> |
| <blockquote> |
| <p> |
| In order to incorporate your own scripting language into BSF, you must first |
| write a class implementing the <code>BSFEngine</code> interface for the |
| language; examples are available in the BSF source distribution. |
| </p> |
| <p> |
| Usually, a scripting language author extends the |
| <code>BSFEngineImpl</code> class, which implements <code>BSFEngine</code>, |
| and only requires the scripting language author to implement the |
| <code>eval()</code> method. However, the following methods specified by |
| the <code>BSFEngine</code> interface are the most commonly implemented: |
| |
| <ul> |
| <li><code>initialize()</code> - used to set up the underlying scripting |
| language engine</li> |
| |
| <li><code>call()</code> - used to call functions or methods within the |
| scripting engine</li> |
| |
| <li><code>eval()</code> - used to evaluate a script</li> |
| |
| <li><code>exec()</code> - used to execute a script</li> |
| |
| <li><code>declareBean()</code> - used to create an implicit object within |
| the scripting language</li> |
| |
| <li><code>undeclareBean()</code> - used to remove an implicit object |
| from the scripting language</li> |
| </ul> |
| </p> |
| <p> |
| Once you have implemented the wrapper for your language engine, you |
| instantiate a <code>BSFManager</code> in your application, and register your |
| engine with it via the <code>registerScriptingEngine()</code> method. |
| Afterward, you may use your language within the application through the |
| usual BSF semantics. |
| </p> |
| </blockquote> |
| </td></tr> |
| </table> |
| <table border="0" cellspacing="0" cellpadding="2" width="100%"> |
| <tr><td bgcolor="#525D76"> |
| <font color="#ffffff" face="arial,helvetica,sanserif"> |
| <a name="Standalone Scripts"><strong>Standalone Scripts</strong></a> |
| </font> |
| </td></tr> |
| <tr><td> |
| <blockquote> |
| <p> |
| BSF provides a facility for running scripting languages itself. Simply running |
| <code>java org.apache.bsf.Main</code> will produce a help message, with |
| instructions on how to run these scripts. |
| </p> |
| </blockquote> |
| </td></tr> |
| </table> |
| </td> |
| </tr> |
| |
| <!-- FOOTER --> |
| <tr><td colspan="2"> |
| <hr noshade="" size="1"/> |
| </td></tr> |
| <tr><td colspan="2"> |
| <div align="center"><font color="#525D76" size="-1"><em> |
| Copyright © 2002-2006, Apache Software Foundation |
| </em></font></div> |
| </td></tr> |
| </table> |
| </body> |
| </html> |
| <!-- end the processing --> |
| |
| |
| |
| |