BeanShell User's Guide

Introduction

About the BeanShell

The BeanShell can operate as a stand-alone application or as a part of another application. When running as a stand-alone application, the interpreter accepts input from the command line of the shell in which it runs. The BeanShell distribution includes a shell for running the interpreter. It can, however, be run from other shells, such as bash or the DOS command window. The JDE includes a command for running the BeanShell in an Emacs shell (comint) buffer. This enables you to interact with the interpreter directly while developing Java programs.

The JDE also  uses the interpreter to implement some JDE commands. The JDE invokes the interpreter via Lisp functions that pass Java statements to the interpreter via the standard input of the interpreter process and retrieve results via the standard output. This guide documents BeanShell functionality that seems relevant to JDE users.  See the BeanShell home page home page for additional information and to download the latest version of the BeanShell.

Using the BeanShell

Starting the BeanShell

The JDE allows you to run only one instance of the BeanShell at a time. If  an instance is already running, the bsh command simply displays the buffer containing the instance, without starting another instance. Note that you can indirectly start a BeanShell instance when you invoke commands implemented as hybrid Lisp/Java scripts, such as jde-wiz-override-method. Such commands start a BeanShell instance if one is not already running.

Evaluating Statements

Statements must conform to Java syntax. For example, simple statements must end in a semicolon. Compound statements, such as if-then constructs, must end in a right brace. Statements may span multiple lines. To continue a statement on a new line, press the Enter key. The BeanShell does not evaluate the statement until you have entered the last line of the statement.

Displaying Results

print(2+2);

4

The show(); command toggles automatic display of the results of evaluating statements as they are entered.

Exiting the Shell

exit();

The BeanShell Language

Java Language Support

    // Use a hashtable
    Hashtable h = new Hashtable();
    Date d = new Date();
    h.put("today", d);

    // Print the current clock value
    print( System.currentTimeMillis() );

    // Loop
    for (int i=0; i<5; i++)
        print(i);

    // Pop up an AWT frame with a button in it
    Button b = new Button("My Button");
    Frame f = new Frame("My Frame");
    f.add(b, "Center");
    f.pack();
    f.show();

import mypackage.*;

    import mypackage.MyClass;

Scripting Extensions

• Script Variables
• Script Methods
• Implicit Objects
• Syntax for accessing Bean properties and Hashtable entries

Script Variables

    foo = new Button("Another Button");

Predefined Variables

• $_ - the value of the last expression evaluated.
• bsh.Console bsh.console - The primary console, if one exists.
• java.awt.AppletContext bsh.appletcontext - the applet context, if one exists.
• String bsh.cwd - used by the cd() and dir() commands.
• boolean bsh.show - used by the show() command.
• boolean bsh.interactive - is this interpreter running in an interactive mode or sourcing a file?
• boolean bsh.evalOnly - Does this interpreter have an input stream or is it only serving as a bag for eval() operations.

Undefined variables

    if ( foobar == void )
        // undefined

a == void;  // true
a=5;
unset("a"); // note the quotes
a == void;  // true

Script Methods

• Script methods are methods of an implicit, typeless object
• Script methods can be defined to accept and return values of any type
• Script methods can define other script methods

    int addTwoNumbers( int a, int b ) {
        return a + b;
    }

    int a = addTwoNumbers( 5, 7 );

You define an untyped script method by omitting type specifications. For example, the following statement

    add( a, b ) {
        return a + b;
    }

    foo = add(1, 2);
    print( foo ); // 3

    foo = add("Oh", " baby");
    print( foo ); // Oh baby

Methods with unspecified return types may return any type of object or no object. A return statement is optional. If omitted, the method returns the value of the last statement or expression in the method body.

Method Namespace

Nested Methods

    foo() {
        bar() {
            ...
        }
    }

Implicit Objects

    a = 42;
    foo() {
        a = 97;
        print( a );
        print( this.a );
        print( super.a );
    }

    foo();  // prints 97, 97, 42

    foo() {
        int a = 42;
        bar() {
            print("The bar is open!");
        }
        
        bar();
        return this;
    }

    obj = foo();     // prints "the bar is open!"
    print ( obj.a )  // 42
    obj.bar();       // prints "the bar is open!"

