nashorn/buildtools/nasgen/README
author lagergren
Wed, 03 Jul 2013 15:46:03 +0200
changeset 18844 f85cfbfb4d11
parent 16147 e63b63819133
permissions -rw-r--r--
8019811: Static calls - self referential functions needed a return type conversion if they were specialized, as they can't use the same mechanism as indy calls Reviewed-by: sundar, jlaskey

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.