Method Detail

• lookup

  public static MethodHandles.Lookup lookup()

  Returns a lookup object on the caller, which has the capability to access any method handle that the caller has access to, including direct method handles to private fields and methods. This lookup object is a capability which may be delegated to trusted agents. Do not store it in place where untrusted code can access it.

• publicLookup

  public static MethodHandles.Lookup publicLookup()

  Returns a lookup object which is trusted minimally. It can only be used to create method handles to publicly accessible fields and methods.

  As a matter of pure convention, the lookup class of this lookup object will be Object.

  The lookup class can be changed to any other class C using an expression of the form publicLookup().in(C.class). Since all classes have equal access to public names, such a change would confer no new access rights.

• arrayElementGetter

  public static MethodHandle arrayElementGetter(Class<?> arrayClass)
                                         throws IllegalArgumentException

  Produces a method handle giving read access to elements of an array. The type of the method handle will have a return type of the array's element type. Its first argument will be the array type, and the second will be int.

  Parameters:

  arrayClass - an array type

  Returns:

  a method handle which can load values from the given array type

  Throws:

  NullPointerException - if the argument is null

  IllegalArgumentException - if arrayClass is not an array type

• arrayElementSetter

  public static MethodHandle arrayElementSetter(Class<?> arrayClass)
                                         throws IllegalArgumentException

  Produces a method handle giving write access to elements of an array. The type of the method handle will have a void return type. Its last argument will be the array's element type. The first and second arguments will be the array type and int.

  Returns:

  a method handle which can store values into the array type

  Throws:

  NullPointerException - if the argument is null

  IllegalArgumentException - if arrayClass is not an array type

• spreadInvoker

  public static MethodHandle spreadInvoker(MethodType type,
                           int objectArgCount)

  Produces a method handle which will invoke any method handle of the given type on a standard set of Object type arguments and a single trailing Object[] array. The resulting invoker will be a method handle with the following arguments:

  • a single MethodHandle target
  • zero or more Object values (counted by objectArgCount)
  • an Object[] array containing more arguments

  The invoker will behave like a call to invokeGeneric with the indicated type. That is, if the target is exactly of the given type, it will behave like invokeExact; otherwise it behave as if asType is used to convert the target to the required type.

  The type of the returned invoker will not be the given type, but rather will have all parameter and return types replaced by Object, except for the last parameter type, which will be the array type Object[].

  Before invoking its target, the invoker will spread the varargs array, apply reference casts as necessary, and unbox and widen primitive arguments. The return value of the invoker will be an Object reference, boxing a primitive value if the original type returns a primitive, and always null if the original type returns void.

  This method is equivalent to the following code (though it may be more efficient):

  MethodHandle invoker = MethodHandles.genericInvoker(type);
  int spreadArgCount = type.parameterCount - objectArgCount;
  invoker = invoker.asSpreader(Object[].class, spreadArgCount);
  return invoker;
   

  This method throws no reflective or security exceptions.

  Parameters:

  type - the desired target type

  objectArgCount - number of fixed (non-varargs) Object arguments

  Returns:

  a method handle suitable for invoking any method handle of the given type

• exactInvoker

  public static MethodHandle exactInvoker(MethodType type)

  Produces a special invoker method handle which can be used to invoke any method handle of the given type, as if by invokeExact. The resulting invoker will have a type which is exactly equal to the desired type, except that it will accept an additional leading argument of type MethodHandle.

  This method is equivalent to the following code (though it may be more efficient):

  publicLookup().findVirtual(MethodHandle.class, "invokeExact", type)
   

  Discussion: Invoker method handles can be useful when working with variable method handles of unknown types. For example, to emulate an invokeExact call to a variable method handle M, extract its type T, look up the invoker method X for T, and call the invoker method, as X.invokeGeneric(T, A...). (It would not work to call X.invokeExact, since the type T is unknown.) If spreading, collecting, or other argument transformations are required, they can be applied once to the invoker X and reused on many M method handle values, as long as they are compatible with the type of X.

  (Note: The invoker method is not available via the Core Reflection API. An attempt to call Method.invoke on the declared invokeExact or invokeGeneric method will raise an UnsupportedOperationException.)

  This method throws no reflective or security exceptions.

  Parameters:

  type - the desired target type

  Returns:

  a method handle suitable for invoking any method handle of the given type

