Home

Back

Contents

Next

Adding BeanShell Commands

Adding to the set of "prefab" commands supplied with BeanShell is as easy as writing any other BeanShell methods. You simply have to place your script into a file named with the same name as the command and place the file in the classpath. You may then "import" the commands with the importCommands() method.

Command files can be placed anywhere in the BeanShell classpath. You can use even use the addClassPath() or setClassPath() commands to add new command directories or JARs containing commands to your script at any time.

Hello World

// File: helloWorld.bsh
helloWorld() { 
    print("Hello World!");
}

Place the command file helloWorld.bsh in a directory or JAR in your classpath and import it with the importCommands() command. You can either set the classpath externally for Java or inside of BeanShell with the addClassPath() command. For example, suppose we have placed the file in the path: /home/pat/mycommands/helloWorld.bsh. We could then do:

addClassPath("/home/pat");  // If it's not already in our classpath
importCommands("/mycommands");

We can now use helloWorld() just like any other BeanShell command.

helloWorld(); // prints "Hello World!"

importCommands() will accept either a "resource path" style path name or a Java package name. Either one is simply converted to a resource path or Java package name as required to load scripts or compiled BeanShell command classes. A relative path (e.g. "mycommands") is turned into an absolute path by prepending "/". You may import "loose" commands (like unpackaged classes) at the top of the classpath by importing "/".

If for example you have placed BeanShell commands along with your other classes in a Java package called com.xyz.utils in your classpath, you can import those commands with:

// equivalent
importCommands("com.xyz.utils");
importCommands("/com/xyz/utils");

Imported commands are scoped just like imported classes. So if you import commands in a method or object they are local to that scope.

Overloaded Commands

// File: helloWorld.bsh
helloWorld() { 
	print("Hello World!"); 
}
helloWorld( String msg ) { 
	print("Hello World: "+msg); 
}

BeanShell will select the appropriate method based on the usual rules for methods selection.

Compiled Commands

The dir() command is an example of a BeanShell command that is implemented in Java. Let's look at a snippet from it to see how it implements a pair of invoke() methods for the dir() and dir(path) commands.

/**
	Implement dir() command.
*/
public static void invoke( Interpreter env, CallStack callstack ) 
{
	String dir = ".";
	invoke( env, callstack, dir );
}

/**
	Implement dir( String directory ) command.
*/
public static void invoke( 
	Interpreter env, CallStack callstack, String dir ) 
{
...
}

User Defined Commands with invoke()

invoke( String methodName, Object [] arguments ) { 
	print("You invoked the method: "+ methodName );
}

// invoke() will be called to handle noSuchMethod()
noSuchMethod("foo"); 

invoke() is called to handle any method invocations for undefined methods within its scope. In this case we have declared it at the global scope.

Commands Scope

Getting the Caller Context

fooSetter() {
    this.caller.foo=42;
}

The above command has the effect that after running it the variable 'foo' will be set in the caller's scope. e.g.:

fooSetter();
print( foo ); // 42

It may appear that we could simply have used the 'super' modifier to accomplish this and in this case it would have worked. However it would not have been correct in general because the 'super' of fooSetter() always points to the same location - the scope in which it was defined. We would like fooSetter() to set the variable in whatever scope it was called from.

To reiterate: The 'super' of a method is always the context in which the method was defined. But the caller may be any context in which the method is used. In the following example, the parent context of foo() and the caller context of foo() are the same:

foo() { ... }
foo();

But this is not always the case, as for bar() in the following example:

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

// somewhere
fooObject.bar();

The special "magic" field reference: 'this.caller' makes it possible to reach the context of whomever called bar(). The 'this.caller' reference always refers to the calling context of the current method context.

The diagram above shows the foo() and bar() scopes, along with the caller's scope access via 'this.caller'.

This is very useful in writing BeanShell commands. BeanShell command methods are always loaded into the global scope. If you refer to 'super' from your command you will simply get 'global'. Often it is desirable to write commands that explicitly have side effects in the caller's scope. The ability to do so makes it possible to write new kinds of commands that have the appearance of being "built-in" to the language.

A good example of this is the eval() BeanShell command. eval() evaluates a string as if it were typed in the current context. To do this, it sends the string to an instance of the BeanShell interpreter. But when it does so it tells the interpreter to evaluate the string in a specific namespace: the namespace of the caller; using this.caller.

    eval("a=5");
    print( a ); // 5

The eval() command is implemented simply as:

eval( String text ) {
	this.interpreter.eval( text, this.caller.namespace );
}

As a novelty, you can follow the call chain further back if you want to by chaining the '.caller' reference, like so:

    this.caller.caller...;

Or, more generally, another magic reference 'this.callstack' returns an array of bsh.NameSpace objects representing the full call "stack". This is an advanced topic for developers that we'll discuss in another location.

setNameSpace()

myCommand() {
	// "Step into" the caller's namespace.
	setNameSpace( this.caller.namespace );

	// work as if we were in the caller's namespace.
}

You can try out the setNameSpace() command with arbitrary object scope's as well. For example:

object = object();

// save our namespace
savedNameSpace = this.namespace;

// step into object's namespace
setNameSpace( object.namespace );

// Work in the object's scope
a=1;
b=2;

// step back 
setNameSpace( savedNameSpace );

print( object.a ); // 1
print( object.b ); // 2

print( a ); // ERROR! undefined

Getting the Invocation Text

assert( boolean condition ) 
{
    if ( condition )
        print( "Test Passed..." );
    else {
        print(
            "Test FAILED: "
            +"Line: "+ this.namespace.getInvocationLine()
            +" : "+this.namespace.getInvocationText()
            +" : while evaluating file: "+getSourceFileInfo()
        );
        super.test_failed = true;
    }
}

Working with Dirctories and Paths

All commands that work with files respect the working directory, including the following:

• dir()
• source()
• run(),
• cat()
• load()
• save()
• mv()
• rm()
• addClassPath()

pathToFile()

absfilename = pathToFile( filename );

Path Names and Slashes

dir("c:/Windows"); // ok
dir("c:\\Windows"); // ok

Working With Class Identifiers

javap( Date.class ); // use a class type directly
javap( new Date() ); // uses class of object
javap( "java.util.Date" ); // Uses string name of class
javap( java.util.Date );  // Use plain class identifier

In the last case above we used the plain Java class identifier java.util.Date. In Beanshell this resolves to a bsh.ClassIdentifier reference. You can get the class represented by a ClassIdentifier using the Name.identifierToClass() method. Here is an example of how to work with all of the above, converting the argument to a class type:

	import bsh.ClassIdentifier;

    if ( o instanceof ClassIdentifier )
        clas = this.namespace.identifierToClass(o);
    if ( o instanceof String)
        clas = this.namespace.getClass((String)o);
    else if ( o instanceof Class )
        clas = o;
    else
        clas = o.getClass();

Working with Iterable Types

The BeanShell CollectionManager is used to get a BshIterator for an interable object or array. It is a dynamically loaded extension, so it provides support for the java.util.Collections API when available, but does not break compatability for Java 1.1 applications. You can use this in the implementation of BeanShell commands to iterate over Enumeration, arrays, Vector, String, StringBuffer and (when the java.util.collections API is present) Collections and Iterator.

cm = CollectionManager.getCollectionManager();
if ( cm.isBshIterable( myObject ) ) 
{
	BshIterator iterator = cm.getBshIterator( myObject );
	while ( iterator.hasNext() )
		i = iterator.next();
}

Home

Back

Contents

Next