Package org.stianloader.remapper

# Interface HierarchyAwareMappingDelegator.TopLevelMemberLookup

All Known Implementing Classes:
  `SimpleTopLevelLookup`

Enclosing class:
  HierarchyAwareMappingDelegator<T extends MappingLookup & MappingSink>

public static interface HierarchyAwareMappingDelegator.TopLevelMemberLookup
Interface for obtaining the root definition of a member. The root definition is then used by a `HierarchyAwareMappingDelegator` to map mappings to a common member within a group of similar methods/fields.

## Thread safety and concurrency

All implementations of `HierarchyAwareMappingDelegator.TopLevelMemberLookup` provided by stianloader-remapper are immutable and thus fully thread safe, unless explicitly stated otherwise, however thread safety is not necessarily a required aspect for implementors, although it is recommended to take advantage of it in order to reduce the required work for those that wish to employ concurrency in their software (which could be you!).

## Method Summary

Modifier and Type
Method
Description
`@NotNull MemberRef`
`getDefinition(@NotNull MemberRef reference)`
Obtain the root-level definition of a member.

## Method Details

### getDefinition

@NotNull @Contract(pure=true, value="!null -> !null; null -> fail") @NonBlocking @NotNull MemberRef getDefinition(@NotNull @NotNull MemberRef reference)
Obtain the root-level definition of a member.

Beware that this method may be called for fields and static methods, too. It is imperative that the declaration of fields is also followed as it is possible for javac to emit GETFIELD and PUTFIELD requests where the owner does not match the class where the field in question is defined - this for example might be produced by anonymous enum members.

Implementors are free to handle bridge methods as they please - the only requirement is that they do it persistently and that implementors should be aware that this would cause the bridge methods to potentially have the same name as the method it bridges to. This interface does not mandate any behaviour towards bridge methods and they may be ignored completely (this most likely won't have any notable repercussions anyways unless the codebase in question uses a lot of generics - however, generics are likely to be absent anyways in which case searching for bridge methods may be a bit superfluous).

Changing the computational type of the descriptor of the member is not permitted and will result in an exception being thrown in `HierarchyAwareMappingDelegator.remapMember(MemberRef, String)`. However, outside of that changing the descriptor of a method is permitted, as might for example be needed for bridge methods.

Implementations should return the original source reference for classes or methods they do not know. Under rare cases it is possible for methods to change their descriptor in the JRE, so this fact shouldn't be ignored even if the implementation should handle JRE classes (this specification recommends against handling inheritance beyond the application that needs to be remapped).

Returning a `MemberRef` in a non-source namespace is permissible, but it is highly recommended against doing so. That being said, the input `MemberRef` MUST be in the source namespace.

#### Performance

Stianloader-remapper expects calls to this method to be non-blocking and quick to process. Thus implementors should use caching if appropriate as it is reasonable to expect that this method will be called multiple times (sometimes even consecutively) with the same input argument - even if the returned value should be the same across all calls.

Parameters:
  `reference` - The reference of the member in the source namespace.
Returns:
  The reference of the declaration of the member