• genericInvoker

  public static MethodHandle genericInvoker(MethodType type)

  Produces a special invoker method handle which can be used to invoke any method handle of the given type, as if by invokeGeneric. The resulting invoker will have a type which is exactly equal to the desired type, except that it will accept an additional leading argument of type MethodHandle.

  Before invoking its target, the invoker will apply reference casts as necessary and unbox and widen primitive arguments, as if by convertArguments. The return value of the invoker will be an Object reference, boxing a primitive value if the original type returns a primitive, and always null if the original type returns void.

  This method is equivalent to the following code (though it may be more efficient):

  publicLookup().findVirtual(MethodHandle.class, "invokeGeneric", type)
   

  This method throws no reflective or security exceptions.

  Parameters:

  type - the desired target type

  Returns:

  a method handle suitable for invoking any method handle convertible to the given type

• convertArguments

  public static MethodHandle convertArguments(MethodHandle target,
                              MethodType newType)

  Produces a method handle which adapts the type of the given method handle to a new type by pairwise argument conversion. The original type and new type must have the same number of arguments. The resulting method handle is guaranteed to report a type which is equal to the desired new type.

  If the original type and new type are equal, returns target.

  The following conversions are applied as needed both to arguments and return types. Let T0 and T1 be the differing new and old parameter types (or old and new return types) for corresponding values passed by the new and old method types. Given those types T0, T1, one of the following conversions is applied if possible:

  • If T0 and T1 are references, then a cast to T1 is applied. (The types do not need to be related in any particular way.)
  • If T0 and T1 are primitives, then a Java method invocation conversion (JLS 5.3) is applied, if one exists.
  • If T0 is a primitive and T1 a reference, a boxing conversion is applied if one exists, possibly followed by a reference conversion to a superclass. T1 must be a wrapper class or a supertype of one.
  • If T0 is a reference and T1 a primitive, an unboxing conversion will be applied at runtime, possibly followed by a Java method invocation conversion (JLS 5.3) on the primitive value. (These are the widening conversions.) T0 must be a wrapper class or a supertype of one. (In the case where T0 is Object, these are the conversions allowed by java.lang.reflect.Method.invoke.)
  • If the return type T1 is void, any returned value is discarded
  • If the return type T0 is void and T1 a reference, a null value is introduced.
  • If the return type T0 is void and T1 a primitive, a zero value is introduced.

  Parameters:

  target - the method handle to invoke after arguments are retyped

  newType - the expected type of the new method handle

  Returns:

  a method handle which delegates to target after performing any necessary argument conversions, and arranges for any necessary return value conversions

  Throws:

  NullPointerException - if either argument is null

  WrongMethodTypeException - if the conversion cannot be made

  See Also:

  MethodHandle.asType(java.lang.invoke.MethodType), explicitCastArguments(java.lang.invoke.MethodHandle, java.lang.invoke.MethodType)

• explicitCastArguments

  public static MethodHandle explicitCastArguments(MethodHandle target,
                                   MethodType newType)

  Produces a method handle which adapts the type of the given method handle to a new type by pairwise argument conversion. The original type and new type must have the same number of arguments. The resulting method handle is guaranteed to report a type which is equal to the desired new type.

  If the original type and new type are equal, returns target.

  The same conversions are allowed as for convertArguments, and some additional conversions are also applied if those conversions fail. Given types T0, T1, one of the following conversions is applied in addition, if the conversions specified for convertArguments would be insufficient:

  • If T0 and T1 are references, and T1 is an interface type, then the value of type T0 is passed as a T1 without a cast. (This treatment of interfaces follows the usage of the bytecode verifier.)
  • If T0 and T1 are primitives and one is boolean, the boolean is treated as a one-bit unsigned integer. (This treatment follows the usage of the bytecode verifier.) A conversion from another primitive type behaves as if it first converts to byte, and then masks all but the low bit.
  • If a primitive value would be converted by convertArguments using Java method invocation conversion (JLS 5.3), Java casting conversion (JLS 5.5) may be used also. This allows primitives to be narrowed as well as widened.

  Parameters:

  target - the method handle to invoke after arguments are retyped

  newType - the expected type of the new method handle

  Returns:

  a method handle which delegates to target after performing any necessary argument conversions, and arranges for any necessary return value conversions

  Throws:

  NullPointerException - if either argument is null

  WrongMethodTypeException - if the conversion cannot be made

  See Also:

  MethodHandle.asType(java.lang.invoke.MethodType), convertArguments(java.lang.invoke.MethodHandle, java.lang.invoke.MethodType)

