/usr/share/doc/bsh-doc/html/reflectivestyle.html

<?xml version="1.0" encoding="UTF-8"?>
<html><head><title>Reflective Style Access to Scripted Methods</title></head><body bgcolor="ffffff"><table cellspacing="10"><tr><td align="center"><a href="http://www.beanshell.org/"><img src="../images/homebutton.gif"/><br/>Home</a></td><td><a href="jconsole.html#Using_JConsole"><img src="../images/backbutton.gif"/><br/>Back
			</a></td><td align="center"><a href="contents.html"><img src="../images/upbutton.gif"/><br/>Contents</a></td><td align="center"><a href="execscripts.html#Executable_scripts_under_Unix"><img src="../images/forwardbutton.gif"/><br/>Next
			</a></td></tr></table><h1>Reflective Style Access to Scripted Methods</h1>


The following examples show how to work with BeanShell methods dynamically 
from within scripts, using the equivalent of reflective style access in Java.
This is an advanced topic primarily of interest to developers who wish to
do tight integration of BeanShell scripts with their application environment.
<p CLEAR="ALL"/>

<h2><a name="eval()">eval()</a></h2>

The simplest form of reflective style access to scripts is through the 
eval() command.  With eval() you can evaluate any text just as if it had 
appeared in the current scope.  For example:

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

So, if you know the signature (argument types) of a method you wish to work 
with you can simply construct a method call as a string and evaluate it 
with eval() as in the following:

<p/><center><table border="1" cellpadding="5" width="100%"><tr><td bgcolor="#dfdfdc"><pre>
// Declare methods foo() and bar( int, String )
foo() { ... }
bar( int arg1, String arg2 ) { ... }

// Invoke a no-args method foo() by its name using eval()
name="foo";
// invoke foo() using eval()
eval( name+"()");

// Invoke two arg method bar(arg1,arg2) by name using eval()
name="bar";
arg1=5;
arg2="stringy";
eval( name+"(arg1,arg2)");
</pre></td></tr></table></center><p/>

You can get the names of all of the methods defined in the current scope
using the 'this.methods' magic reference, which returns an array of Strings:

<p/><center><table border="1" cellpadding="5" width="100%"><tr><td bgcolor="#dfdfdc"><pre>
// Print the methods defined in this namespace
print( this.methods );
</pre></td></tr></table></center><p/>

We'll talk about more powerful forms of method lookup in a moment.

<h2><a name="invokeMethod()">invokeMethod()</a></h2>

You can explicitly invoke a method by name with arguments through a 'this' 
type reference using the invokeMethod() method:

<p/><center><table border="1" cellpadding="5" width="100%"><tr><td bgcolor="#dfdfdc"><pre>
this.invokeMethod( "bar", new Object [] { new Integer(5), "stringy" } );
</pre></td></tr></table></center><p/>

Arguments are passed as an array of objects.  Primitive types must be 
wrapped in their appropriate wrappers.
BeanShell will select among overloaded methods using the standard Java
method resolution rules.  (JLS 15.11.2).

<h2><a name="Method_Lookup">Method Lookup</a></h2>

The previous section showed how to invoke a method by name when we know
the argument types.  Of course, in general we'd like to be able to find out
what methods are defined in the current script or to look up a method by
its signature.
<p CLEAR="ALL"/>

You can get "handles" to all of the methods defined in a context using the 
namespace getMethods() method.  
getMethods() returns an array of bsh.BshMethod objects,
which are wrappers for the internally parsed representation of BeanShell
scripted methods:

<p/><center><table border="1" cellpadding="5" width="100%"><tr><td bgcolor="#dfdfdc"><pre>
foo() { ... }
foo( int a ) { ... }
bar( int arg1, String arg2 ) { ... }

print ( this.namespace.getMethods() );

// Array: [Lbsh.BshMethod;@291aff {
//   Bsh Method: bar
//   Bsh Method: foo
//   Bsh Method: foo
// }
</pre></td></tr></table></center><p/>

We'll talk about what you can do with a BshMethod in a moment.
<p CLEAR="ALL"/>

Alternately, you can use the namespace getMethod() method to search 
for a specific method signature.  The method signature is a set of argument 
types represented by an array of Classes:

<p/><center><table border="1" cellpadding="5" width="100%"><tr><td bgcolor="#dfdfdc"><pre>
name="bar";
signature = new Class [] { Integer.TYPE, String.class };

// Look up a method named bar with arg types int and String
bshMethod = this.namespace.getMethod( name, signature );

print("Found method: "+bshMethod);
</pre></td></tr></table></center><p/>

<p/><center><table cellpadding="5" border="1" width="100%"><tr><td><strong>Tip:</strong><br CLEAR="ALL"/>
The Java reflection API uses special class values to represent primitive types
such as int, char, an boolean.  These types are static fields in the respective
primitive wrapper classes.  e.g. Integer.TYPE, Character.TYPE, Boolean.TYPE.
</td></tr></table></center><p/>

In the above snippet we located the bar() method by its signature.  If there
had been overloaded forms of bar() getMethod() would have located the most
specific one according to the standard Java method resolution rules 
(JLS 15.11.2).
The result of the lookup is a bsh.BshMethod object, as before.
<p CLEAR="ALL"/>

<h2><a name="BshMethod">BshMethod</a></h2>

You can inspect a BshMethod object to determine its method name and
argument types:

<p/><center><table border="1" cellpadding="5" width="100%"><tr><td bgcolor="#dfdfdc"><pre>
name = bshMethod.getName();
Class [] types = bshMethod.getArgumentTypes();
Class returnType = bshMethod.getReturnType();
</pre></td></tr></table></center><p/>

To invoke the BshMethod, call its invoke() method, passing an array of 
arguments, an interpreter reference, and a "callstack" reference.
<p CLEAR="ALL"/>

<p/><center><table border="1" cellpadding="5" width="100%"><tr><td bgcolor="#dfdfdc"><pre>
// invoke the method with arg
bshMethod.invoke( new Object [] { new Integer(1), "blah!" }, 
    this.interpreter, this.callstack );
</pre></td></tr></table></center><p/>

For the
interpreter and callstack references you can simply pass along the current
context's values via 'this.interpreter' and 'this.callstack', as we did
above.  The arguments array may be null or empty for no arguments.
<p CLEAR="ALL"/>



<h2><a name="Uses">Uses</a></h2>

Why would anyone want to do this?  Well, perhaps you are sourcing a script
created by a user and want to automatically begin using methods that they
have defined.  Perhaps the user is allowed to define methods to take control 
of various aspects of your application.  With the tools we've described
in this section you can list the methods they have defined and invoke
them dynamically.

<table cellspacing="10"><tr><td align="center"><a href="http://www.beanshell.org/"><img src="../images/homebutton.gif"/><br/>Home</a></td><td><a href="jconsole.html#Using_JConsole"><img src="../images/backbutton.gif"/><br/>Back
			</a></td><td align="center"><a href="contents.html"><img src="../images/upbutton.gif"/><br/>Contents</a></td><td align="center"><a href="execscripts.html#Executable_scripts_under_Unix"><img src="../images/forwardbutton.gif"/><br/>Next
			</a></td></tr></table></body></html>
bsh-doc 2.0b4-15 / usr / share / doc / bsh-doc / html / reflectivestyle.html
