A Lookup with this lookup mode performs cross-module access check with respect to the lookup class and previous lookup class if present.

If this lookup mode is set, the previous lookup class is always null.

If this lookup mode is set, the previous lookup class is always null.

If this lookup mode is set, the Lookup object must be created by the original lookup class by calling MethodHandles.lookup() method or by a bootstrap method invoked by the VM. The Lookup object with this lookup mode has full privilege access.

If this lookup object has a previous lookup class, access checks are performed against both the lookup class and the previous lookup class.

The class implies a maximum level of access permission, but the permissions may be additionally limited by the bitmask lookupModes, which controls whether non-public members can be accessed.

A Lookup object produced by the factory methods, such as the lookup() and publicLookup() method, has null previous lookup class. A Lookup object has a non-null previous lookup class when this lookup was teleported from an old lookup class in one module to a new lookup class in another module.

A freshly-created lookup object on the caller's class has all possible bits set, except UNCONDITIONAL. A lookup object on a new lookup class created from a previous lookup object may have some mode bits set to zero. Mode bits can also be directly cleared. Once cleared, mode bits cannot be restored from the downgraded lookup object. The purpose of this is to restrict access via the new lookup object, so that it can access only names which can be reached by the original lookup object, and also by the new lookup class.

However, the resulting Lookup object is guaranteed to have no more access capabilities than the original. In particular, access capabilities can be lost as follows:

• If the new lookup class is different from the old lookup class, i.e. ORIGINAL access is lost.
• If the new lookup class is in a different module from the old one, i.e. MODULE access is lost.
• If the new lookup class is in a different package than the old one, protected and default (package) members will not be accessible, i.e. PROTECTED and PACKAGE access are lost.
• If the new lookup class is not within the same package member as the old one, private members will not be accessible, and protected members will not be accessible by virtue of inheritance, i.e. PRIVATE access is lost. (Protected members may continue to be accessible because of package sharing.)
• If the new lookup class is not accessible to this lookup, then no members, not even public members, will be accessible i.e. all access modes are lost.
• If the new lookup class, the old lookup class and the previous lookup class are all in different modules i.e. teleporting to a third module, all access modes are lost.

The new previous lookup class is chosen as follows:

• If the new lookup object has UNCONDITIONAL bit, the new previous lookup class is null.
• If the new lookup class is in the same module as the old lookup class, the new previous lookup class is the old previous lookup class.
• If the new lookup class is in a different module from the old lookup class, the new previous lookup class is the old lookup class.

The resulting lookup's capabilities for loading classes (used during findClass(java.lang.String) invocations) are determined by the lookup class' loader, which may change due to this operation.

If this lookup is a public lookup, this lookup has UNCONDITIONAL mode set and it has no other mode set. When dropping UNCONDITIONAL on a public lookup then the resulting lookup has no access.

If this lookup is not a public lookup, then the following applies regardless of its lookup modes. PROTECTED and ORIGINAL are always dropped and so the resulting lookup mode will never have these access capabilities. When dropping PACKAGE then the resulting lookup will not have PACKAGE or PRIVATE access. When dropping MODULE then the resulting lookup will not have MODULE, PACKAGE, or PRIVATE access. When dropping PUBLIC then the resulting lookup has no access.

The lookup modes for this lookup must include PACKAGE access as default (package) members will be accessible to the class. The PACKAGE lookup mode serves to authenticate that the lookup object was created by a caller in the runtime package (or derived from a lookup originally created by suitably privileged code to a target class in the runtime package).

The bytes parameter is the class bytes of a valid class file (as defined by the The Java Virtual Machine Specification) with a class name in the same package as the lookup class.

This method does not run the class initializer. The class initializer may run at a later time, as detailed in section 12.4 of the The Java Language Specification.

If there is a security manager and this lookup does not have full privilege access, its checkPermission method is first called to check RuntimePermission("defineClass").

Ordinarily, a class or interface C is created by a class loader, which either defines C directly or delegates to another class loader. A class loader defines C directly by invoking ClassLoader::defineClass, which causes the Java Virtual Machine to derive C from a purported representation in class file format. In situations where use of a class loader is undesirable, a class or interface C can be created by this method instead. This method is capable of defining C, and thereby creating it, without invoking ClassLoader::defineClass. Instead, this method defines C as if by arranging for the Java Virtual Machine to derive a nonarray class or interface C from a purported representation in class file format using the following rules:

