The simplest way to set some variable values is to use ScriptEngine.put(name, value):

  ScriptEngine engine = ...;
  engine.put("taxRate", 0.0825); // 8.25%
  // evaluate script
  // invoke function

Now the hardcoded tax rate in the previous script can be replaced with a variable:

// userdef.js
function expectedSalesTax(productType, unitPrice, quantity) {
  return unitPrice * quantity * taxRate;
}

The variables’ values are not limited to simple types like strings and primitives. And the ability to introduce any Java object into the script environment greatly expands the integration’s usefulness. For example, the script can use a product knowledge base:

// userdef.js
function expectedSalesTax(productType, unitPrice, quantity) {
  return productKb.isExemptFromSalesTax(productType)
         ? 0
         : unitPrice * quantity * taxRate;
}

public class ProductKB {
  public boolean isExemptFromSalesTax(Object productInfo) {
    return contains(productInfo, "clothes");
  }
  private boolean contains(Object collection, String item) {
    if (collection instanceof Collection) {
      return ((Collection) collection).contains(item);
    } else {
      String stringForm = ';' + String.valueOf(collection) + ';';
      return stringForm.indexOf(';' + item + ';') >= 0;
  }
}

public class Demo {
  public static void main(...) throws ... {
    ProductKB productKb = new ProductKB();
    ScriptEngine engine = ...;
    engine.put("taxRate", 0.0825); // 8.25%
    engine.put("productKb", productKb);
    engine.eval(...);

    Invocable invocable = (Invocable) engine;
    invocable.invokeFunction("expectedSalesTax",
                             Arrays.asList("clothes", "winter"),
                             89.95, 2); // 0.0
    invocable.invokeFunction("expectedSalesTax",
                             Arrays.asList("sneakers", "basketball"),
                             102.1, 3); // 25/26975
  }
}

Here’s how to simply supply parameter values when calling a function defined in a script. First the ScriptRunner needs to be updated:

pubic class ScriptRunner {
  ...

  public void load(String scriptName) throws ... {
    Reader reader = resourceReader(scriptName);
    _engine.eval(reader);
  }

  public <T> T invoke(String functionName, Object... params) throws ... {
    //noinspection unchecked
    return (T) ((Invocable) _engine).invokeFunction(functionName, params);
  }

  private InputStreamReader resourceReader(String scriptName) {
    InputStream stream = getClass().getResourceAsStream(scriptName);
    return new InputStreamReader(stream);
  }
}

Now, given some script:

// userdef.js
function expectedSalesTax(productType, unitPrice, quantity) {
  return unitPrice * quantity * 0.0825;   // 8.25%
}

It can be invoked after the script is loaded:

  ScriptRunner runner = new ScriptRunner();
  runner.load("userdef.js");
  double taxes = runner.invoke("expectedSalesTax", "sneakers", 99.90, 5);

In the past, I’ve used BeanShell, jython and various DSLs to support test scripts. Recently, I’ve started using Java 6′s embedded ‘Rhino’ JavaScript engine.

In a series of posts, I want to share some basics of how you can enable cross-interactions between some Java code and some JavaScript.

I started with a basic script runner facade:

import javax.script.*;

public class ScriptRunner {
  private final ScriptEngineManager _manager;
  private final ScriptEngine _engine;

  public ScriptRunner() {
    _manager = new ScriptEngineManager();
    _engine = _manager.getEngineByName("JavaScript");
  }

  public Object run(String scriptName) throws ... {
    Reader reader = new InputStreamReader(getClass().getResourceAsStream(scriptName));
    return _engine.eval(reader);
  }
}

For simplicity, I placed this near-trivial script file in the classpath:

// hello_world.js
function myconcat(a, b) { return a + ' ' + b; }
myconcat('hello', 'world');

… and ran the script:

  public static void main(...) throws ... {
    ScriptRunner runner = new ScriptRunner();
    runner.run("hello_world.js");
  }

which produced the expected

hello world

No additional libraries, broadly and well understood script language… so a promising start.

One detail specifically called out is how calls to a proxy instance’s equals(), hashCode() and toString() are dispatched to the invocation handler. The design subtlety turns out be important and well thought-out. To understand why, it is first important to grasp the behavior of java.lang.reflect.Method‘s getDeclaringClass().

Usually, if a method m() of some class A is overridden in a subclass B, then the subclass’s method’s declaring class is B. The junit test code snippet below demonstrates this point:

    public void testStockEqualsMethod() {
        assertSame(Object.class,
                   getEqualsMethod(new Object()).getDeclaringClass());
    }

    public void testEqualsMethodOverridden() {
        assertSame(Integer.class,
                   getEqualsMethod(new Integer(1)).getDeclaringClass());
    }

    private Method getEqualsMethod(Object o) {
        try {
            return o.getClass().getMethod("equals", Object.class);
        }
        catch (NoSuchMethodException e) {
            fail("Developer assumption violated; single arg equals is always available.");
            throw new Error(); // never happens; fail() throws its own exception.
        }
    }

A similar thing happens with dynamic proxies. The test code below illustrates the similarity. Note that in the second test method, the proxy implements interface B, and that the assert checks for a declaring class B:

    interface A {
        void someMethod();
    }

    public void testInterfaceMethod() {
        A proxy = newProxyInstance(A.class, new InvocationHandler() {
            public Object invoke(Object o, Method method, Object[] objects) {
                assertSame(A.class, method.getDeclaringClass());
                return null;
            }
        });
        proxy.someMethod();
    }

    interface B extends A {
        void someMethod();
    }

    public void testRedefiningInterfaceMethod() {
        A proxy = newProxyInstance(B.class, new InvocationHandler() {
            public Object invoke(Object o, Method method, Object[] objects) {
                assertSame(B.class, method.getDeclaringClass());
                return null;
            }
        });
        proxy.someMethod();
    }

If the same behavior were to happen for equals, hashCode and toString, then the invocation handler would need to accommodate cases where some interface redefines one or more of those methods. (An example such a redefinition is java.util.List, where equality is declared to be concrete type agnostic and element order sensitive.)

Instead, invocation handlers can simply have a flow branch for special casing the three methods. The code below demonstrates how the methods should be special-cased for the implementation hiding example posted previously:

    private static class EqualsAwareHandler<T> implements InvocationHandler {
        private static final Method OBJECT_EQUALS =
            getObjectMethod("equals", Object.class);

        private static final Method OBJECT_HASHCODE =
            getObjectMethod("hashCode");

        private final T _implementation;

        EqualsAwareHandler(final T implementation) {
            _implementation = implementation;
        }

        public Object invoke(Object proxy, Method method, Object[] objects)
            throws Throwable {
            if (OBJECT_EQUALS == method) {
                return equalsInternal(proxy, objects[0]);
            }

            if (OBJECT_HASHCODE == method) {
              return _implementation.hashCode();
            }
            // toString() will fall through to the generic handling.
            try {
                return method.invoke(_implementation, objects);
            }
            catch (InvocationTargetException itx) {
                throw itx.getTargetException();
            }
        }

        private boolean equalsInternal(Object me, Object other) {
            if (other == null) {
                return false;
            }
            if (other.getClass() != me.getClass()) {
                // Not same proxy type; false.
                // This may not be true for other scenarios.
            }
            InvocationHandler handler = Proxy.getInvocationHandler(other);
            if (!(handler instanceof EqualsAwareHandler)) {
                // the proxies behave differently.
                return false;
            }
            return ((EqualsAwareHandler) handler)._implementation.equals(_implementation);
        }

        private static Method getObjectMethod(String name, Class... types) {
            try {
                // null 'types' is OK.
                return Object.class.getMethod(name, types);
            }
            catch (NoSuchMethodException e) {
                throw new IllegalArgumentException(e);
            }
        }
    }

The easiest practical demonstration of a dynamic proxy focuses on hiding implementations from clients. When I say ‘hiding’, I mean preventing clients from downcasting and even preventing them from getting anything useful out of instance.getClass(). Here’s how one would start such a proxy:

    public  T rudimentaryHideImplementation(T implementation) {
        if (null == implementation) {
            return null;
        }
        final ClassLoader loader = implementation.getClass().getClassLoader();
        final Class[] interfaces = getImplementedInterfaces(implementation);
        final InvocationHandler handler = new RudimentaryHandler(implementation);
        return (T) Proxy.newProxyInstance(loader, interfaces, handler);
    }

    private static Class[] getImplementedInterfaces(Object implementation) {
        return implementation.getClass().getInterfaces();
    }

