Module java.base

Class MethodHandles.Lookup

  • Enclosing class:
    MethodHandles

    public static final class MethodHandles.Lookup
    extends Object
    A factory for creating MethodHandles that require access-checking on creation.

    Unlike Reflection, MethodHandle only requires access-checking when the MethodHandle is created, not when it is invoked.

    This class provides the lookup authentication necessary when creating MethodHandles. Any number of MethodHandles can be lookup using this token, and the token can be shared to provide others with the the "owner's" authentication level.

    Sharing MethodHandles.Lookup objects should be done with care, as they may allow access to private methods.

    When using the lookup factory methods (find and unreflect methods), creating the MethodHandle may fail because the method's arity is too high.

    • Method Detail

      • lookupModes

        public int lookupModes()
        A query to determine the lookup capabilities held by this instance.
        Returns:
        the lookup mode bit mask for this Lookup object
      • bind

        public MethodHandle bind​(Object receiver,
                                 String methodName,
                                 MethodType type)
                          throws IllegalAccessException,
                                 NoSuchMethodException
        Return an early-bound method handle to a non-static method. The receiver must have a Class in its hierarchy that provides the virtual method named methodName.

        The final MethodType of the MethodHandle will be identical to that of the method. The receiver will be inserted prior to the call and therefore does not need to be included in the MethodType.

        Parameters:
        receiver - - The Object to insert as a receiver. Must implement the methodName
        methodName - - The name of the method
        type - - The MethodType describing the method
        Returns:
        a MethodHandle to the required method.
        Throws:
        IllegalAccessException - if access is denied
        NoSuchMethodException - if the method doesn't exist
      • findSpecial

        public MethodHandle findSpecial​(Class<?> clazz,
                                        String methodName,
                                        MethodType type,
                                        Class<?> specialToken)
                                 throws IllegalAccessException,
                                        NoSuchMethodException,
                                        SecurityException,
                                        NullPointerException
        Return a MethodHandle bound to a specific-implementation of a virtual method, as if created by an invokespecial bytecode using the class specialToken. The method and all Classes in its MethodType must be accessible to the caller.

        The receiver class will be added to the MethodType of the handle, but dispatch will not occur based on the receiver.

        Parameters:
        clazz - - the class or interface from which defines the method
        methodName - - the method name
        type - - the MethodType of the method
        specialToken - - the calling class for the invokespecial
        Returns:
        a MethodHandle
        Throws:
        IllegalAccessException - - if the method is static or access checking fails
        NullPointerException - - if clazz, methodName, type or specialToken is null
        NoSuchMethodException - - if clazz has no instance method named methodName with signature matching type
        SecurityException - - if any installed SecurityManager denies access to the method
      • findStatic

        public MethodHandle findStatic​(Class<?> clazz,
                                       String methodName,
                                       MethodType type)
                                throws IllegalAccessException,
                                       NoSuchMethodException
        Return a MethodHandle to a static method. The MethodHandle will have the same type as the method. The method and all classes in its type must be accessible to the caller.
        Parameters:
        clazz - - the class defining the method
        methodName - - the name of the method
        type - - the MethodType of the method
        Returns:
        A MethodHandle able to invoke the requested static method
        Throws:
        IllegalAccessException - - if the method is not static or access checking fails
        NullPointerException - - if clazz, methodName or type is null
        NoSuchMethodException - - if clazz has no static method named methodName with signature matching type
        SecurityException - - if any installed SecurityManager denies access to the method
      • findVirtual

        public MethodHandle findVirtual​(Class<?> clazz,
                                        String methodName,
                                        MethodType type)
                                 throws IllegalAccessException,
                                        NoSuchMethodException
        Return a MethodHandle to a virtual method. The method will be looked up in the first argument (aka receiver) prior to dispatch. The type of the MethodHandle will be that of the method with the receiver type prepended.
        Parameters:
        clazz - - the class defining the method
        methodName - - the name of the method
        type - - the type of the method
        Returns:
        a MethodHandle that will do virtual dispatch on the first argument
        Throws:
        IllegalAccessException - - if method is static or access is refused or clazz's package is not exported to the current module
        IllegalAccessError - - if the type's packages are not exported to the current module
        NullPointerException - - if clazz, methodName or type is null
        NoSuchMethodException - - if clazz has no virtual method named methodName with signature matching type
        SecurityException - - if any installed SecurityManager denies access to the method
      • in

        public MethodHandles.Lookup in​(Class<?> lookupClass)
        Create a lookup on the request class. The resulting lookup will have no more access privileges than the original.
        Parameters:
        lookupClass - - the class to create the lookup on
        Returns:
        a new MethodHandles.Lookup object
      • lookupClass

        public Class<?> lookupClass()
        The class being used for visibility checks and access permissions.
        Returns:
        The class used in by this Lookup object for access checking
      • unreflect

        public MethodHandle unreflect​(Method method)
                               throws IllegalAccessException
        Make a MethodHandle to the Reflect method. If the method is non-static, the receiver argument is treated as the initial argument in the MethodType.

        If m is a virtual method, normal virtual dispatch is used on each invocation.

        If the accessible flag is not set on the Reflect method, then access checking is performed using the lookup class.

        Parameters:
        method - - the reflect method
        Returns:
        A MethodHandle able to invoke the reflect method
        Throws:
        IllegalAccessException - - if access is denied
      • unreflectConstructor

        public MethodHandle unreflectConstructor​(Constructor<?> method)
                                          throws IllegalAccessException
        Return a MethodHandle for the reflect constructor. The MethodType has a return type of the declared class, and the arguments of the constructor. The MethodHandle creates a new object as through by newInstance.

        If the accessible flag is not set, then access checking is performed using the lookup class.

        Parameters:
        method - - the Reflect constructor
        Returns:
        a Methodhandle that creates new instances using the requested constructor
        Throws:
        IllegalAccessException - - if access is denied
      • findConstructor

        public MethodHandle findConstructor​(Class<?> declaringClass,
                                            MethodType type)
                                     throws IllegalAccessException,
                                            NoSuchMethodException
        Return a MethodHandle that will create an object of the required class and initialize it using the constructor method with signature type. The MethodHandle will have a MethodType with the same parameters as the constructor method, but will have a return type of the declaringClass instead of void.
        Parameters:
        declaringClass - - Class that declares the constructor
        type - - the MethodType of the constructor. Return type must be void.
        Returns:
        a MethodHandle able to construct and initialize the required class
        Throws:
        IllegalAccessException - if access is denied
        NoSuchMethodException - if the method doesn't exist
        SecurityException - if the SecurityManager prevents access
        NullPointerException - if any of the arguments are null
      • unreflectSpecial

        public MethodHandle unreflectSpecial​(Method method,
                                             Class<?> specialToken)
                                      throws IllegalAccessException
        Return a MethodHandle for the Reflect method, that will directly call the requested method as through from the class specialToken. The MethodType of the method handle will be that of the method with the receiver argument prepended.
        Parameters:
        method - - a Reflect method
        specialToken - - the class the call is from
        Returns:
        a MethodHandle that directly dispatches the requested method
        Throws:
        IllegalAccessException - - if access is denied
      • unreflectGetter

        public MethodHandle unreflectGetter​(Field field)
                                     throws IllegalAccessException
        Create a MethodHandle that returns the value of the Reflect field. There are two cases:
        1. a static field - which has the MethodType with only a return type of the field
        2. an instance field - which has the MethodType with a return type of the field and a single argument of the object that contains the field

        If the accessible flag is not set, then access checking is performed using the lookup class.

        Parameters:
        field - - a Reflect field
        Returns:
        a MethodHandle able to return the field value
        Throws:
        IllegalAccessException - - if access is denied
      • unreflectSetter

        public MethodHandle unreflectSetter​(Field field)
                                     throws IllegalAccessException
        Create a MethodHandle that sets the value of the Reflect field. All MethodHandles created here have a return type of void. For the arguments, there are two cases:
        1. a static field - which takes a single argument the same as the field
        2. an instance field - which takes two arguments, the object that contains the field, and the type of the field

        If the accessible flag is not set, then access checking is performed using the lookup class.

        Parameters:
        field - - a Reflect field
        Returns:
        a MethodHandle able to set the field value
        Throws:
        IllegalAccessException - - if access is denied
      • revealDirect

        public MethodHandleInfo revealDirect​(MethodHandle target)
                                      throws IllegalArgumentException,
                                             NullPointerException,
                                             SecurityException
        Cracks a MethodHandle, which allows access to its symbolic parts. The MethodHandle must have been created by this Lookup object or one that is able to recreate the MethodHandle. If the Lookup object is not able to recreate the MethodHandle, the cracking may fail.
        Parameters:
        target - The MethodHandle to be cracked
        Returns:
        a MethodHandleInfo which provides access to the target's symbolic parts
        Throws:
        IllegalArgumentException - if the target is not a direct handle, or if the access check fails
        NullPointerException - if the target is null
        SecurityException - if a SecurityManager denies access
      • unreflectVarHandle

        public VarHandle unreflectVarHandle​(Field field)
                                     throws IllegalAccessException
        Create a VarHandle that operates on the field represented by the reflect field.

        Access checking is performed regardless of whether the reflect field's accessible flag is set.

        Parameters:
        field - - a reflect field
        Returns:
        a VarHandle able to operate on the field
        Throws:
        IllegalAccessException - - if access is denied
      • findClass

        public Class<?> findClass​(String targetName)
                           throws ClassNotFoundException,
                                  IllegalAccessException
        Search the target class by class name via the lookup context. The target class is not statically initialized.

        The lookup context depends upon the lookup class, its classloader and its access modes. This method tells whether the target class is accessible to this lookup class after successfully loading the target class.

        Parameters:
        targetName - - the name of the target class
        Returns:
        the target class
        Throws:
        ClassNotFoundException - if the lookup class's classloader fails to load the target class.
        IllegalAccessException - if access is denied
        SecurityException - if the SecurityManager prevents access
        LinkageError - if it fails in linking
      • accessClass

        public Class<?> accessClass​(Class<?> targetClass)
                             throws IllegalAccessException
        Tells whether the target class is accessible to the lookup class. The target class is not statically initialized.

        The lookup context depends upon the lookup class and its access modes.

        Parameters:
        targetClass - - the target class to be checked
        Returns:
        the target class after check
        Throws:
        IllegalAccessException - if access is denied
        SecurityException - if the SecurityManager prevents access
      • dropLookupMode

        public MethodHandles.Lookup dropLookupMode​(int dropMode)
        Return a MethodHandles.Lookup object without the requested lookup mode. Note: the requested mode must exists in the access mode; otherwise, do nothing.
        Parameters:
        dropMode - the mode to be dropped which must exists in the access mode
        Returns:
        a MethodHandles.Lookup object without the requested lookup mode
        Throws:
        IllegalArgumentException - - if the requested lookup mode is not one of the existing access modes
      • hasPrivateAccess

        public boolean hasPrivateAccess()
        Return true if the lookup class has private access
        Returns:
        a boolean type indicating whether the lookup class has private access