Package org.stianloader.remapper

# Interface MappingLookup

All Known Implementing Classes:
  `HierarchyAwareMappingDelegator`, `SimpleHierarchyAwareMappingLookup`, `SimpleMappingLookup`

public interface MappingLookup
A `MappingLookup` stores mappings which can be obtained by the specified accessor methods. While the `MappingLookup` interface on it's own is strictly read-only, implementations may mutate the mappings between calls and are allowed to implement interfaces that introduce mapping writing properties such as `MappingSink`. That being said, callers should generally be safe in that assumption that one an element maps to a certain value, the association will stay over a longer duration.

Concrete implements of this interface such as `HierarchyAwareMappingDelegator` or `SimpleMappingLookup`, which implement `MappingSink`, should thus not be mutated after performing the first map requests. However, implementations (which include the implementations listed previously) are not required to ensure such immutability.

## Method overloading, inheritance and other remapping restrictions

Implementations of `MappingLookup` are generally encouraged to implement inheritance, and may also support overloading if chosen. However, `MappingLookup` does not explicitly define a behaviour here and implementations such as `SimpleMappingLookup` may choose to handle inheritance and method overloading at all. For more insight as to why inheritance and overloading may be beneficial, see the appropriate section in `Remapper`.

The methods provided by `MappingLookup` should avoid returning illegal names wherever possible. However, beware that `getRemappedMethodName(String, String, String)` is likely to be called with the static initialization block <clinit> or the constructor <init>, which should not map to anything but these names. This means that implementations of `MappingLookup` should not try to be smart and refuse seemingly illegal mapping requests (one can still return the name of the member in the source namespace though) - this behaviour is employed for performance reasons

If an implementation of `MappingLookup` chooses to handle method hierarchies, it must be aware that similar hierarchy structures exist for fields, too. Furthermore, it should be aware that `getRemappedFieldName(String, String, String)` and `getRemappedMethodName(String, String, String)` may be called with member it may not know (this can be the case with different JDKs - even older ones! Breaking changes did happen in the past even within the public APIs).

## Concurrency and thread safety

While a `MappingLookup` instance on it's own is read-only and thus usually fine to use in concurrent environments, there may be implementations that are either not completely in-memory or allow mutation which thus may compromise any thread safety guarantees. As such the usual advice applies here, too: Consult the manual of your implementation regarding thread safety and prefer to err on the side of caution if not known. The `MappingLookup` interface otherwise makes no thread safety and concurrency guarantees.

## Method Summary

