1 /*
2 * Copyright (c) 2024, 2025, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package jdk.incubator.code.dialect.java;
27
28 import jdk.incubator.code.dialect.java.impl.FieldRefImpl;
29 import java.lang.invoke.MethodHandles;
30 import java.lang.invoke.MethodHandles.Lookup;
31 import java.lang.invoke.VarHandle;
32 import java.lang.reflect.Field;
33 import jdk.incubator.code.TypeElement;
34
35 /**
36 * The symbolic reference to a Java field, called the <em>target field</em>.
37 * <p>
38 * All field references are defined in terms of the following attributes:
39 * <ul>
40 * <li>an <em>owner type</em>, the type of which the target field is a member;</li>
41 * <li>a <em>name</em>, the name of the target field.</li>
42 * <li>a <em>type</em>, the type of the target field.</li>
43 * </ul>
44 * <p>
45 * Field references can be <em>resolved</em> to their corresponding {@linkplain #resolveToField(Lookup) target field}.
46 * Or they can be turned into a {@linkplain #resolveToHandle(Lookup) var handle} that can be used to access the target field.
47 */
48 public sealed interface FieldRef extends JavaRef
49 permits FieldRefImpl {
50
51 /**
52 * {@return the owner type of this method reference}
53 */
54 TypeElement refType();
55
56 /**
57 * {@return the name of this method reference}
58 */
59 String name();
60
61 /**
62 * {@return the type of this method reference}
63 */
64 TypeElement type();
65
66 // Conversions
67
68 /**
69 * Resolves the target field associated with this field reference.
70 * @return the field associated with this field reference
71 * @param l the lookup used for resolving this field reference
72 * @throws ReflectiveOperationException if a resolution error occurs
73 */
74 Field resolveToField(MethodHandles.Lookup l) throws ReflectiveOperationException;
75
76 /**
77 * {@return a var handle used to access the target field associated with this field reference}
78 * The var handle is obtained by invoking the corresponding method on the provided lookup, in the following order:
79 * <ol>
80 * <li>first {@link MethodHandles.Lookup#findStaticVarHandle(Class, String, Class)} is used;</li>
81 * <li>if the above step fails, then {@link MethodHandles.Lookup#findVarHandle(Class, String, Class)} is used;</li>
82 * <li>otherwise, resolution fails and an exception is thrown</li>.
83 * </ol>
84 * @param l the lookup used for resolving this field reference
85 * @throws ReflectiveOperationException if a resolution error occurs
86 */
87 VarHandle resolveToHandle(MethodHandles.Lookup l) throws ReflectiveOperationException;
88
89 // Factories
90
91 /**
92 * {@return a field reference obtained from the provided field}
93 * @param f a reflective field
94 */
95 static FieldRef field(Field f) {
96 return field(f.getDeclaringClass(), f.getName(), f.getType());
97 }
98
99 /**
100 * {@return a field reference obtained from the provided owner, name and type}
101 * @param refType the reference owner type
102 * @param name the reference name
103 * @param type the reference type
104 */
105 static FieldRef field(Class<?> refType, String name, Class<?> type) {
106 return field(JavaType.type(refType), name, JavaType.type(type));
107 }
108
109 /**
110 * {@return a field reference obtained from the provided owner, name and type}
111 * @param refType the reference owner type
112 * @param name the reference name
113 * @param type the reference type
114 */
115 static FieldRef field(TypeElement refType, String name, TypeElement type) {
116 return new FieldRefImpl(refType, name, type);
117 }
118 }