public interface MappingSetMerger
A service for merging mappings. The result of a mapping merge is a new mapping which contains the result you would expect to get after using the two mappings being merged in order, left, then right.
Put another way, merging 2 mappings means the deobfuscated output of the left MappingSet and the obfuscated
input of the right MappingSet match, creating a single MappingSet with the obfuscated input of the
left side and the deobfuscated output of the right side.
More complex situations are likely to occur while merging mappings, so this table will go through the different possible cases and how a mapping set merger handles them in the default implementation:
| Left | Right | Output | Note |
|---|---|---|---|
A -> B |
B -> C |
A -> C |
Typical case, easiest to handle |
A -> B |
Missing | A -> B |
Standalone mappings get copied |
| Missing | B -> C |
B -> C |
Standalone mappings get copied |
A -> B |
X -> Y |
A -> BX -> Y |
This is no different than the 2 above cases with missing mappings on each side. This is just meant to be a further example that if two unrelated mappings are present, a standard merger won't know how to handle them other than copying both. |
A -> B |
A -> C |
A -> C |
By default the right mapping is considered the "most up to date" mappings, so in the case where both mapping sets provide mappings for the same obfuscated name, the right mapping is used in the default implementation. |
A -> B(types and names) |
B -> B (types)A -> C (names) |
A -> B (types)A -> C (names) |
This is an example of a special case situation where the left mapping only maps types, then the second mapping set only maps members, but from the expectation that the first mapping set was already applied. The default implementation should handle this case correctly. |
All of these cases can happen in a single mapping merge. That is to say, some cases may apply to some classes and
methods but not others, but all during a single merge. It's important to note that it's illegal to merge a
null mapping set with another set, both must exist. The Missing cases in the table refer to situations
where one mapping set contains entries the other doesn't.
MappingSetMergerHandlerMappingSet.merge(org.cadixdev.lorenz.MappingSet) and related methods were implemented. The merge
methods are equivalent to this class, as they only call back to the default implementation of this class.MappingSetMergerHandler to handle each specific
merging situation. To modify specific instances of merging behavior, it may be simpler to override that
class instead and only modify the specific type of merge you want to change.| Modifier and Type | Method and Description |
|---|---|
static MappingSetMerger |
create(MappingSet left,
MappingSet right)
Creates a mapping set merger, using the default merger implementation with the default
MappingSetMergerHandler implementation. |
static MappingSetMerger |
create(MappingSet left,
MappingSet right,
MergeConfig config)
Creates a mapping set merger, using the default merger implementation with the provided
MappingSetMergerHandler implementation. |
default MappingSet |
merge()
Merge the two
MappingSets in this merger together, returning the result. |
MappingSet |
merge(MappingSet target)
Merge the two
MappingSets in this merger together into the provided target. |
FieldMapping |
mergeField(FieldMapping left,
FieldMapping right,
ClassMapping<?,?> target)
Merge the two provided
FieldMappings together into the provided target. |
InnerClassMapping |
mergeInnerClass(InnerClassMapping left,
InnerClassMapping right,
ClassMapping<?,?> target)
Merge the members of the two provided
InnerClassMappings together into the provided target. |
MethodMapping |
mergeMethod(MethodMapping left,
MethodMapping right,
ClassMapping<?,?> target)
Merge the two provided
MethodMappings together into the provided target. |
MethodParameterMapping |
mergeMethodParameter(MethodParameterMapping left,
MethodParameterMapping right,
MethodMapping target)
Merge the two provided
MethodParameterMappings together into the provided target. |
TopLevelClassMapping |
mergeTopLevelClass(TopLevelClassMapping left,
TopLevelClassMapping right,
MappingSet target)
Merge the members of the two provided
TopLevelClassMappings together into the provided target. |
static MappingSetMerger create(MappingSet left, MappingSet right)
MappingSetMergerHandler implementation.left - The MappingSet for the left side of the mergeright - The MappingSet for the right side of the mergecreate(MappingSet, MappingSet, MergeConfig)static MappingSetMerger create(MappingSet left, MappingSet right, MergeConfig config)
MappingSetMergerHandler implementation.left - The MappingSet for the left side of the mergeright - The MappingSet for the right side of the mergeconfig - The MergeConfig configuration for this merge sessioncreate(MappingSet, MappingSet)default MappingSet merge()
MappingSets in this merger together, returning the result. This is effectively the same as
calling merge(MappingSet) with a new mapping set and returning it.merge(MappingSet)MappingSet merge(MappingSet target)
MappingSets in this merger together into the provided target. For ease of use the
provided target mapping set is also returned.target - The mapping set to insert the merged mappings intotarget parameter.target
parameter. The result shouldn't be a copy.TopLevelClassMapping mergeTopLevelClass(TopLevelClassMapping left, TopLevelClassMapping right, MappingSet target)
TopLevelClassMappings together into the provided target.left - The class mapping for the left side of the merge. May be null.right - The class mapping for the right side of the merge. May be null.target - The mapping set to insert the new merged mapping into. May not be null.null if the mapping is to be removed.merge(MappingSet) method in the default implementation, but can
also be used to map a single class if called directly. If you are overriding the default implementation
to change behavior, first make sure what you're trying to do can't be accomplished by overriding the
MappingSetMergerHandler instead.InnerClassMapping mergeInnerClass(InnerClassMapping left, InnerClassMapping right, ClassMapping<?,?> target)
InnerClassMappings together into the provided target.left - The class mapping for the left side of the merge. May be null.right - The class mapping for the right side of the merge. May be null.target - The class mapping to insert the new merged mapping into. May not be null.null if the mapping is to be removed.mergeTopLevelClass()
method in the default implementation, but can also be used to map a single inner class if called
directly. If you are overriding the default implementation to change behavior, first make sure what
you're trying to do can't be accomplished by overriding the MappingSetMergerHandler instead.FieldMapping mergeField(FieldMapping left, FieldMapping right, ClassMapping<?,?> target)
FieldMappings together into the provided target.left - The field mapping for the left side of the merge. May be null.right - The field mapping for the right side of the merge. May be null.target - The class mapping to insert the new merged mapping into. May not be null.null if the mapping is to be removed.mergeTopLeveClass()
and mergeInnerClass()
methods in the default implementation, but can also be used to map a single field if called directly.
If you are overriding the default implementation to change behavior, first make sure what you're trying
to do can't be accomplished by overriding the MappingSetMergerHandler instead.MethodMapping mergeMethod(MethodMapping left, MethodMapping right, ClassMapping<?,?> target)
MethodMappings together into the provided target.left - The method mapping for the left side of the merge. May be null.right - The method mapping for the right side of the merge. May be null.target - The class mapping to insert the new merged mapping into. May not be null.null if the mapping is to be removed.mergeTopLeveClass()
and mergeInnerClass()
methods in the default implementation, but can also be used to map a single method if called directly.
If you are overriding the default implementation to change behavior, first make sure what you're trying
to do can't be accomplished by overriding the MappingSetMergerHandler instead.MethodParameterMapping mergeMethodParameter(MethodParameterMapping left, MethodParameterMapping right, MethodMapping target)
MethodParameterMappings together into the provided target.left - The method parameter mapping for the left side of the merge. May be null.right - The method parameter mapping for the right side of the merge. May be null.target - The method mapping to insert the new merged mapping into. May not be null.null if the mapping is to be removed.mergeMethod()
method in the default implementation, but can also be used to map a single method parameter if called
directly. If you are overriding the default implementation to change behavior, first make sure what
you're trying to do can't be accomplished by overriding the MappingSetMergerHandler instead.