< prev index next >

src/java.base/share/classes/java/lang/invoke/MethodHandles.java

Print this page




1191          * @see #findVarHandle(Class, String, Class)
1192          */
1193         public MethodHandle findSetter(Class<?> refc, String name, Class<?> type) throws NoSuchFieldException, IllegalAccessException {
1194             MemberName field = resolveOrFail(REF_putField, refc, name, type);
1195             return getDirectField(REF_putField, refc, field);
1196         }
1197 
1198         /**
1199          * Produces a VarHandle giving access to non-static fields of type
1200          * {@code T} declared by a receiver class of type {@code R}, supporting
1201          * shape {@code (R : T)}.
1202          * <p>
1203          * Access checking is performed immediately on behalf of the lookup
1204          * class.
1205          * <p>
1206          * Certain access modes of the returned VarHandle are unsupported under
1207          * the following conditions:
1208          * <ul>
1209          * <li>if the field is declared {@code final}, then the write, atomic
1210          *     update, and numeric atomic update access modes are unsupported.
1211          * <li>if the field type is anything other than {@code int},
1212          *     {@code long} or a reference type, then atomic update access modes

1213          *     are unsupported.  (Future major platform releases of the JDK may
1214          *     support additional types for certain currently unsupported access
1215          *     modes.)
1216          * <li>if the field type is anything other than {@code int} or
1217          *     {@code long}, then numeric atomic update access modes are
1218          *     unsupported.  (Future major platform releases of the JDK may
1219          *     support additional numeric types for certain currently
1220          *     unsupported access modes.)
1221          * </ul>
1222          * <p>
1223          * If the field is declared {@code volatile} then the returned VarHandle
1224          * will override access to the field (effectively ignore the
1225          * {@code volatile} declaration) in accordance to it's specified
1226          * access modes.
1227          * @param recv the receiver class, of type {@code R}, that declares the
1228          * non-static field
1229          * @param name the field's name
1230          * @param type the field's type, of type {@code T}
1231          * @return a VarHandle giving access to non-static fields.
1232          * @throws NoSuchFieldException if the field does not exist
1233          * @throws IllegalAccessException if access checking fails, or if the field is {@code static}
1234          * @exception SecurityException if a security manager is present and it
1235          *                              <a href="MethodHandles.Lookup.html#secmgr">refuses access</a>
1236          * @throws NullPointerException if any argument is null
1237          * @since 9
1238          */
1239         public VarHandle findVarHandle(Class<?> recv, String name, Class<?> type) throws NoSuchFieldException, IllegalAccessException {
1240             MemberName getField = resolveOrFail(REF_getField, recv, name, type);


1289             MemberName field = resolveOrFail(REF_putStatic, refc, name, type);
1290             return getDirectField(REF_putStatic, refc, field);
1291         }
1292 
1293         /**
1294          * Produces a VarHandle giving access to a static field of type
1295          * {@code T} declared by a given declaring class, supporting shape
1296          * {@code ((empty) : T)}.
1297          * <p>
1298          * Access checking is performed immediately on behalf of the lookup
1299          * class.
1300          * <p>
1301          * If the returned VarHandle is operated on, the declaring class will be
1302          * initialized, if it has not already been initialized.
1303          * <p>
1304          * Certain access modes of the returned VarHandle are unsupported under
1305          * the following conditions:
1306          * <ul>
1307          * <li>if the field is declared {@code final}, then the write, atomic
1308          *     update, and numeric atomic update access modes are unsupported.
1309          * <li>if the field type is anything other than {@code int},

1310          *     {@code long} or a reference type, then atomic update access modes
1311          *     are unsupported.  (Future major platform releases of the JDK may
1312          *     support additional types for certain currently unsupported access
1313          *     modes.)
1314          * <li>if the field type is anything other than {@code int} or
1315          *     {@code long}, then numeric atomic update access modes are
1316          *     unsupported.  (Future major platform releases of the JDK may
1317          *     support additional numeric types for certain currently
1318          *     unsupported access modes.)
1319          * </ul>
1320          * <p>
1321          * If the field is declared {@code volatile} then the returned VarHandle
1322          * will override access to the field (effectively ignore the
1323          * {@code volatile} declaration) in accordance to it's specified
1324          * access modes.
1325          * @param decl the class that declares the static field
1326          * @param name the field's name
1327          * @param type the field's type, of type {@code T}
1328          * @return a VarHandle giving access to a static field
1329          * @throws NoSuchFieldException if the field does not exist
1330          * @throws IllegalAccessException if access checking fails, or if the field is not {@code static}
1331          * @exception SecurityException if a security manager is present and it
1332          *                              <a href="MethodHandles.Lookup.html#secmgr">refuses access</a>
1333          * @throws NullPointerException if any argument is null
1334          * @since 9
1335          */
1336         public VarHandle findStaticVarHandle(Class<?> decl, String name, Class<?> type) throws NoSuchFieldException, IllegalAccessException {
1337             MemberName getField = resolveOrFail(REF_getStatic, decl, name, type);
1338             MemberName putField = resolveOrFail(REF_putStatic, decl, name, type);


1573         /**
1574          * Produces a VarHandle that accesses fields of type {@code T} declared
1575          * by a class of type {@code R}, as described by the given reflected
1576          * field.
1577          * If the field is non-static the VarHandle supports a shape of
1578          * {@code (R : T)}, otherwise supports a shape of {@code ((empty) : T)}.
1579          * <p>
1580          * Access checking is performed immediately on behalf of the lookup
1581          * class, regardless of the value of the field's {@code accessible}
1582          * flag.
1583          * <p>
1584          * If the field is static, and if the returned VarHandle is operated
1585          * on, the field's declaring class will be initialized, if it has not
1586          * already been initialized.
1587          * <p>
1588          * Certain access modes of the returned VarHandle are unsupported under
1589          * the following conditions:
1590          * <ul>
1591          * <li>if the field is declared {@code final}, then the write, atomic
1592          *     update, and numeric atomic update access modes are unsupported.
1593          * <li>if the field type is anything other than {@code int},
1594          *     {@code long} or a reference type, then atomic update access modes

1595          *     are unsupported.  (Future major platform releases of the JDK may
1596          *     support additional types for certain currently unsupported access
1597          *     modes.)
1598          * <li>if the field type is anything other than {@code int} or
1599          *     {@code long}, then numeric atomic update access modes are
1600          *     unsupported.  (Future major platform releases of the JDK may
1601          *     support additional numeric types for certain currently
1602          *     unsupported access modes.)
1603          * </ul>
1604          * <p>
1605          * If the field is declared {@code volatile} then the returned VarHandle
1606          * will override access to the field (effectively ignore the
1607          * {@code volatile} declaration) in accordance to it's specified
1608          * access modes.
1609          * @param f the reflected field, with a field of type {@code T}, and
1610          * a declaring class of type {@code R}
1611          * @return a VarHandle giving access to non-static fields or a static
1612          * field
1613          * @throws IllegalAccessException if access checking fails
1614          * @throws NullPointerException if the argument is null
1615          * @since 9
1616          */
1617         public VarHandle unreflectVarHandle(Field f) throws IllegalAccessException {
1618             MemberName getField = new MemberName(f, false);
1619             MemberName putField = new MemberName(f, true);
1620             return getFieldVarHandleNoSecurityManager(getField.getReferenceKind(), putField.getReferenceKind(),
1621                                                       f.getDeclaringClass(), getField, putField);
1622         }


2265      * Its last argument will be the array's element type.
2266      * The first and second arguments will be the array type and int.
2267      * @param arrayClass the class of an array
2268      * @return a method handle which can store values into the array type
2269      * @throws NullPointerException if the argument is null
2270      * @throws IllegalArgumentException if arrayClass is not an array type
2271      */
2272     public static
2273     MethodHandle arrayElementSetter(Class<?> arrayClass) throws IllegalArgumentException {
2274         return MethodHandleImpl.makeArrayElementAccessor(arrayClass, true);
2275     }
2276 
2277     /**
2278      *
2279      * Produces a VarHandle giving access to elements of an array type
2280      * {@code T[]}, supporting shape {@code (T[], int : T)}.
2281      * <p>
2282      * Certain access modes of the returned VarHandle are unsupported under
2283      * the following conditions:
2284      * <ul>
2285      * <li>if the component type is anything other than {@code int},
2286      *     {@code long} or a reference type, then atomic update access modes

2287      *     are unsupported.  (Future major platform releases of the JDK may
2288      *     support additional types for certain currently unsupported access
2289      *     modes.)
2290      * <li>if the component type is anything other than {@code int} or
2291      *     {@code long}, then numeric atomic update access modes are
2292      *     unsupported.  (Future major platform releases of the JDK may
2293      *     support additional numeric types for certain currently
2294      *     unsupported access modes.)
2295      * </ul>
2296      * @param arrayClass the class of an array, of type {@code T[]}
2297      * @return a VarHandle giving access to elements of an array
2298      * @throws NullPointerException if the arrayClass is null
2299      * @throws IllegalArgumentException if arrayClass is not an array type
2300      * @since 9
2301      */
2302     public static
2303     VarHandle arrayElementVarHandle(Class<?> arrayClass) throws IllegalArgumentException {
2304         return VarHandles.makeArrayElementHandle(arrayClass);
2305     }
2306 
2307     /**
2308      * Produces a VarHandle giving access to elements of a {@code byte[]} array
2309      * viewed as if it were a different primitive array type, such as
2310      * {@code int[]} or {@code long[]}.  The shape of the resulting VarHandle is
2311      * {@code (byte[], int : T)}, where the {@code int} coordinate type
2312      * corresponds to an argument that is an index in a {@code byte[]} array,
2313      * and {@code T} is the component type of the given view array class.  The
2314      * returned VarHandle accesses bytes at an index in a {@code byte[]} array,




1191          * @see #findVarHandle(Class, String, Class)
1192          */
1193         public MethodHandle findSetter(Class<?> refc, String name, Class<?> type) throws NoSuchFieldException, IllegalAccessException {
1194             MemberName field = resolveOrFail(REF_putField, refc, name, type);
1195             return getDirectField(REF_putField, refc, field);
1196         }
1197 
1198         /**
1199          * Produces a VarHandle giving access to non-static fields of type
1200          * {@code T} declared by a receiver class of type {@code R}, supporting
1201          * shape {@code (R : T)}.
1202          * <p>
1203          * Access checking is performed immediately on behalf of the lookup
1204          * class.
1205          * <p>
1206          * Certain access modes of the returned VarHandle are unsupported under
1207          * the following conditions:
1208          * <ul>
1209          * <li>if the field is declared {@code final}, then the write, atomic
1210          *     update, and numeric atomic update access modes are unsupported.
1211          * <li>if the field type is anything other than {@code boolean},
1212          *     {@code byte}, {@code short}, {@code char}, {@code int} or
1213          *     a reference type, then atomic update access modes
1214          *     are unsupported.  (Future major platform releases of the JDK may
1215          *     support additional types for certain currently unsupported access
1216          *     modes.)
1217          * <li>if the field type is anything other than {@code byte},
1218          *     {@code short}, {@code char}, {@code int} or {@code long}, then
1219          *     numeric atomic update access modes are unsupported.


1220          * </ul>
1221          * <p>
1222          * If the field is declared {@code volatile} then the returned VarHandle
1223          * will override access to the field (effectively ignore the
1224          * {@code volatile} declaration) in accordance to it's specified
1225          * access modes.
1226          * @param recv the receiver class, of type {@code R}, that declares the
1227          * non-static field
1228          * @param name the field's name
1229          * @param type the field's type, of type {@code T}
1230          * @return a VarHandle giving access to non-static fields.
1231          * @throws NoSuchFieldException if the field does not exist
1232          * @throws IllegalAccessException if access checking fails, or if the field is {@code static}
1233          * @exception SecurityException if a security manager is present and it
1234          *                              <a href="MethodHandles.Lookup.html#secmgr">refuses access</a>
1235          * @throws NullPointerException if any argument is null
1236          * @since 9
1237          */
1238         public VarHandle findVarHandle(Class<?> recv, String name, Class<?> type) throws NoSuchFieldException, IllegalAccessException {
1239             MemberName getField = resolveOrFail(REF_getField, recv, name, type);


1288             MemberName field = resolveOrFail(REF_putStatic, refc, name, type);
1289             return getDirectField(REF_putStatic, refc, field);
1290         }
1291 
1292         /**
1293          * Produces a VarHandle giving access to a static field of type
1294          * {@code T} declared by a given declaring class, supporting shape
1295          * {@code ((empty) : T)}.
1296          * <p>
1297          * Access checking is performed immediately on behalf of the lookup
1298          * class.
1299          * <p>
1300          * If the returned VarHandle is operated on, the declaring class will be
1301          * initialized, if it has not already been initialized.
1302          * <p>
1303          * Certain access modes of the returned VarHandle are unsupported under
1304          * the following conditions:
1305          * <ul>
1306          * <li>if the field is declared {@code final}, then the write, atomic
1307          *     update, and numeric atomic update access modes are unsupported.
1308          * <li>if the field type is anything other than {@code boolean},
1309          *     {@code byte}, {@code short}, {@code char}, {@code int},
1310          *     {@code long} or a reference type, then atomic update access modes
1311          *     are unsupported.  (Future major platform releases of the JDK may
1312          *     support additional types for certain currently unsupported access
1313          *     modes.)
1314          * <li>if the field type is anything other than {@code byte},
1315          *     {@code short}, {@code char}, {@code int} or {@code long}, then
1316          *     numeric atomic update access modes are unsupported.


1317          * </ul>
1318          * <p>
1319          * If the field is declared {@code volatile} then the returned VarHandle
1320          * will override access to the field (effectively ignore the
1321          * {@code volatile} declaration) in accordance to it's specified
1322          * access modes.
1323          * @param decl the class that declares the static field
1324          * @param name the field's name
1325          * @param type the field's type, of type {@code T}
1326          * @return a VarHandle giving access to a static field
1327          * @throws NoSuchFieldException if the field does not exist
1328          * @throws IllegalAccessException if access checking fails, or if the field is not {@code static}
1329          * @exception SecurityException if a security manager is present and it
1330          *                              <a href="MethodHandles.Lookup.html#secmgr">refuses access</a>
1331          * @throws NullPointerException if any argument is null
1332          * @since 9
1333          */
1334         public VarHandle findStaticVarHandle(Class<?> decl, String name, Class<?> type) throws NoSuchFieldException, IllegalAccessException {
1335             MemberName getField = resolveOrFail(REF_getStatic, decl, name, type);
1336             MemberName putField = resolveOrFail(REF_putStatic, decl, name, type);


1571         /**
1572          * Produces a VarHandle that accesses fields of type {@code T} declared
1573          * by a class of type {@code R}, as described by the given reflected
1574          * field.
1575          * If the field is non-static the VarHandle supports a shape of
1576          * {@code (R : T)}, otherwise supports a shape of {@code ((empty) : T)}.
1577          * <p>
1578          * Access checking is performed immediately on behalf of the lookup
1579          * class, regardless of the value of the field's {@code accessible}
1580          * flag.
1581          * <p>
1582          * If the field is static, and if the returned VarHandle is operated
1583          * on, the field's declaring class will be initialized, if it has not
1584          * already been initialized.
1585          * <p>
1586          * Certain access modes of the returned VarHandle are unsupported under
1587          * the following conditions:
1588          * <ul>
1589          * <li>if the field is declared {@code final}, then the write, atomic
1590          *     update, and numeric atomic update access modes are unsupported.
1591          * <li>if the field type is anything other than {@code boolean},
1592          *     {@code byte}, {@code short}, {@code char}, {@code int}, or
1593          *     a reference type, then atomic update access modes
1594          *     are unsupported.  (Future major platform releases of the JDK may
1595          *     support additional types for certain currently unsupported access
1596          *     modes.)
1597          * <li>if the field type is anything other than {@code byte},
1598          *     {@code short}, {@code char}, {@code int} or {@code long}, then
1599          *     numeric atomic update access modes are unsupported.


1600          * </ul>
1601          * <p>
1602          * If the field is declared {@code volatile} then the returned VarHandle
1603          * will override access to the field (effectively ignore the
1604          * {@code volatile} declaration) in accordance to it's specified
1605          * access modes.
1606          * @param f the reflected field, with a field of type {@code T}, and
1607          * a declaring class of type {@code R}
1608          * @return a VarHandle giving access to non-static fields or a static
1609          * field
1610          * @throws IllegalAccessException if access checking fails
1611          * @throws NullPointerException if the argument is null
1612          * @since 9
1613          */
1614         public VarHandle unreflectVarHandle(Field f) throws IllegalAccessException {
1615             MemberName getField = new MemberName(f, false);
1616             MemberName putField = new MemberName(f, true);
1617             return getFieldVarHandleNoSecurityManager(getField.getReferenceKind(), putField.getReferenceKind(),
1618                                                       f.getDeclaringClass(), getField, putField);
1619         }


2262      * Its last argument will be the array's element type.
2263      * The first and second arguments will be the array type and int.
2264      * @param arrayClass the class of an array
2265      * @return a method handle which can store values into the array type
2266      * @throws NullPointerException if the argument is null
2267      * @throws IllegalArgumentException if arrayClass is not an array type
2268      */
2269     public static
2270     MethodHandle arrayElementSetter(Class<?> arrayClass) throws IllegalArgumentException {
2271         return MethodHandleImpl.makeArrayElementAccessor(arrayClass, true);
2272     }
2273 
2274     /**
2275      *
2276      * Produces a VarHandle giving access to elements of an array type
2277      * {@code T[]}, supporting shape {@code (T[], int : T)}.
2278      * <p>
2279      * Certain access modes of the returned VarHandle are unsupported under
2280      * the following conditions:
2281      * <ul>
2282       * <li>if the field type is anything other than {@code boolean},
2283      *     {@code byte}, {@code short}, {@code char}, {@code int} or
2284      *     a reference type, then atomic update access modes
2285      *     are unsupported.  (Future major platform releases of the JDK may
2286      *     support additional types for certain currently unsupported access
2287      *     modes.)
2288      * <li>if the component type is anything other than {@code byte},
2289      *     {@code short}, {@code char}, {@code int} or {@code long}, then
2290      *     numeric atomic update access modes are unsupported.


2291      * </ul>
2292      * @param arrayClass the class of an array, of type {@code T[]}
2293      * @return a VarHandle giving access to elements of an array
2294      * @throws NullPointerException if the arrayClass is null
2295      * @throws IllegalArgumentException if arrayClass is not an array type
2296      * @since 9
2297      */
2298     public static
2299     VarHandle arrayElementVarHandle(Class<?> arrayClass) throws IllegalArgumentException {
2300         return VarHandles.makeArrayElementHandle(arrayClass);
2301     }
2302 
2303     /**
2304      * Produces a VarHandle giving access to elements of a {@code byte[]} array
2305      * viewed as if it were a different primitive array type, such as
2306      * {@code int[]} or {@code long[]}.  The shape of the resulting VarHandle is
2307      * {@code (byte[], int : T)}, where the {@code int} coordinate type
2308      * corresponds to an argument that is an index in a {@code byte[]} array,
2309      * and {@code T} is the component type of the given view array class.  The
2310      * returned VarHandle accesses bytes at an index in a {@code byte[]} array,


< prev index next >