Summary

In the Class-File API, add IllegalArgumentException to methods that accept user-supplied int to truncate to more narrow data formats.

Problem

The Class-File API has many methods that accept user-supplied int values to construct class-file constructs that store more narrow values as u2/u1 (unsigned 2/1 byte). Users currently can pass in out-of-bound values, such as negative values, and they are silently truncated upon writing. They create live data models that are considered different but would be identical once written to class files, and many of these out of range values indicate silent overflows that should have been caught eagerly for program integrity.

Solution

Convert these APIs so they throw IllegalArgumentException whenever they receive an out-of-bounds input. An exception is made for ClassFileVersion::minorVersion, which has a convention of using -1 for 65535, the minor version with all bits set, to indicate preview class files.

Alternative solutions considered include simply performing active truncation so data models would be identical in the views as read from class files; this approach is rejected because these overflow values overwhelmingly indicate program errors that should have been caught eagerly.

The most common data are flag values and indices into lists. In both cases, eager failure almost always seem better.

Specification

The specification patch is attached. Here is the list of APIs changed, ignoring overloads:

java.lang.classfile:

• ClassBuilder::withVersion
• ClassBuilder::withFlags
• ClassBuilder::withField
• ClassBuilder::withMethod
• ClassBuilder::withMethodBody
• ClassFileVersion::of
• CodeBuilder::lineNumber
• CodeBuilder::characterRange
• FieldBuilder::withFlags
• MethodBuilder::withFlags
• TypeAnnotation.TargetInfo::ofParameter
• TypeAnnotation.TargetInfo::ofClassTypeParameter
• TypeAnnotation.TargetInfo::ofMethodTypeParameter
• TypeAnnotation.TargetInfo::ofClassExtends
• TypeAnnotation.TargetInfo::ofTypeParameterBound
• TypeAnnotation.TargetInfo::ofClassTypeParameterBound
• TypeAnnotation.TargetInfo::ofMethodTypeParameterBound
• TypeAnnotation.TargetInfo::ofMethodFormalParameter
• TypeAnnotation.TargetInfo::ofThrows
• TypeAnnotation.TargetInfo::ofExceptionParameter
• TypeAnnotation.TargetInfo::ofTypeArgument
• TypeAnnotation.TargetInfo::ofCastExpr
• TypeAnnotation.TargetInfo::ofConstructorInvocationTypeArgument
• TypeAnnotation.TargetInfo::ofMethodInvocationTypeArgument
• TypeAnnotation.TargetInfo::ofConstructorReferenceTypeArgument
• TypeAnnotation.TargetInfo::ofMethodReferenceTypeArgument
• TypeAnnotation.LocalVarTargetInfo::of
• TypeAnnotation.TypePathComponent::of

attribute:

• CharacterRangeInfo::of
• InnerClassInfo::of
• LineNumberInfo::of
• MethodParameterInfo::of
• MethodParameterInfo::ofParameter
• ModuleAttribute::of
• ModuleAttribute.ModuleAttributeBuilder::moduleFlags
• ModuleExportInfo::of
• ModuleOpenInfo::of
• ModuleRequireInfo::of
• ModuleResolutionAttribute::of

constantpool:

• ConstantPoolBuilder::methodHandleEntry

instruction:

• CharacterRange::of
• LineNumber::of