Java integration

See: http://www.mozilla.org/rhino/ScriptingJava.html

There are three ways to integrate your Java classes (class files) and libraries (jar files) with Ringo:

Drop the Java class or library into the classpath.
Drop the Java library (jar file) in the RingoJS lib directory.
Add the Java library (jar file) or package (directory) to the classpath.

The simplest way to integrate your Java classes and libraries with Ringo is by dropping it into the classpath. The classpath is a parameter that tells the Java Virtual Machine where to look for user-defined classes and packages. The easiest way to set the classpath is to set the environment variable CLASSPATH to the directory in which your Java classes and libraries exist.

To set the CLASSPATH in Unix, use:

export CLASSPATH=/usr/class/path  # for Bourne, bash, etc.

setenv CLASSPATH /usr/class/path  # for csh, etc.

To set the CLASSPATH in Windows, use:

set CLASSPATH=C:\usr\class\path

By setting the classpath to a directory, we simply tell the Java Virtual Machine to look for user-defined classes and packages in that directory. To tell the Java Virtual Machine to look for a specific library, we must add the path of the jar file to classpath. The CLASSPATH may be set to more than one file path, each path separated by either a colon (in Unix) or a semicolon (in Windows).

To set the CLASSPATH to a jar file in Unix, use:

export CLASSPATH=/usr/class/path:/usr/class/path/library.jar

setenv CLASSPATH /usr/class/path:/usr/class/path/library.jar

To set the CLASSPATH to a jar file in Windows, use:

set CLASSPATH=C:\usr\class\path;C:\usr\class\path\library.jar

Adding the path of each library to the classpath is tedious. In Java 6 and higher, all the jar files in specific directory can be added to the classpath using a wildcard notation.

To set the CLASSPATH to a repository in Unix, use:

export CLASSPATH=/usr/class/path:/usr/class/path/lib/*

setenv CLASSPATH /usr/class/path:/usr/class/path/lib/*

To set the CLASSPATH to a repository in Windows, use:

set CLASSPATH=C:\usr\class\path;C:\usr\class\path\lib\*

Dropping the Java class or library into the classpath allows seamless integration with Ringo (i.e. explicit declaration of which Java classes and libraries are to be added to the classpath is not required). An alternate way to seamlessly integrate libraries with Ringo is to drop the jar file in the RingoJS lib directory. All the jar files in the RingoJS lib directory by default, are included in the classpath. Thus it's an easier way integrate libraries with Ringo since the CLASSPATH mustn't be explicitly set.

Finally, libraries and packages may be explicitly added to the classpath at runtime by calling the global addToClasspath(pathName) function in Ringo. The addToClassPath function takes a single argument: the pathName, which is the absolute path name of the library or package to be added to the classpath. To add path names in the module path using the same lookup rules as the module loader, use the module.resolve(pathName) function. It takes a single argument: the pathName, which is the given path name in the module path and returns its absolute path.

To add a library to the classpath, use:

addToClasspath(module.resolve("./library.jar"));

To add a package to the classpath, use:

addToClasspath(module.resolve("./package"));

It's generally a good practice to explicitly add specific libraries and packages to the classpath by using the addToClasspath function in your RingoJS modules, for the following reasons:

End-users and programmers who download your package don't need to manually set their classpath to point to your libraries and packages.
End-users and programmers who download your package don't need to manually copy your libraries into the RingoJS lib directory.
Explicitly adding specific libraries and packages to the classpath throws an exception if the path is invalid or incorrect.
Explicitly adding specific libraries and packages to the classpath serves as a form of documentation for programmers.

Some info on using Ringo with Spring.

edit this page | list all pages | go home