Using Implicit Objects as AWT Event Handlers

    button = new java.awt.Button("foo!");

    actionPerformed( event ) {
        print( event );
    }

    button.addActionListener( this );
    frame( button );  // show it

Remember that you don't have to define all of your event handlers globally. You can handle events in any bsh object scope. For example, the following method creates a button that displays a message when pushed:

    messageButton( message ) {
        b = new Button("Press Me");
        b.addActionListener( this );
        frame(b);
     
        actionPerformed( e ) {
            print( message );
        }
    }

    messageButton("Hey you!");
    messageButton("Another message...");

Using Implicit Objects as Threads

    foo() {
        run() {
            // do work...
        }
        return this;

    }
 
    foo = foo();
    new Thread( foo ).start();
 

Implicit Object Members

this.interpreter refers to the currently executing BeanShell Interpreter object.

this.namespace refers to the BeanShell NameSpace object of the current context.

this.variables refers to an array of strings listing the variables defined in this namespace.

this.methods refers to an array of strings listing the methods defined in this namespace.

Extended Syntax for Accessing Bean Properties and Hashtables Entries

x{name}

    b = new java.awt.Button();
    b{"label"} = "my button";
    // Equivalent to: b.setLabel("my button");

    h = new Hashtable();
    h{"foo"} = "bar";
    // Equivalent to: h.put("foo", "bar");

Implementing Interfaces

Note Implementing arbitrary interfaces requires BeanShell be running under a Java 1.3 environment or higher.

You can use the standard Java anonymous inner class syntax to implement an interface type with a script. For example:

  ActionListener scriptedListener = new ActionListener() {
    actionPerformed( event ) { ... }
  }

