Package org.stianloader.remapper

# Interface MappingSink

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

public interface MappingSink
A `MappingSink` is an object that accepts mappings of classes or class members. A `MappingSink` by itself is strictly write-only, that is it only accepts changes but provides no means of obtaining the current state.

The interface does not specify what the mapping changes are used for - they may be used for a `MappingLookup` instance, but they may also be used to write mappings to a file - or may delegate to multiple `MappingSink` instances at the same time and do multiple actions at once.

Implementations of `MappingSink` are not required to ensure that remapping requests are sensical or valid overall. The burden for this lies on the caller.

Both fields and methods are renamed using `remapMember(MemberRef, String)`. Classes are renamed using `remapClass(String, String)`. It is not yet possible to create inner classes (as in `ClassNode.innerClasses`), rename inner classes (that is `InnerClassNode.innerName`), rename method parameters (both in LVT and via `MethodNode.parameters`) or rename local variables (via `MethodNode.localVariables`). However, it is possible that in the future such functionality is added.

As `MappingSink` has no (direct) way of obtaining the result of a remapping request, implementors are permitted to ignore remapping requests at will. MappingSinks that also implement `MappingLookup` should generally not ignore requests however - but may do so if appropriate. When encountering illegal requests, implementors are encourages to throw an exception (usually `IllegalArgumentException`) over plainly discarding a request in order to aid in troubleshooting bugs or otherwise unintended behaviour.

## Concurrency and thread safety

The `MappingSink` interface makes no guarantees on the behaviour of implementations when it comes to concurrent environment. Implementations may be thread safe and may be usable in concurrent environments, but they might also not be. In case of doubt it is generally recommended to assume that an implementation is not thread-safe.

The burden of making sure that thread safety constraints are correctly handled falls on the API consumer.

## Method Summary

Modifier and Type
Method
Description
`@NotNull MappingSink`
`remapClass(@NotNull String srcName, @NotNull String dstName)`
Remaps a specific class.
`@NotNull MappingSink`
`remapMember(@NotNull MemberRef srcRef, @NotNull String dstName)`
Remaps a class member - that is either a field or a method.
`@NotNull MappingSink`
`remapParameter(@NotNull String srcOwner, @NotNull String srcMethodName, @NotNull String srcDesc, int paramIndex, @NotNull String destParamName)`
Remaps a method parameter.

## Method Details

### remapClass

@Contract(mutates="this", pure=false, value="_, _ -> this") @NotNull @NotNull MappingSink remapClass(@NotNull @NotNull String srcName, @NotNull @NotNull String dstName)
Remaps a specific class. Do note that this makes no promises on inner classes. That is using the dollar ('$') sign or a dot ('.') has no effect on the internal arrangement of inner class nodes. Inner classes are as of now not handled by the `Remapper` implementation and if implemented would be independent of this method.

Class names are defined via the `internal name` of a class - that is forward slashes ('/') are used instead of dots ('.'). Usage of dots or semicolons (';') are completely forbidden as they are not allowed in the JVMS within internal names of classes.

Implementations are not required to ensure that the class names make sense or are valid - the burden of verification falls upon the caller.

Parameters:
  `srcName` - The name of the member in the source namespace (that is the unmapped name)
  `dstName` - The name of the member in the destination namespace (that is the mapped name)
Returns:
  The current `MappingSink` instance (i.e. this), for chaining

### remapMember

@Contract(mutates="this", pure=false, value="_, _ -> this") @NotNull @NotNull MappingSink remapMember(@NotNull @NotNull MemberRef srcRef, @NotNull @NotNull String dstName)
Remaps a class member - that is either a field or a method. Whether the member is a field or a method can be easily discerned by looking at the first character of the `descriptor` of the `MemberRef`. If the first character is a '(', then it is a method - otherwise it is a field.

As no non-method descriptor can start with '(', this check suffices and reduces the work required for bridging between stianloader-remapper and other mapping formats or software.

Parameters:
  `srcRef` - The reference of the member in the source namespace (i.e. the unmapped member)
  `dstName` - The name of the member in the target namespace (i.e. the mapped member name)
Returns:
  The current `MappingSink` instance, for chaining

### remapParameter

@Contract(mutates="this", pure=false, value="_, _, _, _, _ -> this") @NotNull @AvailableSince("0.2.0-a20251220") @NotNull MappingSink remapParameter(@NotNull @NotNull String srcOwner, @NotNull @NotNull String srcMethodName, @NotNull @NotNull String srcDesc, int paramIndex, @NotNull @NotNull String destParamName)
Remaps a method parameter.

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.

If this `MappingSink` instance does not support remapping method parameters then an `UnsupportedOperationException` should be thrown. In cases where libraries are used that link against an older version of stianloader-remapper (namely 0.1.X and earlier), an `AbstractMethodError` may be thrown when attempting to call this method.

Parameters:
  `srcOwner` - The name of the owner of the method in the source namespace.
  `srcMethodName` - The name of the method in the source namespace.
  `srcDesc` - The descriptor of the method in the source namespace.
  `paramIndex` - The index of the parameter, excluding the implied `this` argument on non-static methods.
  `destParamName` - The name of the parameter in the destination namespace.
Returns:
  The current `MappingSink` instance, for chaining.
Since:
  0.2.0-a20251220