SmartHandle (invokebinder 1.2 API)

java.lang.Object
- com.headius.invokebinder.SmartHandle

```
public class SmartHandle
extends Object
```
A tuple of a Signature and a java.lang.invoke.MethodHandle, providing features of both plus a number of MethodHandles.* methods in a simpler form. SmartHandle is provided as a way to couple a given MethodHandle to a Signature, allowing future adaptation of the MethodHandle to proceed using Signature's various shortcuts and conveniences. Example: // A signature that only wants the "context" and "args" arguments public static final Signature ARG_COUNT_CHECK_FOLD = Signature .returning(void.class) .appendArg("args", Object[].class); // The actual target signature for arg count checking, with min and max ints public static final Signature ARG_COUNT_CHECK_SIGNATURE = Signature .returning(int.class) .appendArg("args", Object[].class) .appendArg("min", int.class) .appendArg("max", int.class); // A SmartHandle for the arity-checking method, using the fold and signature // from above and inserting 1, 3 for min, max SmartHandle arityCheck = SmartBinder .from(ARITY_CHECK_FOLD) .append("min", 1) .append("max", 3) .cast(ARITY_CHECK_SIGNATURE) .invokeStaticQuiet(LOOKUP, ArgCountChecker.class, "checkArgumentCount"); // The variable-arity call contaings other arguments plus the Object[] args. // Here, we can just fold with our arityCheck SmartHandle, which drops args // we are not interested in, passes along the args array, and ignores the // return value. variableCall = SmartBinder .from(VARIABLE_ARITY_SIGNATURE) .foldVoid(arityCheck) .invoke(directCall);

Author:

headius

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`SmartHandle`	`apply(int index, Object arg)` Apply an argument into the handle at the given index, returning a new SmartHandle.
`SmartHandle`	`apply(String name, Object arg)` Apply an argument into the handle at the given name, returning a new SmartHandle.
`SmartHandle`	`applyLast(Object arg)` Apply an argument into the handle at the end, returning a new SmartHandle.
`SmartHandle`	`bindTo(Object obj)` Bind the first argument of this SmartHandle to the given object, returning a new adapted handle.
`SmartHandle`	`cast(Class returnType, Class... argTypes)` Create a new SmartHandle that casts arguments from the given return type and argument types to the current signature's type, using the same argument names.
`SmartHandle`	`cast(MethodType incoming)` Create a new SmartHandle that casts arguments from the given type to the current signature's type, using the same argument names.
`SmartHandle`	`cast(Signature incoming)` Create a new SmartHandle that casts arguments from the given signature to the current signature's type with the new argument names.
`SmartHandle`	`convert(Class returnType, Class... argTypes)` Create a new SmartHandle that converts arguments from the given return type and argument types to the current signature's type, using the same argument names.
`SmartHandle`	`convert(MethodType incoming)` Create a new SmartHandle that converts arguments from the given type to the current signature's type, using the same argument names.
`SmartHandle`	`convert(Signature incoming)` Create a new SmartHandle that converts arguments from the given signature to the current signature's type with the new argument names.
`SmartHandle`	`drop(int index, String newName, Class type)` Insert an argument into the handle at the given index, returning a new SmartHandle.
`SmartHandle`	`drop(String beforeName, String newName, Class type)` Insert an argument into the handle at the given index, returning a new SmartHandle.
`SmartHandle`	`dropLast(String newName, Class type)` Insert an argument into the handle at the given index, returning a new SmartHandle.
`static SmartHandle`	`findStaticQuiet(MethodHandles.Lookup lookup, Class target, String name, Signature signature)` Create a new SmartHandle by performing a lookup on the given target class for the given method name with the given signature.
`static SmartHandle`	`from(Signature signature, MethodHandle handle)` Create a new SmartHandle from the given Signature and MethodHandle.
`MethodHandle`	`guard(MethodHandle target, MethodHandle fallback)` Use this SmartHandle as a test to guard target and fallback handles.
`SmartHandle`	`guard(SmartHandle target, SmartHandle fallback)` Use this SmartHandle as a test to guard target and fallback handles.
`MethodHandle`	`handle()` Get the MethodHandle of this SmartHandle.
`SmartHandle`	`returnValue(Class type, Object value)` Replace the return value with the given value, performing no other processing of the original value.
`Signature`	`signature()` Get the Signature of this SmartHandle.
`String`	`toString()` A human-readable String representation of this SamrtHandle.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Method Detail
  - from
