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 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