Executing JavaScript on the JVM
===============================

As you will see in subsequent sections, navigating and manipulating
the JVM's class and object structure can result in verbose and
cumbersome Python code. Therefore, *jtypes.javabridge* ships with
the JavaScript interpreter Rhino, which runs on the JVM.
In many cases, the most convienient way to interact with the JVM is
to execute a piece of JavaScript.

.. autofunction:: jt.javabridge.run_script

For more information on using Rhino with the JVM see
https://developer.mozilla.org/en-US/docs/Rhino/Scripting_Java

Examples:

    >>> from jt import javabridge
    >>> javabridge.run_script("2 + 2")
    4

    >>> javabridge.run_script("a + b", bindings_in={"a": 2, "b": 3})
    5

    >>> outputs = {"result": None}
    >>> javabridge.run_script("var result = 2 + 2;", bindings_out=outputs)
    >>> outputs["result"]
    4
    
    >>> javabridge.run_script("java.lang.Math.abs(v)", bindings_in=dict(v=-1.5))
    1.5

A conversion is necessary when converting from Python primitives and objects
to Java and JavaScript primitives and objects. Python primitives are boxed into
Java objects - Javascript will automatically unbox them when calling a method
that takes primitive arguments (e.g. the call to Math.abs(double) as in the
above example. The following is a table of bidirectional translations from
Python to Java / Javascript and vice-versa:

+-------------------------+------------------------+----------------------+
| Python                  | Java - boxed           | Java-primitive       |
+=========================+========================+======================+
| bool                    | java.lang.Boolean      | boolean              |
+-------------------------+------------------------+----------------------+
| int                     | java.lang.Integer      | int                  |
+-------------------------+------------------------+----------------------+
| long                    | java.lang.Long         | long                 |
+-------------------------+------------------------+----------------------+
| float                   | java.lang.Double       | double               |
+-------------------------+------------------------+----------------------+
| unicode                 | java.lang.String       | N/A                  |
+-------------------------+------------------------+----------------------+
| str (Python->java only) | java.lang.String       | N/A                  |
+-------------------------+------------------------+----------------------+
| None                    | null                   | N/A                  |
+-------------------------+------------------------+----------------------+