```
public static SmartHandle from(Signature signature,
                               MethodHandle handle)
```
    Create a new SmartHandle from the given Signature and MethodHandle.
    
    Parameters:
    
    signature - the signature for the new smart handle
    
    handle - the method handle for the new smart handle
    
    Returns:
    
    a new SmartHandle
  - findStaticQuiet
```
public static SmartHandle findStaticQuiet(MethodHandles.Lookup lookup,
                                          Class target,
                                          String name,
                                          Signature signature)
```
    Create a new SmartHandle by performing a lookup on the given target class for the given method name with the given signature.
    
    Parameters:
    
    lookup - the MethodHandles.Lookup object to use
    
    target - the class where the method is located
    
    name - the name of the method
    
    signature - the signature of the method
    
    Returns:
    
    a new SmartHandle based on the signature and looked-up MethodHandle
  - signature
```
public Signature signature()
```
    Get the Signature of this SmartHandle.
    
    Returns:
    
    the Signature of this SmartHandle
  - handle
```
public MethodHandle handle()
```
    Get the MethodHandle of this SmartHandle.
    
    Returns:
    
    the MethodHandle of this SmartHandle
  - apply
```
public SmartHandle apply(int index,
                         Object arg)
```
    Apply an argument into the handle at the given index, returning a new SmartHandle. The new handle will use the given value for the argument at the given index, accepting one fewer argument as a result. In other words, fix that argument (partial application) into the given handle.
    
    Parameters:
    
    name - the name of the argument in the new SmartHandle's Signature
    
    arg - the argument value
    
    Returns:
    
    a new SmartHandle that already has applied the given argument
  - apply
```
public SmartHandle apply(String name,
                         Object arg)
```
    Apply an argument into the handle at the given name, returning a new SmartHandle. The new handle will use the given value for the argument at the given index, accepting one fewer argument as a result. In other words, fix that argument (partial application) into the given handle.
    
    Parameters:
    
    name - the name of the argument in the new SmartHandle's Signature
    
    arg - the argument value
    
    Returns:
    
    a new SmartHandle that already has applied the given argument
  - applyLast
```
public SmartHandle applyLast(Object arg)
```
    Apply an argument into the handle at the end, returning a new SmartHandle. The new handle will use the given value for the last argument, accepting one fewer argument as a result. In other words, fix that argument (partial application) into the given handle.
    
    Parameters:
    
    name - the name of the argument in the new SmartHandle's Signature
    
    arg - the argument value
    
    Returns:
    
    a new SmartHandle that already has applied the given argument
  - drop
```
public SmartHandle drop(String beforeName,
                        String newName,
                        Class type)
```
    Insert an argument into the handle at the given index, returning a new SmartHandle.
    
    Parameters:
    
    name - the name of the argument in the new SmartHandle's Signature
    
    arg - the argument value
    
    Returns:
    
    a new SmartHandle with the additional argument
  - drop
```
public SmartHandle drop(int index,
                        String newName,
                        Class type)
```
    Insert an argument into the handle at the given index, returning a new SmartHandle.
    
    Parameters:
    
    name - the name of the argument in the new SmartHandle's Signature
    
    arg - the argument value
    
    Returns:
    
    a new SmartHandle with the additional argument
  - dropLast
```
public SmartHandle dropLast(String newName,
                            Class type)
```
    Insert an argument into the handle at the given index, returning a new SmartHandle.
    
    Parameters:
    
    name - the name of the argument in the new SmartHandle's Signature
    
    arg - the argument value
    
    Returns:
    
    a new SmartHandle with the additional argument
  - guard
