< prev index next >
src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/codegen/ClassEmitter.java
Print this page
rev 1309 : 8085885: address Javadoc warnings in Nashorn source code
@@ -98,11 +98,10 @@
* and an error thrown.
* <p>
* There is also a very nice debug interface that can emit formatted
* bytecodes that have been written. This is enabled by setting the
* environment "nashorn.codegen.debug" to true, or --log=codegen:{@literal <level>}
- * <p>
*
* @see Compiler
*/
public class ClassEmitter {
/** Default flags for class generation - public class */
@@ -142,11 +141,11 @@
private final Set<String> methodNames;
/**
* Constructor - only used internally in this class as it breaks
- * abstraction towards ASM or other code generator below
+ * abstraction towards ASM or other code generator below.
*
* @param env script environment
* @param cw ASM classwriter
*/
private ClassEmitter(final Context context, final ClassWriter cw) {
@@ -155,32 +154,34 @@
this.methodsStarted = new HashSet<>();
this.methodNames = new HashSet<>();
}
/**
- * Return the method names encountered
+ * Return the method names encountered.
+ *
* @return method names
*/
public Set<String> getMethodNames() {
return Collections.unmodifiableSet(methodNames);
}
/**
- * Constructor
+ * Constructor.
*
* @param env script environment
* @param className name of class to weave
* @param superClassName super class name for class
- * @param interfaceNames names of interfaces implemented by this class, or null if none
+ * @param interfaceNames names of interfaces implemented by this class, or
+ * {@code null} if none
*/
ClassEmitter(final Context context, final String className, final String superClassName, final String... interfaceNames) {
this(context, new ClassWriter(ClassWriter.COMPUTE_FRAMES | ClassWriter.COMPUTE_MAXS));
cw.visit(V1_7, ACC_PUBLIC | ACC_SUPER, className, null, superClassName, interfaceNames);
}
/**
- * Constructor from the compiler
+ * Constructor from the compiler.
*
* @param env Script environment
* @param sourceName Source name
* @param unitClassName Compile unit class name.
* @param strictMode Should we generate this method in strict mode
@@ -215,61 +216,66 @@
Context getContext() {
return context;
}
/**
- * Returns the name of the compile unit class name.
* @return the name of the compile unit class name.
*/
String getUnitClassName() {
return unitClassName;
}
/**
- * Get the method count, including init and clinit methods
+ * Get the method count, including init and clinit methods.
+ *
* @return method count
*/
public int getMethodCount() {
return methodCount;
}
/**
- * Get the clinit count
+ * Get the clinit count.
+ *
* @return clinit count
*/
public int getClinitCount() {
return clinitCount;
}
/**
- * Get the init count
+ * Get the init count.
+ *
* @return init count
*/
public int getInitCount() {
return initCount;
}
/**
- * Get the field count
+ * Get the field count.
+ *
* @return field count
*/
public int getFieldCount() {
return fieldCount;
}
/**
* Convert a binary name to a package/class name.
*
* @param name Binary name.
+ *
* @return Package/class name.
*/
private static String pathName(final String name) {
return name.replace('.', '/');
}
/**
* Define the static fields common in all scripts.
+ *
* @param strictMode Should we generate this method in strict mode
*/
private void defineCommonStatics(final boolean strictMode) {
// source - used to store the source data (text) for this script. Shared across
// compile units. Set externally by the compiler.
@@ -282,12 +288,12 @@
// strictMode - was this script compiled in strict mode. Set externally by the compiler.
field(EnumSet.of(Flag.PUBLIC, Flag.STATIC, Flag.FINAL), STRICT_MODE.symbolName(), boolean.class, strictMode);
}
/**
- * Define static utilities common needed in scripts. These are per compile unit
- * and therefore have to be defined here and not in code gen.
+ * Define static utilities common needed in scripts. These are per compile
+ * unit and therefore have to be defined here and not in code gen.
*/
private void defineCommonUtilities() {
assert unitClassName != null;
if (constantMethodNeeded.contains(String.class)) {
@@ -331,11 +337,13 @@
}
}
}
/**
- * Constructs a primitive specific method for getting the ith entry from the constants table as an array.
+ * Constructs a primitive specific method for getting the ith entry from the
+ * constants table as an array.
+ *
* @param clazz Array class.
*/
private void defineGetArrayMethod(final Class<?> clazz) {
assert unitClassName != null;
@@ -354,33 +362,36 @@
}
/**
* Generate the name of a get array from constant pool method.
+ *
* @param clazz Name of array class.
+ *
* @return Method name.
*/
static String getArrayMethodName(final Class<?> clazz) {
assert clazz.isArray();
return GET_ARRAY_PREFIX.symbolName() + clazz.getComponentType().getSimpleName() + GET_ARRAY_SUFFIX.symbolName();
}
/**
* Ensure a get constant method is issued for the class.
+ *
* @param clazz Class of constant.
*/
void needGetConstantMethod(final Class<?> clazz) {
constantMethodNeeded.add(clazz);
}
/**
- * Inspect class name and decide whether we are generating a ScriptObject class
+ * Inspect class name and decide whether we are generating a ScriptObject class.
*
* @param scriptPrefix the script class prefix for the current script
* @param type the type to check
*
- * @return true if type is ScriptObject
+ * @return {@code true} if type is ScriptObject
*/
private static boolean isScriptObject(final String scriptPrefix, final String type) {
if (type.startsWith(scriptPrefix)) {
return true;
} else if (type.equals(CompilerConstants.className(ScriptObject.class))) {
@@ -391,18 +402,18 @@
return false;
}
/**
- * Call at beginning of class emission
+ * Call at beginning of class emission.
*/
public void begin() {
classStarted = true;
}
/**
- * Call at end of class emission
+ * Call at end of class emission.
*/
public void end() {
assert classStarted : "class not started for " + unitClassName;
if (unitClassName != null) {
@@ -422,11 +433,13 @@
assert methodsStarted.isEmpty() : "methodsStarted not empty " + methodsStarted;
}
/**
* Disassemble an array of byte code.
+ *
* @param bytecode byte array representing bytecode
+ *
* @return disassembly as human readable string
*/
static String disassemble(final byte[] bytecode) {
final ByteArrayOutputStream baos = new ByteArrayOutputStream();
try (final PrintWriter pw = new PrintWriter(baos)) {
@@ -444,11 +457,11 @@
final String str = new String(baos.toByteArray());
return str;
}
/**
- * Call back from MethodEmitter for method start
+ * Call back from MethodEmitter for method start.
*
* @see MethodEmitter
*
* @param method method emitter.
*/
@@ -456,11 +469,11 @@
assert !methodsStarted.contains(method);
methodsStarted.add(method);
}
/**
- * Call back from MethodEmitter for method end
+ * Call back from MethodEmitter for method end.
*
* @see MethodEmitter
*
* @param method
*/
@@ -468,11 +481,11 @@
assert methodsStarted.contains(method);
methodsStarted.remove(method);
}
/**
- * Add a new method to the class - defaults to public method
+ * Add a new method to the class - defaults to public method.
*
* @param methodName name of method
* @param rtype return type of the method
* @param ptypes parameter types the method
*
@@ -481,11 +494,11 @@
MethodEmitter method(final String methodName, final Class<?> rtype, final Class<?>... ptypes) {
return method(DEFAULT_METHOD_FLAGS, methodName, rtype, ptypes); //TODO why public default ?
}
/**
- * Add a new method to the class - defaults to public method
+ * Add a new method to the class - defaults to public method.
*
* @param methodFlags access flags for the method
* @param methodName name of method
* @param rtype return type of the method
* @param ptypes parameter types the method
@@ -497,11 +510,11 @@
methodNames.add(methodName);
return new MethodEmitter(this, methodVisitor(methodFlags, methodName, rtype, ptypes));
}
/**
- * Add a new method to the class - defaults to public method
+ * Add a new method to the class - defaults to public method.
*
* @param methodName name of method
* @param descriptor descriptor of method
*
* @return method emitter to use for weaving this method
@@ -509,11 +522,11 @@
MethodEmitter method(final String methodName, final String descriptor) {
return method(DEFAULT_METHOD_FLAGS, methodName, descriptor);
}
/**
- * Add a new method to the class - defaults to public method
+ * Add a new method to the class - defaults to public method.
*
* @param methodFlags access flags for the method
* @param methodName name of method
* @param descriptor descriptor of method
*
@@ -524,13 +537,14 @@
methodNames.add(methodName);
return new MethodEmitter(this, cw.visitMethod(Flag.getValue(methodFlags), methodName, descriptor, null, null));
}
/**
- * Add a new method to the class, representing a function node
+ * Add a new method to the class, representing a function node.
*
* @param functionNode the function node to generate a method for
+ *
* @return method emitter to use for weaving this method
*/
MethodEmitter method(final FunctionNode functionNode) {
methodCount++;
methodNames.add(functionNode.getName());
@@ -544,13 +558,15 @@
return new MethodEmitter(this, mv, functionNode);
}
/**
- * Add a new method to the class, representing a rest-of version of the function node
+ * Add a new method to the class, representing a rest-of version of the
+ * function node.
*
* @param functionNode the function node to generate a method for
+ *
* @return method emitter to use for weaving this method
*/
MethodEmitter restOfMethod(final FunctionNode functionNode) {
methodCount++;
methodNames.add(functionNode.getName());
@@ -564,42 +580,42 @@
return new MethodEmitter(this, mv, functionNode);
}
/**
- * Start generating the <clinit> method in the class
+ * Start generating the <clinit> method in the class.
*
* @return method emitter to use for weaving <clinit>
*/
MethodEmitter clinit() {
clinitCount++;
return method(EnumSet.of(Flag.STATIC), CLINIT.symbolName(), void.class);
}
/**
- * Start generating an <init>()V method in the class
+ * Start generating an <init>()V method in the class.
*
* @return method emitter to use for weaving <init>()V
*/
MethodEmitter init() {
initCount++;
return method(INIT.symbolName(), void.class);
}
/**
- * Start generating an <init>()V method in the class
+ * Start generating an <init>()V method in the class.
*
* @param ptypes parameter types for constructor
* @return method emitter to use for weaving <init>()V
*/
MethodEmitter init(final Class<?>... ptypes) {
initCount++;
return method(INIT.symbolName(), void.class, ptypes);
}
/**
- * Start generating an <init>(...)V method in the class
+ * Start generating an <init>(...)V method in the class.
*
* @param flags access flags for the constructor
* @param ptypes parameter types for the constructor
*
* @return method emitter to use for weaving <init>(...)V
@@ -608,11 +624,11 @@
initCount++;
return method(flags, INIT.symbolName(), void.class, ptypes);
}
/**
- * Add a field to the class, initialized to a value
+ * Add a field to the class, initialized to a value.
*
* @param fieldFlags flags, e.g. should it be static or public etc
* @param fieldName name of field
* @param fieldType the type of the field
* @param value the value
@@ -623,11 +639,11 @@
fieldCount++;
cw.visitField(Flag.getValue(fieldFlags), fieldName, typeDescriptor(fieldType), null, value).visitEnd();
}
/**
- * Add a field to the class
+ * Add a field to the class.
*
* @param fieldFlags access flags for the field
* @param fieldName name of field
* @param fieldType type of the field
*
@@ -636,11 +652,11 @@
final void field(final EnumSet<Flag> fieldFlags, final String fieldName, final Class<?> fieldType) {
field(fieldFlags, fieldName, fieldType, null);
}
/**
- * Add a field to the class - defaults to public
+ * Add a field to the class - defaults to public.
*
* @param fieldName name of field
* @param fieldType type of field
*/
final void field(final String fieldName, final Class<?> fieldType) {
@@ -649,11 +665,12 @@
/**
* Return a bytecode array from this ClassEmitter. The ClassEmitter must
* have been ended (having its end function called) for this to work.
*
- * @return byte code array for generated class, null if class generation hasn't been ended with {@link ClassEmitter#end()}
+ * @return byte code array for generated class, {@code null} if class
+ * generation hasn't been ended with {@link ClassEmitter#end()}.
*/
byte[] toByteArray() {
assert classEnded;
if (!classEnded) {
return null;
@@ -661,17 +678,13 @@
return cw.toByteArray();
}
/**
- * Abstraction for flags used in class emission
- *
- * We provide abstraction separating these from the underlying bytecode
- * emitter.
- *
- * Flags are provided for method handles, protection levels, static/virtual
- * fields/methods.
+ * Abstraction for flags used in class emission. We provide abstraction
+ * separating these from the underlying bytecode emitter. Flags are provided
+ * for method handles, protection levels, static/virtual fields/methods.
*/
static enum Flag {
/** method handle with static access */
HANDLE_STATIC(H_INVOKESTATIC),
/** method handle with new invoke special access */
@@ -705,14 +718,16 @@
int getValue() {
return value;
}
/**
- * Return the corresponding ASM flag value for an enum set of flags
+ * Return the corresponding ASM flag value for an enum set of flags.
*
* @param flags enum set of flags
- * @return an integer value representing the flags intrinsic values or:ed together
+ *
+ * @return an integer value representing the flags intrinsic values
+ * or:ed together
*/
static int getValue(final EnumSet<Flag> flags) {
int v = 0;
for (final Flag flag : flags) {
v |= flag.getValue();
< prev index next >