< 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 >