    private static class RudimentaryHandler implements InvocationHandler {
        private final T _implementation;

        RudimentaryHandler(final T implementation) {
            _implementation = implementation;
        }

        public Object invoke(Object proxy,
                             Method method,
                             Object[] objects)
            throws Throwable {
            try {
                return method.invoke(_implementation, objects);
            }
            catch (InvocationTargetException itx) {
                throw itx.getTargetException();
            }
        }
    }

In the above code, getImplementedInterfaces(...) was oversimplified. Specifically, interfaces[] will only contain the interfaces implemented by the instance’s class; it will not contain interfaces imeplemented by its superclasses. Here’s a more correct version:

    private  Class[] getImplementedInterfaces(Object implementation) {
        LinkedHashSet interfaces = new LinkedHashSet();
        for (Class c = implementation.getClass(); c != null; c = c.getSuperclass()) {
            interfaces.addAll(Arrays.asList(c.getInterfaces()));
        }
        return interfaces.toArray(new Class[interfaces.size()]);
    }

Any reflection gurus will tell you that I’ve also oversimplified the code inside the invocation handler. True. I will cover those details in Part 2.

The first one is for creating an empty list, set, or map etc without having to duplicate the template parameters. Here it’s written for a HashMap:

private static <K, V> Map<K, V> newHashMap() {
    return new HashMap<K, V>();
}

It can be used as follows:

// would have had to write
// private final Map<UserId, Set<PhoneNumber>> _phByUserId =
//       new HashMap<UserId, Set<PhoneNumber>>();
// instead we can simplify to
private final Map<UserId, Set<PhoneNumber>> _phByUserId = newHashMap();

The next method is used to instantiate and populate a list or a set:

private static <T> Set<T> toHashSet(T... elements) {
    Set set = new HashSet<T>();
    for (T element : elements) {
        set.add(element);
    }
    return set;
}

The varargs lend the method to elegant use:

Set<String> resourceNames =
    toHashSet(
      "simple_request.xml",
      "malformed_request.xml",
      "incomplete_request.xml"
    );

A similar method can be written for instantiating pre-populated lists. If you know that the list will never be added to, you can forgo writing any convenience method, and use java.util.Arrays directly:

import static java.util.Arrays.asList;
...
List<String> resourceNames =
    asList(
      "simple_request.xml",
      "malformed_request.xml",
      "incomplete_request.xml"
    );

The last also happens to be my favorite. Instantiating pre-populated arrays in Java involves far too much typing. For example:

Class[] interfaces = new Class[] { Person.class, Customer.class };

Using the following simple convenience…

private static <T> T[] array(T... elements) {
    return elements;
}

… The earlier expression can be replaced with:

Class[] interfaces = array(Person.class, Customer.class);

Dynamic dispatching is what makes polymorphic behavior happen. When you call toString() on an object, the right implementation is called because Java dispatches to the appropriate method based on the type of the instance. But Java doesn’t go the whole length when it comes to dynamic dispatch: while it pays attention to the actual type of the instance, it only concerns itself with the type of the reference to any parameters, not their actual types. For example:

abstract class PrettyPrinter {
  abstract void prettyPrint(Number n);
  abstract void prettyPrint(Long l);
  abstract void prettyPrint(Double d);
}

final class AmericanPrettyPrinter extends PrettyPrinter { ... }

final class ItalianPrettyPrinter extends PrettyPrinter { ... }

PrettyPrinter printer = new AmericanPrettyPrinter();
Double d = new Double(34.5);
Number n = d;
printer.prettyPrint(d); // uses AmericanPrettyPrinter.prettyPrint(Double d);
printer.prettyPrint(n); // uses AmericanPrettyPrinter.prettyPrint(Number n);

Yes, this is painfully obvious. I am trying to highlight the asymmetry: while the instance’s type is considered at runtime but the parameter’s type is not. Some languages do not have this limitation; Java does.

The previous post’s if-elseif- sequence is one way of accommodating this limitation. Here’s a more complete list of approaches one might employ:

1. If the method in question doesn’t require parameters, you can simply use the dynamic dispatching supported by Java. There are two reasons to not do so. First, you may not be the author of the classes. In the above example, you cannot add public abstract String toPrettyString() to java.lang.Number, nor can you add concrete implementations of the method to java.lang.Double and java.lang.Long. Second, you may choose to not add the method “family” for coupling & cohesion reasons: you may not want to add various disparate methods like toPrettyString(), toDebugString(), toXmlString() etc., because your core classes’ code gets polluted with a plethora of specialized logic.

2. Use traditional flow control constructs like if-else or switch-case. When there are very few code path alternatives, this solution — however distasteful to purists — is often suitable.

3. Use a double dispatch idiom. The idiom looks like this:

interface ContactInfoVisitor {
  void handlePhysicalAddress(PhysicalAddress pa);
  void handlePhoneNumber(PhoneNumber pn);
  void handleEmailAddress(EmailAddress ea);
}

abstract class ContactInfo {
  abstract void visit(ContactInfoVisitor v);
}

class PhysicalAddress extends ContactInfo {
  void visit(ContactInfoVisitor v) {
    v.handlePhysicalAddress(this);
  }
}

class PhoneNumber extends ContactInfo {
  void visit(ContactInfoVisitor v) {
    v.handlePhoneNumber(this);
  }
}

class EmailAddress extends ContactInfo {
  void visit(ContactInfoVisitor v) {
    v.handleEmailAddress(this);
  }
}

This is an application of what the Gang-of-Four call the Visitor Pattern. Once again, you need access to your parameter classes (in the above example, all ContactInfo types). Furthermore, this approach requires that all code (the parameter types, the visitor interface and visitor implementations) be compiled at the same time. Post a comment if you are interested why this is, or if you seek techniques to relax this limitation.

4. Implement some dynamic dispatching solution yourself. Classification-based, type-based and defaulting-based are some popular implementation approaches. The previous post introduced a simple defaulting-based dispatching.

Sometimes, we need to add a behavior to several classes, where we cannot modify the classes. For example, imagine wanting to add prettyToString() to Strings, Numbers, Booleans, Collections and Maps.

A first stab at the code may look like this:

public static String prettyToString(Object input) {
  if (input instanceof String) {
    return prettyToString((String) input);
  } else if (input instanceof Number) {
    return prettyToString((Number) input);
  } else if (input instanceof Boolean) {
    return prettyToString((Boolean) input);
  } else if (input instanceof Collection) {
    return prettyToString((Collection) input);
  } else if (input instanceof Map) {
    return prettyToString((Map) input);
  }
    return "instance of " + input.getClass().getName();
}

private static String prettyToString(String string) { ... }

private static String prettyToString(Number number) { ... }
...

Problem:

The if-else blocks become unwieldy very quickly.

Simple Improvement:

Define a base type for a family of functors. Each concrete functor knows how to handle one of the condition blocks. When the general method is called, it tries to use each of the functors in turn until one formats the object. If they all fail, then the default formatting is performed.

private static final List<PrettyToString> PRETTY_TO_STRING = buildPrettyToStringHandlers();

public static String prettyToString(Object input) {
  for (PrettyToString functor : PRETTY_TO_STRING) {
    String formatted = functor.handleIfPossible(input);
    if (formatted != null) {
      return formatted;
    }
  }
  return "instance of " + input.getClass().getName();
}

private static String prettyToString(String string) { ... }

private static String prettyToString(Number number) { ... }

private static List<PrettyToString> buildPrettyToStringHandlers() {
  List<PrettyToString> m = new ArrayList<PrettyToString>();
  m.add(new PrettyToString<String>(String.class) {
    String handle(String string) { return prettyToString(string); }
  });
  m.add(new PrettyToString<Number>(Number.class) {
    String handle(Number number) { return prettyToString(number); }
  });
  ...
  return Collections.unmodifiableList(m);
}

private static abstract class PrettyToString<T> {
  private final Class<T> _type;

  PrettyToString(Class<T> type) {
    _type = type;
  }

  final String handleIfPossible(Object object) {
    return _type.isInstance(object) ? handle(_type.cast(object)) : null;
  }

  abstract String handle(T object);
}

Notes:

This is a well known technique. Looking through the Gang of Four’s behavioral design patterns, I see that this is a variation of a “Chain of Responsibility” pattern.

This approach — and the additional code — becomes defensible when the list of functors is determined at runtime. It does not, however, buy an improvement in code. After all, we’ve removed a single sprawling if-else-if block but added a bunch of inner classes, a static builder method and a static member. Furthermore, we’ve harmed performance.

Part 2 will build on this approach but address the deficiencies.