```
public MethodHandle guard(MethodHandle target,
                          MethodHandle fallback)
```
    Use this SmartHandle as a test to guard target and fallback handles.
    
    Parameters:
    
    target - the "true" path for this handle's test
    
    fallback - the "false" path for this handle's test
    
    Returns:
    
    a MethodHandle that performs the test and branch
  - guard
```
public SmartHandle guard(SmartHandle target,
                         SmartHandle fallback)
```
    Use this SmartHandle as a test to guard target and fallback handles.
    
    Parameters:
    
    target - the "true" path for this handle's test
    
    fallback - the "false" path for this handle's test
    
    Returns:
    
    a new SmartHandle that performs the test and branch
  - bindTo
```
public SmartHandle bindTo(Object obj)
```
    Bind the first argument of this SmartHandle to the given object, returning a new adapted handle.
    
    Parameters:
    
    obj - the object to which to bind this handle's first argument
    
    Returns:
    
    a new SmartHandle with the first argument dropped in favor of obj
  - convert
```
public SmartHandle convert(MethodType incoming)
```
    Create a new SmartHandle that converts arguments from the given type to the current signature's type, using the same argument names. This conversion is equivalent to MethodHandle#asType.
    
    Parameters:
    
    incoming - the target MethodType from which arguments will be converted
    
    Returns:
    
    a new SmartHandle that accepts the given argument types
  - convert
```
public SmartHandle convert(Class returnType,
                           Class... argTypes)
```
    Create a new SmartHandle that converts arguments from the given return type and argument types to the current signature's type, using the same argument names. This conversion is equivalent to MethodHandle#asType.
    
    Parameters:
    
    returnType - the return type of the new handle
    
    argTypes - the argument types of the new handle
    
    Returns:
    
    a new SmartHandle that accepts the given argument types
  - convert
```
public SmartHandle convert(Signature incoming)
```
    Create a new SmartHandle that converts arguments from the given signature to the current signature's type with the new argument names. This conversion is equivalent to MethodHandle#asType.
    
    Parameters:
    
    incoming - the target MethodType from which arguments will be converted
    
    Returns:
    
    a new SmartHandle that accepts the given argument types
  - cast
```
public SmartHandle cast(MethodType incoming)
```
    Create a new SmartHandle that casts arguments from the given type to the current signature's type, using the same argument names. This casting is equivalent to MethodHandles#explicitCastArguments.
    
    Parameters:
    
    incoming - the target MethodType from which arguments will be converted
    
    Returns:
    
    a new SmartHandle that accepts the given argument types
  - cast
```
public SmartHandle cast(Signature incoming)
```
    Create a new SmartHandle that casts arguments from the given signature to the current signature's type with the new argument names. This casting is equivalent to MethodHandle#asType.
    
    Parameters:
    
    incoming - the target MethodType from which arguments will be converted
    
    Returns:
    
    a new SmartHandle that accepts the given argument types
  - cast
```
public SmartHandle cast(Class returnType,
                        Class... argTypes)
```
    Create a new SmartHandle that casts arguments from the given return type and argument types to the current signature's type, using the same argument names. This casting is equivalent to MethodHandle#asType.
    
    Parameters:
    
    returnType - the return type of the new handle
    
    argTypes - the argument types of the new handle
    
    Returns:
    
    a new SmartHandle that accepts the given argument types
  - returnValue
```
public SmartHandle returnValue(Class type,
                               Object value)
```
    Replace the return value with the given value, performing no other processing of the original value.
    
    Parameters:
    
    value - the type for the new return value
    
    value - the new value to return
  - toString
```
public String toString()
```
    A human-readable String representation of this SamrtHandle.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    a String representation of this handle

Class SmartHandle

Method Summary

Methods inherited from class java.lang.Object

Method Detail

from

findStaticQuiet

signature

handle

apply

apply

applyLast

drop

drop

dropLast

guard

guard

bindTo

convert

convert

convert

cast

cast

cast

returnValue

toString