• permuteArguments

  public static MethodHandle permuteArguments(MethodHandle target,
                              MethodType newType,
                              int... reorder)

  Produces a method handle which adapts the calling sequence of the given method handle to a new type, by reordering the arguments. The resulting method handle is guaranteed to report a type which is equal to the desired new type.

  The given array controls the reordering. Call #I the number of incoming parameters (the value newType.parameterCount(), and call #O the number of outgoing parameters (the value target.type().parameterCount()). Then the length of the reordering array must be #O, and each element must be a non-negative number less than #I. For every N less than #O, the N-th outgoing argument will be taken from the I-th incoming argument, where I is reorder[N].

  No argument or return value conversions are applied. The type of each incoming argument, as determined by newType, must be identical to the type of the corresponding outgoing argument or arguments in the target method handle. The return type of newType must be identical to the return type of the original target.

  The reordering array need not specify an actual permutation. An incoming argument will be duplicated if its index appears more than once in the array, and an incoming argument will be dropped if its index does not appear in the array. As in the case of dropArguments, incoming arguments which are not mentioned in the reordering array are may be any type, as determined only by newType.

  MethodType intfn1 = MethodType.methodType(int.class, int.class);
  MethodType intfn2 = MethodType.methodType(int.class, int.class, int.class);
  MethodHandle sub = ... {int x, int y => x-y} ...;
  assert(sub.type().equals(intfn2));
  MethodHandle sub1 = MethodHandles.permuteArguments(sub, intfn2, 0, 1);
  MethodHandle rsub = MethodHandles.permuteArguments(sub, intfn2, 1, 0);
  assert((int)rsub.invokeExact(1, 100) == 99);
  MethodHandle add = ... {int x, int y => x+y} ...;
  assert(add.type().equals(intfn2));
  MethodHandle twice = MethodHandles.permuteArguments(add, intfn1, 0, 0);
  assert(twice.type().equals(intfn1));
  assert((int)twice.invokeExact(21) == 42);
   

  Parameters:

  target - the method handle to invoke after arguments are reordered

  newType - the expected type of the new method handle

  reorder - a string which controls the reordering

  Returns:

  a method handle which delegates to target after it drops unused arguments and moves and/or duplicates the other arguments

  Throws:

  NullPointerException - if any argument is null

• constant

  public static MethodHandle constant(Class<?> type,
                      Object value)

  Produces a method handle of the requested return type which returns the given constant value every time it is invoked.

  Before the method handle is returned, the passed-in value is converted to the requested type. If the requested type is primitive, widening primitive conversions are attempted, else reference conversions are attempted.

  The returned method handle is equivalent to identity(type).bindTo(value), unless the type is void, in which case it is identity(type).

  Parameters:

  type - the return type of the desired method handle

  value - the value to return

  Returns:

  a method handle of the given return type and no arguments, which always returns the given value

  Throws:

  NullPointerException - if the type argument is null

  ClassCastException - if the value cannot be converted to the required return type

  IllegalArgumentException - if the given type is void.class

• identity

  public static MethodHandle identity(Class<?> type)

  Produces a method handle which returns its sole argument when invoked.

  The identity function for void takes no arguments and returns no values.

  Parameters:

  type - the type of the sole parameter and return value of the desired method handle

  Returns:

  a unary method handle which accepts and returns the given type

  Throws:

  NullPointerException - if the argument is null

  IllegalArgumentException - if the given type is void.class

