com.headius.invokebinder

Class Signature

java.lang.Object

com.headius.invokebinder.Signature

public class Signature
extends java.lang.Object

Signature represents a series of method arguments plus their symbolic names. In order to make it easier to permute arguments, track their flow, and debug cases where reordering or permuting fails to work properly, the Signature class also tracks symbolic names for all arguments. This allows permuting by name or by name pattern, avoiding the error-prone juggling of int[] for the standard MethodHandles.permuteArguments call. A Signature is created starting using #thatReturns method, and expanded using #withArgument for each named argument in sequence. Order is preserved. A Signature can be mutated into another by manipuating the argument list as with java.lang.invoke.MethodType, but using argument names and name patterns instead of integer offsets. Two signatures can be used to produce a permute array suitable for use in java.lang.invoke.MethodHandles#permuteArguments using the #to methods. The #to method can also accept a list of argument names, as a shortcut.

Field Summary

Fields

Modifier and Type	Field and Description
private java.lang.String[]	argNames
private java.lang.invoke.MethodType	methodType

Constructor Summary

Constructors

Constructor and Description
Signature(java.lang.Class retval) Construct a new signature with the given return value.
Signature(java.lang.Class retval, java.lang.Class[] argTypes, java.lang.String... argNames) Construct a new signature with the given return value, argument types, and argument names.
Signature(java.lang.invoke.MethodType methodType, java.lang.String... argNames) Construct a new signature with the given method type and argument names.

Method Summary

Modifier and Type	Method and Description
Signature	appendArg(java.lang.String name, java.lang.Class type) Append an argument (name + type) to the signature.
Signature	appendArgs(java.lang.String[] names, java.lang.Class... types) Append an argument (name + type) to the signature.
java.lang.String	argName(int index) Retrieve the name of the argument at the given index.
java.lang.String[]	argNames() The current argument names for this signature.
int	argOffset(java.lang.String name) Retrieve the offset of the given argument name in this signature's arguments.
int	argOffsets(java.lang.String pattern) Retrieve the offset of the given argument name in this signature's arguments.
java.lang.Class	argType(int index) Get the argument type at the given index.
Signature	asFold(java.lang.Class retval) Produce a new signature based on this one with a different return type.
Signature	changeReturn(java.lang.Class retval) Create a new signature based on this one with a different return type.
Signature	dropArg(int index) Drops the argument at the given index.
Signature	dropArg(java.lang.String name) Drops the first argument with the given name.
Signature	dropFirst() Drop the first argument from this signature.
Signature	dropLast() Drop the last argument from this signature.
Signature	exclude(java.lang.String... excludeArgs) Create a new signature containing the same return value as this one, but omitting the specified arguments.
java.lang.String	firstArgName() Get the first argument name.
java.lang.Class	firstArgType() Get the first argument type.
Signature	insertArg(int index, java.lang.String name, java.lang.Class type) Insert an argument (name + type) into the signature.
Signature	insertArg(java.lang.String beforeName, java.lang.String name, java.lang.Class type) Insert an argument (name + type) into the signature before the argument with the given name.
Signature	insertArgs(int index, java.lang.String[] names, java.lang.Class... types) Insert arguments (names + types) into the signature.
Signature	insertArgs(java.lang.String beforeName, java.lang.String[] names, java.lang.Class... types) Insert arguments (names + types) into the signature before the argument with the given name.
java.lang.String	lastArgName() Get the last argument name.
java.lang.Class	lastArgType() Get the last argument type.
private int[]	nonMatchingTo(java.lang.String... otherArgNames)
Signature	permute(java.lang.String... permuteArgs) Create a new signature containing the same return value as this one, but only the specified arguments.
java.lang.invoke.MethodHandle	permuteWith(java.lang.invoke.MethodHandle target, java.lang.String... permuteArgs) Produce a method handle permuting the arguments in this signature using the given permute arguments and targeting the given java.lang.invoke.MethodHandle.
SmartHandle	permuteWith(SmartHandle target) Produce a new SmartHandle by permuting this Signature's arguments to the Signature of a target SmartHandle.
Signature	prependArg(java.lang.String name, java.lang.Class type) Prepend an argument (name + type) to the signature.
Signature	prependArgs(java.lang.String[] names, java.lang.Class[] types) Prepend an argument (name + type) to the signature.
Signature	replaceArg(java.lang.String oldName, java.lang.String newName, java.lang.Class newType) Replace the named argument with a new name and type.
static Signature	returning(java.lang.Class retval) Create a new signature returning the given type.
Signature	spread(java.lang.String... names) Spread the trailing [] argument into its component type assigning given names.
Signature	spread(java.lang.String[] names, java.lang.Class... types) Spread the trailing [] argument into the given argument types
Signature	spread(java.lang.String baseName, int count) Spread the trailing [] argument into its component type assigning given names.
int[]	to(Signature other) Generate an array of argument offsets based on permuting this signature to the given signature.
int[]	to(java.lang.String... otherArgPatterns) Generate an array of argument offsets based on permuting this signature to the given signature.
java.lang.String	toString() Produce a human-readable representation of this signature.
java.lang.invoke.MethodType	type() The current java.lang.invoke.MethodType for this Signature.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

