1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
|
<!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/binindex.html">Binaries</a>
</li>
<li> <a href="http://jakarta.apache.org/site/sourceindex.html">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">CVS 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>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Debugging"><strong>Debugging</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>
Debugging support has been added to BSF over the last year. In its
current form, only debugging of Javascript in JSPs is supported. The
focus has been to design an API that would permit a generic debugging
framework for multiple scripting engines; however, this has remained
an goal for BSF 3.0. Included in the debugging support for BSF 2.3 is a
rudimentary command-line debugger named jsdb, which acts as a client
to a debugging server that is managed by the <code>BSFManager</code>.
</p>
<p>
An example of a production debugger using the BSF debugging engine is at
<a href="http://www.eclipse.org/">http://www.eclipse.org/</a>.
</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, Apache Software Foundation
</em></font></div>
</td></tr>
</table>
</body>
</html>
<!-- end the processing -->
|