• insertArguments

  public static MethodHandle insertArguments(MethodHandle target,
                             int pos,
                             Object... values)

  Produces a method handle which calls the original method handle target, after inserting the given argument(s) at the given position. The formal parameters to target which will be supplied by those arguments are called bound parameters, because the new method will contain bindings for those parameters take from values. The type of the new method handle will drop the types for the bound parameters from the original target type, since the new method handle will no longer require those arguments to be supplied by its callers.

  Each given argument object must match the corresponding bound parameter type. If a bound parameter type is a primitive, the argument object must be a wrapper, and will be unboxed to produce the primitive value.

  The pos may range between zero and N (inclusively), where N is the number of argument types in resulting method handle (after bound parameter types are dropped).

  Parameters:

  target - the method handle to invoke after the argument is inserted

  pos - where to insert the argument (zero for the first)

  values - the series of arguments to insert

  Returns:

  a method handle which inserts an additional argument, before calling the original method handle

  Throws:

  NullPointerException - if the target argument or the values array is null

  See Also:

  MethodHandle.bindTo(java.lang.Object)

• dropArguments

  public static MethodHandle dropArguments(MethodHandle target,
                           int pos,
                           List<Class<?>> valueTypes)

  Produces a method handle which calls the original method handle, after dropping the given argument(s) at the given position. The type of the new method handle will insert the given argument type(s), at that position, into the original handle's type.

  The pos may range between zero and N, where N is the number of argument types in target, meaning to drop the first or last argument (respectively), or an argument somewhere in between.

  Example:

  import static java.lang.invoke.MethodHandles.*;
  import static java.lang.invoke.MethodType.*;
  ...
  MethodHandle cat = lookup().findVirtual(String.class,
    "concat", methodType(String.class, String.class));
  assertEquals("xy", (String) cat.invokeExact("x", "y"));
  MethodType bigType = cat.type().insertParameterTypes(0, int.class, String.class);
  MethodHandle d0 = dropArguments(cat, 0, bigType.parameterList().subList(0,2));
  assertEquals(bigType, d0.type());
  assertEquals("yz", (String) d0.invokeExact(123, "x", "y", "z"));
   

  This method is also equivalent to the following code:

   dropArguments(target, pos, valueTypes.toArray(new Class[0]))
   

  Parameters:

  target - the method handle to invoke after the arguments are dropped

  valueTypes - the type(s) of the argument(s) to drop

  pos - position of first argument to drop (zero for the leftmost)

  Returns:

  a method handle which drops arguments of the given types, before calling the original method handle

  Throws:

  NullPointerException - if the target argument is null, or if the valueTypes list or any of its elements is null

  IllegalArgumentException - if any of the valueTypes is void.class

• dropArguments

  public static MethodHandle dropArguments(MethodHandle target,
                           int pos,
                           Class<?>... valueTypes)

  Produces a method handle which calls the original method handle, after dropping the given argument(s) at the given position. The type of the new method handle will insert the given argument type(s), at that position, into the original handle's type.

  The pos may range between zero and N, where N is the number of argument types in target, meaning to drop the first or last argument (respectively), or an argument somewhere in between.

  Example:

  import static java.lang.invoke.MethodHandles.*;
  import static java.lang.invoke.MethodType.*;
  ...
  MethodHandle cat = lookup().findVirtual(String.class,
    "concat", methodType(String.class, String.class));
  assertEquals("xy", (String) cat.invokeExact("x", "y"));
  MethodHandle d0 = dropArguments(cat, 0, String.class);
  assertEquals("yz", (String) d0.invokeExact("x", "y", "z"));
  MethodHandle d1 = dropArguments(cat, 1, String.class);
  assertEquals("xz", (String) d1.invokeExact("x", "y", "z"));
  MethodHandle d2 = dropArguments(cat, 2, String.class);
  assertEquals("xy", (String) d2.invokeExact("x", "y", "z"));
  MethodHandle d12 = dropArguments(cat, 1, int.class, boolean.class);
  assertEquals("xz", (String) d12.invokeExact("x", 12, true, "z"));
   

  This method is also equivalent to the following code:

   dropArguments(target, pos, Arrays.asList(valueTypes))
   

  Parameters:

  target - the method handle to invoke after the arguments are dropped

  valueTypes - the type(s) of the argument(s) to drop

  pos - position of first argument to drop (zero for the leftmost)

  Returns:

  a method handle which drops arguments of the given types, before calling the original method handle

  Throws:

  NullPointerException - if the target argument is null, or if the valueTypes array or any of its elements is null

  IllegalArgumentException - if any of the valueTypes is void.class

