This specification is not final and is subject to change. Use is subject to license terms.

Unnamed Factory Methods

Changes to the Java® Virtual Machine Specification • Version 15-internal+0-adhoc.dlsmith.20200210

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 value CONSTANT_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 the constant_pool table. The constant_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 the constant_pool entry at that index must be a CONSTANT_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 the constant_pool entry at that index must be a CONSTANT_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 the class file version number is less than 52.0, the constant_pool entry at that index must be a CONSTANT_Methodref_info structure; if the class file version number is 52.0 or above, the constant_pool entry at that index must be either a CONSTANT_Methodref_info structure or a CONSTANT_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 the constant_pool entry at that index must be a CONSTANT_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 (REF_invokeStatic), 7 (REF_invokeSpecial), or 9 (REF_invokeInterface), the name of the method represented by a CONSTANT_Methodref_info structure or a CONSTANT_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 a CONSTANT_Methodref_info structure or a CONSTANT_InterfaceMethodref_info structure must not be <init>.

If the value is 8 (REF_newInvokeSpecial), the name of the method represented by a CONSTANT_Methodref_info structure must be <init>.

In no case may the name be <clinit>, because Methodref and InterfaceMethodref 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:

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 a CONSTANT_Dynamic_info structure has the value CONSTANT_Dynamic (17).

The tag item of a CONSTANT_InvokeDynamic_info structure has the value CONSTANT_InvokeDynamic (18).

bootstrap_method_attr_index

The value of the bootstrap_method_attr_index item must be a valid index into the bootstrap_methods table of the BootstrapMethods attribute of this ClassFile 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 the constant_pool table. The constant_pool entry at that index must be a CONSTANT_NameAndType_info structure (4.4.6). This constant_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 its ACC_PUBLIC, ACC_PRIVATE, and ACC_PROTECTED flags set, and may also have its ACC_VARARGS, ACC_STRICT, and ACC_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 except ACC_STATIC, ACC_STRICT, and ACC_SYNTHETIC are treated by the Java Virtual Machine as if they were not set. In a class file whose version number is 51.0 or greater, the ACC_STATIC flag must be set; in a class file whose version number is less than 51.0, the ACC_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 its ACC_PUBLIC, ACC_PRIVATE, and ACC_PROTECTED flags set (JLS §8.4.3).

Methods of interfaces with names other than <clinit> must not have their ACC_PROTECTED, ACC_FINAL, ACC_SYNCHRONIZED, and ACC_NATIVE flags set (JLS §9.4); exactly one of the ACC_PUBLIC or ACC_PRIVATE flags must be set. They may have any of the other flags in Table 4.6-A set. In a class file whose version number is less than 52.0, each method of an interface with a name other than <clinit> must have its ACC_PUBLIC and ACC_ABSTRACT flags set.

A method of a class or interface named <new> (2.9.4) must have its ACC_STATIC flag set.

If a method of a class or interface has its ACC_ABSTRACT flag set, it must not have any of its ACC_PRIVATE, ACC_STATIC, ACC_FINAL, ACC_SYNCHRONIZED, ACC_NATIVE, or ACC_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 generated class files and are ignored by Java Virtual Machine implementations.

name_index

The value of the name_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_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 the constant_pool table. The constant_pool entry at that index must be a CONSTANT_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 a void method.

  • If the name of the method is <clinit>, then the descriptor must denote a void method, and, in a class 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 the access_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 an attribute_info structure (4.7).

The attributes defined by this specification as appearing in the attributes table of a method_info structure are listed in Table 4.7-C.

The rules concerning attributes defined to appear in the attributes table of a method_info structure are given in 4.7.

The rules concerning nonstandard attributes in the attributes table of a method_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:

The static constraints on the operands of instructions in the code array are as follows: