3 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
4 <META NAME="GENERATOR" CONTENT="Mozilla/4.05 [en] (Win95; I) [Netscape]">
5 <TITLE>BeanShell User's Guide</TITLE>
9 <H1>BeanShell User's Guide</H1>
12 <A NAME="Introduction"></A>Introduction</H2>
13 This guide explains how to use version 1.2.7 of the BeanShell Java interpreter with the
14 Java Development Environment for Emacs. This guide contains the following
18 <TABLE BORDER=0 WIDTH="100%" >
20 <TD><A HREF="#About">About the BeanShell</A> </TD>
22 <TD>Brief overview of the BeanShell </TD>
26 <TD VALIGN=TOP><A HREF="#Using">Using the BeanShell</A> </TD>
28 <TD>Explains how to start and shut down the BeanShell, enter statements,
29 and show results.</TD>
33 <TD VALIGN=TOP><A HREF="#LanguageRef">The BeanShell Language</A> </TD>
35 <TD>Describes the Java constructs and scripting extensions supported by
40 <TD VALIGN=TOP><A HREF="#ClassPathManagement">Class Loading and Class Path Management</A></TD>
42 <TD>Explains how to load classes and change the BeanShell class path dynamically.</TD>
46 <TD><A HREF="#CommandRef">BeanShell Commands</A> </TD>
48 <TD>Describes the commands supported by the BeanShell</TD>
53 <A NAME="About"></A>About the BeanShell</H2>
54 The BeanShell is a Java interpreter that evaluates Java statements directly
55 (without first compiling them). The BeanShell has been included in
56 the JDE with the permission of its author, <A HREF="mailto:pat@pat.net">Pat
59 <P>The BeanShell can operate as a stand-alone application or as a part
60 of another application. When running as a stand-alone application, the
61 interpreter accepts input from the command line of the shell in which it
62 runs. The BeanShell distribution includes a shell for running the interpreter.
63 It can, however, be run from other shells, such as bash or the DOS command
64 window. The JDE includes a command for running the BeanShell in an Emacs
65 shell (comint) buffer. This enables you to interact with the interpreter
66 directly while developing Java programs.
68 <P>The JDE also uses the interpreter to implement some JDE commands.
69 The JDE invokes the interpreter via Lisp functions that pass Java statements
70 to the interpreter via the standard input of the interpreter process and
71 retrieve results via the standard output. This guide documents BeanShell
72 functionality that seems relevant to JDE users. See the <A HREF="http://www.ooi.com/beanshell/">BeanShell
73 home page</A> home page for additional information and to download the
74 latest version of the BeanShell.
76 <A NAME="Using"></A>Using the BeanShell</H2>
79 <A NAME="Starting"></A>Starting the BeanShell</H3>
80 To start the BeanShell, select <B><FONT SIZE=-1>Interpret</FONT></B> from
81 the <B><FONT SIZE=-1>JDE</FONT></B> menu or enter the command <TT>M-x bsh</TT>.
82 Emacs starts the BeanShell, if not already started, and displays its prompt
83 in an Emacs shell buffer window.
85 <P><IMG SRC="images/BeanShellBuffer.gif" HEIGHT=536 WIDTH=664>
87 <P>The JDE allows you to run only one instance of the BeanShell at a time.
88 If an instance is already running, the <TT>bsh</TT> command simply
89 displays the buffer containing the instance, without starting another instance.
90 Note that you can indirectly start a BeanShell instance when you invoke
91 commands implemented as hybrid Lisp/Java scripts, such as <TT>jde-wiz-override-method</TT>.
92 Such commands start a BeanShell instance if one is not already running.
94 <A NAME="Evaluating"></A>Evaluating Statements</H3>
95 To evaluate a Java statement, type it at the BeanShell prompt and press
96 the <B><FONT SIZE=-1>Enter</FONT></B> key. The BeanShell evaluates the
97 statement. When it is done, it redisplays the the BeanShell command prompt.
98 You can then enter another statement.
100 <P>Statements must conform to Java syntax. For example, simple statements
101 must end in a semicolon. Compound statements, such as if-then constructs,
102 must end in a right brace. Statements may span multiple lines. To continue
103 a statement on a new line, press the <B><FONT SIZE=-1>Enter</FONT></B>
104 key. The BeanShell does not evaluate the statement until you have entered
105 the last line of the statement.
107 <P><IMG SRC="images/BshMultiLineEx.gif" HEIGHT=264 WIDTH=576>
110 <A NAME="Displaying"></A>Displaying Results</H3>
111 You can display the results of evaluating Java statements via the BeanShell
112 <TT>print</TT> and <TT>show</TT> commands. The print command accepts any
113 Java expression as an argument and displays the result of evaluating that
114 expression in the BeanShell window. For example,
115 <BLOCKQUOTE><TT>print(2+2);</TT></BLOCKQUOTE>
117 <BLOCKQUOTE><TT>4</TT></BLOCKQUOTE>
118 in the BeanShell window. Note that <TT>print(expr)</TT> is equivalent to
119 <TT>System.out.println(expr)</TT> and you can use either method to print
122 <P>The <TT>show();</TT> command toggles automatic display of the results
123 of evaluating statements as they are entered.
125 <A NAME="Exiting"></A>Exiting the Shell</H3>
126 To exit the BeanShell, enter
127 <BLOCKQUOTE><TT>exit();</TT></BLOCKQUOTE>
128 at the command prompt.
130 <A NAME="LanguageRef"></A>The BeanShell Language</H2>
133 <A NAME="JavaSupport"></A>Java Language Support</H3>
134 The BeanShell language includes most of the constructs of the Java language.
135 Standard Java constructs supported by the BeanShell include variable
136 assignments, method calls, math expressions, for-loops, etc.. Here are
138 <PRE> // Use a hashtable
139 Hashtable h = new Hashtable();
140 Date d = new Date();
141 h.put("today", d);
143 // Print the current clock value
144 print( System.currentTimeMillis() );
146 // Loop
147 for (int i=0; i<5; i++)
148 print(i);
150 // Pop up an AWT frame with a button in it
151 Button b = new Button("My Button");
152 Frame f = new Frame("My Frame");
153 f.add(b, "Center");
154 f.pack();
155 f.show();</PRE>
156 By default, the BeanShell imports the Java core classes at startup. You
157 can import additional classes, using standard Java import syntax, for example,
158 <BLOCKQUOTE><TT>import mypackage.*;</TT></BLOCKQUOTE>
160 <PRE> import mypackage.MyClass;</PRE>
163 <A NAME="ScriptExtensions"></A>Scripting Extensions</H3>
164 The BeanShell defines a number of extensions to the Java language designed
165 to facilitate creation of scripts. The scripting extensions include
168 Script Variables</LI>
174 Implicit Objects</LI>
177 Syntax for accessing Bean properties and Hashtable entries</LI>
181 <A NAME="ScriptVariables"></A>Script Variables</H3>
182 The BeanShell allows you to create a special type of variable named a script
183 variable. Unlike a standard Java variable, which can reference objects
184 only of a specified type, a script variable can be defined to reference
185 any type of object, including primitive types, such as <TT>int</TT> and
186 <TT>boolean</TT>. You create a script variable by declaring it with or
187 without a type specifier. If you include a type specifier, the variable
188 can reference only values of the specified type. If you do not specify
189 a type, the variable can reference values of any type. For example, the
191 <PRE> foo = new Button("Another Button");</PRE>
192 creates an untyped script variable named <TT>foo</TT> and assigns it a
193 Button object. You are free to subsequently assign <TT>foo</TT> to
194 any other type of object.
196 Predefined Variables</H4>
200 <B>$_</B> - the value of the last expression evaluated.</LI>
203 <B>bsh.Console bsh.console</B> - The primary console, if one exists.</LI>
206 <B>java.awt.AppletContext bsh.appletcontext</B> - the applet context, if
210 <B>String bsh.cwd</B> - used by the cd() and dir() commands.</LI>
213 <B>boolean bsh.show</B> - used by the show() command.</LI>
216 <B>boolean bsh.interactive</B> - is this interpreter running in an interactive
217 mode or sourcing a file?</LI>
220 <B>boolean bsh.evalOnly</B> - Does this interpreter have an input stream
221 or is it only serving as a bag for eval() operations.</LI>
225 Undefined variables</H4>
226 You can test to see if a variable is "undefined" with the value <TT>void</TT>,
228 <PRE> if ( foobar == void )
229 // undefined</PRE>
230 You can return a defined variable to the undefined state using the unset()
232 <BLOCKQUOTE><TT>a == void; // true</TT>
234 <BR><TT>unset("a"); // note the quotes</TT>
235 <BR><TT>a == void; // true</TT></BLOCKQUOTE>
238 <A NAME="ScriptMethods"></A>Script Methods</H3>
239 BeanShell lets you define and use a special type of method called a script
240 method. Script methods differ from standard Java methods in the following
244 Script methods are methods of an implicit, typeless object</LI>
247 Script methods can be defined to accept and return values of any type</LI>
250 Script methods can define other script methods</LI>
252 You use standard Java syntax to declare a script method that accepts
253 and returns specific types. For example, the following code
254 <PRE> int addTwoNumbers( int a, int b ) {
255 return a + b;
256 }</PRE>
257 defines a BeanShell method called <TT>addTwoNumbers</TT> that accepts and
258 returns values of type <TT>int</TT>. The next example
259 <PRE> int a = addTwoNumbers( 5, 7 );</PRE>
260 uses the newly defined method to add two values of type <TT>int</TT>.
262 <P>You define an untyped script method by omitting type specifications.
263 For example, the following statement
264 <PRE> add( a, b ) {
265 return a + b;
266 }</PRE>
267 defines a script method that accepts arguments of any type. When you invoke
268 an untyped script method, BeanShell interprets the method based on the
269 types of the arguments that you pass to the method. Consider, for example,
270 the following invocations of the untyped add method defined in the preceding
272 <PRE> foo = add(1, 2);
273 print( foo ); // 3
275 foo = add("Oh", " baby");
276 print( foo ); // Oh baby</PRE>
277 The first invocation returns the result of adding, the second, of concatenating
280 <P>Methods with unspecified return types may return any type of object
281 or no object. A return statement is optional. If omitted, the method returns
282 the value of the last statement or expression in the method body.
284 Method Namespace</H4>
285 The namespaces of script methods and variables are separate. Thus, you
286 can define a method and a variable having the same name.
289 Script methods may define methods, for example,
290 <PRE> foo() {
291 bar() {
292 ...
293 }
294 }</PRE>
295 Method may be nested in this way to an arbitrary depth. Within a nested
296 method, locally declared variables and methods shadow identically
297 named variables and methods declared in outer methods. Otherwise, variables
298 and methods are visible to an arbitrary depth of scope. Outer methods can
299 invoke methods defined by inner methods that return a <TT>this</TT> object.
303 <A NAME="ImplicitObjects"></A>Implicit Objects</H3>
304 The methods and variables defined by a script method are considered to
305 be methods and fields of an implicit object. The reserved identifiers,
306 <TT>this</TT>, <TT>super</TT>, and <TT>global</TT>, refer, respectively,
307 to the current object, the calling object, and the global object. A method
308 can access any variable or method in these scopes by qualifying the variable's
309 name with the name of the appropriate implicit object.
310 <PRE> a = 42;
311 foo() {
312 a = 97;
313 print( a );
314 print( this.a );
315 print( super.a );
318 foo(); // prints 97, 97, 42</PRE>
319 A script method can return its implicit object, thereby allowing the invoking
320 script to access variables and methods defined by the method, using standard
321 Java "." notation. For example,
322 <PRE> foo() {
323 int a = 42;
324 bar() {
325 print("The bar is open!");
326 }
327
328 bar();
329 return this;
332 obj = foo(); // prints "the bar is open!"
333 print ( obj.a ) // 42
334 obj.bar(); // prints "the bar is open!"</PRE>
337 Using Implicit Objects as AWT Event Handlers</H4>
338 Implicit method objects can serve as AWT event handlers. To handle an AWT
339 event, a script method defines the appropriate event-handling method and
340 then registering its implicit (<TT>this</TT>) object with the object in
341 which the event originates. For example, the following script
342 <PRE> button = new java.awt.Button("foo!");
344 actionPerformed( event ) {
345 print( event );
348 button.addActionListener( this );
349 frame( button ); // show it</PRE>
350 defines an Action event handler and registers it with a button.
352 <P>Remember that you don't have to define all of your event handlers globally.
353 You can handle events in any bsh object scope. For example, the following
354 method creates a button that displays a message when pushed:
355 <PRE> messageButton( message ) {
356 b = new Button("Press Me");
357 b.addActionListener( this );
358 frame(b);
359
360 actionPerformed( e ) {
361 print( message );
362 }
365 messageButton("Hey you!");
366 messageButton("Another message...");</PRE>
367 The above will create two buttons and each will display its own message
368 when pushed. Each has a separate instance of the event handler object.
369 Note too that we could return a 'this' reference from the handler method
370 and use it in other contexts to register listeners...
372 Using Implicit Objects as Threads</H4>
373 'This' type references also implement the standard Runnable interface,
374 so you can declare a "run()" method in your objects:
375 <BLOCKQUOTE> <TT> foo() {</TT>
376 <BR><TT> run() {</TT>
377 <BR><TT>
379 <BR><TT> }</TT>
380 <BR><TT> return this;</TT>
382 <P><TT> }</TT>
384 <BR><TT> foo = foo();</TT>
385 <BR><TT> new Thread( foo ).start();</TT>
386 <BR> </BLOCKQUOTE>
389 Implicit Object Members</H4>
390 Implicit objects have four "magic" members:
394 <TT>this.interpreter</TT> refers to the currently executing BeanShell Interpreter
398 <TT>this.namespace</TT> refers to the BeanShell NameSpace object of the
399 current context.</LI>
402 <TT>this.variables</TT> refers to an array of strings listing the variables
403 defined in this namespace.</LI>
406 <TT>this.methods</TT> refers to an array of strings listing the methods
407 defined in this namespace.</LI>
410 These are mainly for internal use by BeanShell commands. Note that there
411 are certain special situations in which the <TT>this.interpreter</TT> reference
412 may not be available, such as in AWT event handlers.
414 <A NAME="PropSyntax"></A>Extended Syntax for Accessing Bean Properties
415 and Hashtables Entries</H3>
416 You may use the following syntax
417 <BLOCKQUOTE><TT>x{name}</TT></BLOCKQUOTE>
418 to access properties of Java beans and Hashtable entries, where <TT>x</TT>
419 is a bean or Hashtable and <TT>name</TT> is a String that identifies a
420 bean property or hashtable entry, for example:
421 <PRE> b = new java.awt.Button();
422 b{"label"} = "my button";
423 // Equivalent to: b.setLabel("my button");
425 h = new Hashtable();
426 h{"foo"} = "bar";
427 // Equivalent to: h.put("foo", "bar");</PRE>
430 <h2><a name="ImplementingInterfaces">Implementing Interfaces</a></h2>
432 <p><strong>Note</strong> Implementing arbitrary interfaces requires BeanShell be running under a Java 1.3 environment or higher.</p>
434 <p>You can use the standard Java anonymous inner class syntax to implement an interface type with a script. For example:</p>
438 ActionListener scriptedListener = new ActionListener() {
439 actionPerformed( event ) { ... }
444 <p>You don't have to implement all of the methods defined by an interface.
445 The calling code throws an exception if it tries to invoke a method
446 that isn't defined. If you wish to override the behavior of a large
447 number of methods - say to produce a "dummy" adapter for logging - you
448 can implement a special method signature: <code>invoke(name, args)</code> in your
449 scripted object. The <code>invoke()</code> method is called to handle any undefined
450 method invocations: </p>
453 ml = new MouseListener() {
454 mousePressed( event ) { ... }
456 invoke( name, args ) { print("Method: "+name+" invoked!");
461 <h2><a name="ClassPathManagement">Class Loading and Class Path Management</a></h2>
464 <p>BeanShell is capable of some very fine grained and sophisticated class
465 reloading and modifications to the class path. BeanShell can even map
466 the entire class path to allow for automatic importing of classes.</p>
469 <h3><a name="Changing_the_Class_Path">Changing the Class Path</a></h3>
471 <strong>addClassPath( URL | path )</strong>
474 Add the specified directory or archive to the classpath. Archives may be
475 located by URL, allowing them to be loaded over the network.
480 <p/><center><table border="1" cellpadding="5" width="100%"><tr><td bgcolor="#dfdfdc">
482 addClassPath( "/home/pat/java/classes" );
483 addClassPath( "/home/pat/java/mystuff.jar" );
484 addClassPath( new URL("http://myserver/~pat/somebeans.jar") );
486 </td></tr></table></center><p/>
488 Note that if you add class path that overlaps with the existing Java user
489 classpath then the new path will effectively reload the classes in that
493 If you add a relative path to the classpath it is evaluated to an absolute
494 path; it does not "move with you".
496 <p/><center><table border="1" cellpadding="5" width="100%"><tr><td bgcolor="#dfdfdc"><pre>
498 addClassPath("."); // /tmp
499 </pre></td></tr></table></center><p/>
501 <strong>setClassPath( URL [] )</strong>
503 Change the entire classpath to the specified array of directories and/or
507 This command has some important side effects. It effectively causes all
508 classes to be reloaded (including any in the Java user class path at startup).
509 Please see "Class Reloading" below for further details.
512 Note: setClassPath() cannot currently be used to make the classpath smaller
513 than the Java user path at startup.
517 <h3><a name="Auto-Importing_from_the_Classpath">Auto-Importing from the Classpath</a></h3>
519 As an alternative to explicitly importing class names you may use the
520 following statement to trigger automatic importing:
522 <p/><center><table border="1" cellpadding="5" width="100%"><tr><td bgcolor="#dfdfdc"><pre>
524 </pre></td></tr></table></center><p/>
526 There may be a significant delay while the class path is mapped. This is why
527 auto-importing is not turned on by default. When run interactively, Bsh will
528 report the areas that it is mapping.
531 It is only necessary to issue the auto-import command once. Thereafter changes
532 in the classpath via the addClassPath() and setClassPath() commands will
537 Note: As of BeanShell 1.1alpha new class files added to the classpath
538 (from outside of BeanShell) after mapping will not be seen in imports.
542 <h3><a name="Reloading_Classes">Reloading Classes</a></h3>
544 BeanShell provides an easy to use mechanism for reloading classes from the
545 classpath. It is possible in BeanShell to reload arbitrary subsets of classes
546 down to a single class file. However There are subtle issues to be understood
547 with respect to what it means to reload a class in the Java environment.
548 Please see the discussion of class loading detail below. But in a nutshell,
549 it is important that classes which work together be reloaded together at
550 the same time, unless you know what you are doing.
553 <strong>reloadClasses( [ package name ] )</strong>
555 The most course level of class reloading is accomplished by issuing the
556 reloadClasses() command with no arguments.
558 <p/><center><table border="1" cellpadding="5" width="100%"><tr><td bgcolor="#dfdfdc"><pre>
560 </pre></td></tr></table></center><p/>
562 This will effectively reload all
563 classes in the current classpath (including any changes you have made through
568 Note: that reloading the full path is actually a light weight operation that
569 simply replaces the class loader - normal style class loading is done as
570 classes are subsequently referenced.
574 Be aware that any object instances which you have previously created may not
575 function with new objects created by the new class loader. Please see the
576 discussion of class loading details below.
579 You can also reload all of the classes in a specified package:
581 <p/><center><table border="1" cellpadding="5" width="100%"><tr><td bgcolor="#dfdfdc"><pre>
582 reloadClasses("mypackage.*");
583 </pre></td></tr></table></center><p/>
585 This will reload only the classes in the specified package. The classes will
586 be reloaded even if they are located in different places in the classpath (e.g.
587 if you have some of the package in one directory and some in another).
590 As a special case for reloading unpackaged classes the following commands
592 <p/><center><table border="1" cellpadding="5" width="100%"><tr><td bgcolor="#dfdfdc"><pre>
594 reloadClasses("<unpackaged>")
595 </pre></td></tr></table></center><p/>
598 You can also reload just an individual class file:
599 <p/><center><table border="1" cellpadding="5" width="100%"><tr><td bgcolor="#dfdfdc"><pre>
600 reloadClasses("mypackage.MyClass")
601 </pre></td></tr></table></center><p/>
603 <em>Note: As of alpha1.1 classes contained in archives (jar files) cannot be
604 reloaded. i.e. jar files cannot be swapped.</em>
607 <h3>Mapping the path</h3>
609 Unlike the reloadClases() command which reloads the entire class path,
610 when you issue a command to reload a package or individual class name
611 BeanShell must map some portions of the classpath to find the location of
612 those class files. This operation can be time consuming, but it is only
613 done once. If running in interactive mode feedback will be given on the
614 progress of the mapping.
617 <h3><a name="Loading_Classes_Explicitly">Loading Classes Explicitly</a></h3>
619 In order to perform an explicit class lookup by name while taking into
620 account any BeanShell class path modification you must use a replacement
621 for the standard Class.forName() method.
624 The getClass() command will load a class by name, using the BeanShell
625 classpath. Alternately, you can consult the class manager explicitly:
627 <p/><center><table border="1" cellpadding="5" width="100%"><tr><td bgcolor="#dfdfdc"><pre>
628 name="foo.bar.MyClass";
629 c = getClass( name );
630 c = BshClassManager.classForName( name ); // equivalent
631 </pre></td></tr></table></center><p/>
633 <h3><a name="Setting_the_Default_ClassLoader">Setting the Default ClassLoader</a></h3>
635 The bsh.Interpeter setClassLoader() and bsh.BshClassManager.setClassLoader()
636 methods can be used to set an external class loader which is consulted
637 for all basic class loading in BeanShell.
640 BeanShell will use the specified class loader at the same point where it
641 would otherwise use the plain Class.forName(). If no explicit classpath
642 management is done from the script (addClassPath(), setClassPath(),
643 reloadClasses()) then BeanShell will only use the supplied classloader.
644 If additional classpath management is done then BeanShell will perform that
645 in addition to the supplied external classloader. However BeanShell is not
646 currently able to reload classes supplied through the external classloader.
650 <h3><a name="Class_Loading_in_Java">Class Loading in Java</a></h3>
652 A fundamental Java security proposition is that classes may only be loaded
653 through a class loader once and that classes loaded through different class
654 loaders live in different name spaces. By different name spaces I mean that
655 they are not considered to be of the same type, even if they came from the
656 very same class file.
658 You can think of this in the following way: When you load classes through
659 a new class loader imagine that every class name is prefixed with the
660 identifier "FromClassLoaderXXX" and that all internal references to other
661 classes loaded through that class loader are similarly rewritten. Now if
662 you attempt to pass a reference to a class instance loaded through another
663 class loader to one of your newly loaded objects, it will not recognize it
664 as the same type of class.
667 BeanShell works with objects dynamically through the reflection API, so
668 your scripts will not have a problem recognizing reloaded class objects.
669 However any objects which have you already created might not like them.
672 <h3><a name="Class_Loading_in_BeanShell">Class Loading in BeanShell</a></h3>
674 The following is a discussion of the BeanShell class loader architecture,
675 which allows both course class path extension and fine grained individual
679 <strong>Thriftiness</strong> - Abiding by the BeanShell thriftiness
680 proposition: no class loading code is exercised unless directed by a
681 command. BeanShell begins with no class loader and only adds class loading
682 in layers as necessary to achieve desired effects.
685 The following diagram illustrates the two layer class loading scheme:
688 <img src="images/bshclassloading.gif"/>
692 A "base" class loader is used to handle course changes to the classpath
693 including added path. Unless directed by setClassPath() the base loader will
694 only add path and will not cover existing Java user class path. This prevents
695 unnecessary class space changes for the existing classes.
698 Packages of classes and individual classes are mapped in sets by class
699 loaders capable of handling discrete files. A mapping of reloaded classes
700 is maintained. The discrete file class loaders will also use this mapping
701 to resolve names outside there space, so when any individual class is reloaded
702 it will see all previously reloaded classes as well.
705 The BshClassManager knows about all class loader changes and broadcasts
706 notification of changes to registered listeners. BeanShell namespaces use
707 this mechanism to dereference cached type information, however they do not
708 remove existing object instances.
711 Type caching is extremely important to BeanShell performance. So changing
712 the classloader, which necessitates clearing all type caches, should be
713 considered an expensive operation.
717 <A NAME="CommandRef"></A>BeanShell Commands</H2>
718 The BeanShell provides a set of commands for displaying data, invoking
719 system utilities, and performing various other tasks. See the BeanShell
720 Command Reference for a description of the syntax and usage of each command.
721 The current crop of bsh commands follow. These are, for the most part,
722 just very short bsh scripts, supplied in the bsh.jar file. See <A HREF="#making">making
723 bsh commands</A> below for more details on adding to the "built-in" bsh
728 <H3><A NAME="addClasspathCommand"></A>addClassPath</H3>
729 <code>void addClassPath( string | URL )</code>
732 <p>Add the specified directory or JAR file to the class path. e.g.</p>
735 addClassPath( "/home/pat/java/classes" );
736 addClassPath( "/home/pat/java/mystuff.jar" );
737 addClassPath( new URL("http://myserver/~pat/somebeans.jar") );
742 <H3><A NAME="bgCommand"></A>bg</H3>
743 <TT>bg( String script )</TT>
745 <P>This is like <TT>run()</TT> except that it runs the command in its own
746 thread. Returns the thread object (for <TT>stop()</TT>ing, <TT>join()</TT>ing,
751 <H3><A NAME="bindCommand"></A>bind</H3>
752 <code>bind ( bsh .This ths , bsh .NameSpace namespace )</code>
754 <P>Bind a bsh object into a particular namespace and interpreter.</p>
760 <A NAME="BrowseClassCommand"></A>browseClass</H3>
761 <code>void browseClass( String | Object | Class ) </code>
763 <p>Open the class browser to view the specified class. If the argument is a string it is considered to be a class name. If the argument is an object, the class of the object is used. If the arg is a class, the class is used.
764 Note: To browse the String class you can't supply a String. You'd have to do: </p>
767 browseClass( String.class
770 <P>The browser enables you to browse the contents
771 of any packages packaged as <code>jar</code> files on the classpath defined
772 by <code>jde-global-classpath</code>.
777 <H3> <A NAME="catCommand"></A>cat</H3>
778 <code>cat ( String filename )</code> <br>
779 <code>cat ( URL url )</code> <br>
780 <code>cat ( InputStream ins )</code> <br>
781 <code>cat ( Reader reader )</code> <br>
783 <P>Print the contents of filename, URL, or stream (like Unix cat)l
787 <H3><A NAME="cdCommand"></A>cd</H3>
788 <code>void cd(String path);</code>
790 <P>Change working directory for the <TT>dir()</TT> command (like Unix <TT>cd</TT>).</p>
795 <H3><A NAME="classBrowserCommand"></A>classBrowser</H3>
796 <code>void classBrowser ( )</code>
797 <P>Open the class browser.</p>
803 <H3><A NAME="clearCommand"></A>clear</H3>
806 <P>Clear all variables, methods, and imports from this namespace. If
807 this namespace is the root, it will be reset to the default
808 imports. See NameSpace.clear(); </p>
815 <H3><A NAME="consoleCommand"></A>console</H3>
816 <TT>bsh.Console console()</TT>
818 <P>Create a console window attached to the current interpreter. Returns
823 <H3><A NAME="dirCommand"></A>dir</H3>
824 <TT>void dir(String dirname)</TT>
826 <P>Display the contets of directory dirname. The format is similar to the
827 Unix ls -l command.</p>
831 <H3><A NAME="debugCommand"></A>debug</H3>
832 <TT>void debug()</TT>
834 <P>Toggle on and off debug mode... Note: debug output is verbose and gross.</p>
838 <H3><A NAME="EditorCommand"></A>editor</H3>
840 <code>Frame Frame editor()</code>
842 <P>Create an editor window with an "eval" button. This is primarily useful
843 for typing multi-line commands and experimenting with methods when running
844 the BeanShell outside of the Emacs environment. Returns the editor Frame.
848 <H3><A NAME="errorCommand"></A>error</H3>
850 <code>void error(item)</code>
852 <p>Print the item as an error to standard error.</p>
857 <H3><A NAME="evalCommand"></A>eval</H3>
858 <code>Object eval(String expression)</code>
861 <p>Evaluate the string in the current interpreter (see source()). Returns
862 the result of the evaluation or null. Evaluate a string as if it were
863 written directly in the current scope, with side effects in the
874 <p><code>eval()</code> acts just like invoked text except that any
875 exceptions generated by the code are captured in a <code>bsh.EvalError</code>. This
876 includes <code>ParseException</code> for syntactic errors and <code>TargetError</code> for
877 exceptions thrown by the evaluated code.</p>
883 eval("foo>>><>M>JK$LJLK$");
884 } catch ( EvalError e ) {
885 // ParseException caught here
889 eval("(Integer)true"); // illegal cast
890 } catch ( EvalError e ) {
891 // TargetException caught here
892 print( e.getTarget() ) // prints ClassCastException
896 <p>If you want <code>eval()</code> to throw target exceptions directly, without
897 wrapping them, you can simply redefine own eval like so:</p>
900 myEval( String expression ) {
902 return eval( expression );
903 } catch ( TargetError e ) {
909 <p>Returns the value of the expression.</p>
911 <p>Throws <code>bsh.EvalError</code> on error.</p>
916 <H3><A NAME="execCommand"></A><B>exec</B></H3>
918 <code>exec(String process)</code>
921 <p> Start an external application using the Java Runtime
922 <code>exec()</code> method. Display any output to the standard
923 BeanShell output using <code>print()</code> </p>
928 <H3><A NAME="exitCommand"></A>exit</H3>
932 <p>Conditionally exit the virtual machine. Call
933 <code>System.exit(0)</code> unless <code>bsh.system.shutdownOnExit ==
939 <H3><A NAME="extendCommand"></A>extend</H3>
940 <TT>This extend(This object)</TT>
942 <p>Return a new object that is a child of the specified object. </p>
944 <p><strong>Note</strong> This command will likely change along with a
945 better inheritance mechanism for bsh in a future release.,</p>
947 <p><code>extend()</code> is like the <code>object()</code> command,
948 which creates a new bsh scripted object, except that the namespace of
949 the new object is a child of the parent object.</p>
972 ar.namespace.bind( foo.namespace );
976 <p>The last example above is exactly what the extend() command
977 does. In each case the bar object inherits variables from foo in the
983 <H3><A NAME="FrameCommand"></A>frame</H3>
985 <p><code>Frame | JFrame | JInternalFrame frame(Component component);</code></p>
988 <p>Display the component, centered and packed, in a Frame, JFrame, or
989 JInternalFrame. Returns the frame. If the GUI desktop is running then
990 a JInternaFrame will be used and automatically added to the
991 desktop. Otherwise if Swing is available a top level JFrame will be
992 created. Otherwise a plain AWT Frame will be created.</p>
997 <H3><A NAME="getClassCommand"></A>getClass</H3>
998 <p><code>Class getClass(String name)</code></p>
1001 <p>Get a class through the current namespace utilizing the current
1002 imports, extended classloader, etc. </p>
1004 <p>This is equivalent to the standard <code>Class.forName()</code>
1005 method for class loading. However, it takes advantage of the BeanShell
1006 class manager so that added classpath will be taken into account. You
1007 can also use <code>Class.forName()</code>. However if you have modified the
1008 classpath or reloaded classes from within your script the
1009 modifications will only appear if you use the <code>getClass()</code> command.
1015 <H3><A NAME="getClassPathCommand"></A>getClassPath</H3>
1016 <p><code>URL[] getClassPath()</code></p>
1018 <p>Get the current classpath including all user path, extended path,
1019 and the bootstrap JAR file if possible. </p>
1026 <H3><A NAME="getResourceCommand">getResource</A></H3>
1027 <p><code>URL getResource(String path)</code></p>
1029 <p>The equivalent of calling <code>getResource()</code> on the
1030 interpreter class in the bsh package. Use absolute paths to get stuff
1031 in the classpath.</p>
1035 <H3><A NAME="getSourceFileInfoCommand">getSourceFileInfo</A></H3>
1036 <p><code>getSourceFileInfo() </code></p>
1039 <p>Return the name of the file or source from which the current
1040 interpreter is reading. Note that if you use this within a method, the
1041 result will not be the file from which the method was sourced, but
1042 will be the file that the caller of the method is reading. Methods are
1043 sourced once but can be called many times. Each time the interpreter
1044 may be associated with a different file and it is that calling
1045 interpreter that you are asking for information.</p>
1047 <p><strong>Note</strong> Although it may seems like this command would
1048 always return the <code>getSourceFileInfo.bsh</code> file, it does not
1049 since it is being executed after sourcing by the caller's
1050 interpreter. If one wanted to know the file from which a bsh method
1051 was sourced one would have to either capture that info when the file
1052 was sourced (by saving the state of the
1053 <code>getSourceFileInfo()</code> in a variable outside of the method
1054 or more generally we could add the info to the BshMethod class so that
1055 bsh methods remember from what source they were created.</p>
1060 <H3><A NAME="javapCommand">javap</A></H3>
1062 <p><code>void javap(String | Object | Class)</code></p>
1064 <p>Print the public fields and methods of the specified class (output
1065 similar to the JDK javap command). </p>
1067 <p>If the argument is a string it is considered to be a class name. If
1068 the argument is an object, the class of the object is used. If the arg
1069 is a class, the class is used.</p>
1073 <H3><A NAME="LoadCommand">load</A></H3>
1075 <p><code>Object load(String filename)</code></p>
1077 <p>Load a serialized Java object from filename. Returns the object.</p>
1082 <H3><A NAME="MakeWorkspaceCommand">makeWorkspace</A></H3>
1084 <p><code>makeWorkspace(String name)</code></p>
1086 <p>Open a new workspace (JConsole) in the GUI desktop. </p>
1090 <h3><a name="mvCommand">mv</a></h3>
1091 <p><code>mv (String fromFile, String toFile)</code></p>
1093 <p>Rename a file (like Unix <code>mv</code>).</p>
1097 <h3><a name="objectCommand">object</a></h3>
1098 <p><code>This object()</code></p>
1100 <p>Return an "empty" BeanShell object context which can be used to hold data items. e.g.</p>
1105 myStuff.bar = "blah";
1113 <A NAME="pathToFileCommand">pathToFile</A></H3>
1114 <p><code>File pathToFile(String filename)</code></p>
1116 <p>Create a File object corresponding to the specified file path name,
1117 taking into account the bsh current working directory (bsh.cwd)</p>
1122 <A NAME="PrintCommand">print</A></H3>
1123 <p><code>void print(item);</code></p>
1125 <p>Print the string value of the argument, which may be of any type. If beanshell is running interactively, the output will always go to the command line, otherwise it will go to System.out.</p>
1127 <p>Most often the printed value of an object will simply be the Java toString() of the object. However if the argument is an array the contents of the array will be (recursively) listed in a verbose way.</p>
1129 <p>Note that you are always free to use <code>System.out.println()</code>
1130 instead of <code>print()</code>.</p>
1134 <H3><A NAME="pwdCommand">pwd</A></H3>
1138 <TT>void pwd();</TT></DT>
1142 <P>Print the bsh working directory. This is the cwd obeyed by all the unix
1147 <h3><a name="reloadClassesCommand">reloadClasses</a></h3>
1148 <p><code>void reloadClasses([package name])</code></p>
1150 <p>Reload the specified class, package name, or all classes if no name is given. e.g.
1154 reloadClasses("mypackage.*");
1155 reloadClasses(".*") // reload unpackaged classes
1156 reloadClasses("mypackage.MyClass")
1159 <p>See "Class Path Management" </p>
1166 <A NAME="rmCommand">rm</A></H3>
1167 <p><code>void rm(String pathname);</code></p>
1169 <P>Remove the file (like Unix rm)
1174 <A NAME="runCommand">run</A></H3>
1175 <p><code>run(String filename, Object runArgument);</code></p>
1176 <p><code>run(String filename);</code></p>
1178 <p>Run a command in its own private global namespace and interpeter
1179 context (kind of like the unix <code>chroot</code> for the namespace).
1180 The root bsh system object is extended (with the <code>extend()</code>
1181 command) and made visible here, so that system info is effectively
1182 inherited. Because the root bsh object is extended, it is effectively
1183 read / copy on write, e.g. you can change directories in the child
1184 context, do imports, etc. and it will not affect the calling
1187 <p>Parameter <code>runArgument</code> an argument passed to the child
1188 context under the name runArgument, e.g. you might pass in the calling
1189 <code>this</code> context from which to draw variables, etc. </p>
1195 <H3><A NAME="SaveCommand">save</A></H3>
1196 <p><code>void save(Component component, String filename);</code></p>
1198 <p>Save a serializable Java object to filename.</p>
1200 <p>Since the AWT Button class happens to be serializable, we could test
1201 drive the <code>save()</code> command.</p>
1204 save(foo, "myButton.ser");
1207 <p>If we did save our button, we could revive it later with the
1208 <code>load()</code> command.</p>
1210 <pre> bar = load("myButton.ser");
1217 <H3><A NAME="serverCommand">server</A></H3>
1219 <p><code>void server(int port);</code></p>
1221 <p>Create a <A HREF="file:///D|/jde-dev/doc/guide.html#server">Server Mode</A>
1222 server attached to the current interpreter, listening on the specified
1228 <H3><A NAME="setAccessibilityCommand">setAccessibility</A></H3>
1230 <p><code>setAccessibility(boolean b);</code></p>
1232 <p>Setting accessibility on enables access to private and other
1233 non-public fields and methods.</p>
1238 <H3><A NAME="setClasspathCommand">setClassPath</A></H3>
1240 <p><code>void setClassPath(URL[]);</code></p>
1242 <p>Change the classpath to the specified array of directories and/or archives.</p>
1244 See "Class Path Management" for details.
1251 <H3><A NAME="setFontCommand">setFont</A></H3>
1252 <p><code>Font setFont(Component comp, int ptsize)</code></p>
1254 <p>Change the point size of the font on the specified component,
1255 to <code>ptsize</code>.</p>
1259 <H3><A NAME="setNameSpaceCommand">setNameSpace</A></H3>
1260 <p><code>setNameSpace(ns)</code></p>
1263 <p>Set the namespace (context) of the current scope.
1264 The following example illustrates swapping the current namespace.
1268 fooState = object();
1269 barState = object();
1271 print(this.namespace);
1272 setNameSpace(fooState.namespace);
1273 print(this.namespace);
1275 setNameSpace(barState.namespace);
1276 print(this.namespace);
1279 setNameSpace(fooState.namespace);
1280 print(this.namespace);
1283 setNameSpace(barState.namespace);
1284 print(this.namespace);
1289 <p>You could use this to creates the effect of a static namespace for a method by explicitly setting the namespace upon entry.</p>
1294 <H3><A NAME="setStrictJavaCommand">setStrictJava</A></H3>
1295 <p><code>void setStrictJava(boolean val)</code></p>
1298 <p> Enable or disable "Strict Java Mode". When strict Java mode is enabled BeanShell will:
1302 <li><p>Require typed variable declarations, method arguments and return types.</p>
1305 <p> Modify the scoping of variables to look for the variable
1306 declaration first in the parent namespace, as in a java method
1307 inside a java class. e.g. if you can write a method called
1308 incrementFoo() that will do the expected thing without referring to
1310 <p>See "Strict Java Mode" for more details.</p>
1314 <p><strong>Note</strong> Currently most standard BeanShell commands will not work in Strict Java mode simply because they have not been written with full types, etc.
1320 <A NAME="ShowCommand"></A>show</H3>
1321 <TT>void show();</TT>
1323 <P>Toggle on or off the display of the value of expressions evalauted on
1324 the command line. Show mode may be useful if you find yourself typing print()
1331 <A NAME="sourceCommand"></A>source</H3>
1332 <p><code>Object source(String filename)</code></p>
1333 <p><code>Object source(URL url)</code></p>
1335 <p>Read filename into the interpreter and evaluate it in the current namespace.
1336 Like Bourne Shell "." command.
1343 <A NAME="unsetCommand"></A>unset</H3>
1344 <TT>void unset(String name);</TT>
1346 <P>"undefine" the variable specified by 'name' (So that it tests == void).
1348 <p><strong>Note</strong> There will be a better way to do this in the future. This is currently equivalent to doing</p>
1351 namespace.setVariable(name, null);
1357 <A NAME="whichCommand">which</A></H3>
1359 <p><code>which( classIdentifier | string | class )</code></p>
1361 <p>Use classpath mapping to determine the source of the specified class file. (Like the Unix which command for executables).
1368 <A NAME="MakeCommands"></A>Making BeanShell Commands</H2>
1369 Adding to the set of "prefab" commands supplied with bsh can be about as
1370 easy as writing any other bsh methods. You simply have to place your bsh
1371 scripts in a bsh/commands/ directory in the classpath (or inside the JAR
projects / packages / blob