Embedding:

The scripting engine is contained in oscript.jar, and has one dependency, the bcel-5.1.jar (Byte Code Engineering Library). To add scripting to an existing java application, add these two files to your classpath.

The oscript.OscriptInterpreter class provides static eval methods that provide your primary interface to the interpreter. Also useful will be oscript.data.Value. In general all the methods you will need to access a script value are in Value, and they are overloaded by various subclasses as needed. You shouldn't really have any need to cast a Value to any other type.

You cannot have separate instances of the interpreter in your application. What you do instead, if you want to have multiple script contexts, is to create a new scope for each context, and use the eval methods that let you specify a scope to evaluate in. For example:

import oscript.data.Scope;
import oscript.data.BasicScope;
import oscript.data.JavaBridge;
import oscript.OscriptInterpreter;
...

    Scope a = new BasicScope( OscriptInterpreter.getGlobalScope() );
    Scope b = new BasicScope( OscriptInterpreter.getGlobalScope() );

    OscriptInterpreter.eval( "var foo = 1;", a );
    OscriptInterpreter.eval( "foo;", b ).
      opAssign( JavaBridge.convertToScriptObject(1) );

here evaluating foo; in the different scope will cause a NoSuchMember exception (packaged in a PackagedScriptObjectException) to be thrown, because that variable has not been defined in scope b.₁

Also, if you have need of an interactive read-eval-print loop, Have a look at oscript.Shell.

Accessing Script Objects:

These following methods, defined in the base class oscript.data.Value provide a mechanism to access the value of a script object as various types of java objects. Of course not all script objects will be accessible as any given java object, for example the string "foo" cannot be accessed as an integer number, and attempts to access it as such would result in a script object (wrapped in a PackagedScriptObjectException) being thrown.

castToBoolean() returns boolean
castToInexactNumber() returns double
castToExactNumber() returns long
castToString() returns java.lang.String
castToJavaObject() returns java.lang.Object

or to access elements of an array object:

elementAt(oscript.data.Value) returns oscript.data.Value

or call a script object as a function or constructor:

callAsFunction(oscript.data.Value[]) returns the value returned from the function, oscript.data.Value
callAsConstructor(oscript.data.Value[]) returns the newly constructed object, oscript.data.Value

Creating Script Objects:

The class oscript.data.JavaBridge contains various static convertToScriptObject methods to convert various types of java objects to script objects:

convertToScriptObject(boolean) returns oscript.data.Value
convertToScriptObject(double) returns oscript.data.Value
convertToScriptObject(long) returns oscript.data.Value
convertToScriptObject(java.lang.String) returns oscript.data.Value
convertToScriptObject(java.lang.Object) returns oscript.data.Value

[1]: Note that PackagedScriptObjectException is a subclass of java.lang.RuntimeException, so it is not necessarily explicitly declared to be thrown by methods. Since all script exceptions get wrapped by PackagedScriptObjectException, any time any method gets called that results in script code being evaluated, PackagedScriptObjectException may be thrown. This doesn't mean that it should be necessarily caught (for example java code called by script code may not want to catch the exception, because that would prevent the script code calling the java code from catching it), just that care should be taken to use finally where necessary.

Last modified: Wed Aug 13 16:28:18 PDT 2003