• filterArguments

  public static MethodHandle filterArguments(MethodHandle target,
                             int pos,
                             MethodHandle... filters)

  Adapts a target method handle target by pre-processing one or more of its arguments, each with its own unary filter function, and then calling the target with each pre-processed argument replaced by the result of its corresponding filter function.

  The pre-processing is performed by one or more method handles, specified in the elements of the filters array. Null arguments in the array are ignored, and the corresponding arguments left unchanged. (If there are no non-null elements in the array, the original target is returned.) Each filter is applied to the corresponding argument of the adapter.

  If a filter F applies to the Nth argument of the method handle, then F must be a method handle which takes exactly one argument. The type of F's sole argument replaces the corresponding argument type of the target in the resulting adapted method handle. The return type of F must be identical to the corresponding parameter type of the target.

  It is an error if there are elements of filters which do not correspond to argument positions in the target. Example:

  import static java.lang.invoke.MethodHandles.*;
  import static java.lang.invoke.MethodType.*;
  ...
  MethodHandle cat = lookup().findVirtual(String.class,
    "concat", methodType(String.class, String.class));
  MethodHandle upcase = lookup().findVirtual(String.class,
    "toUpperCase", methodType(String.class));
  assertEquals("xy", (String) cat.invokeExact("x", "y"));
  MethodHandle f0 = filterArguments(cat, 0, upcase);
  assertEquals("Xy", (String) f0.invokeExact("x", "y")); // Xy
  MethodHandle f1 = filterArguments(cat, 1, upcase);
  assertEquals("xY", (String) f1.invokeExact("x", "y")); // xY
  MethodHandle f2 = filterArguments(cat, 0, upcase, upcase);
  assertEquals("XY", (String) f2.invokeExact("x", "y")); // XY
   

  Parameters:

  target - the method handle to invoke after arguments are filtered

  pos - the position of the first argument to filter

  filters - method handles to call initially on filtered arguments

  Returns:

  method handle which incorporates the specified argument filtering logic

  Throws:

  NullPointerException - if the target argument is null or if the filters array is null

  IllegalArgumentException - if a non-null element of filters does not match a corresponding argument type of target as described above, or if the pos+filters.length is greater than target.type().parameterCount()

• filterReturnValue

  public static MethodHandle filterReturnValue(MethodHandle target,
                               MethodHandle filter)

  Adapts a target method handle target by post-processing its return value with a unary filter function.

  If a filter F applies to the return value of the target method handle, then F must be a method handle which takes exactly one argument. The return type of F replaces the return type of the target in the resulting adapted method handle. The argument type of F must be identical to the return type of the target. Example:

  import static java.lang.invoke.MethodHandles.*;
  import static java.lang.invoke.MethodType.*;
  ...
  MethodHandle cat = lookup().findVirtual(String.class,
    "concat", methodType(String.class, String.class));
  MethodHandle length = lookup().findVirtual(String.class,
    "length", methodType(int.class));
  System.out.println((String) cat.invokeExact("x", "y")); // xy
  MethodHandle f0 = filterReturnValue(cat, length);
  System.out.println((int) f0.invokeExact("x", "y")); // 2
   

  Parameters:

  target - the method handle to invoke before filtering the return value

  filter - method handle to call on the return value

  Returns:

  method handle which incorporates the specified return value filtering logic

  Throws:

  NullPointerException - if either argument is null

  IllegalArgumentException - if filter does not match the return type of target as described above

