manual/interfaces.html

<?xml version="1.0" encoding="UTF-8"?>
<html>

<head>
    <title>Scripting Interfaces</title>
</head>

<body bgcolor="ffffff">
    <table cellspacing="10">
        <tr>
            <td align="center"><a href="http://www.beanshell.org/"><img src="images/homebutton.png" /><br />Home</a>
            </td>
            <td><a href="scope.html#Scope_Modifiers"><img src="images/backbutton.png" /><br />Back
                </a></td>
            <td align="center"><a href="contents.html"><img src="images/upbutton.png" /><br />Contents</a></td>
            <td align="center"><a href="specialvarsvalues.html#Special_Variables_and_Values"><img
                        src="images/forwardbutton.png" /><br />Next
                </a></td>
        </tr>
    </table>
    <h1>Scripting Interfaces</h1>


    One of the most powerful features of BeanShell is the ability to script
    Java interfaces. This feature allows you to write scripts that serve
    as event handlers, listeners, and components of other Java APIs. It also
    makes calling scripted components from within your applications easier
    because they can be made to look just like any other Java object.
    <p CLEAR="ALL" />

    <h2><a name="Anonymous_Inner-Class_Style">Anonymous Inner-Class Style</a></h2>

    One way to get a scripted component to implement a Java interface is by
    using the standard Java anonymous inner class syntax to construct a scripted
    object implementing the interface type. For example:
    <p CLEAR="ALL" />

    <p />
    <center>
        <table border="1" cellpadding="5" width="100%">
            <tr>
                <td bgcolor="#dfdfdc">
                    <pre>
buttonHandler = new ActionListener() {
    actionPerformed( event ) { 
        print(event);
    }
};

button = new JButton();
button.addActionListener( buttonHandler );
frame(button);
</pre>
                </td>
            </tr>
        </table>
    </center>
    <p />
    <p CLEAR="ALL" />

    In the above example we have created an object that implements the
    <code>ActionListener</code> interface and assigned it to a variable called
    buttonHandler.
    The buttonHandler object contains the scripted method actionPerformed(),
    which will be called to handle invocations of that method on the interface.
    <p CLEAR="ALL" />

    Note that in the example we registered our scripted ActionListener with a
    JButton using its addActionListener() method. The JButton is, of course,
    a standard Swing component written in Java. It has no knowledge that when it
    invokes the buttonHandler's actionPerformed() method it will actually be
    causing the BeanShell interpreter to run a script to evaluate the outcome.
    <p CLEAR="ALL" />

    To generalize beyond this example a bit - Scripted interfaces work by looking
    for scripted methods to implement the methods of the interface.
    A Java method invocation on a script that implements an interface causes
    BeanShell to look for a corresponding scripted method with
    a matching signature (name and argument types). BeanShell then invokes the
    method, passing along the arguments and passing back any return value.
    When BeanShell runs in the same Java VM as the rest of the code, you can
    freely pass "live" Java objects as arguments and return values, working
    with them dynamically in your scripts; the integration can be seamless.
    <p CLEAR="ALL" />

    See also <a href="examples/dragtext.html">the dragText example</a>.
    <p CLEAR="ALL" />

    <h2><a name="'this'_references_as_Interface_Types">'this' references as Interface Types</a></h2>

    The anonymous inner class style syntax which we just discussed allows you
    to explicitly create an object of a specified interface type, just as you
    would in Java. But BeanShell is more flexible than that. In fact,
    within your BeanShell scripts, any 'this' type script reference can
    automatically implement any interface type, as needed. This means that you can
    simply use a 'this' reference to your script or a scripted object anywhere
    that you would use the interface type. BeanShell will automatically "cast"
    it to the correct type and perform the method delegation for you.
    <p CLEAR="ALL" />

    For example, we could script an event handler for our button even
    more simply using just a global method, like this:

    <p />
    <center>
        <table border="1" cellpadding="5" width="100%">
            <tr>
                <td bgcolor="#dfdfdc">
                    <pre>
