annotate buildtools/nasgen/README @ 628:676cd7bf5e09 jdk8-b113

Merge
author lana
date Thu, 17 Oct 2013 16:19:45 -0700
parents da1e581c933b
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
2
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
1 Nasgen is a tool for processing Java classes that implement native
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
2 JavaScript objects. It does so by looking for the
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
3 com.oracle.nashorn.objects.annotations.ScriptClass annotation and other
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
4 annotations in that package.
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
5
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
6 For each class "C", nasgen instruments the original class and generates
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
7 two additional classes: a "C$Prototype" class for the JavaScript
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
8 prototype object, and a "C$Constructor" class for the JavaScript
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
9 constructor function.
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
10
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
11 Each class instrumented or generated by nasgen contains a private static
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
12 "$nasgenmap$" field of type com.oracle.nashorn.runtime.PropertyMap and
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
13 static initializer block to initialize the field to the object's
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
14 JavaScript properties.
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
15
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
16 Members annotated with @Function, @Property, @Getter, and @Setter are
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
17 mapped to the $Constructor, $Prototype, or main class, depending on the
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
18 value of the annotation's 'where' field. By default, @Property, @Getter,
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
19 and @Setter belong to the main class while @Function methods without
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
20 explicit 'where' field belong to the $Prototype class. The @Constructor
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
21 annotation marks a method to be invoked as JavaScript constructor.
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
22
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
23 Nasgen enforces all @Function/@Getter/@Setter/@Constructor annotated
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
24 methods to be declared as static. Static final @Property fields remain
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
25 in the main class while other @Property fields are moved to respective
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
26 classes depending on the annotation's 'where' value. For functions
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
27 mapped to the $Prototype or $Constructor class, nasgen also generates
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
28 getters and setters prefixed by G$ and S$, respectively.
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
29
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
30 Nasgen-generated classes are hidden from normal ClassLoaders by giving
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
31 them a ".clazz" file name extension instead of the standard ".class"
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
32 extension. This allows script classes to be loaded independently by each
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
33 Nashorn context through the com.oracle.nashorn.runtime.StructureLoader
da1e581c933b 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
34 class loader.