-
Notifications
You must be signed in to change notification settings - Fork 5
/
Copy pathbshmanual.html
8004 lines (6902 loc) · 237 KB
/
bshmanual.html
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
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="manual.xsl"?>
<html>
<head>
<title>BeanShell User's Manual</title>
</head>
<body bgcolor="#ffffff">
<table border="1" width="100%" height="100%">
<tr>
<td>
<table width="100%" height="100%">
<tr>
<td height="70%" align="center">
<font size="+4">BeanShell</font>
<br CLEAR="ALL" />
<font size="+3"><em>Simple Java Scripting</em></font>
<br CLEAR="ALL" />
<br CLEAR="ALL" />
<font size="+0"><em>version 1.3</em></font>
</td>
</tr>
<tr>
<td />
</tr>
</table>
</td>
</tr>
</table>
<!-- PAGE BREAK -->
<h1><a name="Table_of_Contents">Table of Contents</a></h1>
<ul>
<li><a href="#Table_of_Contents">Table of Contents</a></li>
<li><a href="#Introduction">Introduction</a></li>
<ul>
<li><a href="#Scripting_vs._Application_Languages">Scripting vs. Application Languages</a></li>
<li><a href="#Tearing_Down_the_Barriers">Tearing Down the Barriers</a></li>
<li><a href="#History">History</a></li>
<li><a href="#Conclusion">Conclusion</a></li>
</ul>
<li><a href="#Quick_Start">Quick Start</a></li>
<ul>
<li><a href="#Download_and_Run_BeanShell">
Download and Run BeanShell
</a></li>
<li><a href="#The_BeanShell_GUI">
The BeanShell GUI
</a></li>
<li><a href="#Java_Statements_and_Expressions">
Java Statements and Expressions
</a></li>
<li><a href="#Useful_BeanShell_Commands">
Useful BeanShell Commands
</a></li>
<li><a href="#Scripted_Methods">
Scripted Methods
</a></li>
<li><a href="#Implementing_Interfaces">Implementing Interfaces</a></li>
<li><a href="#Scripted_Objects">
Scripted Objects
</a></li>
<li><a href="#Calling_BeanShell_From_Your_Application">Calling BeanShell From Your Application</a></li>
<li><a href="#Conclusion">Conclusion</a></li>
</ul>
<li><a href="#Basic_Syntax">Basic Syntax</a></li>
<ul>
<li><a href="#Standard_Java_Syntax"> Standard Java Syntax </a></li>
<li><a href="#Loosely_Typed_Java_Syntax">Loosely Typed Java Syntax </a></li>
<li><a href="#Exception_Handling">Exception Handling</a></li>
<li><a href="#Basic_Scoping_of_Variables">Basic Scoping of Variables</a></li>
<li><a href="#Variable_Modifiers">Variable Modifiers</a></li>
<li><a href="#Convenience_Syntax">Convenience Syntax</a></li>
<li><a href="#Auto_Boxing_and_Unboxing">Auto Boxing and Unboxing</a></li>
<li><a href="#Importing_Classes_and_Packages">Importing Classes and Packages</a></li>
<li><a href="#Document_Friendly_Entities">Document Friendly Entities</a></li>
</ul>
<li><a href="#Scripted_Methods">Scripted Methods</a></li>
<ul>
<li><a href="#Scoping_of_Variables_and_Methods">Scoping of Variables and Methods</a></li>
<li><a href="#Scope_Modifier:_'super'">Scope Modifier: 'super'</a></li>
</ul>
<li><a href="#Scripted_Objects">Scripted Objects</a></li>
<ul>
<li><a href="#The_'this'_reference">The 'this' reference</a></li>
</ul>
<li><a href="#Scope_Modifiers">Scope Modifiers</a></li>
<ul>
<li><a href="#'this',_'super',_and_'global'">'this', 'super', and 'global'</a></li>
<li><a href="#Synchronized_Methods_Revisited">Synchronized Methods Revisited</a></li>
</ul>
<li><a href="#Scripting_Interfaces">Scripting Interfaces</a></li>
<ul>
<li><a href="#Anonymous_Inner-Class_Style">Anonymous Inner-Class Style</a></li>
<li><a href="#'this'_references_as_Interface_Types">'this' references as Interface Types</a></li>
<li><a href="#Interface_Types_and_Casting">Interface Types and Casting</a></li>
<li><a href="#"Dummy"_Adapters_and_Incomplete_Interfaces">"Dummy" Adapters and Incomplete
Interfaces</a></li>
<li><a href="#Threads_-_Scripting_Runnable">Threads - Scripting Runnable</a></li>
<li><a href="#Limitations">Limitations</a></li>
</ul>
<li><a href="#Special_Variables_and_Values">Special Variables and Values</a></li>
<ul>
<li><a href="#Special_Members_of_'this'_type_References">Special Members of 'this' type References</a></li>
<li><a href="#Undefined_Variables">Undefined Variables</a></li>
<li><a href="#Setting_the_Command_Prompt">Setting the Command Prompt</a></li>
</ul>
<li><a href="#BeanShell_Commands">BeanShell Commands</a></li>
<ul>
<li><a href="#Commands_Overview">Commands Overview</a></li>
</ul>
<li><a href="#Adding_BeanShell_Commands">Adding BeanShell Commands</a></li>
<ul>
<li><a href="#Hello_World">Hello World</a></li>
<li><a href="#Compiled_Commands">Compiled Commands</a></li>
<li><a href="#User_Defined_Commands_with_invoke()">User Defined Commands with invoke()</a></li>
<li><a href="#Commands_Scope">Commands Scope</a></li>
<li><a href="#Getting_the_Caller_Context">Getting the Caller Context</a></li>
<li><a href="#setNameSpace()">setNameSpace()</a></li>
<li><a href="#Getting_the_Invocation_Text">Getting the Invocation Text</a></li>
<li><a href="#Working_with_Dirctories_and_Paths">Working with Dirctories and Paths</a></li>
<li><a href="#Working_With_Class_Identifiers">Working With Class Identifiers</a></li>
<li><a href="#Working_with_Iterable_Types">Working with Iterable Types</a></li>
</ul>
<li><a href="#Strict_Java_Mode">Strict Java Mode</a></li>
<li><a href="#Class_Loading_and_Class_Path_Management">Class Loading and Class Path Management</a></li>
<ul>
<li><a href="#Changing_the_Class_Path">Changing the Class Path</a></li>
<li><a href="#Auto-Importing_from_the_Classpath">Auto-Importing from the Classpath</a></li>
<li><a href="#Reloading_Classes">Reloading Classes</a></li>
<li><a href="#Loading_Classes_Explicitly">Loading Classes Explicitly</a></li>
<li><a href="#Setting_the_Default_ClassLoader">Setting the Default ClassLoader</a></li>
<li><a href="#Class_Loading_in_Java">Class Loading in Java</a></li>
<li><a href="#Class_Loading_in_BeanShell">Class Loading in BeanShell</a></li>
</ul>
<li><a href="#Modes_of_Operation">Modes of Operation</a></li>
<ul>
<li><a href="#Standalone">Standalone</a></li>
<li><a href="#Remote">Remote</a></li>
<li><a href="#Interactive_Use">Interactive Use</a></li>
<li><a href="#The_.bshrc_Init_File">The .bshrc Init File</a></li>
</ul>
<li><a href="#Embedding_BeanShell_in_Your_Application">Embedding BeanShell in Your Application</a></li>
<ul>
<li><a href="#The_BeanShell_Core_Distribution">The BeanShell Core Distribution</a></li>
<li><a href="#Calling_BeanShell_From_Java">Calling BeanShell From Java</a></li>
<li><a href="#eval()">eval()</a></li>
<li><a href="#EvalError">EvalError</a></li>
<li><a href="#source()">source()</a></li>
<li><a href="#Multiple_Interpreters_vs._Multi-threading">Multiple Interpreters vs. Multi-threading</a></li>
<li><a href="#Serializing_Interpreters_and_Scripted_Objects">Serializing Interpreters and Scripted
Objects</a></li>
</ul>
<li><a href="#Remote_Server_Mode">Remote Server Mode</a></li>
<ul>
<li><a href="#Web_Browser_Access">Web Browser Access</a></li>
<li><a href="#Example">Example</a></li>
<li><a href="#Telnet_Access">Telnet Access</a></li>
</ul>
<li><a href="#BshServlet_and_Servlet_Mode_Scripting">BshServlet and Servlet Mode Scripting</a></li>
<ul>
<li><a href="#Deploying_BshServlet">Deploying BshServlet</a></li>
<li><a href="#Running_Scripts">Running Scripts</a></li>
<li><a href="#The_Script_Environment">The Script Environment</a></li>
<li><a href="#BshServlet_Parameters">BshServlet Parameters</a></li>
</ul>
<li><a href="#The_BeanShell_Demo_Applet">The BeanShell Demo Applet</a></li>
<li><a href="#BeanShell_Desktop">BeanShell Desktop</a></li>
<ul>
<li><a href="#Shell_Windows">Shell Windows</a></li>
<li><a href="#Editor_Windows">Editor Windows</a></li>
<li><a href="#The_Class_Browser">The Class Browser</a></li>
</ul>
<li><a href="#BshDoc_-_Javadoc_Style_Documentation">BshDoc - Javadoc Style Documentation</a></li>
<ul>
<li><a href="#BshDoc_Comments">BshDoc Comments</a></li>
<li><a href="#BshDoc_XML_Output">BshDoc XML Output</a></li>
<li><a href="#The_bshcommands.xsl_stylesheet">The bshcommands.xsl stylesheet</a></li>
</ul>
<li><a href="#The_BeanShell_Parser">The BeanShell Parser</a></li>
<ul>
<li><a href="#Validating_Scripts_With_bsh.Parser">Validating Scripts With bsh.Parser</a></li>
<li><a href="#Parsing_and_Performance">Parsing and Performance</a></li>
<li><a href="#Parsing_Scripts_Procedurally">Parsing Scripts Procedurally</a></li>
</ul>
<li><a href="#Using_JConsole">Using JConsole</a></li>
<ul>
<li><a href="#ConsoleInterface">ConsoleInterface</a></li>
</ul>
<li><a href="#Reflective_Style_Access_to_Scripted_Methods">Reflective Style Access to Scripted Methods</a></li>
<ul>
<li><a href="#eval()">eval()</a></li>
<li><a href="#invokeMethod()">invokeMethod()</a></li>
<li><a href="#Method_Lookup">Method Lookup</a></li>
<li><a href="#BshMethod">BshMethod</a></li>
<li><a href="#Uses">Uses</a></li>
</ul>
<li><a href="#Executable_scripts_under_Unix">Executable scripts under Unix</a></li>
<li><a href="#BSF_Bean_Scripting_Framework">BSF Bean Scripting Framework</a></li>
<ul>
<li><a href="#Ant">Ant</a></li>
</ul>
<li><a href="#Learning_More">Learning More</a></li>
<ul>
<li><a href="#Helping_With_the_Project">Helping With the Project</a></li>
</ul>
<li><a href="#Credit_and_Acknowledgments">Credit and Acknowledgments</a></li>
<ul>
<li><a href="#License_and_Terms_of_Use">License and Terms of Use</a></li>
</ul>
<li><a href="#BeanShell_Commands_Documentation">BeanShell Commands Documentation</a></li>
</ul> <!-- Auto generated table of contents -->
<hr />
<!--PAGE BREAK-->
<!-- Auto generated table of contents -->
<h1><a name="Introduction">Introduction</a></h1>
This document is about BeanShell.
BeanShell is a small, free, embeddable Java source interpreter with
object scripting language features, written in Java. BeanShell executes
standard Java statements and expressions but also extends Java into the
scripting domain with common scripting language conventions and syntax.
BeanShell is a <em>natural</em> scripting language for Java.
<p CLEAR="ALL" />
<h2><a name="Scripting_vs._Application_Languages">Scripting vs. Application Languages</a></h2>
Traditionally, the primary difference between a scripting language and
a compiled language has been in its type system: the way in which you define
and use data elements. You might be thinking that there is a more obvious
difference here - that of "interpreted" code vs. compiled code. But
the compiler in and of itself does not fundamentally change the way you work
with a language. Nor does interpreting a language necessarily make
it more useful for what we think of as "scripting".
It is the type system of a language that makes it possible for a compiler
to analyze the structure of an application for correctness.
Without types, compilation is reduced to just a grammar check and an
optimization for speed.
From the developer's perspective, it is also the type system that
characterizes the way in which we interact with the code.
<p CLEAR="ALL" />
Types are good. Without strongly type languages it would be very hard to
write large scale systems and make any assertions about their correctness
before they are run. But working with types imposes a burden on the developer.
Types are labels and labeling things can be tedious. It can be especially
tedious during certain kinds of development or special applications where
it is flexibility and not program structure that is paramount.
There are times where simplicity and ease of use is a more important
criterion.
<p CLEAR="ALL" />
This is not just rationalization to cover some underlying laziness.
Productivity affects
what people do and more importantly do *not* do in the real world, much more
than you might think. There is a lot of important software that exists in
the world today only because the cost/benefit ratio in some developer's mind
reached a certain threshold.
<p CLEAR="ALL" />
Unit testing - one of the foundations of
writing good code - is a prime example. Unit tests for well written code are,
in general, vitally important as a collective but almost insignificant
individually. It's a "tragedy of the commons" that leads individual
developers to repeatedly weigh the importance of writing another unit test
with working on "real code".
Give developers have a tool that makes it easy to perform a test with a line or
two of code they will probably use it. If, moreover, it is also a tool that
they enjoy using during their development process - that saves the time, they
will be even more inclined to use it.
<p CLEAR="ALL" />
Customizability through scripting also opens the door to applications that
are more powerful than the sum of their parts. When users can extend, enhance,
and add to their applications they use them in new and unexpected ways.
<p CLEAR="ALL" />
Scripting is powerful.
<p CLEAR="ALL" />
<h2><a name="Tearing_Down_the_Barriers">Tearing Down the Barriers</a></h2>
Traditionally scripting languages have traded
in the power of types for simplicity. Most scripting languages distill the
type system to just one or a handful of types such as strings, numbers, or
simple lists. This is sufficient for many kinds of scripting.
<p CLEAR="ALL" />
Many scripting languages operate in a loose, unstructured land - a place
dominated by text and course-grained tools.
As such these scripting languages have evolved
sophisticated mechanisms for working with these simple types (regular
expressions, pipes, etc.).
As a result there has developed a casm between the scripting languages
and the application languages created by the collapse of the type system
in-between.
The scripting languages have remained a separate species, isolated and
speaking a different dialect from their brothers the application languages.
<p CLEAR="ALL" />
BeanShell is a new kind of scripting language. BeanShell begins with
the standard Java language and bridges it into the scripting domain in a
natural way, but allowing the developer to relaxing types where appropriate.
It is possible to write BeanShell scripts that look exactly like Java
method code. But it's also possible to write scripts that look more like
a traditional scripting language, while still maintaining the framework
of the Java syntax.
<p CLEAR="ALL" />
BeanShell emulates typed variables and parameters when they are used. This
allows you to "seed" your code with strong types where appropriate. You can
"shore up" repeatedly used methods as you work on them, migrating them
closer to Java. Eventually you may find that you want to compile
these methods and maintain them in standard Java. With BeanShell this is
easy. BeanShell does not impose a syntactic boundary between your
scripts and Java.
<p CLEAR="ALL" />
But the bridge to Java extends much deeper than simple code similarity.
BeanShell is one of a new breed of scripting languages made possible by
Java's advanced reflection capabilities. Since BeanShell can run in the same
Java virtual machine as your application, you can freely work with real,
live, Java objects - passing them into and out of your scripts. Combined
with BeanShell's ability to implement Java interfaces, you can achieve
seamless and simple integration of scripting into your Java applications.
BeanShell does not impose a type boundary between your scripts and Java.
<p CLEAR="ALL" />
<h2><a name="History">History</a></h2>
What seems like an eternity ago, back in the summer of 1993, I was working at
Southwestern Bell Technology Resources and I was infatuated with the Tcl/Tk
scripting language.
On the advice of someone at Sun I also began playing around a bit with the
Oak language written by James Gosling.
Little did I know that within just a few years Oak, which would become Java,
would not only spark a revolution, but that I would be writing one of the
first books on the new Java language (Exploring Java,
O'Reilly & Associates) and creating
Java's first scripting language, BeanShell, drawing inspiration from Tcl.
<p CLEAR="ALL" />
BeanShell's first public release was not until 1997, but I had been
poking at it in one form or another for some time before that. BeanShell
as a language became practical when Sun added reflection to the Java language
in version 1.1. After that, and after having seen its value in helping me
create examples and snippets for the second edition of my book, I decided to
try to polish it up and release it.
<p CLEAR="ALL" />
BeanShell has slowly, but steadily gained popularity since then. It has
grown in fits and spurts as its contributor's time has allowed. But recently
BeanShell has achieved a sort of critical mass. BeanShell is distributed with
Emacs as part of the JDE and with Sun Microsystem's NetBeans / Forte for Java
IDEs. BeanShell is also bundled by BEA with their Weblogic application
server. We've had reports of BeanShell being used everywhere from
the high energy physics laboratory CERN, to classrooms teaching programming
to nine year olds. BeanShell is being used in everything from large
financial applications all the way down to embedded systems floating in Buoys
in the pacific ocean. I attribute this success to the power of the open
source development model and owe many thanks to everyone who has contributed.
<p CLEAR="ALL" />
<h2><a name="Conclusion">Conclusion</a></h2>
I believe that BeanShell is the simplest and most natural scripting language
for Java because it is, foremost, Java. BeanShell draws on a
rich history of scripting languages for its scripting syntax and uses it to
very conservatively extend the Java language into this new domain.
I hope that you have half as much fun using BeanShell as I have had working
on it and I welcome all comments and suggestions.
<p CLEAR="ALL" />
<hr />
<!--PAGE BREAK-->
<h1><a name="Quick_Start">Quick Start</a></h1>
Welcome to BeanShell.
This is a crash course to get you going. We'll leave out many
important options and details. Please see the rest of the user's guide
for more information.
<p CLEAR="ALL" />
<h2><a name="Download_and_Run_BeanShell">
Download and Run BeanShell
</a></h2>
Download the latest JAR file from http://www.beanshell.org
and start up BeanShell either in the graphical desktop mode or on
the command line.
<p CLEAR="ALL" />
If you just want to start playing around you may be able to launch the
BeanShell desktop by simply double clicking on the BeanShell JAR file. More
generally however you'll want to add the jar to your classpath so that you
can work with your own classes and applications easily.
<p CLEAR="ALL" />
To do this you can either drop the BeanShell JAR file into your Java
extensions folder or add it to your classpath. (Important: If you put
BeanShell in the extensions folder and wish to use it with BSF applications
like Jakarta Ant you must install the bsf.jar in the same location).
<p />
<center>
<table border="1" cellpadding="5" width="100%">
<tr>
<td bgcolor="#dfdfdc">
<pre>
To install as an extension place the bsh.jar file in your
$JAVA_HOME/jre/lib/ext folder. (OSX users: place the bsh.jar in
/Library/Java/Extensions or ~/Library/Java/Extensions for individual users.)
Or add BeanShell to your classpath like this:
unix: export CLASSPATH=$CLASSPATH:bsh-xx.jar
windows: set classpath %classpath%;bsh-xx.jar
</pre>
</td>
</tr>
</table>
</center>
<p />
<p />
<center>
<table cellpadding="5" border="1" width="100%">
<tr>
<td><strong>Tip:</strong><br CLEAR="ALL" />
You can modify the classpath from within BeanShell using the addClassPath()
and setClassPath() commands.
</td>
</tr>
</table>
</center>
<p />
You can then run BeanShell in either a GUI or command line mode:
<p />
<center>
<table border="1" cellpadding="5" width="100%">
<tr>
<td bgcolor="#dfdfdc">
<pre>
java bsh.Console // run the graphical desktop
or
java bsh.Interpreter // run as text-only on the command line
or
java bsh.Interpreter filename [ args ] // run script file
</pre>
</td>
</tr>
</table>
</center>
<p />
<p CLEAR="ALL" />
It's also possible to call BeanShell from within your own Java applications,
to reach it in a remote server mode for debugging, to use it as a servlet,
or even in an applet. See "BeanShell Modes of Operation" for more details.
<h2><a name="The_BeanShell_GUI">
The BeanShell GUI
</a></h2>
The BeanShell GUI desktop is meant to allow some experimentation with the
features of BeanShell. It is not intended to be a replacement for a full
featured IDE. Please check out the
<a href="http://www.jedit.org/">jEdit editor</a> for an example of a full
featured development environment based in part on BeanShell scripting
capabilities.
<p CLEAR="ALL" />
Upon starting the BeanShell in GUI mode a console window will open.
By right clicking on the desktop background you can open additional
console windows and other tools such as a simple class browser.
<p CLEAR="ALL" />
Each console window runs a separate instance of the BeanShell interpreter.
The graphical console supports basic command history, line editing,
cut and paste, and even class and variable name completion. From the console
you can open a simple editor window. In it you can write
scripts and use the 'eval' option to evaluate the text in the attached
console's workspace or a new workspace.
<p CLEAR="ALL" />
<h2><a name="Java_Statements_and_Expressions">
Java Statements and Expressions
</a></h2>
BeanShell understands standard Java statements, expressions, and
method declarations.
Statements and expressions are all of the normal things that you'd say
inside a Java method such as variable declarations and assignments,
method calls, loops, and conditionals.
<p CLEAR="ALL" />
You can use these exactly as they would appear in Java,
however in BeanShell you also have the option of working with "loosely typed"
variables. That is, you can simply omit the types of variables that you use
(both primitives and objects). BeanShell will only
signal an error if you attempt to misuse the actual type of the variable.
<p CLEAR="ALL" />
Here are some examples:
<p />
<center>
<table border="1" cellpadding="5" width="100%">
<tr>
<td bgcolor="#dfdfdc">
<pre>
foo = "Foo";
four = (2 + 2)*2/2;
print( foo + " = " + four ); // print() is a BeanShell command
// Do a loop
for (i=0; i<5; i++)
print(i);
// Pop up a frame with a button in it
button = new JButton( "My Button" );
frame = new JFrame( "My Frame" );
frame.getContentPane().add( button, "Center" );
frame.pack();
frame.setVisible(true);
</pre>
</td>
</tr>
</table>
</center>
<p />
<p CLEAR="ALL" />
<h2><a name="Useful_BeanShell_Commands">
Useful BeanShell Commands
</a></h2>
In the previous example we used a convenient "built-in" BeanShell command
called print(), to display values. print() does pretty
much the same thing as System.out.println() except that it insures that the
output always goes to the command line. print() also displays some types
of objects (such as arrays) more verbosely than Java would.
Another related command is show(), which toggles on and off automatic
display of the result of every line you type.
<p CLEAR="ALL" />
Here are a few other examples of BeanShell commands:
<ul>
<li> <strong>source(), run()</strong>
- Read a bsh script into this interpreter, or run it
in a new interpreter</li>
<li> <strong>frame()</strong>
- Display a GUI component in a Frame or JFrame.</li>
<li> <strong>load(), save()</strong>
- Load or save serializable objects to a file.</li>
<li> <strong>cd(), cat(), dir(), pwd(), etc.</strong>
- Unix-like shell commands</li>
<li> <strong>exec()</strong> - Run a native application </li>
<li><strong>javap()</strong> - Print the methods and fields of an object,
similar to the output of the Java javap command.</li>
<li> <strong>setAccessibility()</strong>
- Turn on unrestricted access to private and protected components.</li>
</ul>
<p CLEAR="ALL" />
See the complete list of <a href="bshcommands.html">BeanShell Commands</a>
for more information.
<p CLEAR="ALL" />
<p />
<center>
<table cellpadding="5" border="1" width="100%">
<tr>
<td><strong>Tip:</strong><br CLEAR="ALL" />
BeanShell commands are not really "built-in" but are simply BeanShell scripts
that are automatically loaded from the classpath. You can add your
own scripts to the classpath to extend the basic command set.
</td>
</tr>
</table>
</center>
<p />
<h2><a name="Scripted_Methods">
Scripted Methods
</a></h2>
You can declare and use methods in BeanShell just as you would in a Java class.
<p />
<center>
<table border="1" cellpadding="5" width="100%">
<tr>
<td bgcolor="#dfdfdc">
<pre>
int addTwoNumbers( int a, int b ) {
return a + b;
}
sum = addTwoNumbers( 5, 7 ); // 12
</pre>
</td>
</tr>
</table>
</center>
<p />
Bsh methods may also allow dynamic (loose) argument and return types.
<p />
<center>
<table border="1" cellpadding="5" width="100%">
<tr>
<td bgcolor="#dfdfdc">
<pre>
add( a, b ) {
return a + b;
}
foo = add(1, 2); // 3
foo = add("Oh", " baby"); // "Oh baby"
</pre>
</td>
</tr>
</table>
</center>
<p />
<h2><a name="Implementing_Interfaces">Implementing Interfaces</a></h2>
<em>Note: implementing arbitrary interfaces requires BeanShell be run
under a Java 1.3 or higher environment.</em>
<p CLEAR="ALL" />
You can use the standard Java anonymous inner class syntax to implement an
interface type with a script. For example:
<p />
<center>
<table border="1" cellpadding="5" width="100%">
<tr>
<td bgcolor="#dfdfdc">
<pre>
ActionListener scriptedListener = new ActionListener() {
actionPerformed( event ) { ... }
}
</pre>
</td>
</tr>
</table>
</center>
<p />
You don't have to script all of the methods of an interface. You can opt to
script only those that you intend to call if you want to.
The calling code will simply throw an exception if it tries to
invoke a method that isn't defined.
If you wish to override the behavior of a large number of methods - say to
produce a "dummy" adapter for logging - you can implement a special method
signature: invoke(name, args) in your scripted object. The invoke() method
is called to handle any undefined method invocations:
<p />
<center>
<table border="1" cellpadding="5" width="100%">
<tr>
<td bgcolor="#dfdfdc">
<pre>
ml = new MouseListener() {
mousePressed( event ) { ... }
// handle the rest
invoke( name, args ) { print("Method: "+name+" invoked!");
}
</pre>
</td>
</tr>
</table>
</center>
<p />
<h2><a name="Scripted_Objects">
Scripted Objects
</a></h2>
In BeanShell, as in JavaScript and Perl, method "closures" allow you to create
scripted objects. You can turn the results of a method call into an object
reference by having the method return the special value <strong>this</strong>.
You can then use the reference to refer to any variables set during the method
call. Useful objects need methods of course, so in BeanShell scripted methods
may also contain methods at any level. For example:
<p />
<center>
<table border="1" cellpadding="5" width="100%">
<tr>
<td bgcolor="#dfdfdc">
<pre>
foo() {
print("foo");
x=5;
bar() {
print("bar");
}
return this;
}
myfoo = foo(); // prints "foo"
print( myfoo.x ); // prints "5"
myfoo.bar(); // prints "bar"
</pre>
</td>
</tr>
</table>
</center>
<p />
If this "closure" thing seems strange to don't worry. It's just an
evolutionary step that languages acquired along the path to Objects.
Please see the user's manual for a more thorough explanation.
<p CLEAR="ALL" />
Within your scripts, BeanShell scripted objects
(i.e. any <em>'this'</em> type reference like myFoo in the previous example)
can automatically implement any Java interface type. When Java code calls
methods on the interface the corresponding scripted methods will be invoked to
handle them. BeanShell will automatically "cast" your scripted object
when you attempt to pass it as an argument to a method that takes an interface
type.
For passing script references outside of BeanShell, you can perform an
explicit cast where necessary. Please see the user manual for full details.
<p CLEAR="ALL" />
<h2><a name="Calling_BeanShell_From_Your_Application">Calling BeanShell From Your Application</a></h2>
You can evaluate text and run scripts from within your application by
creating an instance of the BeanShell interpreter and using the eval()
or source() commands. You may pass in variable references to objects you
wish to use in scripts via the set() method and retrieve results with the
get() method.
<p />
<center>
<table border="1" cellpadding="5" width="100%">
<tr>
<td bgcolor="#dfdfdc">
<pre>
import bsh.Interpreter;
Interpreter i = new Interpreter(); // Construct an interpreter
i.set("foo", 5); // Set variables
i.set("date", new Date() );
Date date = (Date)i.get("date"); // retrieve a variable
// Eval a statement and get the result
i.eval("bar = foo*10");
System.out.println( i.get("bar") );
// Source an external script file
i.source("somefile.bsh");
</pre>
</td>
</tr>
</table>
</center>
<p />
<p />
<center>
<table cellpadding="5" border="1" width="100%">
<tr>
<td><strong>Tip:</strong><br CLEAR="ALL" />In the above example the Interpreter's eval() method also
returned the
value of bar as the result of the evaluation.</td>
</tr>
</table>
</center>
<p />
<h2><a name="Conclusion">Conclusion</a></h2>
We hope this brief introduction gets you started. Please see the full user
manual for more details. Please consult the mailing list archives for
more useful information. http://www.beanshell.org/
<hr />
<!--PAGE BREAK-->
<h1><a name="Basic_Syntax">Basic Syntax</a></h1>
BeanShell is, foremost, a Java interpreter. So you probably already know
most of what you need to start scripting with BeanShell. This
section describes specifically what portion of the Java language BeanShell
interprets and how BeanShell extends it or "loosens" it to be more
scripting-language-like.
<p CLEAR="ALL" />
<h2><a name="Standard_Java_Syntax"> Standard Java Syntax </a></h2>
In a BeanShell script (and on the command line) you can type normal
Java statements and expressions and display the results.
Statements and expressions are the kinds of things you normally find
inside of a Java method: variable assignments, method calls, math
expressions, for-loops, etc.
<p CLEAR="ALL" />
Here are some examples:
<p />
<center>
<table border="1" cellpadding="5" width="100%">
<tr>
<td bgcolor="#dfdfdc">
<pre>
/*
Standard Java syntax
*/
// Use a hashtable
Hashtable hashtable = new Hashtable();
Date date = new Date();
hashtable.put( "today", date );
// Print the current clock value
print( System.currentTimeMillis() );
// Loop
for (int i=0; i<5; i++)
print(i);
// Pop up a frame with a button in it
JButton button = new JButton( "My Button" );
JFrame frame = new JFrame( "My Frame" );
frame.getContentPane().add( button, "Center" );
frame.pack();
frame.setVisible(true);
</pre>
</td>
</tr>
</table>
</center>
<p />
You can also define your own methods and use them just as you would inside a
Java class. We'll get to that in a moment.
<h2><a name="Loosely_Typed_Java_Syntax">Loosely Typed Java Syntax </a></h2>
In the examples above, all of our variables have declared types. e.g.
"JButton button". Beanshell will enforce these types, as you will see if
you later try to assign something other than a JButton to the variable
"button" (you will get an error message).
However BeanShell also supports "loose" or dynamically typed variables.
That is, you can refer to
variables without declaring them first and without specifying any type.
In this case BeanShell will do type checking where appropriate at runtime.
So, for example, we could have left off the types in the above example and
written all of the above as:
<p />
<center>
<table border="1" cellpadding="5" width="100%">
<tr>
<td bgcolor="#dfdfdc">
<pre>
/*
Loosely Typed Java syntax
*/
// Use a hashtable
hashtable = new Hashtable();
date = new Date();
hashtable.put( "today", date );
// Print the current clock value
print( System.currentTimeMillis() );
// Loop
for (i=0; i<5; i++)
print(i);
// Pop up a frame with a button in it
button = new JButton( "My Button" );
frame = new JFrame( "My Frame" );
frame.getContentPane().add( button, "Center" );
frame.pack();
frame.setVisible(true);
</pre>
</td>
</tr>
</table>
</center>
<p />
This may not seem like it has saved us a great deal of work. But you will
see the difference when you come to rely on scripting as part of your
development and testing process; especially for in interactive use.
<p CLEAR="ALL" />
When a "loose" variable is used you are free to reassign it to another type of
Java object later. Untyped BeanShell variables can also freely hold Java
primitive values like <b>int</b>
and <b>boolean</b>. Don't worry, BeanShell always knows the real types and
only lets you use the values where appropriate. For primitive types this
includes doing the
correct numeric promotion that the real Java language would do when you use
them in an expression.
<p CLEAR="ALL" />
<h2><a name="Exception_Handling">Exception Handling</a></h2>
Exception handling using try/catch blocks works just as it does in Java.
For example:
<p />
<center>
<table border="1" cellpadding="5" width="100%">
<tr>
<td bgcolor="#dfdfdc">
<pre>
try {
int i = 1/0;
} catch ( ArithmeticException e ) {
print( e );
}
</pre>
</td>
</tr>
</table>
</center>
<p />
But you can loosely type your catch blocks if you wish:
<p />
<center>
<table border="1" cellpadding="5" width="100%">
<tr>
<td bgcolor="#dfdfdc">
<pre>
try {
...
} catch ( e ) {
print( "caught exception: "+e );
}
</pre>
</td>
</tr>
</table>
</center>
<p />
<h2><a name="Basic_Scoping_of_Variables">Basic Scoping of Variables</a></h2>
<p />
<center>
<table cellpadding="5" border="1" width="90%">
<tr>
<td bgcolor="#eeeebb"><strong>Note:</strong><br CLEAR="ALL" />
As of BeanShell version 1.3 the default scoping of loosely typed variables was
changed to be more consistent with Java. BeanShell still supports an alternate
scoping used in earlier versions. This mode can be enabled for legacy code by
setting the system property "localscoping" to true.
See appendix "Local Scoping".
</td>
</tr>
</table>
</center>
<p />
Variable scoping in BeanShell behaves, wherever possible, just like that in
Java. Ordinary Java, however, does not offer "loose" variables
(variables that can be used without being declared first).
So we must define their behavior within BeanShell.
We'll see in the next section that untyped variables - variables that are not
declared and not assigned a value elsewhere - default to the