This document describes changes to the Java Virtual Machine Specification as modified by Format Checking Cleanup and JVM Types Cleanup to allow the special method name <new>
to be used to declare unnamed factory methods.
Changes are described with respect to existing sections of the JVM Specification. New text is indicated like this and deleted text is indicated like this. Explanation and discussion, as needed, is set aside in grey boxes.
Chapter 2: The Structure of the Java Virtual Machine
2.9 Special Methods
2.9.4 Unnamed Factory Methods
A class or interface may declare zero or more unnamed factory methods. These methods return instances of the class or interface while encapsulating the process used to create or look up those instances.
An unnamed factory method is declared with the special name <new>
.
The declaration and use of an unnamed factory method is constrained by the Java Virtual Machine. For the declaration, the method's access_flags
item and descriptor are constrained (4.6). For a use, an unnamed factory method may be invoked only by the invokestatic instruction (4.9.1).
Because the name
<new>
is not a valid identifier in the Java programming language, it cannot be used directly in a program written in the Java programming language.
This section follows the pattern of 2.9.1 and 2.9.2.
It may make sense to swap this new section with 2.9.3, with associated renumbering of cross references.
Chapter 4: The class
File Format
4.2 Names
4.2.2 Unqualified Names
Names of methods, fields, local variables, and formal parameters are stored as unqualified names. An unqualified name must contain at least one Unicode code point and must not contain any of the ASCII characters .
;
[
/
(that is, period or semicolon or left square bracket or forward slash).
Method names are further constrained so that, with the exception of the special method names <init>
, and <clinit>
, and <new>
(2.9), they must not contain the ASCII characters <
or >
(that is, left angle bracket or right angle bracket).
4.4 The Constant Pool
4.4.8 The CONSTANT_MethodHandle_info
Structure
The CONSTANT_MethodHandle_info
structure is used to represent a method handle:
CONSTANT_MethodHandle_info {
u1 tag;
u1 reference_kind;
u2 reference_index;
}
The items of the CONSTANT_MethodHandle_info
structure are the following:
- tag
The
tag
item has the valueCONSTANT_MethodHandle
(15).- reference_kind
The value of the
reference_kind
item must be in the range 1 to 9. The value denotes the kind of this method handle, which characterizes its bytecode behavior (5.4.3.5).- reference_index
The value of the
reference_index
item must be a valid index into theconstant_pool
table. Theconstant_pool
entry at that index must be as follows:If the value of the
reference_kind
item is 1 (REF_getField
), 2 (REF_getStatic
), 3 (REF_putField
), or 4 (REF_putStatic
), then theconstant_pool
entry at that index must be aCONSTANT_Fieldref_info
structure (4.4.2).The
reference_index
item represents a field for which a method handle is to be created.If the value of the
reference_kind
item is 5 (REF_invokeVirtual
) or 8 (REF_newInvokeSpecial
), then theconstant_pool
entry at that index must be aCONSTANT_Methodref_info
structure (4.4.2).The
reference_index
item represents a class's method or constructor (2.9.1) for which a method handle is to be created.If the value of the
reference_kind
item is 6 (REF_invokeStatic
) or 7 (REF_invokeSpecial
), then if theclass
file version number is less than 52.0, theconstant_pool
entry at that index must be aCONSTANT_Methodref_info
structure; if theclass
file version number is 52.0 or above, theconstant_pool
entry at that index must be either aCONSTANT_Methodref_info
structure or aCONSTANT_InterfaceMethodref_info
structure (4.4.2).The
reference_index
item represents a class's or interface's method for which a method handle is to be created.If the value of the
reference_kind
item is 9 (REF_invokeInterface
), then theconstant_pool
entry at that index must be aCONSTANT_InterfaceMethodref_info
structure.The
reference_index
item represents an interface's method for which a method handle is to be created.
If the value of the
reference_kind
item is 5 (REF_invokeVirtual
),6 (, 7 (REF_invokeStatic
)REF_invokeSpecial
), or 9 (REF_invokeInterface
), the name of the method represented by aCONSTANT_Methodref_info
structure or aCONSTANT_InterfaceMethodref_info
structure must not be<init>
or<new>
.If the value of the
reference_kind
item is 6 (REF_invokeStatic
), the name of the method represented by aCONSTANT_Methodref_info
structure or aCONSTANT_InterfaceMethodref_info
structure must not be<init>
.If the value is 8 (
REF_newInvokeSpecial
), the name of the method represented by aCONSTANT_Methodref_info
structure must be<init>
.In no case may the name be
<clinit>
, becauseMethodref
andInterfaceMethodref
structures that reference that name are already prohibited (4.4.2).
4.4.10 The CONSTANT_Dynamic_info
and CONSTANT_InvokeDynamic_info
Structures
Most structures in the constant_pool
table represent entities directly, by combining names, descriptors, and values recorded statically in the table. In contrast, the CONSTANT_Dynamic_info
and CONSTANT_InvokeDynamic_info
structures represent entities indirectly, by pointing to code which computes an entity dynamically. The code, called a bootstrap method, is invoked by the Java Virtual Machine during resolution of symbolic references derived from these structures (5.1, 5.4.3.6). Each structure specifies a bootstrap method as well as an auxiliary name and type that characterize the entity to be computed. In more detail:
The
CONSTANT_Dynamic_info
structure is used to represent a dynamically-computed constant, an arbitrary value that is produced by invocation of a bootstrap method in the course of an ldc instruction (6.5.ldc), among others. The auxiliary type specified by the structure constrains the type of the dynamically-computed constant.The
CONSTANT_InvokeDynamic_info
structure is used to represent a dynamically-computed call site, an instance ofjava.lang.invoke.CallSite
that is produced by invocation of a bootstrap method in the course of an invokedynamic instruction (6.5.invokedynamic). The auxiliary type specified by the structure constrains the method type of the dynamically-computed call site.
CONSTANT_Dynamic_info {
u1 tag;
u2 bootstrap_method_attr_index;
u2 name_and_type_index;
}
CONSTANT_InvokeDynamic_info {
u1 tag;
u2 bootstrap_method_attr_index;
u2 name_and_type_index;
}
The items of these structures are as follows:
- tag
The
tag
item of aCONSTANT_Dynamic_info
structure has the valueCONSTANT_Dynamic
(17).The
tag
item of aCONSTANT_InvokeDynamic_info
structure has the valueCONSTANT_InvokeDynamic
(18).- bootstrap_method_attr_index
The value of the
bootstrap_method_attr_index
item must be a valid index into thebootstrap_methods
table of theBootstrapMethods
attribute of thisClassFile
structure (4.7.23).CONSTANT_Dynamic_info
structures are unique in that they are syntactically allowed to refer to themselves via the bootstrap method table. Rather than mandating that such cycles are detected when classes are loaded (a potentially expensive check), we permit cycles initially but mandate a failure at resolution (5.4.3.6).- name_and_type_index
The value of the
name_and_type_index
item must be a valid index into theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_NameAndType_info
structure (4.4.6). Thisconstant_pool
entry indicates a name and descriptor.In a
CONSTANT_Dynamic_info
structure, the indicated descriptor must be a field descriptor (4.3.2).In a
CONSTANT_InvokeDynamic_info
structure, the indicated name must be a valid method name (4.2.1) and must not be<clinit>
,or<init>
, or<new>
. The indicated descriptor must be a method descriptor (4.3.3).We could allow
<new>
here, but the precedent seems to be to avoid any special method names when using invokedynamic.
4.6 Methods
Each method, including each instance initialization method (2.9.1) and the class or interface initialization method (2.9.2), is described by a method_info
structure.
A ClassFile
structure must not declare two methods with the same name and descriptor (4.3.3).
The structure has the following format:
method_info {
u2 access_flags;
u2 name_index;
u2 descriptor_index;
u2 attributes_count;
attribute_info attributes[attributes_count];
}
The items of the method_info
structure are as follows:
- access_flags
The value of the
access_flags
item is a mask of flags used to denote access permission to and properties of this method. The interpretation of each flag, when set, is specified in Table 4.6-A.Table 4.6-A. Method access and property flags
Flag Name Value Interpretation ACC_PUBLIC
0x0001 Declared public
; may be accessed from outside its package.ACC_PRIVATE
0x0002 Declared private
; accessible only within the defining class and other classes belonging to the same nest (5.4.4).ACC_PROTECTED
0x0004 Declared protected
; may be accessed within subclasses.ACC_STATIC
0x0008 Declared static
.ACC_FINAL
0x0010 Declared final
; must not be overridden (5.4.5).ACC_SYNCHRONIZED
0x0020 Declared synchronized
; invocation is wrapped by a monitor use.ACC_BRIDGE
0x0040 A bridge method, generated by the compiler. ACC_VARARGS
0x0080 Declared with variable number of arguments. ACC_NATIVE
0x0100 Declared native
; implemented in a language other than the Java programming language.ACC_ABSTRACT
0x0400 Declared abstract
; no implementation is provided.ACC_STRICT
0x0800 Declared strictfp
; floating-point mode is FP-strict.ACC_SYNTHETIC
0x1000 Declared synthetic; not present in the source code. A method named
<init>
(2.9.1) must have at most one of itsACC_PUBLIC
,ACC_PRIVATE
, andACC_PROTECTED
flags set, and may also have itsACC_VARARGS
,ACC_STRICT
, andACC_SYNTHETIC
flags set, but must not have any of the other flags in Table 4.6-A set.A method named
<clinit>
(2.9.2) may have any of the flags in Table 4.6-A set, in any combination, but all flags exceptACC_STATIC
,ACC_STRICT
, andACC_SYNTHETIC
are treated by the Java Virtual Machine as if they were not set. In aclass
file whose version number is 51.0 or greater, theACC_STATIC
flag must be set; in aclass
file whose version number is less than 51.0, theACC_STATIC
flag is treated by the Java Virtual Machine as if it were set.Methods of classes with names other than
<init>
and<clinit>
may have any of the flags in Table 4.6-A set. However, each such method must have at most one of itsACC_PUBLIC
,ACC_PRIVATE
, andACC_PROTECTED
flags set (JLS §8.4.3).Methods of interfaces with names other than
<clinit>
must not have theirACC_PROTECTED
,ACC_FINAL
,ACC_SYNCHRONIZED
, andACC_NATIVE
flags set (JLS §9.4); exactly one of theACC_PUBLIC
orACC_PRIVATE
flags must be set. They may have any of the other flags in Table 4.6-A set. In aclass
file whose version number is less than 52.0, each method of an interface with a name other than<clinit>
must have itsACC_PUBLIC
andACC_ABSTRACT
flags set.A method of a class or interface named
<new>
(2.9.4) must have itsACC_STATIC
flag set.If a method of a class or interface has its
ACC_ABSTRACT
flag set, it must not have any of itsACC_PRIVATE
,ACC_STATIC
,ACC_FINAL
,ACC_SYNCHRONIZED
,ACC_NATIVE
, orACC_STRICT
flags set.The
ACC_BRIDGE
flag is used to indicate a bridge method generated by a compiler for the Java programming language.The
ACC_VARARGS
flag indicates that this method takes a variable number of arguments at the source code level.The
ACC_SYNTHETIC
flag indicates that this method was generated by a compiler and does not appear in source code, and is not one of the methods named in 4.7.8.All bits of the
access_flags
item not assigned in Table 4.6-A are reserved for future use. They should be set to zero in generatedclass
files and are ignored by Java Virtual Machine implementations.- name_index
The value of the
name_index
item must be a valid index into theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_Utf8_info
structure (4.4.7) representing a valid unqualified method name.A method of an interface must not have the name
<init>
.- descriptor_index
The value of the
descriptor_index
item must be a valid index into theconstant_pool
table. Theconstant_pool
entry at that index must be aCONSTANT_Utf8_info
structure representing a valid method descriptor (4.3.3). Furthermore:If the name of the method is
<init>
, then the descriptor must denote avoid
method.If the name of the method is
<clinit>
, then the descriptor must denote avoid
method, and, in aclass
file whose version number is 51.0 or above, a method that takes no arguments.If the name of the method is
<new>
, then the descriptor must denote a return type that is the type of the current class or interface.It seems like a useful invariant that a class's factory method has a matching return type. This is consistent with the behavior of
<init>
methods (which, when invoked, set the type of all matching instances in the stack frame to the class's type). But, if needed, this requirement could be relaxed.
A future edition of this specification may require that the last parameter descriptor of the method descriptor is an array type if the
ACC_VARARGS
flag is set in theaccess_flags
item.- attributes_count
The value of the
attributes_count
item indicates the number of additional attributes of this method.- attributes[]
Each value of the
attributes
table must be anattribute_info
structure (4.7).The attributes defined by this specification as appearing in the
attributes
table of amethod_info
structure are listed in Table 4.7-C.The rules concerning attributes defined to appear in the
attributes
table of amethod_info
structure are given in 4.7.The rules concerning nonstandard attributes in the
attributes
table of amethod_info
structure are given in 4.7.1.
4.9 Constraints on Java Virtual Machine Code
4.9.1 Static Constraints
The static constraints on a class
file are those defining the well-formedness of the file. These constraints have been given in the previous sections, except for static constraints on the code in the class
file. The static constraints on the code in a class
file specify how Java Virtual Machine instructions must be laid out in the code
array and what the operands of individual instructions must be.
The static constraints on the instructions in the code
array are as follows:
Only instances of the instructions documented in 6.5 may appear in the
code
array. Instances of instructions using the reserved opcodes (6.2) or any opcodes not documented in this specification must not appear in thecode
array.If the
class
file version number is 51.0 or above, then neither the jsr opcode or the jsr_w opcode may appear in thecode
array.The opcode of the first instruction in the
code
array begins at index0
.For each instruction in the
code
array except the last, the index of the opcode of the next instruction equals the index of the opcode of the current instruction plus the length of that instruction, including all its operands.The wide instruction is treated like any other instruction for these purposes; the opcode specifying the operation that a wide instruction is to modify is treated as one of the operands of that wide instruction. That opcode must never be directly reachable by the computation.
The last byte of the last instruction in the
code
array must be the byte at indexcode_length - 1
.
The static constraints on the operands of instructions in the code
array are as follows:
The target of each jump and branch instruction (jsr, jsr_w, goto, goto_w, ifeq, ifne, ifle, iflt, ifge, ifgt, ifnull, ifnonnull, if_icmpeq, if_icmpne, if_icmple, if_icmplt, if_icmpge, if_icmpgt, if_acmpeq, if_acmpne) must be the opcode of an instruction within this method.
The target of a jump or branch instruction must never be the opcode used to specify the operation to be modified by a wide instruction; a jump or branch target may be the wide instruction itself.
Each target, including the default, of each tableswitch instruction must be the opcode of an instruction within this method.
Each tableswitch instruction must have a number of entries in its jump table that is consistent with the value of its low and high jump table operands, and its low value must be less than or equal to its high value.
No target of a tableswitch instruction may be the opcode used to specify the operation to be modified by a wide instruction; a tableswitch target may be a wide instruction itself.
Each target, including the default, of each lookupswitch instruction must be the opcode of an instruction within this method.
Each lookupswitch instruction must have a number of match-offset pairs that is consistent with the value of its npairs operand. The match-offset pairs must be sorted in increasing numerical order by signed match value.
No target of a lookupswitch instruction may be the opcode used to specify the operation to be modified by a wide instruction; a lookupswitch target may be a wide instruction itself.
The operands of each ldc instruction and each ldc_w instruction must represent a valid index into the
constant_pool
table. The constant pool entry referenced by that index must be loadable (4.4), and not any of the following:An entry of kind
CONSTANT_Long
orCONSTANT_Double
.An entry of kind
CONSTANT_Dynamic
that references aCONSTANT_NameAndType_info
structure which indicates a descriptor ofJ
(denotinglong
) orD
(denotingdouble
).
The operands of each ldc2_w instruction must represent a valid index into the
constant_pool
table. The constant pool entry referenced by that index must be loadable, and in particular one of the following:An entry of kind
CONSTANT_Long
orCONSTANT_Double
.An entry of kind
CONSTANT_Dynamic
that references aCONSTANT_NameAndType_info
structure which indicates a descriptor ofJ
(denotinglong
) orD
(denotingdouble
).
The operands of each getfield, putfield, getstatic, and putstatic instruction must represent a valid index into the
constant_pool
table. The constant pool entry referenced by that index must be of kindCONSTANT_Fieldref
.The indexbyte operands of each invokevirtual instruction must represent a valid index into the
constant_pool
table. The constant pool entry referenced by that index must be of kindCONSTANT_Methodref
.The indexbyte operands of each invokespecial and invokestatic instruction must represent a valid index into the
constant_pool
table. If theclass
file version number is less than 52.0, the constant pool entry referenced by that index must be of kindCONSTANT_Methodref
; if theclass
file version number is 52.0 or above, the constant pool entry referenced by that index must be of kindCONSTANT_Methodref
orCONSTANT_InterfaceMethodref
.The indexbyte operands of each invokeinterface instruction must represent a valid index into the
constant_pool
table. The constant pool entry referenced by that index must be of kindCONSTANT_InterfaceMethodref
.The value of the count operand of each invokeinterface instruction must reflect the number of local variables necessary to store the arguments to be passed to the interface method, as implied by the descriptor of the
CONSTANT_NameAndType_info
structure referenced by theCONSTANT_InterfaceMethodref
constant pool entry.The fourth operand byte of each invokeinterface instruction must have the value zero.
The indexbyte operands of each invokedynamic instruction must represent a valid index into the
constant_pool
table. The constant pool entry referenced by that index must be of kindCONSTANT_InvokeDynamic
.The third and fourth operand bytes of each invokedynamic instruction must have the value zero.
The method name of the
CONSTANT_Methodref
orCONSTANT_InterfaceMethodref
referenced by one of the instructions invokevirtual, invokestatic, or invokeinterface must not be<init>
.The method name of the
CONSTANT_Methodref
orCONSTANT_InterfaceMethodref
referenced by one of the instructions invokevirtual, invokespecial, or invokeinterface must not be<new>
.Only the invokespecial instruction is allowed to invoke an instance initialization method (2.9.1). Only the invokestatic instruction is allowed to invoke an unnamed factory method (2.9.4). No instruction is allowed to invoke a class initialization method, because it cannot be referenced (4.4.2)—such methods are only invoked implicitly by the Java Virtual Machine (5.5).
The operands of each instanceof, checkcast, new, and anewarray instruction, and the indexbyte operands of each multianewarray instruction, must represent a valid index into the
constant_pool
table. The constant pool entry referenced by that index must be of kindCONSTANT_Class
.No new instruction may reference a constant pool entry of kind
CONSTANT_Class
that represents an array type (4.3.2). The new instruction cannot be used to create an array.No anewarray instruction may reference a constant pool entry of kind
CONSTANT_Class
that represents an array type with more than 254 dimensions.A multianewarray instruction must be used only to create an array of a type that has at least as many dimensions as the value of its dimensions operand. That is, while a multianewarray instruction is not required to create all of the dimensions of the array type referenced by its indexbyte operands, it must not attempt to create more dimensions than are in the array type.
The dimensions operand of each multianewarray instruction must not be zero.
The atype operand of each newarray instruction must take one of the values
T_BOOLEAN
(4),T_CHAR
(5),T_FLOAT
(6),T_DOUBLE
(7),T_BYTE
(8),T_SHORT
(9),T_INT
(10), orT_LONG
(11).The index operand of each iload, fload, aload, istore, fstore, astore, iinc, and ret instruction must be a non-negative integer no greater than
max_locals - 1
.The implicit index of each iload_<n>, fload_<n>, aload_<n>, istore_<n>, fstore_<n>, and astore_<n> instruction must be no greater than
max_locals - 1
.The index operand of each lload, dload, lstore, and dstore instruction must be no greater than
max_locals - 2
.The implicit index of each lload_<n>, dload_<n>, lstore_<n>, and dstore_<n> instruction must be no greater than
max_locals - 2
.The indexbyte operands of each wide instruction modifying an iload, fload, aload, istore, fstore, astore, iinc, or ret instruction must represent a non-negative integer no greater than
max_locals - 1
.The indexbyte operands of each wide instruction modifying an lload, dload, lstore, or dstore instruction must represent a non-negative integer no greater than
max_locals - 2
.