methodType

private final java.lang.invoke.MethodType methodType

argNames

private final java.lang.String[] argNames

Constructor Detail

Signature

Signature(java.lang.Class retval)

Construct a new signature with the given return value.

Parameters:

retval - the return value for the new signature

Signature

Signature(java.lang.Class retval,
          java.lang.Class[] argTypes,
          java.lang.String... argNames)

Construct a new signature with the given return value, argument types, and argument names.

Parameters:

retval - the return value for the new signature

argTypes - the argument types for the new signature

argNames - the argument names for the new signature

Signature

Signature(java.lang.invoke.MethodType methodType,
          java.lang.String... argNames)

Construct a new signature with the given method type and argument names.

Parameters:

methodType - the method type for the new signature

argNames - the argument names for the new signature

Method Detail

toString

public java.lang.String toString()

Produce a human-readable representation of this signature. This representation uses Class#getSimpleName to improve readability.

Overrides:

toString in class java.lang.Object

Returns:

a human-readable representation of the signature

returning

public static Signature returning(java.lang.Class retval)

Create a new signature returning the given type.

Parameters:

retval - the return type for the new signature

Returns:

the new signature

changeReturn

public Signature changeReturn(java.lang.Class retval)

Create a new signature based on this one with a different return type.

Parameters:

retval - the class for the new signature's return type

Returns:

the new signature

asFold

public Signature asFold(java.lang.Class retval)

Produce a new signature based on this one with a different return type.

Parameters:

retval - the new return type for the new signature

Returns:

the new signature

appendArg

public Signature appendArg(java.lang.String name,
                           java.lang.Class type)

Append an argument (name + type) to the signature.

Parameters:

name - the name of the argument

type - the type of the argument

Returns:

a new signature

appendArgs

public Signature appendArgs(java.lang.String[] names,
                            java.lang.Class... types)

Append an argument (name + type) to the signature.

Parameters:

name - the name of the argument

type - the type of the argument

Returns:

a new signature

prependArg

public Signature prependArg(java.lang.String name,
                            java.lang.Class type)

Prepend an argument (name + type) to the signature.

Parameters:

name - the name of the argument

type - the type of the argument

Returns:

a new signature

prependArgs

public Signature prependArgs(java.lang.String[] names,
                             java.lang.Class[] types)

Prepend an argument (name + type) to the signature.

Parameters:

name - the name of the argument

type - the type of the argument

Returns:

a new signature

insertArg

public Signature insertArg(int index,
                           java.lang.String name,
                           java.lang.Class type)

Insert an argument (name + type) into the signature.

Parameters:

index - the index at which to insert

name - the name of the new argument

type - the type of the new argument

Returns:

a new signature

insertArg

public Signature insertArg(java.lang.String beforeName,
                           java.lang.String name,
                           java.lang.Class type)

Insert an argument (name + type) into the signature before the argument with the given name.

Parameters:

beforeName - the name of the argument before which to insert

name - the name of the new argument

type - the type of the new argument

Returns:

a new signature

insertArgs

public Signature insertArgs(int index,
                            java.lang.String[] names,
                            java.lang.Class... types)

Insert arguments (names + types) into the signature.

Parameters:

index - the index at which to insert

names - the names of the new arguments

types - the types of the new arguments

Returns:

a new signature

insertArgs

public Signature insertArgs(java.lang.String beforeName,
                            java.lang.String[] names,
                            java.lang.Class... types)

Insert arguments (names + types) into the signature before the argument with the given name.

Parameters:

beforeName - the name of the argument before which to insert

names - the names of the new arguments

types - the types of the new arguments

Returns:

dropArg

public Signature dropArg(java.lang.String name)

Drops the first argument with the given name.

Parameters:

name - the name of the argument to drop

Returns:

a new signature

dropArg

public Signature dropArg(int index)

Drops the argument at the given index.

Parameters:

index - the index of the argument to drop

Returns:

a new signature

dropLast

