Loading and Importing Frag Files and Java Classes
Frag provides a number of commands for loading Frag files and Java classes into Frag.
The source command allows you
to load a Frag program during the execution of another program. The load command
allows you to load a Java class that extends Frag with a new object
during the execution of another program. import is an abstraction over these two
commands, allowing you to source Frag programs or Java classes using the usual conventions
with which source and load are used.
source loads the Frag file fileName, optionally considering a given encoding,
and dynamically evaluates the Frag code contained in the file. source has the following syntax:
source <fileName> ?encoding?
The following reads and evaluates the file MyFile.fragsource MyFile.frag
load looks up the Java class class in the class path (or optionally in the
given dirOrJarFileNames). If it is found, the class is loaded. The class must be
of type FragJavaObject or one of its sub-types. In Frag, the Java class is
registered using the given objectName. load has the following syntax:
load <class> <objectName> ?dirOrJarFileNames?
Consider we define the following Java class, and place it in the class path:
package tests;
import frag.core.*;
import frag.exceptions.*;
public class TestObj2 extends FragJavaObject {
public TestObj2(Interp interp, String objName) {
super(interp, objName);
addMethod(interp, "test", new FragJavaMethod(0));
}
public void invokeJavaMethod(Interp interp, FragObject obj, int id,
Dual[] args, CodeLine codeLine) throws FragException {
checkNumberOfArgs(args, 3, 3, "<arg>");
interp.setResult("test " + args[2]);
}
}
Next, we could dynamically load the class and assign it the object name T2.
Then we could further create an instance of T2, and call the ordinary object methods
like set or the user defined method defined above, called test. The last statement
returns: test xxx.
load tests.TestObj2 T2
T2 create x
x set r 5
set result [x test xxx]
import loads and executes a package, being either a Frag source file
or a Java class containing a Frag extension. It has the syntax:
import <package name>
That is, import performs the
functionality of both load and source, following a set of simple
conventions. In addition, import maintains a database of imported packages
and does not allow a package to be imported twice. If a package already imported is
imported again, the second import statement is ignored.
import first searches each directory on the interpreter's import path
(see Sections interp setImportPath and
interp getImportPath) for a file with the name "<package name>.frag". If such
a file is found, it is imported using source with the default encoding.
If sourcing a ".frag" file fails, import interprets <package name>
as the fully qualified name of a Java class, and tries to
dynamically load this class. The class must be a Frag extension, which is then loaded
using the load mechanism (described in Section load). The
object name given to the Frag object wrapping the loaded class is the unqualified, simple
name of the Java class.
If loading the Java class fails too, an exception is thrown.
Consider a Frag package is implemented in a file f1.frag, located in a
directory dir1, which is not yet on the import path of the interpreter. To
import this package, we first must add dir1 to the import path of the interpreter,
and then import the package f1:
interp setImportPath [list build [* interp getImportPath] dir1]
import f1
Consider a Frag extension is implemented as a Java class TestObj in a Java package tests.
If this Java class is located at the CLASSPATH, it will be imported in the following example.
An object TestObj is created, which wraps an instance of the loaded Java class.
In the example, we invoke a method import-test on
this dynamically loaded Frag object.
import tests.TestObj
TestObj import-test
During the import, the dirOrJarFileNames used for loading the Java class are set
to the value of the interpreter's import path, too. In the import path, you can provide any number of
directories or jar files which might contain the imported class.
For example, the following import path causes import to search for Frag files and Java classes
in the libraries ./extensions and ./bin. Further, Java classes are searched in the two jar files.
interp setImportPath [list build
./extensions
./bin
./lib/lib1.jar
./lib/lib2.jar
[* interp getImportPath]]
Sometimes it is tedious to name all jar files in a directory. In the Frag distribution we
provide a simple command getAllJarFiles that lists the names of all jar files in a directory. It
is used as follows:
interp setImportPath [list build
./extensions
./bin
[* getAllJarFiles ./lib]
[* interp getImportPath]]