1. The lookup modes for this Lookup must include full privilege access. This level of access is needed to create C in the module of the lookup class of this Lookup.
2. The purported representation in bytes must be a ClassFile structure (JVMS 4.1) of a supported major and minor version. The major and minor version may differ from the class file version of the lookup class of this Lookup.
3. The value of this_class must be a valid index in the constant_pool table, and the entry at that index must be a valid CONSTANT_Class_info structure. Let N be the binary name encoded in internal form that is specified by this structure. N must denote a class or interface in the same package as the lookup class.
4. Let CN be the string N + "." + <suffix>, where <suffix> is an unqualified name.

   Let newBytes be the ClassFile structure given by bytes with an additional entry in the constant_pool table, indicating a CONSTANT_Utf8_info structure for CN, and where the CONSTANT_Class_info structure indicated by this_class refers to the new CONSTANT_Utf8_info structure.

   Let L be the defining class loader of the lookup class of this Lookup.

   C is derived with name CN, class loader L, and purported representation newBytes as if by the rules of JVMS 5.3.5, with the following adjustments:

   • The constant indicated by this_class is permitted to specify a name that includes a single "." character, even though this is not a valid binary class or interface name in internal form.
   • The Java Virtual Machine marks L as the defining class loader of C, but no class loader is recorded as an initiating class loader of C.
   • C is considered to have the same runtime package, module and protection domain as the lookup class of this Lookup.
   • Let GN be the binary name obtained by taking N (a binary name encoded in internal form) and replacing ASCII forward slashes with ASCII periods. For the instance of Class representing C:
     • Class.getName() returns the string GN + "/" + <suffix>, even though this is not a valid binary class or interface name.
     • Class.descriptorString() returns the string "L" + N + "." + <suffix> + ";", even though this is not a valid type descriptor name.
     • Class.describeConstable() returns an empty optional as C cannot be described in nominal form.

After C is derived, it is linked by the Java Virtual Machine. Linkage occurs as specified in JVMS 5.4.3, with the following adjustments:

• During verification, whenever it is necessary to load the class named CN, the attempt succeeds, producing class C. No request is made of any class loader.
• On any attempt to resolve the entry in the run-time constant pool indicated by this_class, the symbolic reference is considered to be resolved to C and resolution always succeeds immediately.

If the initialize parameter is true, then C is initialized by the Java Virtual Machine.

The newly created class or interface C serves as the lookup class of the Lookup object returned by this method. C is hidden in the sense that no other class or interface can refer to C via a constant pool entry. That is, a hidden class or interface cannot be named as a supertype, a field type, a method parameter type, or a method return type by any other class. This is because a hidden class or interface does not have a binary name, so there is no internal form available to record in any class's constant pool. A hidden class or interface is not discoverable by Class.forName(String, boolean, ClassLoader), ClassLoader.loadClass(String, boolean), or findClass(String), and is not modifiable by Java agents or tool agents using the JVM Tool Interface.

A class or interface created by a class loader has a strong relationship with that class loader. That is, every Class object contains a reference to the ClassLoader that defined it. This means that a class created by a class loader may be unloaded if and only if its defining loader is not reachable and thus may be reclaimed by a garbage collector (JLS 12.7). By default, however, a hidden class or interface may be unloaded even if the class loader that is marked as its defining loader is reachable. This behavior is useful when a hidden class or interface serves multiple classes defined by arbitrary class loaders. In other cases, a hidden class or interface may be linked to a single class (or a small number of classes) with the same defining loader as the hidden class or interface. In such cases, where the hidden class or interface must be coterminous with a normal class or interface, the STRONG option may be passed in options. This arranges for a hidden class to have the same strong relationship with the class loader marked as its defining loader, as a normal class or interface has with its own defining loader. If STRONG is not used, then the invoker of defineHiddenClass may still prevent a hidden class or interface from being unloaded by ensuring that the Class object is reachable.

The unloading characteristics are set for each hidden class when it is defined, and cannot be changed later. An advantage of allowing hidden classes to be unloaded independently of the class loader marked as their defining loader is that a very large number of hidden classes may be created by an application. In contrast, if STRONG is used, then the JVM may run out of memory, just as if normal classes were created by class loaders.

Classes and interfaces in a nest are allowed to have mutual access to their private members. The nest relationship is determined by the NestHost attribute (JVMS 4.7.28) and the NestMembers attribute (JVMS 4.7.29) in a class file. By default, a hidden class belongs to a nest consisting only of itself because a hidden class has no binary name. The NESTMATE option can be passed in options to create a hidden class or interface C as a member of a nest. The nest to which C belongs is not based on any NestHost attribute in the ClassFile structure from which C was derived. Instead, the following rules determine the nest host of C:

• If the nest host of the lookup class of this Lookup has previously been determined, then let H be the nest host of the lookup class. Otherwise, the nest host of the lookup class is determined using the algorithm in JVMS 5.4.4, yielding H.
• The nest host of C is determined to be H, the nest host of the lookup class.

A hidden class or interface may be serializable, but this requires a custom serialization mechanism in order to ensure that instances are properly serialized and deserialized. The default serialization mechanism supports only classes and interfaces that are discoverable by their class name.

This method is equivalent to calling defineHiddenClass(bytes, initialize, options) as if the hidden class is injected with a private static final unnamed field which is initialized with the given classData at the first instruction of the class initializer. The newly created class is linked by the Java Virtual Machine.

The MethodHandles::classData and MethodHandles::classDataAt methods can be used to retrieve the classData.

• If no access is allowed, the suffix is "/noaccess".
• If only unconditional access is allowed, the suffix is "/publicLookup".
• If only public access to types in exported packages is allowed, the suffix is "/public".
• If only public and module access are allowed, the suffix is "/module".
• If public and package access are allowed, the suffix is "/package".
• If public, package, and private access are allowed, the suffix is "/private".

(It may seem strange that protected access should be stronger than private access. Viewed independently from package access, protected access is the first to be lost, because it requires a direct subclass relationship between caller and callee.)

The returned method handle will have variable arity if and only if the method's variable arity modifier bit (0x0080) is set.

If the returned method handle is invoked, the method's class will be initialized, if it has not already been initialized.

Example:

Copy

import static java.lang.invoke.MethodHandles.*;
import static java.lang.invoke.MethodType.*;
...
MethodHandle MH_asList = publicLookup().findStatic(Arrays.class,
  "asList", methodType(List.class, Object[].class));
assertEquals("[x, y]", MH_asList.invoke("x", "y").toString());

When called, the handle will treat the first argument as a receiver and, for non-private methods, dispatch on the receiver's type to determine which method implementation to enter. For private methods the named method in refc will be invoked on the receiver. (The dispatching action is identical with that performed by an invokevirtual or invokeinterface instruction.)

The first argument will be of type refc if the lookup class has full privileges to access the member. Otherwise the member must be protected and the first argument will be restricted in type to the lookup class.

The returned method handle will have variable arity if and only if the method's variable arity modifier bit (0x0080) is set.

Because of the general equivalence between invokevirtual instructions and method handles produced by findVirtual, if the class is MethodHandle and the name string is invokeExact or invoke, the resulting method handle is equivalent to one produced by MethodHandles.exactInvoker or MethodHandles.invoker with the same type argument.

If the class is VarHandle and the name string corresponds to the name of a signature-polymorphic access mode method, the resulting method handle is equivalent to one produced by MethodHandles.varHandleInvoker(java.lang.invoke.VarHandle.AccessMode, java.lang.invoke.MethodType) with the access mode corresponding to the name string and with the same type arguments.

Example:

Copy

import static java.lang.invoke.MethodHandles.*;
import static java.lang.invoke.MethodType.*;
...
MethodHandle MH_concat = publicLookup().findVirtual(String.class,
  "concat", methodType(String.class, String.class));
MethodHandle MH_hashCode = publicLookup().findVirtual(Object.class,
  "hashCode", methodType(int.class));
MethodHandle MH_hashCode_String = publicLookup().findVirtual(String.class,
  "hashCode", methodType(int.class));
assertEquals("xy", (String) MH_concat.invokeExact("x", "y"));
assertEquals("xy".hashCode(), (int) MH_hashCode.invokeExact((Object)"xy"));
assertEquals("xy".hashCode(), (int) MH_hashCode_String.invokeExact("xy"));
// interface method:
MethodHandle MH_subSequence = publicLookup().findVirtual(CharSequence.class,
  "subSequence", methodType(CharSequence.class, int.class, int.class));
assertEquals("def", MH_subSequence.invoke("abcdefghi", 3, 6).toString());
// constructor "internal method" must be accessed differently:
MethodType MT_newString = methodType(void.class); //()V for new String()
try { assertEquals("impossible", lookup()
        .findVirtual(String.class, "<init>", MT_newString));
 } catch (NoSuchMethodException ex) { } // OK
MethodHandle MH_newString = publicLookup()
  .findConstructor(String.class, MT_newString);
assertEquals("", (String) MH_newString.invokeExact());

