org.cadixdev.lorenz.merge

Interface MappingSetMerger

All Known Implementing Classes:

MappingSetMergerImpl

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 -> B X -> 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.

Since:

0.5.4

See Also:

MappingSetMergerHandler

API Note:

This class was added after the MappingSet.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.

Implementation Note:

The default implementation of this interface uses a 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.

Method Summary

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.

Method Detail

create

static MappingSetMerger create(MappingSet left,
                               MappingSet right)

Creates a mapping set merger, using the default merger implementation with the default MappingSetMergerHandler implementation.

Parameters:

left - The MappingSet for the left side of the merge

right - The MappingSet for the right side of the merge

Returns:

The merger

See Also:

create(MappingSet, MappingSet, MergeConfig)

create

static MappingSetMerger create(MappingSet left,
                               MappingSet right,
                               MergeConfig config)

Creates a mapping set merger, using the default merger implementation with the provided MappingSetMergerHandler implementation.

Parameters:

left - The MappingSet for the left side of the merge

right - The MappingSet for the right side of the merge

config - The MergeConfig configuration for this merge session

Returns:

The merger

See Also:

create(MappingSet, MappingSet)

merge

default MappingSet merge()

Merge the two 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.

Returns:

The merged mapping set

See Also:

merge(MappingSet)

merge

MappingSet merge(MappingSet target)

Merge the two MappingSets in this merger together into the provided target. For ease of use the provided target mapping set is also returned.

Parameters:

target - The mapping set to insert the merged mappings into

Returns:

The target parameter.

Implementation Requirements:

The return value of this method should always be the same object provided in the target parameter. The result shouldn't be a copy.

mergeTopLevelClass

TopLevelClassMapping mergeTopLevelClass(TopLevelClassMapping left,
                                        TopLevelClassMapping right,
                                        MappingSet target)

Merge the members of the two provided TopLevelClassMappings together into the provided target.

Parameters:

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.

Returns:

The new class mapping, or null if the mapping is to be removed.

Implementation Note:

This method is used by the 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.

mergeInnerClass

InnerClassMapping mergeInnerClass(InnerClassMapping left,
                                  InnerClassMapping right,
                                  ClassMapping<?,?> target)

Merge the members of the two provided InnerClassMappings together into the provided target.

Parameters:

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.

Returns:

The new class mapping, or null if the mapping is to be removed.

Implementation Note:

This method is used by the 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.

mergeField

FieldMapping mergeField(FieldMapping left,
                        FieldMapping right,
                        ClassMapping<?,?> target)

Merge the two provided FieldMappings together into the provided target.

Parameters:

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.

Returns:

The new field mapping, or null if the mapping is to be removed.

Implementation Note:

This method is used by the 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.

mergeMethod

MethodMapping mergeMethod(MethodMapping left,
                          MethodMapping right,
                          ClassMapping<?,?> target)

Merge the two provided MethodMappings together into the provided target.

Parameters:

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.

Returns:

The new method mapping, or null if the mapping is to be removed.

Implementation Note:

This method is used by the 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.

mergeMethodParameter

MethodParameterMapping mergeMethodParameter(MethodParameterMapping left,
                                            MethodParameterMapping right,
                                            MethodMapping target)

Merge the two provided MethodParameterMappings together into the provided target.

Parameters:

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.

Returns:

The new method parameter mapping, or null if the mapping is to be removed.

Implementation Note:

This method is used by the 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.