public Signature dropLast()

Drop the last argument from this signature.

Returns:

a new signature

dropFirst

public Signature dropFirst()

Drop the first argument from this signature.

Returns:

a new signature

replaceArg

public Signature replaceArg(java.lang.String oldName,
                            java.lang.String newName,
                            java.lang.Class newType)

Replace the named argument with a new name and type.

Parameters:

oldName - the old name of the argument

newName - the new name of the argument; can be the same as old

oldName - the new type of the argument; can be the same as old

spread

public Signature spread(java.lang.String[] names,
                        java.lang.Class... types)

Spread the trailing [] argument into the given argument types

spread

public Signature spread(java.lang.String... names)

Spread the trailing [] argument into its component type assigning given names.

spread

public Signature spread(java.lang.String baseName,
                        int count)

Spread the trailing [] argument into its component type assigning given names.

type

public java.lang.invoke.MethodType type()

The current java.lang.invoke.MethodType for this Signature.

Returns:

the current method type

argNames

public java.lang.String[] argNames()

The current argument names for this signature.

Returns:

the current argument names

argName

public java.lang.String argName(int index)

Retrieve the name of the argument at the given index.

Parameters:

index - the index from which to get the argument name

Returns:

the argument name

argOffset

public int argOffset(java.lang.String name)

Retrieve the offset of the given argument name in this signature's arguments. If the argument name is not in the argument list, returns -1.

Parameters:

name - the argument name to search for

Returns:

the offset at which the argument name was found or -1

argOffsets

public int argOffsets(java.lang.String pattern)

Retrieve the offset of the given argument name in this signature's arguments. If the argument name is not in the argument list, returns -1.

Parameters:

name - the argument name to search for

Returns:

the offset at which the argument name was found or -1

firstArgName

public java.lang.String firstArgName()

Get the first argument name.

Returns:

the first argument name

lastArgName

public java.lang.String lastArgName()

Get the last argument name.

Returns:

the last argument name

argType

public java.lang.Class argType(int index)

Get the argument type at the given index.

Parameters:

index - the index from which to get the argument type

Returns:

the argument type

firstArgType

public java.lang.Class firstArgType()

Get the first argument type.

Returns:

the first argument type

lastArgType

public java.lang.Class lastArgType()

Get the last argument type.

Returns:

the last argument type

permute

public Signature permute(java.lang.String... permuteArgs)

Create a new signature containing the same return value as this one, but only the specified arguments.

Parameters:

permuteArgs - the names of the arguments to preserve

Returns:

the new signature

exclude

public Signature exclude(java.lang.String... excludeArgs)

Create a new signature containing the same return value as this one, but omitting the specified arguments. Blacklisting to #permute's whitelisting.

Parameters:

excludeArgs - the names of the arguments to exclude

Returns:

the new signature

permuteWith

public java.lang.invoke.MethodHandle permuteWith(java.lang.invoke.MethodHandle target,
                                                 java.lang.String... permuteArgs)

Produce a method handle permuting the arguments in this signature using the given permute arguments and targeting the given java.lang.invoke.MethodHandle. Example:

 Signature sig = Signature.returning(String.class).appendArg("a", int.class).appendArg("b", int.class);
 MethodHandle handle = handleThatTakesOneInt();
 MethodHandle newHandle = sig.permuteTo(handle, "b");
 

Parameters:

target - the method handle to target

permuteArgs - the arguments to permute

Returns:

a new handle that permutes appropriate positions based on the given permute args

permuteWith

public SmartHandle permuteWith(SmartHandle target)

Produce a new SmartHandle by permuting this Signature's arguments to the Signature of a target SmartHandle. The new SmartHandle's signature will match this one, permuting those arguments and invoking the target handle.

Parameters:

target - the SmartHandle to use as a permutation target

Returns:

a new SmartHandle that permutes this Signature's args into a call to the target SmartHandle.

See Also:

permuteWith(java.lang.invoke.MethodHandle, java.lang.String[])

to

public int[] to(Signature other)

Generate an array of argument offsets based on permuting this signature to the given signature.

Parameters:

other - the signature to target

Returns:

an array of argument offsets that will permute to the given signature

to

public int[] to(java.lang.String... otherArgPatterns)

Generate an array of argument offsets based on permuting this signature to the given signature. Repeats are permitted, and the patterns will be matched against actual argument names using regex matching.

Parameters:

otherArgPatterns - the argument name patterns to permute

Returns:

an array of argument offsets that will permute to the matching argument names

nonMatchingTo

private int[] nonMatchingTo(java.lang.String... otherArgNames)