• foldArguments

  public static MethodHandle foldArguments(MethodHandle target,
                           MethodHandle combiner)

  Adapts a target method handle target by pre-processing some of its arguments, and then calling the target with the result of the pre-processing, plus all original arguments.

  The pre-processing is performed by a second method handle, the combiner. The first N arguments passed to the adapter, are copied to the combiner, which then produces a result. (Here, N is defined as the parameter count of the adapter.) After this, control passes to the target, with both the result of the combiner, and all the original incoming arguments.

  The first argument type of the target must be identical with the return type of the combiner. The resulting adapter is the same type as the target, except that the initial argument type of the target is dropped.

  (Note that dropArguments can be used to remove any arguments that either the combiner or target does not wish to receive. If some of the incoming arguments are destined only for the combiner, consider using asCollector instead, since those arguments will not need to be live on the stack on entry to the target.)

  The first argument of the target must be identical with the return value of the combiner.

  Here is pseudocode for the resulting adapter:

   // there are N arguments in the A sequence
   T target(V, A[N]..., B...);
   V combiner(A...);
   T adapter(A... a, B... b) {
     V v = combiner(a...);
     return target(v, a..., b...);
   }
   

  Parameters:

  target - the method handle to invoke after arguments are combined

  combiner - method handle to call initially on the incoming arguments

  Returns:

  method handle which incorporates the specified argument folding logic

  Throws:

  NullPointerException - if either argument is null

  IllegalArgumentException - if the first argument type of target is not the same as combiner's return type, or if the following argument types of target are not identical with the argument types of combiner

• guardWithTest

  public static MethodHandle guardWithTest(MethodHandle test,
                           MethodHandle target,
                           MethodHandle fallback)

  Makes a method handle which adapts a target method handle, by guarding it with a test, a boolean-valued method handle. If the guard fails, a fallback handle is called instead. All three method handles must have the same corresponding argument and return types, except that the return type of the test must be boolean, and the test is allowed to have fewer arguments than the other two method handles.

  Here is pseudocode for the resulting adapter:

   boolean test(A...);
   T target(A...,B...);
   T fallback(A...,B...);
   T adapter(A... a,B... b) {
     if (test(a...))
       return target(a..., b...);
     else
       return fallback(a..., b...);
   }
   

  Note that the test arguments (a... in the pseudocode) cannot be modified by execution of the test, and so are passed unchanged from the caller to the target or fallback as appropriate.

  Parameters:

  test - method handle used for test, must return boolean

  target - method handle to call if test passes

  fallback - method handle to call if test fails

  Returns:

  method handle which incorporates the specified if/then/else logic

  Throws:

  NullPointerException - if any argument is null

  IllegalArgumentException - if test does not return boolean, or if all three method types do not match (with the return type of test changed to match that of target).

• catchException

  public static MethodHandle catchException(MethodHandle target,
                            Class<? extends Throwable> exType,
                            MethodHandle handler)

  Makes a method handle which adapts a target method handle, by running it inside an exception handler. If the target returns normally, the adapter returns that value. If an exception matching the specified type is thrown, the fallback handle is called instead on the exception, plus the original arguments.

  The target and handler must have the same corresponding argument and return types, except that handler may omit trailing arguments (similarly to the predicate in guardWithTest). Also, the handler must have an extra leading parameter of exType or a supertype.

  Here is pseudocode for the resulting adapter:

   T target(A..., B...);
   T handler(ExType, A...);
   T adapter(A... a, B... b) {
     try {
       return target(a..., b...);
     } catch (ExType ex) {
       return handler(ex, a...);
     }
   }
   

  Note that the saved arguments (a... in the pseudocode) cannot be modified by execution of the target, and so are passed unchanged from the caller to the handler, if the handler is invoked.

  The target and handler must return the same type, even if the handler always throws. (This might happen, for instance, because the handler is simulating a finally clause). To create such a throwing handler, compose the handler creation logic with throwException, in order to create a method handle of the correct return type.

  Parameters:

  target - method handle to call

  exType - the type of exception which the handler will catch

  handler - method handle to call if a matching exception is thrown

  Returns:

  method handle which incorporates the specified try/catch logic

  Throws:

  NullPointerException - if any argument is null

  IllegalArgumentException - if handler does not accept the given exception type, or if the method handle types do not match in their return types and their corresponding parameters