actionPerformed( event ) {
    print( event );
}

button = new JButton("Foo!");
button.addActionListener( this );
frame( button ); 
</pre>
                </td>
            </tr>
        </table>
    </center>
    <p />

    Here, instead of making a scripted object to hold our actionPerformed()
    method we have simply placed the method in the current context
    (the global scope) and told BeanShell to look there for the method.
    <p CLEAR="ALL" />

    Just as before, when <code>ActionEvents</code> are fired by the button, your
    actionPerformed() method will be invoked. The BeanShell 'this' reference
    to our script implements the interface and directs method invocations to the
    appropriately named method, if it exists.
    <p CLEAR="ALL" />

    <p />
    <center>
        <table cellpadding="5" border="1" width="90%">
            <tr>
                <td bgcolor="#eeeebb"><strong>Note:</strong><br CLEAR="ALL" />
                    If you want to have some fun, try entering the previous example interactively
                    in a shell or on the command line. You'll see that you can then redefine
                    actionPerformed() as often as you like by simply entering the method again.
                    Each button press will find the current version in your shell. In a sense,
                    you are working inside a dynamic Java object that you are creating and
                    modifying as you type. Neat, huh? Be the Bean!
                </td>
            </tr>
        </table>
    </center>
    <p />

    Of course, you don't have to define all of your interface methods globally.
    You can create references in any scope, as we discussed in "Scripting Objects".
    For example, the following code creates a scripted message button object which
    displays a message when its pushed. The scripted object holds its own
    actionPerformed() method, along with a variable to hold the Frame used for
    the GUI:
    <p CLEAR="ALL" />

    <p />
    <center>
        <table border="1" cellpadding="5" width="100%">
            <tr>
                <td bgcolor="#dfdfdc">
                    <pre>
messageButton( message ) {
    JButton button = new JButton("Press Me");
    button.addActionListener( this );
    JFrame frame = frame( button );
 
    actionPerformed( e ) {
        print( message );
        frame.setVisible(false);
    }
}

messageButton("Hey you!");
messageButton("Another message...");
</pre>
                </td>
            </tr>
        </table>
    </center>
    <p />

    The above example creates two buttons, with separate messages. Each button
    prints its message when pushed and then dismisses itself.
    The buttons are created by separate calls to the messageButton() method,
    so each will have its own method context, separate local variables, and a
    separate instance of the ActionListener interface handler. Each registers
    itself (its own method context) as the ActionListener for its button, using
    its own 'this' reference.
    <p CLEAR="ALL" />

    In this example all of the "action" is contained in messageButton() method
    context. It serves as a scripted object that implements the interface and
    also holds some state, the frame variable, which is used to dismiss the GUI.
    More generally however, as we saw in the "Scripting Objects" section,
    we could have returned the 'this' reference to the caller, allowing it to
    work with our messageButton object in other ways.
    <p CLEAR="ALL" />

    <h2><a name="Interface_Types_and_Casting">Interface Types and Casting</a></h2>

    It is legal, but not usually necessary to perform an explicit cast of a
    BeanShell scripted object to an interface type. For example:

    <p />
    <center>
        <table border="1" cellpadding="5" width="100%">
            <tr>
                <td bgcolor="#dfdfdc">
                    <pre>
actionPerformed( event ) {
    print( event );
}

button.addActionListener( 
    (ActionListener)this ); // added cast