Modifier and Type
Method
Description
`@NotNull String`
`getRemappedClassName(@NotNull String srcName)`
Obtains the name of the class in the destination namespace (or in laymen's terms the remapped name).
`default @Nullable String`
`getRemappedClassNameFast(@NotNull String srcName)`
Obtains the name of the class in the destination namespace (or in laymen's terms the remapped name).
`@NotNull String`
`getRemappedFieldName(@NotNull String srcOwner, @NotNull String srcName, @NotNull String srcDesc)`
Obtains the name of a field in the destination namespace (or the mapped name).
`@NotNull String`
`getRemappedMethodName(@NotNull String srcOwner, @NotNull String srcName, @NotNull String srcDesc)`
Obtains the name of a field in the destination namespace (or the mapped name).
`default @Nullable String`
`getRemappedParameterName(@NotNull String srcOwner, @NotNull String srcName, @NotNull String srcDesc, int paramIndex, boolean isStaticMethod)`
Obtains the name of the parameter in the destination namespace (or in laymen's terms the remapped name of the parameter).

## Method Details

### getRemappedClassName

@NotNull @Contract(pure=true) @NotNull String getRemappedClassName(@NotNull @NotNull String srcName)
Obtains the name of the class in the destination namespace (or in laymen's terms the remapped name). If the class name in the source namespace is equal to the name in the destination namespace (e.g. because there is no mapping), then the name in the source namespace must be returned.

It is valid to have `getRemappedClassNameFast(String)` and `getRemappedClassName(String)` be the same implementation for as long as `getRemappedClassName(String)` never returns null, however doing so might incur a slight performance reduction.

srcName and the returned value are in the same format as `Type.getInternalName()`.

Parameters:
  `srcName` - The name of the class in the source namespace
Returns:
  The mapped name in the destination namespace, or the name in the source namespace if no mapping exists.

### getRemappedClassNameFast

@Nullable @Contract(pure=true) default @Nullable String getRemappedClassNameFast(@NotNull @NotNull String srcName)
Obtains the name of the class in the destination namespace (or in laymen's terms the remapped name). If the class name in the source namespace is equal to the name in the destination namespace (e.g. because there is no mapping), then null can be returned for performance reasons.

This is especially done when some string manipulation can be skipped if the source name equals the destination name.

It is valid to have `getRemappedClassNameFast(String)` and `getRemappedClassName(String)` be the same implementation for as long as `getRemappedClassName(String)` never returns null, however doing so might incur a slight performance reduction.

srcName and the returned value are in the same format as `Type.getInternalName()`.

Parameters:
  `srcName` - The name of the class in the source namespace
Returns:
  The name in the destination namespace, or null if the name is the same as the source namespace

### getRemappedFieldName

@NotNull @Contract(pure=true) @NotNull String getRemappedFieldName(@NotNull @NotNull String srcOwner, @NotNull @NotNull String srcName, @NotNull @NotNull String srcDesc)
Obtains the name of a field in the destination namespace (or the mapped name). If the field is not known or if no mapping exists for the field, then the name in the source namespace must be returned (that is the srcName parameter).

srcOwner is in the same format as `Type.getInternalName()`.

Implementations of this interface are encouraged to not throw if possible.

Parameters:
  `srcOwner` - The name of the owner of the member in the source namespace
  `srcName` - The name of the member in the source namespace
  `srcDesc` - The descriptor of the member (where as classes are all in the source namespace)
Returns:
  The mapped name in the destination namespace, or the name in the source namespace if no mapping exists.

### getRemappedMethodName

@NotNull @Contract(pure=true) @NotNull String getRemappedMethodName(@NotNull @NotNull String srcOwner, @NotNull @NotNull String srcName, @NotNull @NotNull String srcDesc)
Obtains the name of a field in the destination namespace (or the mapped name). If the field is not known or if no mapping exists for the field, then the name in the source namespace must be returned (that is the srcName parameter).

srcOwner is in the same format as `Type.getInternalName()`.

Implementations of this interface are encouraged to not throw if possible.

Parameters:
  `srcOwner` - The name of the owner of the member in the source namespace
  `srcName` - The name of the member in the source namespace
  `srcDesc` - The descriptor of the member (where as classes are all in the source namespace)
Returns:
  The mapped name in the destination namespace, or the name in the source namespace if no mapping exists.

### getRemappedParameterName

@Nullable @Contract(pure=true) @AvailableSince("0.2.0-a20251220") default @Nullable String getRemappedParameterName(@NotNull @NotNull String srcOwner, @NotNull @NotNull String srcName, @NotNull @NotNull String srcDesc, int paramIndex, boolean isStaticMethod)
Obtains the name of the parameter in the destination namespace (or in laymen's terms the remapped name of the parameter). Should the name of the parameter not be known in the destination namespace, then `null` is returned. This is the default behaviour of this method.

The `paramIndex` argument is 0-indexed. It does not distinguish between computational categories. Or in other words, for both `(IZ)V` and `(JZ)V` the boolean parameter corresponds to a `paramIndex` value of 1, while the integer and long have a value of 0.

Callers may throw an `IndexOutOfBoundsException` if `paramIndex` is below 0 or above the amount of parameters as discernible by `srcDesc`. As such, this method cannot be used to remap LVT entries, even though they are quite similar in structure. This is because LVT entries can be reused. By default this method does not do any checks whether `paramIndex` is a valid value. This is done for performance reasons.

Implementations of this method are encouraged to not throw if possible, unless for reasons described above. While it theoretically makes sense to throw an exception in cases where a method is known to not exist, this is generally rarely the case.

If this `MappingLookup` instance does not support remapping parameters, then `null` should be returned unconditionally, without throwing outside of aforementioned reasons.

Parameters:
  `srcOwner` - The name of the owner of the member in the source namespace.
  `srcName` - The name of the member in the source namespace.
  `srcDesc` - The descriptor of the member (where as classes are all in the source namespace).
  `paramIndex` - The index of the parameter, excluding the implied `this` parameter.
  `isStaticMethod` - Whether the method is static. Used when working with mappings formats such as Enigma, TINYv2, or TSRG.
Returns:
  The name of the parameter in the destination namespace, or `null` if not applicable.
Since:
  0.2.0-a20251220