• throwException

  public static MethodHandle throwException(Class<?> returnType,
                            Class<? extends Throwable> exType)

  Produces a method handle which will throw exceptions of the given exType. The method handle will accept a single argument of exType, and immediately throw it as an exception. The method type will nominally specify a return of returnType. The return type may be anything convenient: It doesn't matter to the method handle's behavior, since it will never return normally.

  Returns:

  method handle which can throw the given exceptions

  Throws:

  NullPointerException - if either argument is null

• asInstance

  public static <T> T asInstance(MethodHandle target,
                 Class<T> smType)

  Produces an instance of the given single-method interface which redirects its calls to the given method handle.

  A single-method interface is an interface which declares a unique method. When determining the unique method of a single-method interface, the public Object methods (toString, equals, hashCode) are disregarded. For example, Comparator is a single-method interface, even though it re-declares the Object.equals method.

  The type must be public. No additional access checks are performed.

  The resulting instance of the required type will respond to invocation of the type's single abstract method by calling the given target on the incoming arguments, and returning or throwing whatever the target returns or throws. The invocation will be as if by target.invokeGeneric. The target's type will be checked before the instance is created, as if by a call to asType, which may result in a WrongMethodTypeException.

  The wrapper instance will implement the requested interface and its super-types, but no other single-method interfaces. This means that the instance will not unexpectedly pass an instanceof test for any unrequested type.

  Implementation Note: Therefore, each instance must implement a unique single-method interface. Implementations may not bundle together multiple single-method interfaces onto single implementation classes in the style of AWTEventMulticaster.

  The method handle may throw an undeclared exception, which means any checked exception (or other checked throwable) not declared by the requested type's single abstract method. If this happens, the throwable will be wrapped in an instance of UndeclaredThrowableException and thrown in that wrapped form.

  Like Integer.valueOf, asInstance is a factory method whose results are defined by their behavior. It is not guaranteed to return a new instance for every call.

  Because of the possibility of bridge methods and other corner cases, the interface may also have several abstract methods with the same name but having distinct descriptors (types of returns and parameters). In this case, all the methods are bound in common to the one given target. The type check and effective asType conversion is applied to each method type descriptor, and all abstract methods are bound to the target in common. Beyond this type check, no further checks are made to determine that the abstract methods are related in any way.

  Future versions of this API may accept additional types, such as abstract classes with single abstract methods. Future versions of this API may also equip wrapper instances with one or more additional public "marker" interfaces.

  Parameters:

  target - the method handle to invoke from the wrapper

  smType - the desired type of the wrapper, a single-method interface

  Returns:

  a correctly-typed wrapper for the given target

  Throws:

  NullPointerException - if either argument is null

  IllegalArgumentException - if the smType is not a valid argument to this method

  WrongMethodTypeException - if the target cannot be converted to the type required by the requested interface

• isWrapperInstance

  public static boolean isWrapperInstance(Object x)

  Determines if the given object was produced by a call to asInstance.

  Parameters:

  x - any reference

  Returns:

  true if the reference is not null and points to an object produced by asInstance

• wrapperInstanceTarget

  public static MethodHandle wrapperInstanceTarget(Object x)

  Produces or recovers a target method handle which is behaviorally equivalent to the unique method of this wrapper instance. The object x must have been produced by a call to asInstance. This requirement may be tested via isWrapperInstance.

  Parameters:

  x - any reference

  Returns:

  a method handle implementing the unique method

  Throws:

  IllegalArgumentException - if the reference x is not to a wrapper instance

• wrapperInstanceType

  public static Class<?> wrapperInstanceType(Object x)

  Recovers the unique single-method interface type for which this wrapper instance was created. The object x must have been produced by a call to asInstance. This requirement may be tested via isWrapperInstance.

  Parameters:

  x - any reference

  Returns:

  the single-method interface type for which the wrapper was created

  Throws:

  IllegalArgumentException - if the reference x is not to a wrapper instance