You don't have to implement all of the methods defined by an interface. The calling code throws 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:

  ml = new MouseListener() {
    mousePressed( event ) { ... }
    // handle the rest
    invoke( name, args ) { print("Method: "+name+" invoked!");
  }

Class Loading and Class Path Management

BeanShell is capable of some very fine grained and sophisticated class reloading and modifications to the class path. BeanShell can even map the entire class path to allow for automatic importing of classes.

Changing the Class Path

Add the specified directory or archive to the classpath. Archives may be located by URL, allowing them to be loaded over the network.

Examples:

addClassPath( "/home/pat/java/classes" );
addClassPath( "/home/pat/java/mystuff.jar" );
addClassPath( new URL("http://myserver/~pat/somebeans.jar") );

Note that if you add class path that overlaps with the existing Java user classpath then the new path will effectively reload the classes in that area.

If you add a relative path to the classpath it is evaluated to an absolute path; it does not "move with you".

cd("/tmp");
addClassPath("."); // /tmp

setClassPath( URL [] )

Change the entire classpath to the specified array of directories and/or archives.

This command has some important side effects. It effectively causes all classes to be reloaded (including any in the Java user class path at startup). Please see "Class Reloading" below for further details.

Note: setClassPath() cannot currently be used to make the classpath smaller than the Java user path at startup.

Auto-Importing from the Classpath

import *;

There may be a significant delay while the class path is mapped. This is why auto-importing is not turned on by default. When run interactively, Bsh will report the areas that it is mapping.

It is only necessary to issue the auto-import command once. Thereafter changes in the classpath via the addClassPath() and setClassPath() commands will remap as necessary.

Note: As of BeanShell 1.1alpha new class files added to the classpath (from outside of BeanShell) after mapping will not be seen in imports.

Reloading Classes

reloadClasses( [ package name ] )

The most course level of class reloading is accomplished by issuing the reloadClasses() command with no arguments.

reloadClasses();

This will effectively reload all classes in the current classpath (including any changes you have made through addClassPath()).

Note: that reloading the full path is actually a light weight operation that simply replaces the class loader - normal style class loading is done as classes are subsequently referenced.

Be aware that any object instances which you have previously created may not function with new objects created by the new class loader. Please see the discussion of class loading details below.

You can also reload all of the classes in a specified package:

reloadClasses("mypackage.*");

This will reload only the classes in the specified package. The classes will be reloaded even if they are located in different places in the classpath (e.g. if you have some of the package in one directory and some in another).

As a special case for reloading unpackaged classes the following commands are equivalent:

reloadClasses(".*") 
reloadClasses("<unpackaged>")

You can also reload just an individual class file:

reloadClasses("mypackage.MyClass") 

Note: As of alpha1.1 classes contained in archives (jar files) cannot be reloaded. i.e. jar files cannot be swapped.

Mapping the path

Loading Classes Explicitly

The getClass() command will load a class by name, using the BeanShell classpath. Alternately, you can consult the class manager explicitly:

name="foo.bar.MyClass";
c = getClass( name );
c = BshClassManager.classForName( name );  // equivalent

Setting the Default ClassLoader

BeanShell will use the specified class loader at the same point where it would otherwise use the plain Class.forName(). If no explicit classpath management is done from the script (addClassPath(), setClassPath(), reloadClasses()) then BeanShell will only use the supplied classloader. If additional classpath management is done then BeanShell will perform that in addition to the supplied external classloader. However BeanShell is not currently able to reload classes supplied through the external classloader.

Class Loading in Java

You can think of this in the following way: When you load classes through a new class loader imagine that every class name is prefixed with the identifier "FromClassLoaderXXX" and that all internal references to other classes loaded through that class loader are similarly rewritten. Now if you attempt to pass a reference to a class instance loaded through another class loader to one of your newly loaded objects, it will not recognize it as the same type of class.

BeanShell works with objects dynamically through the reflection API, so your scripts will not have a problem recognizing reloaded class objects. However any objects which have you already created might not like them.

Class Loading in BeanShell

Thriftiness - Abiding by the BeanShell thriftiness proposition: no class loading code is exercised unless directed by a command. BeanShell begins with no class loader and only adds class loading in layers as necessary to achieve desired effects.

The following diagram illustrates the two layer class loading scheme:

A "base" class loader is used to handle course changes to the classpath including added path. Unless directed by setClassPath() the base loader will only add path and will not cover existing Java user class path. This prevents unnecessary class space changes for the existing classes.

Packages of classes and individual classes are mapped in sets by class loaders capable of handling discrete files. A mapping of reloaded classes is maintained. The discrete file class loaders will also use this mapping to resolve names outside there space, so when any individual class is reloaded it will see all previously reloaded classes as well.

The BshClassManager knows about all class loader changes and broadcasts notification of changes to registered listeners. BeanShell namespaces use this mechanism to dereference cached type information, however they do not remove existing object instances.

Type caching is extremely important to BeanShell performance. So changing the classloader, which necessitates clearing all type caches, should be considered an expensive operation.

BeanShell Commands

addClassPath

Add the specified directory or JAR file to the class path. e.g.

    addClassPath( "/home/pat/java/classes" );
    addClassPath( "/home/pat/java/mystuff.jar" );
    addClassPath( new URL("http://myserver/~pat/somebeans.jar") );

bg

This is like run() except that it runs the command in its own thread. Returns the thread object (for stop()ing, join()ing, etc.)

bind

Bind a bsh object into a particular namespace and interpreter.

browseClass

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. Note: To browse the String class you can't supply a String. You'd have to do:

    browseClass( String.class

The browser enables you to browse the contents of any packages packaged as jar files on the classpath defined by jde-global-classpath.
 

cat

Print the contents of filename, URL, or stream (like Unix cat)l

cd

Change working directory for the dir() command (like Unix cd).

classBrowser

Open the class browser.

clear

Clear all variables, methods, and imports from this namespace. If this namespace is the root, it will be reset to the default imports. See NameSpace.clear();

console

Create a console window attached to the current interpreter. Returns the console Frame.

dir

Display the contets of directory dirname. The format is similar to the Unix ls -l command.

debug

Toggle on and off debug mode... Note: debug output is verbose and gross.

editor

Create an editor window with an "eval" button. This is primarily useful for typing multi-line commands and experimenting with methods when running the BeanShell outside of the Emacs environment. Returns the editor Frame.

error

Print the item as an error to standard error.

eval

Evaluate the string in the current interpreter (see source()). Returns the result of the evaluation or null. Evaluate a string as if it were written directly in the current scope, with side effects in the current scope.

e.g.

    a=5;
    eval("b=a*2");
    print(b); // 10

eval() acts just like invoked text except that any exceptions generated by the code are captured in a bsh.EvalError. This includes ParseException for syntactic errors and TargetError for exceptions thrown by the evaluated code.

e.g.

    try {
        eval("foo>>><>M>JK$LJLK$");
    } catch ( EvalError e ) {
        // ParseException caught here
    }

    try {
        eval("(Integer)true");  // illegal cast
    } catch ( EvalError e ) {
        // TargetException caught here
        print( e.getTarget() )  // prints ClassCastException
    }

If you want eval() to throw target exceptions directly, without wrapping them, you can simply redefine own eval like so:

    myEval( String expression ) {
        try {
            return eval( expression );
        } catch ( TargetError e ) {
            throw e.getTarget();
        }
    }
 

Returns the value of the expression.

Throws bsh.EvalError on error.

exec

Start an external application using the Java Runtime exec() method. Display any output to the standard BeanShell output using print()

exit

Conditionally exit the virtual machine. Call System.exit(0) unless bsh.system.shutdownOnExit == false.

extend

Return a new object that is a child of the specified object.

Note This command will likely change along with a better inheritance mechanism for bsh in a future release.,

extend() is like the object() command, which creates a new bsh scripted object, except that the namespace of the new object is a child of the parent object.

For example:

    foo=object();
    bar=extend(foo);

    is equivalent to:
      
    foo() { 
        bar() {
            return this; 
        }
    }

    foo=foo();
    bar=foo.bar();

    and also:
     
    oo=object();
    ar=object();
    ar.namespace.bind( foo.namespace );
    

The last example above is exactly what the extend() command does. In each case the bar object inherits variables from foo in the usual way.

frame

Frame | JFrame | JInternalFrame frame(Component component);

Display the component, centered and packed, in a Frame, JFrame, or JInternalFrame. Returns the frame. If the GUI desktop is running then a JInternaFrame will be used and automatically added to the desktop. Otherwise if Swing is available a top level JFrame will be created. Otherwise a plain AWT Frame will be created.

getClass

Class getClass(String name)

Get a class through the current namespace utilizing the current imports, extended classloader, etc.

This is equivalent to the standard Class.forName() method for class loading. However, it takes advantage of the BeanShell class manager so that added classpath will be taken into account. You can also use Class.forName(). However if you have modified the classpath or reloaded classes from within your script the modifications will only appear if you use the getClass() command.

getClassPath

URL[] getClassPath()

Get the current classpath including all user path, extended path, and the bootstrap JAR file if possible.

getResource

URL getResource(String path)

The equivalent of calling getResource() on the interpreter class in the bsh package. Use absolute paths to get stuff in the classpath.

getSourceFileInfo

getSourceFileInfo()

Return the name of the file or source from which the current interpreter is reading. Note that if you use this within a method, the result will not be the file from which the method was sourced, but will be the file that the caller of the method is reading. Methods are sourced once but can be called many times. Each time the interpreter may be associated with a different file and it is that calling interpreter that you are asking for information.

Note Although it may seems like this command would always return the getSourceFileInfo.bsh file, it does not since it is being executed after sourcing by the caller's interpreter. If one wanted to know the file from which a bsh method was sourced one would have to either capture that info when the file was sourced (by saving the state of the getSourceFileInfo() in a variable outside of the method or more generally we could add the info to the BshMethod class so that bsh methods remember from what source they were created.

javap

void javap(String | Object | Class)

Print the public fields and methods of the specified class (output similar to the JDK javap command).

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.

load

Object load(String filename)

Load a serialized Java object from filename. Returns the object.

makeWorkspace

makeWorkspace(String name)

Open a new workspace (JConsole) in the GUI desktop.

mv

mv (String fromFile, String toFile)

Rename a file (like Unix mv).

object

This object()

Return an "empty" BeanShell object context which can be used to hold data items. e.g.

    myStuff = object();
    myStuff.foo = 42;
    myStuff.bar = "blah";

pathToFile

File pathToFile(String filename)

Create a File object corresponding to the specified file path name, taking into account the bsh current working directory (bsh.cwd)

print

void print(item);

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.

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.

Note that you are always free to use System.out.println() instead of print().

pwd

void pwd();

Print the bsh working directory. This is the cwd obeyed by all the unix like bsh comands.

reloadClasses

void reloadClasses([package name])

Reload the specified class, package name, or all classes if no name is given. e.g.

    reloadClasses();
    reloadClasses("mypackage.*");
    reloadClasses(".*")  // reload unpackaged classes
    reloadClasses("mypackage.MyClass") 

See "Class Path Management"

rm

void rm(String pathname);

Remove the file (like Unix rm)

run

run(String filename, Object runArgument);

run(String filename);

Run a command in its own private global namespace and interpeter context (kind of like the unix chroot for the namespace). The root bsh system object is extended (with the extend() command) and made visible here, so that system info is effectively inherited. Because the root bsh object is extended, it is effectively read / copy on write, e.g. you can change directories in the child context, do imports, etc. and it will not affect the calling context.

Parameter runArgument an argument passed to the child context under the name runArgument, e.g. you might pass in the calling this context from which to draw variables, etc.

save

void save(Component component, String filename);

Save a serializable Java object to filename.

Since the AWT Button class happens to be serializable, we could test drive the save() command.

   save(foo, "myButton.ser");

If we did save our button, we could revive it later with the load() command.

  bar = load("myButton.ser");
  frame(bar);

server

void server(int port);

Create a Server Mode server attached to the current interpreter, listening on the specified port.

setAccessibility

setAccessibility(boolean b);

Setting accessibility on enables access to private and other non-public fields and methods.

setClassPath

void setClassPath(URL[]);

Change the classpath to the specified array of directories and/or archives.

setFont

Font setFont(Component comp, int ptsize)

Change the point size of the font on the specified component, to ptsize.

setNameSpace

setNameSpace(ns)

Set the namespace (context) of the current scope. The following example illustrates swapping the current namespace.

    fooState = object(); 
    barState = object(); 
    
    print(this.namespace);
    setNameSpace(fooState.namespace);
    print(this.namespace);
    a=5;
    setNameSpace(barState.namespace);
    print(this.namespace);
    a=6;
    
    setNameSpace(fooState.namespace);
    print(this.namespace);
    print(a);  // 5
    
    setNameSpace(barState.namespace);
    print(this.namespace);
    print(a); // 6
    

You could use this to creates the effect of a static namespace for a method by explicitly setting the namespace upon entry.

setStrictJava

void setStrictJava(boolean val)

Enable or disable "Strict Java Mode". When strict Java mode is enabled BeanShell will:

1. Require typed variable declarations, method arguments and return types.

2. Modify the scoping of variables to look for the variable declaration first in the parent namespace, as in a java method inside a java class. e.g. if you can write a method called incrementFoo() that will do the expected thing without referring to "super.foo".

   See "Strict Java Mode" for more details.

Note Currently most standard BeanShell commands will not work in Strict Java mode simply because they have not been written with full types, etc.

show

Toggle on or off the display of the value of expressions evalauted on the command line. Show mode may be useful if you find yourself typing print() a lot.

source

Object source(String filename)

Object source(URL url)

Read filename into the interpreter and evaluate it in the current namespace. Like Bourne Shell "." command.

unset

"undefine" the variable specified by 'name' (So that it tests == void).

Note There will be a better way to do this in the future. This is currently equivalent to doing

  namespace.setVariable(name, null); 

which

which( classIdentifier | string | class )

Use classpath mapping to determine the source of the specified class file. (Like the Unix which command for executables).

Making BeanShell Commands