- All Implemented Interfaces:
Serializable
,Constable
,TypeDescriptor
,TypeDescriptor.OfMethod<Class<?>,
MethodType>
MethodHandle.invokeExact
and MethodHandle.invoke
, and during execution
of invokedynamic
instructions.
The structure is a return type accompanied by any number of parameter types.
The types (primitive, void
, and reference) are represented by Class
objects.
(For ease of exposition, we treat void
as if it were a type.
In fact, it denotes the absence of a return type.)
All instances of MethodType
are immutable.
Two instances are completely interchangeable if they compare equal.
Equality depends on pairwise correspondence of the return and parameter types and on nothing else.
This type can be created only by factory methods. All factory methods may cache values, though caching is not guaranteed. Some factory methods are static, while others are virtual methods which modify precursor method types, e.g., by changing a selected parameter.
Factory methods which operate on groups of parameter types
are systematically presented in two versions, so that both Java arrays and
Java lists can be used to work with groups of parameter types.
The query methods parameterArray
and parameterList
also provide a choice between arrays and lists.
MethodType
objects are sometimes derived from bytecode instructions
such as invokedynamic
, specifically from the type descriptor strings associated
with the instructions in a class file's constant pool.
Like classes and strings, method types can also be represented directly
in a class file's constant pool as constants.
A method type may be loaded by an ldc
instruction which refers
to a suitable CONSTANT_MethodType
constant pool entry.
The entry refers to a CONSTANT_Utf8
spelling for the descriptor string.
(For full details on method type constants, see sections 4.4.8 and 5.4.3.5 of the Java Virtual Machine
Specification.)
When the JVM materializes a MethodType
from a descriptor string,
all classes named in the descriptor must be accessible, and will be loaded.
(But the classes need not be initialized, as is the case with a CONSTANT_Class
.)
This loading may occur at any time before the MethodType
object is first derived.
A MethodType
can be described in nominal form
if and only if all of the parameter types and return type can be described
with a nominal descriptor
represented by
ClassDesc
. If a method type can be described nominally, then:
- The method type has a
nominal descriptor
returned byMethodType::describeConstable
. - The descriptor string returned by
MethodType::descriptorString
orMethodType::toMethodDescriptorString
for the method type is a method descriptor (JVMS 4.3.3).
If any of the parameter types or return type cannot be described
nominally, i.e. Class::describeConstable
returns an empty optional for that type,
then the method type cannot be described nominally:
- The method type has no
nominal descriptor
andMethodType::describeConstable
returns an empty optional. - The descriptor string returned by
MethodType::descriptorString
orMethodType::toMethodDescriptorString
for the method type is not a type descriptor.
- Since:
- 1.7
- See Also:
-
Nested Class Summary
Nested classes/interfaces inherited from interface java.lang.invoke.TypeDescriptor
TypeDescriptor.OfField<F extends TypeDescriptor.OfField<F>>, TypeDescriptor.OfMethod<F extends TypeDescriptor.OfField<F>,
M extends TypeDescriptor.OfMethod<F, M>> -
Method Summary
Modifier and TypeMethodDescriptionappendParameterTypes
(Class<?>... ptypesToInsert) Finds or creates a method type with additional parameter types.appendParameterTypes
(List<Class<?>> ptypesToInsert) Finds or creates a method type with additional parameter types.changeParameterType
(int num, Class<?> nptype) Finds or creates a method type with a single different parameter type.changeReturnType
(Class<?> nrtype) Finds or creates a method type with a different return type.Returns a nominal descriptor for this instance, if one can be constructed, or an emptyOptional
if one cannot be.Returns a descriptor string for this method type.dropParameterTypes
(int start, int end) Finds or creates a method type with some parameter types omitted.boolean
Compares the specified object with this type for equality.erase()
Erases all reference types toObject
.static MethodType
fromMethodDescriptorString
(String descriptor, ClassLoader loader) Finds or creates an instance of a method type, given the spelling of its bytecode descriptor.generic()
Converts all types, both reference and primitive, toObject
.static MethodType
genericMethodType
(int objectArgCount) Finds or creates a method type whose components are allObject
.static MethodType
genericMethodType
(int objectArgCount, boolean finalArray) Finds or creates a method type whose components areObject
with an optional trailingObject[]
array.int
hashCode()
Returns the hash code value for this method type.boolean
Reports if this type contains a primitive argument or return value.boolean
Reports if this type contains a wrapper argument or return value.insertParameterTypes
(int num, Class<?>... ptypesToInsert) Finds or creates a method type with additional parameter types.insertParameterTypes
(int num, List<Class<?>> ptypesToInsert) Finds or creates a method type with additional parameter types.Class<?>
Returns the last parameter type of this method type.static MethodType
methodType
(Class<?> rtype) Finds or creates a method type with the given components.static MethodType
methodType
(Class<?> rtype, Class<?> ptype0) Finds or creates a method type with the given components.static MethodType
methodType
(Class<?> rtype, Class<?>[] ptypes) Finds or creates an instance of the given method type.static MethodType
methodType
(Class<?> rtype, Class<?> ptype0, Class<?>... ptypes) Finds or creates a method type with the given components.static MethodType
methodType
(Class<?> rtype, MethodType ptypes) Finds or creates a method type with the given components.static MethodType
methodType
(Class<?> rtype, List<Class<?>> ptypes) Finds or creates a method type with the given components.Class<?>[]
Presents the parameter types as an array (a convenience method).int
Returns the number of parameter types in this method type.Presents the parameter types as a list (a convenience method).Class<?>
parameterType
(int num) Returns the parameter type at the specified index, within this method type.Class<?>
Returns the return type of this method type.Returns a descriptor string for the method type.toString()
Returns a string representation of the method type, of the form"(PT0,PT1...)RT"
.unwrap()
Converts all wrapper types to their corresponding primitive types.wrap()
Converts all primitive types to their corresponding wrapper types.
-
Method Details
-
methodType
Finds or creates an instance of the given method type.- Parameters:
rtype
- the return typeptypes
- the parameter types- Returns:
- a method type with the given components
- Throws:
NullPointerException
- ifrtype
orptypes
or any element ofptypes
is nullIllegalArgumentException
- if any element ofptypes
isvoid.class
-
methodType
Finds or creates a method type with the given components. Convenience method formethodType
.- Parameters:
rtype
- the return typeptypes
- the parameter types- Returns:
- a method type with the given components
- Throws:
NullPointerException
- ifrtype
orptypes
or any element ofptypes
is nullIllegalArgumentException
- if any element ofptypes
isvoid.class
-
methodType
Finds or creates a method type with the given components. Convenience method formethodType
. The leading parameter type is prepended to the remaining array.- Parameters:
rtype
- the return typeptype0
- the first parameter typeptypes
- the remaining parameter types- Returns:
- a method type with the given components
- Throws:
NullPointerException
- ifrtype
orptype0
orptypes
or any element ofptypes
is nullIllegalArgumentException
- ifptype0
orptypes
or any element ofptypes
isvoid.class
-
methodType
Finds or creates a method type with the given components. Convenience method formethodType
. The resulting method has no parameter types.- Parameters:
rtype
- the return type- Returns:
- a method type with the given return value
- Throws:
NullPointerException
- ifrtype
is null
-
methodType
Finds or creates a method type with the given components. Convenience method formethodType
. The resulting method has the single given parameter type.- Parameters:
rtype
- the return typeptype0
- the parameter type- Returns:
- a method type with the given return value and parameter type
- Throws:
NullPointerException
- ifrtype
orptype0
is nullIllegalArgumentException
- ifptype0
isvoid.class
-
methodType
Finds or creates a method type with the given components. Convenience method formethodType
. The resulting method has the same parameter types asptypes
, and the specified return type.- Parameters:
rtype
- the return typeptypes
- the method type which supplies the parameter types- Returns:
- a method type with the given components
- Throws:
NullPointerException
- ifrtype
orptypes
is null
-
genericMethodType
Finds or creates a method type whose components areObject
with an optional trailingObject[]
array. Convenience method formethodType
. All parameters and the return type will beObject
, except the final array parameter if any, which will beObject[]
.- Parameters:
objectArgCount
- number of parameters (excluding the final array parameter if any)finalArray
- whether there will be a trailing array parameter, of typeObject[]
- Returns:
- a generally applicable method type, for all calls of the given fixed argument count and a collected array of further arguments
- Throws:
IllegalArgumentException
- ifobjectArgCount
is negative or greater than 255 (or 254, iffinalArray
is true)- See Also:
-
genericMethodType
Finds or creates a method type whose components are allObject
. Convenience method formethodType
. All parameters and the return type will be Object.- Parameters:
objectArgCount
- number of parameters- Returns:
- a generally applicable method type, for all calls of the given argument count
- Throws:
IllegalArgumentException
- ifobjectArgCount
is negative or greater than 255- See Also:
-
changeParameterType
Finds or creates a method type with a single different parameter type. Convenience method formethodType
.- Specified by:
changeParameterType
in interfaceTypeDescriptor.OfMethod<Class<?>,
MethodType> - Parameters:
num
- the index (zero-based) of the parameter type to changenptype
- a new parameter type to replace the old one with- Returns:
- the same type, except with the selected parameter changed
- Throws:
IndexOutOfBoundsException
- ifnum
is not a valid index intoparameterArray()
IllegalArgumentException
- ifnptype
isvoid.class
NullPointerException
- ifnptype
is null
-
insertParameterTypes
Finds or creates a method type with additional parameter types. Convenience method formethodType
.- Specified by:
insertParameterTypes
in interfaceTypeDescriptor.OfMethod<Class<?>,
MethodType> - Parameters:
num
- the position (zero-based) of the inserted parameter type(s)ptypesToInsert
- zero or more new parameter types to insert into the parameter list- Returns:
- the same type, except with the selected parameter(s) inserted
- Throws:
IndexOutOfBoundsException
- ifnum
is negative or greater thanparameterCount()
IllegalArgumentException
- if any element ofptypesToInsert
isvoid.class
or if the resulting method type would have more than 255 parameter slotsNullPointerException
- ifptypesToInsert
or any of its elements is null
-
appendParameterTypes
Finds or creates a method type with additional parameter types. Convenience method formethodType
.- Parameters:
ptypesToInsert
- zero or more new parameter types to insert after the end of the parameter list- Returns:
- the same type, except with the selected parameter(s) appended
- Throws:
IllegalArgumentException
- if any element ofptypesToInsert
isvoid.class
or if the resulting method type would have more than 255 parameter slotsNullPointerException
- ifptypesToInsert
or any of its elements is null
-
insertParameterTypes
Finds or creates a method type with additional parameter types. Convenience method formethodType
.- Parameters:
num
- the position (zero-based) of the inserted parameter type(s)ptypesToInsert
- zero or more new parameter types to insert into the parameter list- Returns:
- the same type, except with the selected parameter(s) inserted
- Throws:
IndexOutOfBoundsException
- ifnum
is negative or greater thanparameterCount()
IllegalArgumentException
- if any element ofptypesToInsert
isvoid.class
or if the resulting method type would have more than 255 parameter slotsNullPointerException
- ifptypesToInsert
or any of its elements is null
-
appendParameterTypes
Finds or creates a method type with additional parameter types. Convenience method formethodType
.- Parameters:
ptypesToInsert
- zero or more new parameter types to insert after the end of the parameter list- Returns:
- the same type, except with the selected parameter(s) appended
- Throws:
IllegalArgumentException
- if any element ofptypesToInsert
isvoid.class
or if the resulting method type would have more than 255 parameter slotsNullPointerException
- ifptypesToInsert
or any of its elements is null
-
dropParameterTypes
Finds or creates a method type with some parameter types omitted. Convenience method formethodType
.- Specified by:
dropParameterTypes
in interfaceTypeDescriptor.OfMethod<Class<?>,
MethodType> - Parameters:
start
- the index (zero-based) of the first parameter type to removeend
- the index (greater thanstart
) of the first parameter type after not to remove- Returns:
- the same type, except with the selected parameter(s) removed
- Throws:
IndexOutOfBoundsException
- ifstart
is negative or greater thanparameterCount()
or ifend
is negative or greater thanparameterCount()
or ifstart
is greater thanend
-
changeReturnType
Finds or creates a method type with a different return type. Convenience method formethodType
.- Specified by:
changeReturnType
in interfaceTypeDescriptor.OfMethod<Class<?>,
MethodType> - Parameters:
nrtype
- a return parameter type to replace the old one with- Returns:
- the same type, except with the return type change
- Throws:
NullPointerException
- ifnrtype
is null
-
hasPrimitives
public boolean hasPrimitives()Reports if this type contains a primitive argument or return value. The return typevoid
counts as a primitive.- Returns:
- true if any of the types are primitives
-
hasWrappers
public boolean hasWrappers()Reports if this type contains a wrapper argument or return value. Wrappers are types which box primitive values, such asInteger
. The reference typejava.lang.Void
counts as a wrapper, if it occurs as a return type.- Returns:
- true if any of the types are wrappers
-
erase
Erases all reference types toObject
. Convenience method formethodType
. All primitive types (includingvoid
) will remain unchanged.- Returns:
- a version of the original type with all reference types replaced
-
generic
Converts all types, both reference and primitive, toObject
. Convenience method forgenericMethodType
. The expressiontype.wrap().erase()
produces the same value astype.generic()
.- Returns:
- a version of the original type with all types replaced
-
wrap
Converts all primitive types to their corresponding wrapper types. Convenience method formethodType
. All reference types (including wrapper types) will remain unchanged. Avoid
return type is changed to the typejava.lang.Void
. The expressiontype.wrap().erase()
produces the same value astype.generic()
.- Returns:
- a version of the original type with all primitive types replaced
-
unwrap
Converts all wrapper types to their corresponding primitive types. Convenience method formethodType
. All primitive types (includingvoid
) will remain unchanged. A return type ofjava.lang.Void
is changed tovoid
.- Returns:
- a version of the original type with all wrapper types replaced
-
parameterType
Returns the parameter type at the specified index, within this method type.- Specified by:
parameterType
in interfaceTypeDescriptor.OfMethod<Class<?>,
MethodType> - Parameters:
num
- the index (zero-based) of the desired parameter type- Returns:
- the selected parameter type
- Throws:
IndexOutOfBoundsException
- ifnum
is not a valid index intoparameterArray()
-
parameterCount
public int parameterCount()Returns the number of parameter types in this method type.- Specified by:
parameterCount
in interfaceTypeDescriptor.OfMethod<Class<?>,
MethodType> - Returns:
- the number of parameter types
-
returnType
Returns the return type of this method type.- Specified by:
returnType
in interfaceTypeDescriptor.OfMethod<Class<?>,
MethodType> - Returns:
- the return type
-
parameterList
Presents the parameter types as a list (a convenience method). The list will be immutable.- Specified by:
parameterList
in interfaceTypeDescriptor.OfMethod<Class<?>,
MethodType> - Returns:
- the parameter types (as an immutable list)
-
lastParameterType
Returns the last parameter type of this method type. If this type has no parameters, the sentinel valuevoid.class
is returned instead.- API Note:
The sentinel value is chosen so that reflective queries can be made directly against the result value. The sentinel value cannot be confused with a real parameter, since
void
is never acceptable as a parameter type. For variable arity invocation modes, the expressionlastParameterType().getComponentType()
is useful to query the type of the "varargs" parameter.- Returns:
- the last parameter type if any, else
void.class
- Since:
- 10
-
parameterArray
Presents the parameter types as an array (a convenience method). Changes to the array will not result in changes to the type.- Specified by:
parameterArray
in interfaceTypeDescriptor.OfMethod<Class<?>,
MethodType> - Returns:
- the parameter types (as a fresh copy if necessary)
-
equals
Compares the specified object with this type for equality. That is, it returnstrue
if and only if the specified object is also a method type with exactly the same parameters and return type. -
hashCode
public int hashCode()Returns the hash code value for this method type. It is defined to be the same as the hashcode of a List whose elements are the return type followed by the parameter types. -
toString
Returns a string representation of the method type, of the form"(PT0,PT1...)RT"
. The string representation of a method type is a parenthesis enclosed, comma separated list of type names, followed immediately by the return type.Each type is represented by its
simple name
. -
fromMethodDescriptorString
public static MethodType fromMethodDescriptorString(String descriptor, ClassLoader loader) throws IllegalArgumentException, TypeNotPresentException Finds or creates an instance of a method type, given the spelling of its bytecode descriptor. Convenience method formethodType
. Any class or interface name embedded in the descriptor string will be resolved by the given loader (or if it is null, on the system class loader).Note that it is possible to encounter method types which cannot be constructed by this method, because their component types are not all reachable from a common class loader.
This method is included for the benefit of applications that must generate bytecodes that process method handles and
invokedynamic
.- Parameters:
descriptor
- a bytecode-level type descriptor string "(T...)T"loader
- the class loader in which to look up the types- Returns:
- a method type matching the bytecode-level type descriptor
- Throws:
NullPointerException
- if the string is nullIllegalArgumentException
- if the string is not well-formedTypeNotPresentException
- if a named type cannot be foundSecurityException
- if the security manager is present andloader
isnull
and the caller does not have theRuntimePermission
("getClassLoader")
-
toMethodDescriptorString
Returns a descriptor string for the method type. This method is equivalent to callingMethodType::descriptorString
.Note that this is not a strict inverse of
fromMethodDescriptorString
. Two distinct classes which share a common name but have different class loaders will appear identical when viewed within descriptor strings.This method is included for the benefit of applications that must generate bytecodes that process method handles and
invokedynamic
.fromMethodDescriptorString
, because the latter requires a suitable class loader argument.- Returns:
- the descriptor string for this method type
- See Java Virtual Machine Specification:
-
4.3.3 Method Descriptors
- See Also:
-
descriptorString
Returns a descriptor string for this method type.If this method type can be described nominally, then the result is a method type descriptor (JVMS 4.3.3).
MethodTypeDesc
for this method type can be produced by callingMethodTypeDesc::ofDescriptor
with the result descriptor string.If this method type cannot be described nominally and the result is a string of the form:
where"(<parameter-descriptors>)<return-descriptor>"
<parameter-descriptors>
is the concatenation of the descriptor string of all of the parameter types and the descriptor string of the return type. NoMethodTypeDesc
can be produced from the result string.- Specified by:
descriptorString
in interfaceTypeDescriptor
- Returns:
- the descriptor string for this method type
- See Java Virtual Machine Specification:
-
4.3.3 Method Descriptors
- Since:
- 12
- See Also:
-
describeConstable
Returns a nominal descriptor for this instance, if one can be constructed, or an emptyOptional
if one cannot be.- Specified by:
describeConstable
in interfaceConstable
- Returns:
- An
Optional
containing the resulting nominal descriptor, or an emptyOptional
if one cannot be constructed. - Since:
- 12
- See Also:
-