The requested type must have a return type of void. (This is consistent with the JVM's treatment of constructor type descriptors.)

The returned method handle will have variable arity if and only if the constructor's variable arity modifier bit (0x0080) is set.

If the returned method handle is invoked, the constructor's class will be initialized, if it has not already been initialized.

Example:

Copy

import static java.lang.invoke.MethodHandles.*;
import static java.lang.invoke.MethodType.*;
...
MethodHandle MH_newArrayList = publicLookup().findConstructor(
  ArrayList.class, methodType(void.class, Collection.class));
Collection orig = Arrays.asList("x", "y");
Collection copy = (ArrayList) MH_newArrayList.invokeExact(orig);
assert(orig != copy);
assertEquals(orig, copy);
// a variable-arity constructor:
MethodHandle MH_newProcessBuilder = publicLookup().findConstructor(
  ProcessBuilder.class, methodType(void.class, String[].class));
ProcessBuilder pb = (ProcessBuilder)
  MH_newProcessBuilder.invoke("x", "y", "z");
assertEquals("[x, y, z]", pb.command().toString());

For a class or an interface, the name is the binary name. For an array class of n dimensions, the name begins with n occurrences of '[' and followed by the element type as encoded in the table specified in Class.getName().

The lookup context here is determined by the lookup class, its class loader, and the lookup modes.

This method returns when targetClass is fully initialized, or when targetClass is being initialized by the current thread.

If targetClass is in the same module as the lookup class, the lookup class is LC in module M1 and the previous lookup class is in module M0 or null if not present, targetClass is accessible if and only if one of the following is true:

• If this lookup has PRIVATE access, targetClass is LC or other class in the same nest of LC.
• If this lookup has PACKAGE access, targetClass is in the same runtime package of LC.
• If this lookup has MODULE access, targetClass is a public type in M1.
• If this lookup has PUBLIC access, targetClass is a public type in a package exported by M1 to at least M0 if the previous lookup class is present; otherwise, targetClass is a public type in a package exported by M1 unconditionally.

Otherwise, if this lookup has UNCONDITIONAL access, this lookup can access public types in all modules when the type is in a package that is exported unconditionally.

Otherwise, targetClass is in a different module from lookupClass, and if this lookup does not have PUBLIC access, lookupClass is inaccessible.

Otherwise, if this lookup has no previous lookup class, M1 is the module containing lookupClass and M2 is the module containing targetClass, then targetClass is accessible if and only if

• M1 reads M2, and
• targetClass is public and in a package exported by M2 at least to M1.

Otherwise, if this lookup has a previous lookup class, M1 and M2 are as before, and M0 is the module containing the previous lookup class, then targetClass is accessible if and only if one of the following is true:

• targetClass is in M0 and M1 reads M0 and the type is in a package that is exported to at least M1.
• targetClass is in M1 and M0 reads M1 and the type is in a package that is exported to at least M0.
• targetClass is in a third module M2 and both M0 and M1 reads M2 and the type is in a package that is exported to at least both M0 and M2.

Otherwise, targetClass is not accessible.

Before method resolution, if the explicitly specified caller class is not identical with the lookup class, or if this lookup object does not have private access privileges, the access fails.

The returned method handle will have variable arity if and only if the method's variable arity modifier bit (0x0080) is set.

(Note: JVM internal methods named "<init>" are not visible to this API, even though the invokespecial instruction can refer to them in special circumstances. Use findConstructor to access instance initialization methods in a safe manner.)

Example:

Copy

import static java.lang.invoke.MethodHandles.*;
import static java.lang.invoke.MethodType.*;
...
static class Listie extends ArrayList {
  public String toString() { return "[wee Listie]"; }
  static Lookup lookup() { return MethodHandles.lookup(); }
}
...
// no access to constructor via invokeSpecial:
MethodHandle MH_newListie = Listie.lookup()
  .findConstructor(Listie.class, methodType(void.class));
Listie l = (Listie) MH_newListie.invokeExact();
try { assertEquals("impossible", Listie.lookup().findSpecial(
        Listie.class, "<init>", methodType(void.class), Listie.class));
 } catch (NoSuchMethodException ex) { } // OK
// access to super and self methods via invokeSpecial:
MethodHandle MH_super = Listie.lookup().findSpecial(
  ArrayList.class, "toString" , methodType(String.class), Listie.class);
MethodHandle MH_this = Listie.lookup().findSpecial(
  Listie.class, "toString" , methodType(String.class), Listie.class);
MethodHandle MH_duper = Listie.lookup().findSpecial(
  Object.class, "toString" , methodType(String.class), Listie.class);
assertEquals("[]", (String) MH_super.invokeExact(l));
assertEquals(""+l, (String) MH_this.invokeExact(l));
assertEquals("[]", (String) MH_duper.invokeExact(l)); // ArrayList method
try { assertEquals("inaccessible", Listie.lookup().findSpecial(
        String.class, "toString", methodType(String.class), Listie.class));
 } catch (IllegalAccessException ex) { } // OK
Listie subl = new Listie() { public String toString() { return "[subclass]"; } };
assertEquals(""+l, (String) MH_this.invokeExact(subl)); // Listie method

Access checking is performed immediately on behalf of the lookup class.

Certain access modes of the returned VarHandle are unsupported under the following conditions:

• if the field is declared final, then the write, atomic update, numeric atomic update, and bitwise atomic update access modes are unsupported.
• if the field type is anything other than byte, short, char, int, long, float, or double then numeric atomic update access modes are unsupported.
• if the field type is anything other than boolean, byte, short, char, int or long then bitwise atomic update access modes are unsupported.

If the field is declared volatile then the returned VarHandle will override access to the field (effectively ignore the volatile declaration) in accordance to its specified access modes.

If the field type is float or double then numeric and atomic update access modes compare values using their bitwise representation (see Float.floatToRawIntBits(float) and Double.doubleToRawLongBits(double), respectively).

If the returned method handle is invoked, the field's class will be initialized, if it has not already been initialized.

If the returned method handle is invoked, the field's class will be initialized, if it has not already been initialized.

Access checking is performed immediately on behalf of the lookup class.

If the returned VarHandle is operated on, the declaring class will be initialized, if it has not already been initialized.

Certain access modes of the returned VarHandle are unsupported under the following conditions:

• if the field is declared final, then the write, atomic update, numeric atomic update, and bitwise atomic update access modes are unsupported.
• if the field type is anything other than byte, short, char, int, long, float, or double, then numeric atomic update access modes are unsupported.
• if the field type is anything other than boolean, byte, short, char, int or long then bitwise atomic update access modes are unsupported.

If the field is declared volatile then the returned VarHandle will override access to the field (effectively ignore the volatile declaration) in accordance to its specified access modes.

If the field type is float or double then numeric and atomic update access modes compare values using their bitwise representation (see Float.floatToRawIntBits(float) and Double.doubleToRawLongBits(double), respectively).

The returned method handle will have variable arity if and only if the method's variable arity modifier bit (0x0080) is set and the trailing array argument is not the only argument. (If the trailing array argument is the only argument, the given receiver value will be bound to it.)

This is almost equivalent to the following code, with some differences noted below:

Copy

import static java.lang.invoke.MethodHandles.*;
import static java.lang.invoke.MethodType.*;
...
MethodHandle mh0 = lookup().findVirtual(defc, name, type);
MethodHandle mh1 = mh0.bindTo(receiver);
mh1 = mh1.withVarargs(mh0.isVarargsCollector());
return mh1;

The returned method handle will have variable arity if and only if the method's variable arity modifier bit (0x0080) is set.

If m is static, and if the returned method handle is invoked, the method's class will be initialized, if it has not already been initialized.

Before method resolution, if the explicitly specified caller class is not identical with the lookup class, or if this lookup object does not have private access privileges, the access fails.

The returned method handle will have variable arity if and only if the method's variable arity modifier bit (0x0080) is set.

If the constructor's accessible flag is not set, access checking is performed immediately on behalf of the lookup class.

The returned method handle will have variable arity if and only if the constructor's variable arity modifier bit (0x0080) is set.

If the returned method handle is invoked, the constructor's class will be initialized, if it has not already been initialized.

If the field is static, and if the returned method handle is invoked, the field's class will be initialized, if it has not already been initialized.

If the field is final, write access will not be allowed and access checking will fail, except under certain narrow circumstances documented for Field.set. A method handle is returned only if a corresponding call to the Field object's set method could return normally. In particular, fields which are both static and final may never be set.

If the field is static, and if the returned method handle is invoked, the field's class will be initialized, if it has not already been initialized.

Access checking is performed immediately on behalf of the lookup class, regardless of the value of the field's accessible flag.

If the field is static, and if the returned VarHandle is operated on, the field's declaring class will be initialized, if it has not already been initialized.

Certain access modes of the returned VarHandle are unsupported under the following conditions:

• if the field is declared final, then the write, atomic update, numeric atomic update, and bitwise atomic update access modes are unsupported.
• if the field type is anything other than byte, short, char, int, long, float, or double then numeric atomic update access modes are unsupported.
• if the field type is anything other than boolean, byte, short, char, int or long then bitwise atomic update access modes are unsupported.

If the field is declared volatile then the returned VarHandle will override access to the field (effectively ignore the volatile declaration) in accordance to its specified access modes.

If the field type is float or double then numeric and atomic update access modes compare values using their bitwise representation (see Float.floatToRawIntBits(float) and Double.doubleToRawLongBits(double), respectively).