make/nashorn/buildtools/nasgen/README
author dfuchs
Thu, 12 Sep 2019 15:46:11 +0100
changeset 58108 5302477c8285
parent 47216 71c04702a3d5
permissions -rw-r--r--
8230858: Replace wildcard address with loopback or local host in tests - part 23 Summary: Add new traces for better diagnosis, refrain binding to the wildcard address when possible. Reviewed-by: chegar, xuelei

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.