nashorn/buildtools/nasgen/README
author bpb
Wed, 03 Feb 2016 13:34:19 -0800
changeset 35703 0bcc18fb1c5e
parent 16147 e63b63819133
permissions -rw-r--r--
8148821: (fs) Path.getParent() javadoc error Summary: Change "If this path has one or more elements" to "If this path has more than one element." Reviewed-by: rriggs, alanb
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
16147
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
     1
Nasgen is a tool for processing Java classes that implement native
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
     2
JavaScript objects. It does so by looking for the
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
     3
com.oracle.nashorn.objects.annotations.ScriptClass annotation and other
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
     4
annotations in that package.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
     5
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
     6
For each  class "C", nasgen instruments the original class and generates
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
     7
two additional classes: a "C$Prototype" class for the JavaScript
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
     8
prototype object, and a "C$Constructor" class for the JavaScript
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
     9
constructor function.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    10
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    11
Each class instrumented or generated by nasgen contains a private static
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    12
"$nasgenmap$" field of type com.oracle.nashorn.runtime.PropertyMap and
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    13
static initializer block to initialize the field to the object's
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    14
JavaScript properties.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    15
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    16
Members annotated with @Function, @Property, @Getter, and @Setter are
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    17
mapped to the $Constructor, $Prototype, or main class, depending on the
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    18
value of the annotation's 'where' field. By default, @Property, @Getter,
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    19
and @Setter belong to the main class while @Function methods without
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    20
explicit 'where' field belong to the $Prototype class. The @Constructor
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    21
annotation marks a method to be invoked as JavaScript constructor.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    22
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    23
Nasgen enforces all @Function/@Getter/@Setter/@Constructor annotated
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    24
methods to be declared as static. Static final @Property fields remain
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    25
in the main class while other @Property fields are moved to respective
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    26
classes depending on the annotation's 'where' value. For functions
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    27
mapped to the $Prototype or $Constructor class, nasgen also generates
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    28
getters and setters prefixed by G$ and S$, respectively.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    29
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    30
Nasgen-generated classes are hidden from normal ClassLoaders by giving
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    31
them a ".clazz" file name extension instead of the standard ".class"
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    32
extension. This allows script classes to be loaded independently by each
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    33
Nashorn context through the com.oracle.nashorn.runtime.StructureLoader
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    34
class loader.