Package com.headius.invokebinder

Class Binder

  • public class Binder
extends java.lang.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);

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private java.util.logging.Logger logger  
      private java.lang.invoke.MethodHandles.Lookup lookup  
      private java.lang.invoke.MethodType start  
      private java.util.List<Transform> transforms  
      private java.util.List<java.lang.invoke.MethodType> types  

    • Constructor Summary

      Constructors 
      Constructor Description
      Binder​(Binder source)
      Construct a new Binder using the given invokebinder.
      Binder​(Binder source, Transform transform)
      Construct a new Binder using the given invokebinder plus an additional transform
      Binder​(Binder source, Transform transform, java.lang.invoke.MethodType type)
      Construct a new Binder using the given invokebinder plus an additional transform and current type
      Binder​(java.lang.invoke.MethodHandles.Lookup lookup, Binder source)
      Construct a new Binder using the given Lookup and invokebinder.
      Binder​(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.invoke.MethodType start)
      Construct a new Binder, starting from a given Lookup and MethodType.
      Binder​(java.lang.invoke.MethodType start)
      Construct a new Binder, starting from a given MethodType.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      private void add​(Transform transform)
      Add a Transform to the chain.
      private void add​(Transform transform, java.lang.invoke.MethodType target)
      Add a Transform with an associated MethodType target to the chain.
      Binder append​(boolean value)
      Append to the argument list the given boolean value.
      Binder append​(byte value)
      Append to the argument list the given byte value.
      Binder append​(char value)
      Append to the argument list the given char value.
      Binder append​(double value)
      Append to the argument list the given double value.
      Binder append​(float value)
      Append to the argument list the given float value.
      Binder append​(int value)
      Append to the argument list the given int value.
      Binder append​(long value)
      Append to the argument list the given long value.
      Binder append​(short value)
      Append to the argument list the given short value.
      Binder append​(java.lang.Class[] types, java.lang.Object... values)
      Append to the argument list the given argument value(s).
      Binder append​(java.lang.Object... values)
      Append to the argument list the given argument value(s).
      java.lang.invoke.MethodHandle arrayGet()
      Apply the chain of transforms and bind them to an array element get.
      java.lang.invoke.MethodHandle arraySet()
      Apply the chain of transforms and bind them to an array element set.
      java.lang.invoke.MethodHandle branch​(java.lang.invoke.MethodHandle test, java.lang.invoke.MethodHandle truePath, java.lang.invoke.MethodHandle falsePath)
      Apply the chain of transforms and bind them to a boolean branch as from java.lang.invoke.MethodHandles.guardWithTest.
      Binder cast​(java.lang.Class returnType, java.lang.Class... argTypes)
      Cast the incoming arguments to the given MethodType.
      Binder cast​(java.lang.invoke.MethodType type)
      Cast the incoming arguments to the given MethodType.
      Binder catchException​(java.lang.Class<? extends java.lang.Throwable> throwable, java.lang.invoke.MethodHandle function)
      Catch the given exception type from the downstream chain and handle it with the given function.
      Binder collect​(int index, java.lang.Class type)
      Box all incoming arguments from the given position onward into the given array type.
      java.lang.invoke.MethodHandle constant​(java.lang.Object value)
      Apply the tranforms, binding them to a constant value that will propagate back through the chain.
      Binder convert​(java.lang.Class returnType, java.lang.Class... argTypes)
      Convert the incoming arguments to the given MethodType.
      Binder convert​(java.lang.invoke.MethodType target)
      Convert the incoming arguments to the given MethodType.
      Binder drop​(int index)
      Drop a single argument at the given index.
      Binder drop​(int index, int count)
      Drop from the given index a number of arguments.
      Binder dropLast()
      Drop a single argument at the end of the argument list.
      Binder dropLast​(int count)
      Drop from the end of the argument list a number of arguments.
      Binder filter​(int index, java.lang.invoke.MethodHandle... functions)
      Filter incoming arguments, starting at the given index, replacing each with the result of calling the associated function in the given list.
      Binder filterReturn​(java.lang.invoke.MethodHandle function)
      Filter return value, using a function that produces the current return type from another type.
      Binder fold​(java.lang.invoke.MethodHandle function)
      Process the incoming arguments using the given handle, inserting the result as the first argument.
      Binder foldStatic​(java.lang.Class target, java.lang.String method)
      Process the incoming arguments by calling the given static method on the given class, inserting the result as the first argument.
      Binder foldStatic​(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.Class target, java.lang.String method)
      Process the incoming arguments by calling the given static method on the given class, inserting the result as the first argument.
      Binder foldVirtual​(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.String method)
      Process the incoming arguments by calling the given method on the first argument, inserting the result as the first argument.
      Binder foldVirtual​(java.lang.String method)
      Process the incoming arguments by calling the given method on the first argument, inserting the result as the first argument.
      Binder foldVoid​(java.lang.invoke.MethodHandle function)  
      static Binder from​(Binder start)
      Construct a new Binder, starting from a given invokebinder.
      static Binder from​(java.lang.Class returnType)
      Construct a new Binder using a return type.
      static Binder from​(java.lang.Class returnType, java.lang.Class[] argTypes)
      Construct a new Binder using a return type and argument types.
      static Binder from​(java.lang.Class returnType, java.lang.Class argType0, java.lang.Class... argTypes)
      Construct a new Binder using a return type and argument types.
      static Binder from​(java.lang.invoke.MethodHandles.Lookup lookup, Binder start)
      Construct a new Binder, starting from a given invokebinder.
      static Binder from​(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.Class returnType)
      Construct a new Binder using a return type.
      static Binder from​(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.Class returnType, java.lang.Class[] argTypes)
      Construct a new Binder using a return type and argument types.
      static Binder from​(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.Class returnType, java.lang.Class argType0, java.lang.Class... argTypes)
      Construct a new Binder using a return type and argument types.
      static Binder from​(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.invoke.MethodType start)
      Construct a new Binder, starting from a given MethodType.
      static Binder from​(java.lang.invoke.MethodType start)
      Construct a new Binder, starting from a given MethodType.
      java.lang.invoke.MethodHandle getField​(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.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.
      java.lang.invoke.MethodHandle getFieldQuiet​(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.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.
      java.lang.invoke.MethodHandle getStatic​(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.Class target, java.lang.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.
      java.lang.invoke.MethodHandle getStaticQuiet​(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.Class target, java.lang.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.
      java.lang.invoke.MethodHandle identity()
      Apply the tranforms, binding them to a handle that will simply return its sole argument as its return value.
      Binder insert​(int index, boolean value)
      Insert at the given index the given boolean value.
      Binder insert​(int index, byte value)
      Insert at the given index the given byte value.
      Binder insert​(int index, char value)
      Insert at the given index the given char value.
      Binder insert​(int index, double value)
      Insert at the given index the given double value.
      Binder insert​(int index, float value)
      Insert at the given index the given float value.
      Binder insert​(int index, int value)
      Insert at the given index the given int value.
      Binder insert​(int index, long value)
      Insert at the given index the given long value.
      Binder insert​(int index, short value)
      Insert at the given index the given short value.
      Binder insert​(int index, java.lang.Class[] types, java.lang.Object... values)
      Insert at the given index the given argument value(s).
      Binder insert​(int index, java.lang.Object... values)
      Insert at the given index the given argument value(s).
      java.lang.invoke.MethodHandle invoke​(java.lang.invoke.MethodHandle target)
      Apply the chain of transforms with the target method handle as the final endpoint.
      java.lang.invoke.MethodHandle invoke​(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.reflect.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.
      java.lang.invoke.MethodHandle invokeConstructor​(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.Class target)
      Apply the chain of transforms and bind them to a constructor specified using the end signature plus the given class.
      java.lang.invoke.MethodHandle invokeConstructorQuiet​(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.Class target)
      Apply the chain of transforms and bind them to a constructor specified using the end signature plus the given class.
      java.lang.invoke.MethodHandle invokeQuiet​(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.reflect.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.
      java.lang.invoke.MethodHandle invoker()
      Produce a MethodHandle that invokes its leading MethodHandle argument with the remaining arguments, returning the result.
      java.lang.invoke.MethodHandle invokeSpecial​(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.String name, java.lang.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.
      java.lang.invoke.MethodHandle invokeSpecialQuiet​(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.String name, java.lang.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.
      java.lang.invoke.MethodHandle invokeStatic​(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.Class target, java.lang.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.
      java.lang.invoke.MethodHandle invokeStaticQuiet​(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.Class target, java.lang.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.
      java.lang.invoke.MethodHandle invokeVirtual​(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.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.
      java.lang.invoke.MethodHandle invokeVirtualQuiet​(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.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.
      Binder logType()
      Log the current MethodType as info.
      java.lang.invoke.MethodHandle nop()
      Apply all transforms to an endpoint that does absolutely nothing.
      Binder permute​(int... reorder)
      Permute the incoming arguments to a new sequence specified by the given values.
      Binder prepend​(boolean value)
      Prepend to the argument list the given boolean value.
      Binder prepend​(byte value)
      Prepend to the argument list the given byte value.
      Binder prepend​(char value)
      Prepend to the argument list the given char value.
      Binder prepend​(double value)
      Prepend to the argument list the given double value.
      Binder prepend​(float value)
      Prepend to the argument list the given float value.
      Binder prepend​(int value)
      Prepend to the argument list the given int value.
      Binder prepend​(long value)
      Prepend to the argument list the given long value.
      Binder prepend​(short value)
      Prepend to the argument list the given short value.
      Binder prepend​(java.lang.Object... values)
      Prepend to the argument list the given argument value(s).
      Binder printType()
      Println the current MethodType to stdout.
      Binder printType​(java.io.PrintStream ps)
      Println the current MethodType to the given stream.
      java.lang.invoke.MethodHandle setField​(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.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.
      java.lang.invoke.MethodHandle setFieldQuiet​(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.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.
      java.lang.invoke.MethodHandle setStatic​(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.Class target, java.lang.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.
      java.lang.invoke.MethodHandle setStaticQuiet​(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.Class target, java.lang.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.
      Binder spread​(int count)
      Spread a trailing array argument into the given number of arguments of the type of the array.
      Binder spread​(java.lang.Class... spreadTypes)
      Spread a trailing array argument into the specified argument types.
      java.lang.invoke.MethodHandle throwException()
      Throw the current signature's sole Throwable argument.
      Binder to​(Binder other)
      Join this binder to an existing one by applying its transformations after this one.
      Binder tryFinally​(java.lang.invoke.MethodHandle post)
      Apply transforms to run the given handle's logic as a "finally" block.
      java.lang.invoke.MethodType type()
      The current MethodType, were the handle chain to terminate at this point.
      Binder varargs​(int index, java.lang.Class type)
      Box all incoming arguments from the given position onward into the given array type.
      Binder withLookup​(java.lang.invoke.MethodHandles.Lookup lookup)
      Use an alternate java.lang.invoke.MethodHandles.Lookup as the default for any direct handles created.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • logger

        private final java.util.logging.Logger logger

      • transforms

        private final java.util.List<Transform> transforms

      • types

        private final java.util.List<java.lang.invoke.MethodType> types

      • start

        private final java.lang.invoke.MethodType start

      • lookup

        private final java.lang.invoke.MethodHandles.Lookup lookup

    • Constructor Detail

      • Binder

        public Binder​(java.lang.invoke.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​(java.lang.invoke.MethodHandles.Lookup lookup,
              java.lang.invoke.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.

      • Binder

        public Binder​(java.lang.invoke.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,
              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,
              Transform transform,
              java.lang.invoke.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 Detail

      • from

        public static Binder from​(java.lang.invoke.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​(java.lang.invoke.MethodHandles.Lookup lookup,
                          java.lang.invoke.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​(java.lang.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​(java.lang.invoke.MethodHandles.Lookup lookup,
                          java.lang.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​(java.lang.Class returnType,
                          java.lang.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​(java.lang.invoke.MethodHandles.Lookup lookup,
                          java.lang.Class returnType,
                          java.lang.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​(java.lang.Class returnType,
                          java.lang.Class argType0,
                          java.lang.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​(java.lang.invoke.MethodHandles.Lookup lookup,
                          java.lang.Class returnType,
                          java.lang.Class argType0,
                          java.lang.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​(java.lang.invoke.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​(java.lang.invoke.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

      • add

        private void add​(Transform transform)
        Add a Transform to the chain.
        Parameters:
        transform -

      • add

        private void add​(Transform transform,
                 java.lang.invoke.MethodType target)
        Add a Transform with an associated MethodType target to the chain.
        Parameters:
        transform -
        target -

      • type

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

      • printType

        public Binder printType​(java.io.PrintStream ps)
        Println the current MethodType to the given stream.
        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,
                     java.lang.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,
                     java.lang.Class[] types,
                     java.lang.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

      • 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

      • 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

      • 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

      • 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

      • 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

      • 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

      • 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

      • append

        public Binder append​(java.lang.Object... values)
        Append to the argument list the given argument value(s).
        Parameters:
        values - 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

      • 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

      • 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

      • 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

      • 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

      • 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

      • 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

      • 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

      • prepend

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

      • append

        public Binder append​(java.lang.Class[] types,
                     java.lang.Object... values)
        Append to the argument list the given argument value(s).
        Parameters:
        types - the actual types to use, rather than getClass
        values - the value(s) to append
        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

      • convert

        public Binder convert​(java.lang.invoke.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​(java.lang.Class returnType,
                      java.lang.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​(java.lang.invoke.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​(java.lang.Class returnType,
                   java.lang.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

      • spread

        public Binder spread​(java.lang.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,
                      java.lang.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

      • varargs

        public Binder varargs​(int index,
                      java.lang.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​(java.lang.invoke.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​(java.lang.invoke.MethodHandle function)

      • foldStatic

        public Binder foldStatic​(java.lang.invoke.MethodHandles.Lookup lookup,
                         java.lang.Class target,
                         java.lang.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​(java.lang.Class target,
                         java.lang.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​(java.lang.invoke.MethodHandles.Lookup lookup,
                          java.lang.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​(java.lang.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,
                     java.lang.invoke.MethodHandle... functions)
        Filter incoming arguments, starting at the given index, replacing each with the result of calling the associated function in the given list.
        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​(java.lang.invoke.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​(java.lang.invoke.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​(java.lang.Class<? extends java.lang.Throwable> throwable,
                             java.lang.invoke.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 java.lang.invoke.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 java.lang.invoke.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 java.lang.invoke.MethodHandle constant​(java.lang.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 java.lang.invoke.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 java.lang.invoke.MethodHandle invoke​(java.lang.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 java.lang.invoke.MethodHandle invoke​(java.lang.invoke.MethodHandles.Lookup lookup,
                                            java.lang.reflect.Method method)
                                     throws java.lang.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:
        java.lang.IllegalAccessException

      • invokeQuiet

        public java.lang.invoke.MethodHandle invokeQuiet​(java.lang.invoke.MethodHandles.Lookup lookup,
                                                 java.lang.reflect.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

      • invokeStatic

        public java.lang.invoke.MethodHandle invokeStatic​(java.lang.invoke.MethodHandles.Lookup lookup,
                                                  java.lang.Class target,
                                                  java.lang.String name)
                                           throws java.lang.NoSuchMethodException,
                                                  java.lang.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:
        java.lang.NoSuchMethodException
        java.lang.IllegalAccessException

      • invokeStaticQuiet

        public java.lang.invoke.MethodHandle invokeStaticQuiet​(java.lang.invoke.MethodHandles.Lookup lookup,
                                                       java.lang.Class target,
                                                       java.lang.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

      • invokeVirtual

        public java.lang.invoke.MethodHandle invokeVirtual​(java.lang.invoke.MethodHandles.Lookup lookup,
                                                   java.lang.String name)
                                            throws java.lang.NoSuchMethodException,
                                                   java.lang.IllegalAccessException
        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:
        java.lang.NoSuchMethodException
        java.lang.IllegalAccessException

      • invokeVirtualQuiet

        public java.lang.invoke.MethodHandle invokeVirtualQuiet​(java.lang.invoke.MethodHandles.Lookup lookup,
                                                        java.lang.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

      • invokeSpecial

        public java.lang.invoke.MethodHandle invokeSpecial​(java.lang.invoke.MethodHandles.Lookup lookup,
                                                   java.lang.String name,
                                                   java.lang.Class caller)
                                            throws java.lang.NoSuchMethodException,
                                                   java.lang.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:
        java.lang.NoSuchMethodException
        java.lang.IllegalAccessException

      • invokeSpecialQuiet

        public java.lang.invoke.MethodHandle invokeSpecialQuiet​(java.lang.invoke.MethodHandles.Lookup lookup,
                                                        java.lang.String name,
                                                        java.lang.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

      • invokeConstructor

        public java.lang.invoke.MethodHandle invokeConstructor​(java.lang.invoke.MethodHandles.Lookup lookup,
                                                       java.lang.Class target)
                                                throws java.lang.NoSuchMethodException,
                                                       java.lang.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:
        java.lang.NoSuchMethodException
        java.lang.IllegalAccessException

      • invokeConstructorQuiet

        public java.lang.invoke.MethodHandle invokeConstructorQuiet​(java.lang.invoke.MethodHandles.Lookup lookup,
                                                            java.lang.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

      • getField

        public java.lang.invoke.MethodHandle getField​(java.lang.invoke.MethodHandles.Lookup lookup,
                                              java.lang.String name)
                                       throws java.lang.NoSuchFieldException,
                                              java.lang.IllegalAccessException
        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:
        java.lang.NoSuchFieldException
        java.lang.IllegalAccessException

      • getFieldQuiet

        public java.lang.invoke.MethodHandle getFieldQuiet​(java.lang.invoke.MethodHandles.Lookup lookup,
                                                   java.lang.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

      • getStatic

        public java.lang.invoke.MethodHandle getStatic​(java.lang.invoke.MethodHandles.Lookup lookup,
                                               java.lang.Class target,
                                               java.lang.String name)
                                        throws java.lang.NoSuchFieldException,
                                               java.lang.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:
        java.lang.NoSuchFieldException
        java.lang.IllegalAccessException

      • getStaticQuiet

        public java.lang.invoke.MethodHandle getStaticQuiet​(java.lang.invoke.MethodHandles.Lookup lookup,
                                                    java.lang.Class target,
                                                    java.lang.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

      • setField

        public java.lang.invoke.MethodHandle setField​(java.lang.invoke.MethodHandles.Lookup lookup,
                                              java.lang.String name)
                                       throws java.lang.NoSuchFieldException,
                                              java.lang.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
        name - the field's name
        Returns:
        the full handle chain, bound to the given field assignment
        Throws:
        java.lang.NoSuchFieldException
        java.lang.IllegalAccessException

      • setFieldQuiet

        public java.lang.invoke.MethodHandle setFieldQuiet​(java.lang.invoke.MethodHandles.Lookup lookup,
                                                   java.lang.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

      • setStatic

        public java.lang.invoke.MethodHandle setStatic​(java.lang.invoke.MethodHandles.Lookup lookup,
                                               java.lang.Class target,
                                               java.lang.String name)
                                        throws java.lang.NoSuchFieldException,
                                               java.lang.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:
        java.lang.NoSuchFieldException
        java.lang.IllegalAccessException

      • setStaticQuiet

        public java.lang.invoke.MethodHandle setStaticQuiet​(java.lang.invoke.MethodHandles.Lookup lookup,
                                                    java.lang.Class target,
                                                    java.lang.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

      • arraySet

        public java.lang.invoke.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.

      • arrayGet

        public java.lang.invoke.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.

      • branch

        public java.lang.invoke.MethodHandle branch​(java.lang.invoke.MethodHandle test,
                                            java.lang.invoke.MethodHandle truePath,
                                            java.lang.invoke.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 java.lang.invoke.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