</pre>
                </td>
            </tr>
        </table>
    </center>
    <p />

    In the above, the cast to ActionListener would have been done automatically
    by BeanShell when it tried to match the 'this' type argument to the signature
    of the addActionListener() method.
    <p CLEAR="ALL" />

    Doing the cast explicitly has the same effect, but takes a different route
    internally. With the cast, BeanShell creates the necessary adapter
    that implements the ActionListener interface first, at the time of the cast,
    and then later finds that the method is a perfect match.
    <p CLEAR="ALL" />

    What's the difference? Well, there are times where performing
    an explicit cast to control when the type is created may be important.
    Specifically, when you are passing references out of your script, to Java
    classes that don't immediately use them as their intended type.

    In our earlier discussion we said that automatic casting happens "within
    your BeanShell scripts". And in our examples so far BeanShell has always
    had the opportunity to arrange for the scripted object to become the correct
    type, before passing it on. But it is possible for you to pass a 'this'
    reference to a method that, for example, takes the type 'Object', in which
    case BeanShell would have no way of knowning what it was destined for later.
    You might do this, for example, if you were placing your scripted objects
    into a collection (Map or List) of some kind. In that case, you can
    control the process by performing an explicit cast to the desired type before
    the reference leaves your script.
    <p CLEAR="ALL" />

    Another case where you may have to perform a cast is where you are using
    BeanShell in an embedded application and returning a scripted object as
    the result of an eval() or a get() variable from the Interpreter class.
    There again
    is a case where BeanShell has no way of knowing the intended type within
    the script. By performing an explicit cast you can create the type
    before the reference leaves your script.
    <p CLEAR="ALL" />
    We'll discuss embedded applications of BeanShell in the
    "Embedding BeanShell" section a bit later, along with the Interpreter
    getInterface() method, which is another way of accomplishing this type of
    cast from outside a script.
    <p CLEAR="ALL" />

    <h2><a name="&quot;Dummy&quot;_Adapters_and_Incomplete_Interfaces">"Dummy" Adapters and Incomplete Interfaces</a>
    </h2>

    It is common in Java to see "dummy" adapters created for interfaces that
    have more than one method. The job of a dummy adapter is to implement all
    of the methods of the interface with stubs (empty bodies), allowing the
    developer to extend the adapter and override just the methods of interest.
    <p CLEAR="ALL" />

    We hinted in our earlier discussion that BeanShell could handle scripted
    interfaces that implement only the subset of methods that are actually used
    and that is indeed the case. You are free in BeanShell to script only the
    interface methods that you expect to be called. The penalty for leaving out
    a method that is actually invoked is a special run-time exception:
    java.lang.reflect.UndeclaredThrowableException, which the caller will
    receive.
    <p CLEAR="ALL" />

    The UndeclaredThrowableException is an artifact of Java Proxy API that makes
    dynamic interfaces possible. It says that an interface threw a checked
    exception type that was not prescribed by the method signature. This is
    a situation that cannot normally happen in compiled Java. So the Java
    reflection API handles it by wrapping the checked exception in this special
    unchecked (RuntimeException) type in order to throw it.
    You can get the underlying
    error using the exception's getCause() method, which will, in this case,
    reveal the BeanShell EvalError exception, reporting that the scripted method
    of the correct signature was not found.
    <p CLEAR="ALL" />


    <h3>The invoke() Meta-Method</h3>

    BeanShell provides a very simple short-hand mechanism for scripting interfaces
    with large numbers of methods. You can implement the special method
    <em>invoke( name, args )</em> in any scripted
    context. The invoke() method will be called to handle the invocation of
    any method of the interface that is not defined. For example:
    <p CLEAR="ALL" />

    <p />
    <center>
        <table border="1" cellpadding="5" width="100%">
            <tr>
                <td bgcolor="#dfdfdc">
                    <pre>
mouseHandler = new MouseListener() {
    mousePressed( event ) { 
        print("mouse button pressed");  
    }

    invoke( method, args ) { 
        print("Undefined method of MouseListener interface invoked:"
            + name +", with args: "+args
        );
    }
};
</pre>
                </td>
            </tr>
        </table>
    </center>
    <p />
    <p CLEAR="ALL" />

    In the above example we have neglected to implement four of the five
    methods of the MouseListener interface. They will be handled by the invoke()
    method, which will simply print the name of the method and its arguments.
    However since mousePressed() is defined it will be called for the interface.
    <p CLEAR="ALL" />

    Here is a slightly more realistic example of where this comes in handy.
    Let's use the invoke() method to print the names of methods called via
    the ContentHandler interface of the Java SAX API, while parsing an XML
    document.

    <p />
    <center>
        <table border="1" cellpadding="5" width="100%">
            <tr>
                <td bgcolor="#dfdfdc">
                    <pre>
