View source for JDT Core Programmer Guide/ECJ/Bindings

{{note|Bindings implement what some text books call "Symbols": unique values used for linking name references to their target.}}

==Main Kinds of Bindings==
See the type hierarchy of <code>org.eclipse.jdt.internal.compiler.lookup.Binding</code>. This class also declares constants which define possible answers from <code>Binding.kind()</code>.
* One reason why kinds are or-able bits: a NameReference can use an int as bitset to encode if it can legally resolve to a variable, or a type, or both, where variable can be either a field or a local.


As a special type, <code>UnresolvedReferenceBinding</code> is a placeholder for a not-yet resolved ReferenceBinding. Resolving an UnresolvedReferenceBinding will update its holder, too. This type is used in signatures of members of <code>BinaryTypeBinding</code> to avoid the need to read ''all class file dependencies''. By construction, types in class files are always represented by their fully qualified name, so lookup of these types does not require any context.


Another group of bindings is '''synthesized''' by the compiler from thin air, see [[#Synthetic Bindings]].

==General rules for Bindings==
===No <code>null</code>===
In constrast to AST, where <code>null</code> is typically a legal field value, bindings typically use constants of the <code>NO_*</code> family to denote "nothing here". <code>null</code> would typically indicate "not initialized".

===Comparison===
Since bindings are unique by construction, it would normally be OK to compare bindings using <code>==</code> or <code>!=</code>. Specifically with the introduction of TYPE_USE annotations, even the same type can be represented by different bindings to account for attached annotations. For that reason, specific comparison methods have been added, which should be used throughout:
* <code>TypeBinding.equalsEquals()</code>
* <code>TypeBinding.notEquals()</code>

These methods ignore difference only in annotations. Those rare cases where annotation difference should indeed be considered have to be marked in source with <code>//$IDENTITY-COMPARISON$</code>, to suppress a warning implemented specifically for the compiler's own sake.

Internally, each <code>TypeBinding</code> has an <code>id</code>. Low values correspond to well-known types (see <code>TypeIds</code>), while higher values are allocated dynamically. Ids are interesting as the family of all type bindings derived from the same original share the same id. Ids also simplify checks for well-known types.

==Non-Uniqueness==
Contrary to the general rule, a number of reasons exist, why the same source entity can be represented by several distinct bindings:

* When the same '''package''' exists in several modules, we create one <code>PlainPackageBinding</code> per module, plus a <code>SplitPackageBinding</code> to combine the slices into one. The current strategy concerning SplitPackageBinding was developed via {{Bug|547181}} and friends, which has a lot of explanations.
* From a '''generic type''' (<code>SourceTypeBinding</code> or <code>BinaryTypeBinding</code>) a number of parameterizations can be created using <code>ParameterizedTypeBinding</code>.
** For each contained <code>MethodBinding</code> a <code>ParameterizedMethodBinding</code> is created to carry the instantiation of type variables.
** For each contained <code>FieldBinding</code> a <code>ParameterizedFieldBinding</code> is created to carry the instantiation of type variables.
* From a '''generic method''' (<code>MethodBinding</code>) a number of parameterizations can be created using <code>ParameterizedGenericMethodBinding</code>. While ParameterizedMethodBinding captures type variables of the declaring class, ParameterizedGenericMethodBinding captures type variables declared by the method itself.
* From each <code>TypeBinding</code> a number of "clones" (of the same type) can be created with different sets of TYPE_USE '''annotations'''. Indeed, method <code>TypeBinding.clone()</code> is used for this process, and <code>TypeBinding.prototype()</code> will answer the original from which an annotated type was cloned. Also see [[#Comparison]] above.
* From each <code>WildcardBinding</code> a number of <code>CaptureBinding</code> can be created, but that's not of ECJ's invention, but specified in JLS.


When comparing bindings, it is sometimes necessary, to explicitly strip a wrapper binding using one of these methods:
* <code>TypeBinding.original()</code> strips annotations, and erases parameterized, raw and array types
* <code>TypeBinding.erasure()</code> full erasure (no type arguments), but may or may not retain annotations
* <code>TypeBinding.unannotated()</code> strips annotations only
* <code>TypeBinding.actualType()</code> answers the erasure from ParameterizedTypeBinding and WildcardBinding, <code>null</code> otherwise
* <code>ParameterizedTypeBinding.genericType()</code>: like <code>actualType()</code> but performes lazy resolving of UnresolvedReferenceBinding
* <code>MethodBinding.genericMethod()</code>: strips instantiation of a method's own type variables
* <code>MethodBinding.original()</code>: strips any parameterization
* <code>MethodBinding.shallowOriginal()</code>: strips instantiation of a method's own type variables, but leaves instantiations of class parameters in place (''unclear if different from genericMethod()'').

==Parameterization and nesting==
A plain method inside a ParameterizedType will be represented by a ParameterizedMethodBinding. But what about a nested type inside a generic outer type?
* If the nested type is '''static''', any type parameters from its outer class are irrelevant for the nested type, as it cannot access them without an outer instance.
* If the nested type is '''non-static''', reference to this type are represented by a ParameterizedTypeBinding even if the nested type itself declares no type parameters, because here the nested type can refer to type variables of the enclosing type & instance (this was wrong prior to {{Bug|460491}}).

==Flag vectors==
* <code>tagBits</code> (TypeBinding,MethodBinding,VariableBinding): set of bits as declared in <code>TagBits</code>
** Is*: fine grained classification of a binding
** Begin*, End*: pairs of flags that indicate when a given processing step is active / complete (used to avoid re-entrance / recursion).
** AreFieldsComplete, AreFieldsSorted, AreMethodsComplete, AreMethodsSorted: describes that status of arrays <code>fields</code> and <code>methods</code>
** Has*: various diagnostics
** Annotation*: marks when a given annotation has been applied to the element.
* <code>extendedTagBits</code> (TypeBinding): overflow from tagBits, constants are in <code>ExtendedTagBits</code>.<br>'''New bits should preferrably be allocated here, rather than the crowded TagBits'''.
* <code>typeBits</code> (ReferenceBinding): classification of types, constants in <code>TypeIds</code>:
** classification of resources (below <code>Closeable</code>), see [[JDT Core Programmer Guide/ECJ/Analyse#Black_lists_.2F_white_lists|Analysis->Black lists / white lists]]
** BitUninitialized
** BitUninternedType: classify JDT's own types <code>TypeBinding</code> (compiler) and <code>ITypeBinding</code> (DOM) as not suitable for reference comparison (<code>==</code>, <code>!=</code>), unless documented as <code>//$IDENTITY-COMPARISON</code>.
** Bit*Null*Annotation: detect annotation types, configured for use by ECJ's annotation based null analysis.
** BitMap, BitCollection, BitList: mark types which have methods with well-known problems (see [[ JDT Core Programmer Guide/ECJ/AST#Algorithm_implementations|UnlikelyArgumentCheck]]).

==Synthetic Bindings==

While the normal process goes AST -> Bindings -> byte code, some elements are synthesized by the compiler skipping the initial AST stage. These elements are implemented as <code>SyntheticFieldBinding</code>, <code>SyntheticMethodBinding</code>, <code>SyntheticArgumentBinding</code>. 

Some of these are managed in <code>SourceTypeBinding.synthetics</code>, an array of maps, where the array index is one of <code>FIELD_EMUL</code>, <code>METHOD_EMUL</code>, <code>CLASS_LITERAL_EMUL</code>.

Each <code>SyntheticMethodBinding</code> classifies itself in its field <code>purpose</code>.

The following constants represent the different purposes of synthetic methods (best effort description, may not completely capture all usage scenarios):

{| class="wikitable"
!Purpose!!bytecode name!!Description
|-
|FieldReadAccess||access$''n''||Read access to a bytecode-inaccessible field
|-
|FieldWriteAccess||access$''n''||Write access to a bytecode-inaccessible field
|-
|SuperFieldReadAccess||access$''n''||Read access to a bytecode-inaccessible field
|-
|SuperFieldWriteAccess||access$''n''||Write access to a bytecode-inaccessible field
|-
|MethodAccess||access$''n''||Invocation of a bytecode-inaccessible method
|-
|ConstructorAccess||&lt;init&gt;||Invocation of a bytecode-inaccessible constructor
|-
|SuperMethodAccess||access$''n''||Invocation of an bytecode-inaccessible constructor in an anonymous instance creation
|-
|SuperMethodAccess||''same as the original method''||Invocation of a super method inherited from a non-public class into a public class
|-
|BridgeMethod||''same as the original method''||Method that overrides an inherited method and invokes an overriding method with a more specific signature (parameterization or covariant return)
|-
|EnumValues||values||generated method <code>values()</code>
|-
|EnumValueOf||values||generated method <code>valueOf()</code>
|-
|SwitchTable||$SWITCH_TABLE$''enumName''||generated lookup function for <code>switch</code> statements
|-
|TooManyEnumsConstants||"&nbsp;enum&nbsp;constant&nbsp;initialization$''n''"||generated method for enum initialization if byte code cannot fit into <code>&lt;clinit&gt;</code> method, see {{Bug|331334}}.
|-
|LambdaMethod||lambda$''n''||Implementation of a lambda expression
|-
|ArrayConstructor||lambda$''n''||Lambda implementation of a method reference for array allocation
|-
|ArrayClone||lambda$''n''||Lambda implementation of a method reference for array cloning
|-
|FactoryMethod||lambda$''n''||Lambda implementation for a regular constructor reference
|-
|DeserializeLambda||$deserializeLambda$''n''||Generated method for deserializing a serializable lambda
|}


Here "bytecode-inaccessible" is typically an access from a nested class to a private member of an enclosing class. Since in bytecode, nested types appear like toplevel types, the privilege to access private members of enclosings needs to be faked by synthetic delegation methods, which are public, but should not be called from client code. Much of this is '''obsoleted''' as of Java 11 due to [https://openjdk.java.net/jeps/181 JEP 181] (Nest-Based Access Control).

Many of these synthetic bindings are '''created''' in the <code>manageSyntheticAccessIfNecessary()</code> family of methods in various AST types.

Finally, <code>CodeStream</code> directly '''generates the bytecode''' from the synthetic binding, using one of the <code>generateSyntheticBodyFor*</code> methods.

==Peculiarities of ModuleBinding==
Firstly, four kinds of modules must be distinguished:
* SourceModuleBinding (corresponds to some <code>module-info.java</code>
* BinaryModuleBinding (corresponds to some <code>module-info.class</code>
* AutomaticModule (corresponds to a jar file without <code>module-info.class</code>)
* UnnamedModule (corresponds to code outside any "real" module, classes on the classpath as opposed to modulepath)

Even if <code>module-info</code> is found, this need not be the final word: through command line options like <code>--add-reads</code> etc the declarations of a module can be altered after the fact. To feed these tweaks into compilation, we apply the following tricks:
* <code>IUpdatableModule</code> super interface of <code>ModuleBinding</code> exposing mutators for a module.
* Member classes of the above: <code>AddReads</code>, <code>AddExports</code> which encode changes to be performed once the module binding will be known. Method <code>accept()</code> will actually perform that change.
* The '''batch''' compiler stores all updates seen on the command line in <code>FileSystem.moduleUpdates</code>, to be applied using <code>applyModuleUpdates()</code>
* In the IDE, class <code>org.eclipse.jdt.internal.core.ModuleUpdater</code> is the hub for this information.
* '''Note''' that module updates are persisted in the <code>org.eclipse.jdt.internal.core.builder.State</code> (from <code>ClasspathLocation#updates</code>) (we had a conflict, where a module update was implemented as a lambda (of type <code>Consumer<IUpdatableModule></code>), which could not be persisted - this is still the case for the update setting the MODULE_MAIN_CLASS, but that update is not persisted at the moment.).
* It is a bit tricky how and where exactly application of these updates is integrated into compilation.
* At the bottom line, this architecture de-couples the compiler from the different ways how such updates are defined: command line or classpath attributes.

==Other classes in the lookup package==

''the structure of this section should be improved.''


===Constants===
* TagBits - big bag of flags in bitset <code>tagBits</code>, see [[#Flag Vectors]]
* ExtendedTagBits, see [[#Flag Vectors]]
* ExtraCompilerModifiers - will appear in fields <code>modifier</code> but are never found in .class files
* ProblemReasons - constants used in Problem*Binding
* TypeConstants - not only type, also well-known method names etc
* TypeIds - integer constants relating to types

===Management of variants of a type binding===
* TypeSystem
** AnnotatableTypeSystem

===Type Inference===

Here be draggons, read [[https://docs.oracle.com/javase/specs/jls/se14/html/jls-18.html JLS §18]] first.
* InferenceContext18 (variant InferenceContext is used only below 1.8 - not really maintained any more)
* BoundSet
* InferenceVariable
* ReductionResult
** TypeBound
** ConstraintFormula
*** ConstraintExpressionFormula
*** ConstraintExceptionFormula
*** ConstraintTypeFormula
* InferenceSubstitution

===Scopes===
see [[../Lookups#Scopes]]


===Reading .class files===
* SignatureWrapper: incremental interpretation of a signature in binary format

===Visiting===
* TypeBindingVisitor


===Null Annotations===
* ImplicitNullAnnotationVerifier: check if method overriding is valid wrt null annotations
* ParameterNonNullDefaultProvider: implements the effect of @NonNullByDefault on method parameters
* ExternalAnnotationSuperimposer: See hierarchy of <code>org.eclipse.jdt.internal.compiler.env.ITypeAnnotationWalker</code>.


===Post-resolution computations===
* MethodVerifier
** MethodVerifier15

[[Category:JDT]]