Class Binder

java.lang.Object
com.headius.invokebinder.Binder

public class Binder extends Object
The Binder class provides a DSL for building a chain of MethodHandles using various of the adaptations provided by java.lang.invoke.MethodHandles. The transformations are pushed into a stack, allowing the DSL to operate forward from an incoming signature rather than backward from a target handle. This is often conceptually easier to understand, and certainly easier to read. The transformations are also applied simultaneously to the starting java.lang.invoke.MethodType, allowing Binder to check at each step whether the adaptation is valid. Here's a typical use, starting with a signature that takes two Strings and returns a String, dropping and inserting arguments, casting to a target signature, and finally calling a target handle with that signature.
 MethodHandle mh = Binder
     .from(String.class, String.class, String.class) // String w(String, String)
     .drop(1, String.class) // String x(String)
     .insert(0, 'hello') // String y(String, String)
     .cast(String.class, CharSequence.class, Object.class) // String z(CharSequence, Object)String
     .invoke(someTargetHandle);
 
  • Constructor Details

    • Binder

      public Binder(MethodType start)
      Construct a new Binder, starting from a given MethodType. Use a public java.lang.invoke.MethodHandles.Lookup for retrieving direct handles.
      Parameters:
      start - the starting MethodType, for calls entering the eventual chain
    • Binder

      public Binder(MethodHandles.Lookup lookup, MethodType start)
      Construct a new Binder, starting from a given Lookup and MethodType.
      Parameters:
      lookup - the Lookup context to use for direct handles
      start - the starting MethodType, for calls entering the eventual chain
    • Binder

      public Binder(Binder source)
      Construct a new Binder using the given invokebinder.
      Parameters:
      source - a Binder to duplicate
    • Binder

      public Binder(MethodHandles.Lookup lookup, Binder source)
      Construct a new Binder using the given Lookup and invokebinder.
      Parameters:
      lookup - the Lookup context to use for direct handles
      source - the source Binder
    • Binder

      public Binder(Binder source, com.headius.invokebinder.transform.Transform transform)
      Construct a new Binder using the given invokebinder plus an additional transform
      Parameters:
      source - the source Binder
      transform - the additional Transform
    • Binder

      public Binder(Binder source, com.headius.invokebinder.transform.Transform transform, MethodType type)
      Construct a new Binder using the given invokebinder plus an additional transform and current type
      Parameters:
      source - the source Binder
      transform - the additional Transform
      type - the new current type resulting from the transform
  • Method Details

    • from

      public static Binder from(MethodType start)
      Construct a new Binder, starting from a given MethodType.
      Parameters:
      start - the starting MethodType, for calls entering the eventual chain
      Returns:
      the Binder object
    • from

      public static Binder from(MethodHandles.Lookup lookup, MethodType start)
      Construct a new Binder, starting from a given MethodType.
      Parameters:
      lookup - the Lookup context to use for direct handles
      start - the starting MethodType, for calls entering the eventual chain
      Returns:
      the Binder object
    • from

      public static Binder from(Class<?> returnType)
      Construct a new Binder using a return type.
      Parameters:
      returnType - the return type of the incoming signature
      Returns:
      the Binder object
    • from

      public static Binder from(MethodHandles.Lookup lookup, Class<?> returnType)
      Construct a new Binder using a return type.
      Parameters:
      lookup - the Lookup context to use for direct handles
      returnType - the return type of the incoming signature
      Returns:
      the Binder object
    • from

      public static Binder from(Class<?> returnType, Class<?>[] argTypes)
      Construct a new Binder using a return type and argument types.
      Parameters:
      returnType - the return type of the incoming signature
      argTypes - the argument types of the incoming signature
      Returns:
      the Binder object
    • from

      public static Binder from(MethodHandles.Lookup lookup, Class<?> returnType, Class<?>[] argTypes)
      Construct a new Binder using a return type and argument types.
      Parameters:
      lookup - the Lookup context to use for direct handles
      returnType - the return type of the incoming signature
      argTypes - the argument types of the incoming signature
      Returns:
      the Binder object
    • from

      public static Binder from(Class<?> returnType, Class<?> argType0, Class<?>... argTypes)
      Construct a new Binder using a return type and argument types.
      Parameters:
      returnType - the return type of the incoming signature
      argType0 - the first argument type of the incoming signature
      argTypes - the remaining argument types of the incoming signature
      Returns:
      the Binder object
    • from

      public static Binder from(MethodHandles.Lookup lookup, Class<?> returnType, Class<?> argType0, Class<?>... argTypes)
      Construct a new Binder using a return type and argument types.
      Parameters:
      lookup - the Lookup context to use for direct handles
      returnType - the return type of the incoming signature
      argType0 - the first argument type of the incoming signature
      argTypes - the remaining argument types of the incoming signature
      Returns:
      the Binder object
    • from

      public static Binder from(Binder start)
      Construct a new Binder, starting from a given invokebinder.
      Parameters:
      start - the starting invokebinder; the new one will start with the current endpoint type of the given invokebinder
      Returns:
      the Binder object
    • from

      public static Binder from(MethodHandles.Lookup lookup, Binder start)
      Construct a new Binder, starting from a given invokebinder.
      Parameters:
      lookup - the Lookup context to use for direct handles
      start - the starting invokebinder; the new one will start with the current endpoint type of the given invokebinder
      Returns:
      the Binder object
    • to

      public Binder to(Binder other)
      Join this binder to an existing one by applying its transformations after this one.
      Parameters:
      other - the Binder containing the set of transformations to append
      Returns:
      a new Binder combining this Binder with the target Binder
    • withLookup

      public Binder withLookup(MethodHandles.Lookup lookup)
      Use an alternate java.lang.invoke.MethodHandles.Lookup as the default for any direct handles created.
      Parameters:
      lookup - the new Lookup context to use
      Returns:
      a new Binder with the given lookup
    • type

      public MethodType type()
      The current MethodType, were the handle chain to terminate at this point.
      Returns:
      the current MethodType
    • printType

      public Binder printType(PrintStream ps)
      Println the current MethodType to the given stream.
      Parameters:
      ps - a PrintStream to which to println the current MethodType
      Returns:
      this Binding
    • printType

      public Binder printType()
      Println the current MethodType to stdout.
      Returns:
      this Binding
    • logType

      public Binder logType()
      Log the current MethodType as info.
      Returns:
      this Binding
    • insert

      public Binder insert(int index, boolean value)
      Insert at the given index the given boolean value.
      Parameters:
      index - the index at which to insert the argument value
      value - the value to insert
      Returns:
      a new Binder
    • insert

      public Binder insert(int index, byte value)
      Insert at the given index the given byte value.
      Parameters:
      index - the index at which to insert the argument value
      value - the value to insert
      Returns:
      a new Binder
    • insert

      public Binder insert(int index, short value)
      Insert at the given index the given short value.
      Parameters:
      index - the index at which to insert the argument value
      value - the value to insert
      Returns:
      a new Binder
    • insert

      public Binder insert(int index, char value)
      Insert at the given index the given char value.
      Parameters:
      index - the index at which to insert the argument value
      value - the value to insert
      Returns:
      a new Binder
    • insert

      public Binder insert(int index, int value)
      Insert at the given index the given int value.
      Parameters:
      index - the index at which to insert the argument value
      value - the value to insert
      Returns:
      a new Binder
    • insert

      public Binder insert(int index, long value)
      Insert at the given index the given long value.
      Parameters:
      index - the index at which to insert the argument value
      value - the value to insert
      Returns:
      a new Binder
    • insert

      public Binder insert(int index, float value)
      Insert at the given index the given float value.
      Parameters:
      index - the index at which to insert the argument value
      value - the value to insert
      Returns:
      a new Binder
    • insert

      public Binder insert(int index, double value)
      Insert at the given index the given double value.
      Parameters:
      index - the index at which to insert the argument value
      value - the value to insert
      Returns:
      a new Binder
    • insert

      public Binder insert(int index, Object... values)
      Insert at the given index the given argument value(s).
      Parameters:
      index - the index at which to insert the argument value
      values - the value(s) to insert
      Returns:
      a new Binder
    • insert

      public Binder insert(int index, Class<?> type, Object value)
      Insert at the given index the given argument value.
      Parameters:
      index - the index at which to insert the argument value
      type - the actual type to use, rather than getClass
      value - the value to insert
      Returns:
      a new Binder
    • insert

      public Binder insert(int index, Class<?>[] types, Object... values)
      Insert at the given index the given argument value(s).
      Parameters:
      index - the index at which to insert the argument value
      types - the actual types to use, rather than getClass
      values - the value(s) to insert
      Returns:
      a new Binder
    • append

      public Binder append(boolean value)
      Append to the argument list the given boolean value.
      Parameters:
      value - the value to append
      Returns:
      a new Binder
    • appendBooleans

      public Binder appendBooleans(boolean... values)
      Append to the argument list the given boolean values.
      Parameters:
      values - the value to append
      Returns:
      a new Binder
    • append

      public Binder append(byte value)
      Append to the argument list the given byte value.
      Parameters:
      value - the value to append
      Returns:
      a new Binder
    • appendBytes

      public Binder appendBytes(byte... values)
      Append to the argument list the given byte values.
      Parameters:
      values - the values to append
      Returns:
      a new Binder
    • append

      public Binder append(short value)
      Append to the argument list the given short value.
      Parameters:
      value - the value to append
      Returns:
      a new Binder
    • appendShorts

      public Binder appendShorts(short... values)
      Append to the argument list the given short values.
      Parameters:
      values - the values to append
      Returns:
      a new Binder
    • append

      public Binder append(char value)
      Append to the argument list the given char value.
      Parameters:
      value - the value to append
      Returns:
      a new Binder
    • appendChars

      public Binder appendChars(char... values)
      Append to the argument list the given char values.
      Parameters:
      values - the values to append
      Returns:
      a new Binder
    • append

      public Binder append(int value)
      Append to the argument list the given int value.
      Parameters:
      value - the value to append
      Returns:
      a new Binder
    • appendInts

      public Binder appendInts(int... values)
      Append to the argument list the given int values.
      Parameters:
      values - the values to append
      Returns:
      a new Binder
    • append

      public Binder append(long value)
      Append to the argument list the given long value.
      Parameters:
      value - the value to append
      Returns:
      a new Binder
    • appendLongs

      public Binder appendLongs(long... values)
      Append to the argument list the given long values.
      Parameters:
      values - the values to append
      Returns:
      a new Binder
    • append

      public Binder append(float value)
      Append to the argument list the given float value.
      Parameters:
      value - the value to append
      Returns:
      a new Binder
    • appendFloats

      public Binder appendFloats(float... values)
      Append to the argument list the given float values.
      Parameters:
      values - the values to append
      Returns:
      a new Binder
    • append

      public Binder append(double value)
      Append to the argument list the given double value.
      Parameters:
      value - the value to append
      Returns:
      a new Binder
    • appendDoubles

      public Binder appendDoubles(double... values)
      Append to the argument list the given double values.
      Parameters:
      values - the values to append
      Returns:
      a new Binder
    • append

      public Binder append(Object... values)
      Append to the argument list the given argument value(s).
      Parameters:
      values - the value(s) to append
      Returns:
      a new Binder
    • appendWithTypes

      public Binder appendWithTypes(Object... typesAndValues)
      Append to the argument list the given argument type(s) and value(s), provided as (Class, value) pairs of arguments.
      Parameters:
      typesAndValues - the value(s) to append
      Returns:
      a new Binder
    • prepend

      public Binder prepend(boolean value)
      Prepend to the argument list the given boolean value.
      Parameters:
      value - the value to prepend
      Returns:
      a new Binder
    • prependBooleans

      public Binder prependBooleans(boolean... values)
      Prepend to the argument list the given boolean values.
      Parameters:
      values - the values to prepend
      Returns:
      a new Binder
    • prepend

      public Binder prepend(byte value)
      Prepend to the argument list the given byte value.
      Parameters:
      value - the value to prepend
      Returns:
      a new Binder
    • prependBytes

      public Binder prependBytes(byte... values)
      Prepend to the argument list the given byte values.
      Parameters:
      values - the values to prepend
      Returns:
      a new Binder
    • prepend

      public Binder prepend(short value)
      Prepend to the argument list the given short value.
      Parameters:
      value - the value to prepend
      Returns:
      a new Binder
    • prependShorts

      public Binder prependShorts(short... values)
      Prepend to the argument list the given short values.
      Parameters:
      values - the values to prepend
      Returns:
      a new Binder
    • prepend

      public Binder prepend(char value)
      Prepend to the argument list the given char value.
      Parameters:
      value - the value to prepend
      Returns:
      a new Binder
    • prependChars

      public Binder prependChars(char... values)
      Prepend to the argument list the given char values.
      Parameters:
      values - the values to prepend
      Returns:
      a new Binder
    • prepend

      public Binder prepend(int value)
      Prepend to the argument list the given int value.
      Parameters:
      value - the value to prepend
      Returns:
      a new Binder
    • prependInts

      public Binder prependInts(int... values)
      Prepend to the argument list the given int values.
      Parameters:
      values - the values to prepend
      Returns:
      a new Binder
    • prepend

      public Binder prepend(long value)
      Prepend to the argument list the given long value.
      Parameters:
      value - the value to prepend
      Returns:
      a new Binder
    • prependLongs

      public Binder prependLongs(long... values)
      Prepend to the argument list the given long values.
      Parameters:
      values - the values to prepend
      Returns:
      a new Binder
    • prepend

      public Binder prepend(float value)
      Prepend to the argument list the given float value.
      Parameters:
      value - the value to prepend
      Returns:
      a new Binder
    • prependFloats

      public Binder prependFloats(float... values)
      Prepend to the argument list the given float values.
      Parameters:
      values - the values to prepend
      Returns:
      a new Binder
    • prepend

      public Binder prepend(double value)
      Prepend to the argument list the given double value.
      Parameters:
      value - the value to prepend
      Returns:
      a new Binder
    • prependDoubles

      public Binder prependDoubles(double... values)
      Prepend to the argument list the given double values.
      Parameters:
      values - the values to prepend
      Returns:
      a new Binder
    • prepend

      public Binder prepend(Object... values)
      Prepend to the argument list the given argument value(s).
      Parameters:
      values - the value(s) to prepend
      Returns:
      a new Binder
    • prependWithTypes

      public Binder prependWithTypes(Object... typesAndValues)
      Prepend to the argument list the given argument type(s) and value(s), provided as (Class, value) pairs of arguments.
      Parameters:
      typesAndValues - the value(s) to append
      Returns:
      a new Binder
    • append

      public Binder append(Class<?> type, Object value)
      Append to the argument list the given argument value with the specified type.
      Parameters:
      type - the actual type to use, rather than getClass
      value - the value to append
      Returns:
      a new Binder
    • append

      public Binder append(Class<?>[] types, Object... values)
      Append to the argument list the given argument values with the specified types.
      Parameters:
      types - the actual types to use, rather than getClass
      values - the value(s) to append
      Returns:
      a new Binder
    • prepend

      public Binder prepend(Class<?> type, Object value)
      Prepend to the argument list the given argument value with the specified type
      Parameters:
      type - the actual type to use, rather than getClass
      value - the value(s) to prepend
      Returns:
      a new Binder
    • prepend

      public Binder prepend(Class<?>[] types, Object... values)
      Prepend to the argument list the given argument values with the specified types.
      Parameters:
      types - the actual types to use, rather than getClass
      values - the value(s) to prepend
      Returns:
      a new Binder
    • drop

      public Binder drop(int index)
      Drop a single argument at the given index.
      Parameters:
      index - the index at which to drop an argument
      Returns:
      a new Binder
    • drop

      public Binder drop(int index, int count)
      Drop from the given index a number of arguments.
      Parameters:
      index - the index at which to start dropping
      count - the number of arguments to drop
      Returns:
      a new Binder
    • dropLast

      public Binder dropLast()
      Drop a single argument at the end of the argument list.
      Returns:
      a new Binder
    • dropLast

      public Binder dropLast(int count)
      Drop from the end of the argument list a number of arguments.
      Parameters:
      count - the number of arguments to drop
      Returns:
      a new Binder
    • dropFirst

      public Binder dropFirst()
      Drop a single argument at the beginning of the argument list.
      Returns:
      a new Binder
    • dropFirst

      public Binder dropFirst(int count)
      Drop from the end of the argument list a number of arguments.
      Parameters:
      count - the number of arguments to drop
      Returns:
      a new Binder
    • dropAll

      public Binder dropAll()
      Drop all arguments from this handle chain
      Returns:
      a new Binder
    • convert

      public Binder convert(MethodType target)
      Convert the incoming arguments to the given MethodType. The conversions applied are equivalent to those in MethodHandle.asType(MethodType).
      Parameters:
      target - the target MethodType
      Returns:
      a new Binder
    • convert

      public Binder convert(Class<?> returnType, Class<?>... argTypes)
      Convert the incoming arguments to the given MethodType. The conversions applied are equivalent to those in MethodHandle.asType(MethodType).
      Parameters:
      returnType - the target return type
      argTypes - the target argument types
      Returns:
      a new Binder
    • cast

      public Binder cast(MethodType type)
      Cast the incoming arguments to the given MethodType. The casts applied are equivalent to those in MethodHandles.explicitCastArguments(mh, MethodType).
      Parameters:
      type - the target MethodType
      Returns:
      a new Binder
    • cast

      public Binder cast(Class<?> returnType, Class<?>... argTypes)
      Cast the incoming arguments to the given MethodType. The casts applied are equivalent to those in MethodHandle.explicitCastArguments(MethodType).
      Parameters:
      returnType - the target return type
      argTypes - the target argument types
      Returns:
      a new Binder
    • castVirtual

      public Binder castVirtual(Class<?> returnType, Class<?> firstType, Class<?>... restTypes)
      Cast the incoming arguments to the given MethodType. The casts applied are equivalent to those in MethodHandle.explicitCastArguments(MethodType).
      Parameters:
      returnType - the target return type
      firstType - the first argument type, usually a target type
      restTypes - the remaining target argument types
      Returns:
      a new Binder
    • spread

      public Binder spread(Class<?>... spreadTypes)
      Spread a trailing array argument into the specified argument types.
      Parameters:
      spreadTypes - the types into which to spread the incoming Object[]
      Returns:
      a new Binder
    • spread

      public Binder spread(int count)
      Spread a trailing array argument into the given number of arguments of the type of the array.
      Parameters:
      count - the new count of arguments to spread from the trailing array
      Returns:
      a new Binder
    • collect

      public Binder collect(int index, Class<?> type)
      Box all incoming arguments from the given position onward into the given array type.
      Parameters:
      index - the index from which to start boxing args
      type - the array type into which the args will be boxed
      Returns:
      a new Binder
    • collect

      public Binder collect(int index, Class<?> type, MethodHandle collector)
      Box all incoming arguments from the given position onward into the given array type.
      Parameters:
      index - the index from which to start boxing args
      type - the array type into which the args will be boxed
      collector - a function to use for collecting the arguments
      Returns:
      a new Binder
    • collect

      public Binder collect(int index, int count, Class<?> type)
      Box a range of incoming arguments into the given array type.
      Parameters:
      index - the index from which to start boxing args
      count - the count of arguments to box
      type - the array type into which the args will be boxed
      Returns:
      a new Binder
    • collect

      public Binder collect(int index, int count, Class<?> type, MethodHandle collector)
      Box a range of incoming arguments into the given array type using the given constructor to construct the array. The collector signature should match (T1, ..., Tn) where T is the type of the arguments being collected and n is the number of arguments being collected.
      Parameters:
      index - the index from which to start boxing args
      count - the count of arguments to box
      type - the array type into which the args will be boxed
      collector - a function to use for collecting the arguments
      Returns:
      a new Binder
    • varargs

      public Binder varargs(int index, Class<?> type)
      Box all incoming arguments from the given position onward into the given array type. This version accepts a variable number of incoming arguments.
      Parameters:
      index - the index from which to start boxing args
      type - the array type into which the args will be boxed
      Returns:
      a new Binder
    • permute

      public Binder permute(int... reorder)
      Permute the incoming arguments to a new sequence specified by the given values. Arguments may be duplicated or dropped in this sequence.
      Parameters:
      reorder - the int offsets of the incoming arguments in the desired permutation
      Returns:
      a new Binder
    • fold

      public Binder fold(MethodHandle function)
      Process the incoming arguments using the given handle, inserting the result as the first argument.
      Parameters:
      function - the function that will process the incoming arguments. Its signature must match the current signature's arguments exactly.
      Returns:
      a new Binder
    • foldVoid

      public Binder foldVoid(MethodHandle function)
      Process the incoming arguments using the given handle, leaving the argument list unmodified.
      Parameters:
      function - the function that will process the incoming arguments. Its signature must match the current signature's arguments exactly.
      Returns:
      a new Binder
    • foldStatic

      public Binder foldStatic(MethodHandles.Lookup lookup, Class<?> target, String method)
      Process the incoming arguments by calling the given static method on the given class, inserting the result as the first argument.
      Parameters:
      lookup - the java.lang.invoke.MethodHandles.Lookup to use
      target - the class on which the method is defined
      method - the method to invoke on the first argument
      Returns:
      a new Binder
    • foldStatic

      public Binder foldStatic(Class<?> target, String method)
      Process the incoming arguments by calling the given static method on the given class, inserting the result as the first argument.
      Parameters:
      target - the class on which the method is defined
      method - the method to invoke on the first argument
      Returns:
      a new Binder
    • foldVirtual

      public Binder foldVirtual(MethodHandles.Lookup lookup, String method)
      Process the incoming arguments by calling the given method on the first argument, inserting the result as the first argument.
      Parameters:
      lookup - the java.lang.invoke.MethodHandles.Lookup to use
      method - the method to invoke on the first argument
      Returns:
      a new Binder
    • foldVirtual

      public Binder foldVirtual(String method)
      Process the incoming arguments by calling the given method on the first argument, inserting the result as the first argument.
      Parameters:
      method - the method to invoke on the first argument
      Returns:
      a new Binder
    • filter

      public Binder filter(int index, MethodHandle... functions)
      Filter incoming arguments, from the given index, replacing each with the result of calling the associated function in the given list. Note that the order in which the filters are applied is undefined; OpenJDK produces handles that execute them in reverse order.
      Parameters:
      index - the index of the first argument to filter
      functions - the array of functions to transform the arguments
      Returns:
      a new Binder
      See Also:
    • filterForward

      public Binder filterForward(int index, MethodHandle... functions)
      Filter incoming arguments, from the given index, replacing each with the result of calling the associated function in the given list. This version guarantees left-to-right evaluation of filter functions, potentially at the cost of a more complex handle tree.
      Parameters:
      index - the index of the first argument to filter
      functions - the array of functions to transform the arguments
      Returns:
      a new Binder
    • filterReturn

      public Binder filterReturn(MethodHandle function)
      Filter return value, using a function that produces the current return type from another type. The new endpoint will have the return value that the filter function accepts as an argument.
      Parameters:
      function - the array of functions to transform the arguments
      Returns:
      a new Binder
    • tryFinally

      public Binder tryFinally(MethodHandle post)
      Apply transforms to run the given handle's logic as a "finally" block. try { some_code // your eventual endpoint } finally { finally_logic // the given handle } The layering uses a combination of catch and fold to reuse the same target handle for both exceptional and non-exceptional paths. In essence, the result is equivalent to using the given post logic as both an exception handler (using catchException) and a "post fold" that runs after the main downstream handles have run.
      Parameters:
      post - the logic that would live inside the "finally" block
      Returns:
      a new Binder
    • catchException

      public Binder catchException(Class<? extends Throwable> throwable, MethodHandle function)
      Catch the given exception type from the downstream chain and handle it with the given function.
      Parameters:
      throwable - the exception type to catch
      function - the function to use for handling the exception
      Returns:
      a new Binder
    • nop

      public MethodHandle nop()
      Apply all transforms to an endpoint that does absolutely nothing. Useful for creating exception handlers in void methods that simply ignore the exception.
      Returns:
      a handle that has all transforms applied and does nothing at its endpoint
    • throwException

      public MethodHandle throwException()
      Throw the current signature's sole Throwable argument. Return type does not matter, since it will never return.
      Returns:
      a handle that has all transforms applied and which will eventually throw an exception
    • constant

      public MethodHandle constant(Object value)
      Apply the tranforms, binding them to a constant value that will propagate back through the chain. The chain's expected return type at that point must be compatible with the given value's type.
      Parameters:
      value - the constant value to put at the end of the chain
      Returns:
      a handle that has all transforms applied in sequence up to the constant
    • identity

      public MethodHandle identity()
      Apply the tranforms, binding them to a handle that will simply return its sole argument as its return value. The endpoint signature must have a single argument of the same type as its return type.
      Returns:
      a handle that has all transforms applied in sequence
    • invoke

      public MethodHandle invoke(MethodHandle target)
      Apply the chain of transforms with the target method handle as the final endpoint. Produces a handle that has the transforms in given sequence. If the final handle's type does not exactly match the initial type for this Binder, an additional cast will be attempted.
      Parameters:
      target - the endpoint handle to bind to
      Returns:
      a handle that has all transforms applied in sequence up to endpoint
    • invoke

      public MethodHandle invoke(MethodHandles.Lookup lookup, Method method) throws IllegalAccessException
      Apply the chain of transforms and bind them to a static method specified using the end signature plus the given class and method. The method will be retrieved using the given Lookup and must match the end signature exactly. If the final handle's type does not exactly match the initial type for this Binder, an additional cast will be attempted.
      Parameters:
      lookup - the MethodHandles.Lookup to use to unreflect the method
      method - the Method to unreflect
      Returns:
      the full handle chain, bound to the given method
      Throws:
      IllegalAccessException - if the method is not accessible
    • invoke

      public MethodHandle invoke(Method method) throws IllegalAccessException
      Same as invoke(MethodHandles.Lookup, Method method) but using the default lookup for this binder.
      Throws:
      IllegalAccessException
    • invokeQuiet

      public MethodHandle invokeQuiet(MethodHandles.Lookup lookup, Method method)
      Apply the chain of transforms and bind them to a static method specified using the end signature plus the given class and method. The method will be retrieved using the given Lookup and must match the end signature exactly. If the final handle's type does not exactly match the initial type for this Binder, an additional cast will be attempted. This version is "quiet" in that it throws an unchecked InvalidTransformException if the target method does not exist or is inaccessible.
      Parameters:
      lookup - the MethodHandles.Lookup to use to unreflect the method
      method - the Method to unreflect
      Returns:
      the full handle chain, bound to the given method
    • invokeQuiet

      public MethodHandle invokeQuiet(Method method)
      Same as invokeQuiet(MethodHandles.Lookup, Method method) but using the default lookup for this binder.
    • invokeStatic

      public MethodHandle invokeStatic(MethodHandles.Lookup lookup, Class<?> target, String name) throws NoSuchMethodException, IllegalAccessException
      Apply the chain of transforms and bind them to a static method specified using the end signature plus the given class and name. The method will be retrieved using the given Lookup and must match the end signature exactly. If the final handle's type does not exactly match the initial type for this Binder, an additional cast will be attempted.
      Parameters:
      lookup - the MethodHandles.Lookup to use to unreflect the method
      target - the class in which to find the method
      name - the name of the method to invoke
      Returns:
      the full handle chain, bound to the given method
      Throws:
      NoSuchMethodException - if the method does not exist
      IllegalAccessException - if the method is not accessible
    • invokeStatic

      public MethodHandle invokeStatic(Class<?> target, String name) throws NoSuchMethodException, IllegalAccessException
      Same as invokeStaticQuiet(MethodHandles.Lookup, Class, String) but using the default lookup for this binder.
      Throws:
      NoSuchMethodException
      IllegalAccessException
    • invokeStaticQuiet

      public MethodHandle invokeStaticQuiet(MethodHandles.Lookup lookup, Class<?> target, String name)
      Apply the chain of transforms and bind them to a static method specified using the end signature plus the given class and name. The method will be retrieved using the given Lookup and must match the end signature exactly. If the final handle's type does not exactly match the initial type for this Binder, an additional cast will be attempted. This version is "quiet" in that it throws an unchecked InvalidTransformException if the target method does not exist or is inaccessible.
      Parameters:
      lookup - the MethodHandles.Lookup to use to look up the method
      target - the class in which to find the method
      name - the name of the method to invoke
      Returns:
      the full handle chain, bound to the given method
    • invokeStaticQuiet

      public MethodHandle invokeStaticQuiet(Class<?> target, String name)
      Same as invokeStaticQuiet(MethodHandles.Lookup, Class, String) but using the default lookup for this binder.
    • invokeVirtual

      Apply the chain of transforms and bind them to a virtual method specified using the end signature plus the given class and name. The method will be retrieved using the given Lookup and must match the end signature exactly. If the final handle's type does not exactly match the initial type for this Binder, an additional cast will be attempted.
      Parameters:
      lookup - the MethodHandles.Lookup to use to look up the method
      name - the name of the method to invoke
      Returns:
      the full handle chain, bound to the given method
      Throws:
      NoSuchMethodException - if the method does not exist
      IllegalAccessException - if the method is not accessible
    • invokeVirtual

      public MethodHandle invokeVirtual(String name) throws NoSuchMethodException, IllegalAccessException
      Same as invokeVirtual(MethodHandles.Lookup, String) but using the default lookup for this binder.
      Throws:
      NoSuchMethodException
      IllegalAccessException
    • invokeVirtualQuiet

      public MethodHandle invokeVirtualQuiet(MethodHandles.Lookup lookup, String name)
      Apply the chain of transforms and bind them to a virtual method specified using the end signature plus the given class and name. The method will be retrieved using the given Lookup and must match the end signature exactly. If the final handle's type does not exactly match the initial type for this Binder, an additional cast will be attempted. This version is "quiet" in that it throws an unchecked InvalidTransformException if the target method does not exist or is inaccessible.
      Parameters:
      lookup - the MethodHandles.Lookup to use to look up the method
      name - the name of the method to invoke
      Returns:
      the full handle chain, bound to the given method
    • invokeVirtualQuiet

      public MethodHandle invokeVirtualQuiet(String name)
      Same as invokeVirtualQuiet(MethodHandles.Lookup, String) but using the default lookup for this binder.
    • invokeSpecial

      public MethodHandle invokeSpecial(MethodHandles.Lookup lookup, String name, Class<?> caller) throws NoSuchMethodException, IllegalAccessException
      Apply the chain of transforms and bind them to a special method specified using the end signature plus the given class and name. The method will be retrieved using the given Lookup and must match the end signature exactly. If the final handle's type does not exactly match the initial type for this Binder, an additional cast will be attempted.
      Parameters:
      lookup - the MethodHandles.Lookup to use to look up the method
      name - the name of the method to invoke
      caller - the calling class
      Returns:
      the full handle chain, bound to the given method
      Throws:
      NoSuchMethodException - if the method does not exist
      IllegalAccessException - if the method is not accessible
    • invokeSpecial

      public MethodHandle invokeSpecial(String name, Class<?> caller) throws NoSuchMethodException, IllegalAccessException
      Same as invokeSpecial(MethodHandles.Lookup, String, Class<?>) but using the default lookup for this binder.
      Throws:
      NoSuchMethodException
      IllegalAccessException
    • invokeSpecialQuiet

      public MethodHandle invokeSpecialQuiet(MethodHandles.Lookup lookup, String name, Class<?> caller)
      Apply the chain of transforms and bind them to a special method specified using the end signature plus the given class and name. The method will be retrieved using the given Lookup and must match the end signature exactly. If the final handle's type does not exactly match the initial type for this Binder, an additional cast will be attempted. This version is "quiet" in that it throws an unchecked InvalidTransformException if the target method does not exist or is inaccessible.
      Parameters:
      lookup - the MethodHandles.Lookup to use to look up the method
      name - the name of the method to invoke
      caller - the calling class
      Returns:
      the full handle chain, bound to the given method
    • invokeSpecialQuiet

      public MethodHandle invokeSpecialQuiet(String name, Class<?> caller)
      Same as invokeSpecialQuiet(MethodHandles.Lookup, String, Class) but using the default lookup for this binder.
    • invokeConstructor

      public MethodHandle invokeConstructor(MethodHandles.Lookup lookup, Class<?> target) throws NoSuchMethodException, IllegalAccessException
      Apply the chain of transforms and bind them to a constructor specified using the end signature plus the given class. The constructor will be retrieved using the given Lookup and must match the end signature's arguments exactly. If the final handle's type does not exactly match the initial type for this Binder, an additional cast will be attempted.
      Parameters:
      lookup - the MethodHandles.Lookup to use to look up the constructor
      target - the constructor's class
      Returns:
      the full handle chain, bound to the given constructor
      Throws:
      NoSuchMethodException - if the constructor does not exist
      IllegalAccessException - if the constructor is not accessible
    • invokeConstructor

      public MethodHandle invokeConstructor(Class<?> target) throws NoSuchMethodException, IllegalAccessException
      Same as invokeConstructor(MethodHandles.Lookup, Class) but using the default lookup for this binder.
      Throws:
      NoSuchMethodException
      IllegalAccessException
    • invokeConstructorQuiet

      public MethodHandle invokeConstructorQuiet(MethodHandles.Lookup lookup, Class<?> target)
      Apply the chain of transforms and bind them to a constructor specified using the end signature plus the given class. The constructor will be retrieved using the given Lookup and must match the end signature's arguments exactly. If the final handle's type does not exactly match the initial type for this Binder, an additional cast will be attempted. This version is "quiet" in that it throws an unchecked InvalidTransformException if the target method does not exist or is inaccessible.
      Parameters:
      lookup - the MethodHandles.Lookup to use to look up the constructor
      target - the constructor's class
      Returns:
      the full handle chain, bound to the given constructor
    • invokeConstructorQuiet

      public MethodHandle invokeConstructorQuiet(Class<?> target)
      Same as invokeConstructorQuiet(MethodHandles.Lookup, Class) but using the default lookup for this binder.
    • getField

      Apply the chain of transforms and bind them to an object field retrieval specified using the end signature plus the given class and name. The field must match the end signature's return value and the end signature must take the target class or a subclass as its only argument. If the final handle's type does not exactly match the initial type for this Binder, an additional cast will be attempted.
      Parameters:
      lookup - the MethodHandles.Lookup to use to look up the field
      name - the field's name
      Returns:
      the full handle chain, bound to the given field access
      Throws:
      NoSuchFieldException - if the field does not exist
      IllegalAccessException - if the field is not accessible
      NoSuchFieldException - if the field does not exist
      IllegalAccessException - if the field is not accessible
    • getField

      Same as getField(MethodHandles.Lookup, String) but using the default lookup for this binder.
      Throws:
      NoSuchFieldException
      IllegalAccessException
    • getFieldQuiet

      public MethodHandle getFieldQuiet(MethodHandles.Lookup lookup, String name)
      Apply the chain of transforms and bind them to an object field retrieval specified using the end signature plus the given class and name. The field must match the end signature's return value and the end signature must take the target class or a subclass as its only argument. If the final handle's type does not exactly match the initial type for this Binder, an additional cast will be attempted. This version is "quiet" in that it throws an unchecked InvalidTransformException if the target method does not exist or is inaccessible.
      Parameters:
      lookup - the MethodHandles.Lookup to use to look up the field
      name - the field's name
      Returns:
      the full handle chain, bound to the given field access
    • getFieldQuiet

      public MethodHandle getFieldQuiet(String name)
      Same as getFieldQuiet(MethodHandles.Lookup, String) but using the default lookup for this binder.
    • getStatic

      public MethodHandle getStatic(MethodHandles.Lookup lookup, Class<?> target, String name) throws NoSuchFieldException, IllegalAccessException
      Apply the chain of transforms and bind them to a static field retrieval specified using the end signature plus the given class and name. The field must match the end signature's return value and the end signature must take no arguments. If the final handle's type does not exactly match the initial type for this Binder, an additional cast will be attempted.
      Parameters:
      lookup - the MethodHandles.Lookup to use to look up the field
      target - the class in which the field is defined
      name - the field's name
      Returns:
      the full handle chain, bound to the given field access
      Throws:
      NoSuchFieldException - if the field does not exist
      IllegalAccessException - if the field is not accessible or cannot be modified
    • getStatic

      public MethodHandle getStatic(Class<?> target, String name) throws NoSuchFieldException, IllegalAccessException
      Same as getStatic(MethodHandles.Lookup, Class, String) but using the default lookup for this binder.
      Throws:
      NoSuchFieldException
      IllegalAccessException
    • getStaticQuiet

      public MethodHandle getStaticQuiet(MethodHandles.Lookup lookup, Class<?> target, String name)
      Apply the chain of transforms and bind them to a static field retrieval specified using the end signature plus the given class and name. The field must match the end signature's return value and the end signature must take no arguments. If the final handle's type does not exactly match the initial type for this Binder, an additional cast will be attempted. This version is "quiet" in that it throws an unchecked InvalidTransformException if the target method does not exist or is inaccessible.
      Parameters:
      lookup - the MethodHandles.Lookup to use to look up the field
      target - the class in which the field is defined
      name - the field's name
      Returns:
      the full handle chain, bound to the given field access
    • getStaticQuiet

      public MethodHandle getStaticQuiet(Class<?> target, String name)
      Same as getStaticQuiet(MethodHandles.Lookup, Class, String) but using the default lookup for this binder.
    • setField

      Apply the chain of transforms and bind them to an object field assignment specified using the end signature plus the given class and name. The end signature must take the target class or a subclass and the field's type as its arguments, and its return type must be compatible with void. If the final handle's type does not exactly match the initial type for this Binder, an additional cast will be attempted.
      Parameters:
      lookup - the MethodHandles.Lookup to use to look up the field
      name - the field's name
      Returns:
      the full handle chain, bound to the given field assignment
      Throws:
      NoSuchFieldException - if the field does not exist
      IllegalAccessException - if the field is not accessible or cannot be modified
    • setField

      Same as setField(MethodHandles.Lookup, String) but using the default lookup for this binder.
      Throws:
      NoSuchFieldException
      IllegalAccessException
    • setFieldQuiet

      public MethodHandle setFieldQuiet(MethodHandles.Lookup lookup, String name)
      Apply the chain of transforms and bind them to an object field assignment specified using the end signature plus the given class and name. The end signature must take the target class or a subclass and the field's type as its arguments, and its return type must be compatible with void. If the final handle's type does not exactly match the initial type for this Binder, an additional cast will be attempted. This version is "quiet" in that it throws an unchecked InvalidTransformException if the target method does not exist or is inaccessible.
      Parameters:
      lookup - the MethodHandles.Lookup to use to look up the field
      name - the field's name
      Returns:
      the full handle chain, bound to the given field assignment
    • setFieldQuiet

      public MethodHandle setFieldQuiet(String name)
      Same as setFieldQuiet(MethodHandles.Lookup, String) but using the default lookup for this binder.
    • setStatic

      public MethodHandle setStatic(MethodHandles.Lookup lookup, Class<?> target, String name) throws NoSuchFieldException, IllegalAccessException
      Apply the chain of transforms and bind them to an object field assignment specified using the end signature plus the given class and name. The end signature must take the target class or a subclass and the field's type as its arguments, and its return type must be compatible with void. If the final handle's type does not exactly match the initial type for this Binder, an additional cast will be attempted.
      Parameters:
      lookup - the MethodHandles.Lookup to use to look up the field
      target - the class in which the field is defined
      name - the field's name
      Returns:
      the full handle chain, bound to the given field assignment
      Throws:
      NoSuchFieldException - if the field does not exist
      IllegalAccessException - if the field is not accessible or cannot be modified
    • setStatic

      public MethodHandle setStatic(Class<?> target, String name) throws NoSuchFieldException, IllegalAccessException
      Same as setStatic(MethodHandles.Lookup, Class, String) but using the default lookup for this binder.
      Throws:
      NoSuchFieldException
      IllegalAccessException
    • setStaticQuiet

      public MethodHandle setStaticQuiet(MethodHandles.Lookup lookup, Class<?> target, String name)
      Apply the chain of transforms and bind them to an object field assignment specified using the end signature plus the given class and name. The end signature must take the target class or a subclass and the field's type as its arguments, and its return type must be compatible with void. If the final handle's type does not exactly match the initial type for this Binder, an additional cast will be attempted. This version is "quiet" in that it throws an unchecked InvalidTransformException if the target method does not exist or is inaccessible.
      Parameters:
      lookup - the MethodHandles.Lookup to use to look up the field
      target - the class in which the field is defined
      name - the field's name
      Returns:
      the full handle chain, bound to the given field assignment
    • setStaticQuiet

      public MethodHandle setStaticQuiet(Class<?> target, String name)
      Same as setStaticQuiet(MethodHandles.Lookup, Class, String) but using the default lookup for this binder.
    • newArray

      public MethodHandle newArray()
      Construct a new array. The signature at the endpoint must return the array type and accept an integer length.
      Returns:
      a handle that constructs an array
    • arrayLength

      public MethodHandle arrayLength()
      Get the length of an array. The signature must accept an array and return an integer length.
      Returns:
      a handle that gets the size of an array
    • arraySet

      public MethodHandle arraySet()
      Apply the chain of transforms and bind them to an array element set. The signature at the endpoint must return void and receive the array type, int index, and array element type.
      Returns:
      the full handle chain, bound to an array element set.
    • arraySetVolatile

      public MethodHandle arraySetVolatile()
      Apply the chain of transforms and bind them to a volatile array element set.
      See Also:
    • arraySetAcquire

      public MethodHandle arraySetAcquire()
      Apply the chain of transforms and bind them to a release-fenced array element set.
      See Also:
    • arraySetOpaque

      public MethodHandle arraySetOpaque()
      Apply the chain of transforms and bind them to an opaque (no ordering guarantee) array element set.
      See Also:
    • arrayGet

      public MethodHandle arrayGet()
      Apply the chain of transforms and bind them to an array element get. The signature at the endpoint must return the array element type and receive the array type and int index.
      Returns:
      the full handle chain, bound to an array element get.
    • arrayGetVolatile

      public MethodHandle arrayGetVolatile()
      Apply the chain of transforms and bind them to a volatile array element get.
      See Also:
    • arrayGetAcquire

      public MethodHandle arrayGetAcquire()
      Apply the chain of transforms and bind them to an acquire-fenced array element get.
      See Also:
    • arrayGetOpaque

      public MethodHandle arrayGetOpaque()
      Apply the chain of transforms and bind them to an opaque (no ordering guarantee) array element get.
      See Also:
    • arrayAccess

      public MethodHandle arrayAccess(VarHandle.AccessMode mode)
      Apply the chain of transforms and bind them to an array varhandle operation. The signature at the endpoint must match the VarHandle access type passed in.
    • branch

      public MethodHandle branch(MethodHandle test, MethodHandle truePath, MethodHandle falsePath)
      Apply the chain of transforms and bind them to a boolean branch as from java.lang.invoke.MethodHandles.guardWithTest. As with GWT, the current endpoint signature must match the given target and fallback signatures.
      Parameters:
      test - the test handle
      truePath - the target handle
      falsePath - the fallback handle
      Returns:
      the full handle chain bound to a branch
    • invoker

      public MethodHandle invoker()
      Produce a MethodHandle that invokes its leading MethodHandle argument with the remaining arguments, returning the result.
      Returns:
      a new handle that invokes its leading MethodHandle argument
    • toJava

      public String toJava(MethodType incoming)
      Produce Java code that would perform equivalent operations to this binder.
      Returns:
      Java code for the handle adaptations this Binder would produce.