import javax.xml.parsers.*;
import org.xml.sax.InputSource;

factory = SAXParserFactory.newInstance();
saxParser = factory.newSAXParser();
parser = saxParser.getXMLReader();
parser.setContentHandler( this );

invoke( name, args ) {
    print( name );
}

parser.parse( new InputSource(bsh.args[0]) );
</pre>
                </td>
            </tr>
        </table>
    </center>
    <p />

    By running this script with the XML file as an argument, we can see which
    of the dozen or so methods of the SAX API are being exercised by the structure
    of the document, without having to write a stub for each of them.
    <p CLEAR="ALL" />

    <p />
    <center>
        <table cellpadding="5" border="1" width="100%">
            <tr>
                <td><strong>Tip:</strong><br CLEAR="ALL" />
                    You can use the invoke( name, args ) meta-method directly in your own scope or
                    in the global scope as well, in which case you can handle arbitrary "unknown"
                    method invocations yourself, perhaps to implement your own "virtual" commands.
                    Try typing this on the command line:
                    <pre>
  invoke(name,args) { print("Command: "+name+" invoked!"); }
  noSuchMethod(); // prints "Command: noSuchMethod() invoked!"
</pre>
                </td>
            </tr>
        </table>
    </center>
    <p />

    <h2><a name="Threads_-_Scripting_Runnable">Threads - Scripting Runnable</a></h2>

    BeanShell 'this' type references can implement the standard java.lang.Runnable
    interface. So you can declare a "run()" method in your bsh objects and make
    it the target of a Thread:

    <p />
    <center>
        <table border="1" cellpadding="5" width="100%">
            <tr>
                <td bgcolor="#dfdfdc">
                    <pre>
foo() {
    run() {
        // do work...
    }
    return this;
}

foo = foo();
// Start two threads on foo.run()
new Thread( foo ).start();
new Thread( foo ).start();
</pre>
                </td>
            </tr>
        </table>
    </center>
    <p />
    <p CLEAR="ALL" />

    BeanShell is thread-safe internally, so as long as your scripts do not
    explicitly do anything ordinarily non-thread safe (e.g. access shared
    variables or objects) you can write multi-threaded scripts.
    <p CLEAR="ALL" />

    <p />
    <center>
        <table cellpadding="5" border="1" width="90%">
            <tr>
                <td bgcolor="#eeeebb"><strong>Note:</strong><br CLEAR="ALL" />
                    You can use the bg() "background" command to run an external script in a
                    separate thread. See bg().
                </td>
            </tr>
        </table>
    </center>
    <p />
    <p CLEAR="ALL" />

    <h2><a name="Limitations">Limitations</a></h2>
    <p CLEAR="ALL" />

    When running under JDK 1.3 or greater BeanShell can script any kind of
    Java interface. However when running under JDK 1.2 (or JDK1.1 + Swing) only
    the core AWT and Swing interfaces are available. To support those legacy
    cases a special extension of the 'this' reference implementation (the
    bsh.This class) is loaded which implements these interfaces along with
    Runnable, statically.
    <p CLEAR="ALL" />

    <table cellspacing="10">
        <tr>
            <td align="center"><a href="http://www.beanshell.org/"><img src="images/homebutton.png" /><br />Home</a>
            </td>
            <td><a href="scope.html#Scope_Modifiers"><img src="images/backbutton.png" /><br />Back
                </a></td>
            <td align="center"><a href="contents.html"><img src="images/upbutton.png" /><br />Contents</a></td>
            <td align="center"><a href="specialvarsvalues.html#Special_Variables_and_Values"><img
                        src="images/forwardbutton.png" /><br />Next
                </a></td>
        </tr>
    </table>
</body>

</html>