nashorn/buildtools/nasgen/README
author dholmes
Tue, 15 Oct 2013 20:54:00 -0400
changeset 20858 b20874db4f81
parent 16147 e63b63819133
permissions -rw-r--r--
8026378: TEST_BUG: Clean up TEST.groups Reviewed-by: mduigou, mchung, alanb

Nasgen is a tool for processing Java classes that implement native
JavaScript objects. It does so by looking for the
com.oracle.nashorn.objects.annotations.ScriptClass annotation and other
annotations in that package.

For each  class "C", nasgen instruments the original class and generates
two additional classes: a "C$Prototype" class for the JavaScript
prototype object, and a "C$Constructor" class for the JavaScript
constructor function.

Each class instrumented or generated by nasgen contains a private static
"$nasgenmap$" field of type com.oracle.nashorn.runtime.PropertyMap and
static initializer block to initialize the field to the object's
JavaScript properties.

Members annotated with @Function, @Property, @Getter, and @Setter are
mapped to the $Constructor, $Prototype, or main class, depending on the
value of the annotation's 'where' field. By default, @Property, @Getter,
and @Setter belong to the main class while @Function methods without
explicit 'where' field belong to the $Prototype class. The @Constructor
annotation marks a method to be invoked as JavaScript constructor.

Nasgen enforces all @Function/@Getter/@Setter/@Constructor annotated
methods to be declared as static. Static final @Property fields remain
in the main class while other @Property fields are moved to respective
classes depending on the annotation's 'where' value. For functions
mapped to the $Prototype or $Constructor class, nasgen also generates
getters and setters prefixed by G$ and S$, respectively.

Nasgen-generated classes are hidden from normal ClassLoaders by giving
them a ".clazz" file name extension instead of the standard ".class"
extension. This allows script classes to be loaded independently by each
Nashorn context through the com.oracle.nashorn.runtime.StructureLoader
class loader.