Package ghidra.program.util

# Class ProgramMergeManager

java.lang.Object
ghidra.program.util.ProgramMergeManager

public class ProgramMergeManager extends Object
`ProgramMergeManager` is a class for merging the differences between two programs as specified by a `ProgramMergeFilter` and the address ranges to be merged.

Program1 is the program being modified by the merge. Program2 is source for obtaining differences to apply to program1.

`ProgramDiff` is being used to determine the differences between the two programs.

If name conflicts occur while merging, the item (for example, symbol) will be merged with a new name that consists of the original name followed by "_conflict" and a one up number.

See Also:
  - `ProgramMergeFilter`
  - `ProgramDiff`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ProgramMergeManager(Program program1, Program program2)`
  `ProgramMergeManager` allows the merging of differences from program1 or program2 into the merged program.
  `ProgramMergeManager(Program program1, Program program2, AddressSetView p1LimitedAddressSet)`
  `ProgramMergeManager` allows the merging of differences from program1 or program2 into the merged program.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `AddressSetView`
  `getAddressesInCommon()`
  Returns the addresses in common between program1 and program2
  `AddressSetView`
  `getAddressesOnlyInOne()`
  Returns the addresses that are in program1, but not in program2
  `AddressSetView`
  `getAddressesOnlyInTwo()`
  Returns the addresses that are in program2, but not in program1
  `AddressSetView`
  `getCombinedAddresses()`
  Returns the addresses from combining the address sets in program1 and program2
  `ProgramDiffFilter`
  `getDiffFilter()`
  Get a copy of the diff filter that the merge is using.
  `String`
  `getErrorMessage()`
  Get the error messages that resulted from doing the merge.
  `AddressSetView`
  `getFilteredDifferences(TaskMonitor monitor)`
  Gets the filtered program differences for this merge.
  `AddressSetView`
  `getIgnoreAddressSet()`
  Get the address set indicating the addresses to be ignored (not checked) when determining differences between the two programs.
  `String`
  `getInfoMessage()`
  Get the informational messages that resulted from doing the merge.
  `AddressSetView`
  `getLimitedAddressSet()`
  Get the address set that the process of determining differences is limited to.
  `ProgramMergeFilter`
  `getMergeFilter()`
  Get a copy of the filter that indicates which parts of the Program should be merged.
  `Program`
  `getProgramOne()`
  Gets the first program being compared by the ProgramDiff.
  `Program`
  `getProgramTwo()`
  Gets the second program being compared by the ProgramDiff.
  `AddressSetView`
  `getRestrictedAddressSet()`
  Return the address set that is currently being used to restrict the differences that get returned.
  `String`
  `getWarnings()`
  Gets a string indicating warnings that occurred during the initial Diff of the two programs.
  `void`
  `ignore(AddressSetView p1AddressSet)`
  Ignore the differences for the indicated address set.
  `boolean`
  `memoryMatches()`
  Determine whether memory between the two programs matches.
  `boolean`
  `merge(Address p2Address, ProgramMergeFilter filter)`
  Merge the differences from the indicated program at the specified address with the indicated filtering.
  `boolean`
  `merge(Address p2Address, ProgramMergeFilter filter, TaskMonitor monitor)`
  Merge the differences from the indicated program at the specified address with the indicated filtering.
  `boolean`
  `merge(Address p2Address, TaskMonitor monitor)`
  Merge the differences from the indicated program at the specified address with the current filtering.
  `boolean`
  `merge(AddressSetView p1MergeSet, ProgramMergeFilter filter)`
  Merge the differences from the indicated program on the specified address set with the indicated filtering.
  `boolean`
  `merge(AddressSetView p1MergeSet, ProgramMergeFilter filter, TaskMonitor monitor)`
  Merge the differences from the indicated program on the specified address set with the indicated filtering.
  `boolean`
  `merge(AddressSetView p1MergeSet, TaskMonitor monitor)`
  Merge the differences from the indicated program on the specified address set with the filtering that is currently set.
  `void`
  `removeResultRestrictions()`
  Remove the restriction for the resulting differences to the indicated address set.
  `void`
  `restrictResults(AddressSetView p1AddressSet)`
  Restrict the resulting differences to the indicated address set.
  `void`
  `setDiffFilter(ProgramDiffFilter filter)`
  Set the filter that indicates which parts of the Program should be diffed.
  `void`
  `setMergeFilter(ProgramMergeFilter filter)`
  Set the filter that indicates which parts of the Program should be applied from the second program to the first program.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### ProgramMergeManager

    public ProgramMergeManager(Program program1, Program program2) throws ProgramConflictException
    `ProgramMergeManager` allows the merging of differences from program1 or program2 into the merged program.
    Parameters:
      `program1` - the first program (read only) for the merge.
      `program2` - the second program (read only) for the merge.
    Throws:
      `ProgramConflictException` - if the memory blocks, that overlap between the two programs, do not match. This indicates that programs couldn't be compared to determine the differences.

  - ### ProgramMergeManager

    public ProgramMergeManager(Program program1, Program program2, AddressSetView p1LimitedAddressSet) throws ProgramConflictException
    `ProgramMergeManager` allows the merging of differences from program1 or program2 into the merged program.
    Parameters:
      `program1` - the first program for the merge. This program will get modified by merge.
      `program2` - the second program (read only) for the merge.
      `p1LimitedAddressSet` - the limited address set. program differences can only be merged if they overlap this address set. null means find differences in each of the entire programs. The addresses in this set should be derived from program1.
    Throws:
      `ProgramConflictException` - if the memory blocks, that overlap between the two programs, do not match. This indicates that programs couldn't be compared to determine the differences.

- ## Method Details

  - ### memoryMatches

    public boolean memoryMatches()
    Determine whether memory between the two programs matches. For example, if one program has more memory than the other then it doesn't match or if the address ranges for memory are different for the two programs then they don't match.
    Returns:
      whether the memory matches between the two programs.

  - ### getFilteredDifferences

    public AddressSetView getFilteredDifferences(TaskMonitor monitor) throws CancelledException
    Gets the filtered program differences for this merge. Only differences are indicated for merge filter categories that are enabled and for address that have not been marked as ignored.
    Parameters:
      `monitor` - the task monitor for indicating the progress of determining differences. This monitor also allows the user to cancel if the diff takes too long. If no monitor is desired, use null.
    Returns:
      the program differences. The addresses in this address set are derived from program2.
    Throws:
      `CancelledException`

  - ### getDiffFilter

    public ProgramDiffFilter getDiffFilter()
    Get a copy of the diff filter that the merge is using.

  - ### setDiffFilter

    public void setDiffFilter(ProgramDiffFilter filter)
    Set the filter that indicates which parts of the Program should be diffed.
    Parameters:
      `filter` - the filter indicating the types of differences to be determined by this ProgramMerge.

  - ### getMergeFilter

    public ProgramMergeFilter getMergeFilter()
    Get a copy of the filter that indicates which parts of the Program should be merged.

  - ### setMergeFilter

    public void setMergeFilter(ProgramMergeFilter filter)
    Set the filter that indicates which parts of the Program should be applied from the second program to the first program.
    Parameters:
      `filter` - the filter indicating the types of differences to apply.

  - ### getCombinedAddresses

    public AddressSetView getCombinedAddresses()
    Returns the addresses from combining the address sets in program1 and program2
    Returns:
      the addresses for both program1 and program2. The addresses in this address set are derived from program1.

  - ### getAddressesInCommon

    public AddressSetView getAddressesInCommon()
    Returns the addresses in common between program1 and program2
    Returns:
      the addresses in common between program1 and program2. The addresses in this address set are derived from program1.

  - ### getAddressesOnlyInOne

    public AddressSetView getAddressesOnlyInOne()
    Returns the addresses that are in program1, but not in program2
    Returns:
      the addresses that are in program1, but not in program2. The addresses in this address set are derived from program1.

  - ### getAddressesOnlyInTwo

    public AddressSetView getAddressesOnlyInTwo()
    Returns the addresses that are in program2, but not in program1
    Returns:
      the addresses that are in program2, but not in program1. The addresses in this address set are derived from program2.

  - ### getProgramOne

    public Program getProgramOne()
    Gets the first program being compared by the ProgramDiff.
    Returns:
      program1. This is the program being modified by the merge. The addresses in this address set are derived from program1.

  - ### getProgramTwo

    public Program getProgramTwo()
    Gets the second program being compared by the ProgramDiff.
    Returns:
      program2. This is the program for obtaining the program information to merge.

  - ### getIgnoreAddressSet

    public AddressSetView getIgnoreAddressSet()
    Get the address set indicating the addresses to be ignored (not checked) when determining differences between the two programs.
    Returns:
      the set of addresses to ignore. The addresses in this address set are derived from program1.

  - ### getLimitedAddressSet

    public AddressSetView getLimitedAddressSet()
    Get the address set that the process of determining differences is limited to. In other words, only addresses in this set will be checked by the Diff.
    Returns:
      the address set The addresses in this address set are derived from program1.

  - ### getWarnings

    public String getWarnings()
    Gets a string indicating warnings that occurred during the initial Diff of the two programs.
    Returns:
      the warnings

  - ### merge

    public boolean merge(Address p2Address, ProgramMergeFilter filter) throws MemoryAccessException, CancelledException
    Merge the differences from the indicated program at the specified address with the indicated filtering.
    Parameters:
      `p2Address` - the address to be merged. This address should be derived from program2.
      `filter` - the filter indicating what types of differences to merge.
    Returns:
      true if merge succeeds
    Throws:
      `MemoryAccessException` - if bytes can't be copied.
      `CancelledException` - if user cancels via the monitor.

  - ### merge

    public boolean merge(Address p2Address, TaskMonitor monitor) throws MemoryAccessException, CancelledException
    Merge the differences from the indicated program at the specified address with the current filtering.
    Parameters:
      `p2Address` - the address to be merged. This address should be derived from program2.
      `monitor` - monitor for reporting merge status to the user.
    Returns:
      true if merge succeeds
    Throws:
      `MemoryAccessException` - if bytes can't be copied.
      `CancelledException` - if user cancels via the monitor.

  - ### merge

    public boolean merge(Address p2Address, ProgramMergeFilter filter, TaskMonitor monitor) throws MemoryAccessException, CancelledException
    Merge the differences from the indicated program at the specified address with the indicated filtering.
    Parameters:
      `p2Address` - the address to be merged. This address should be derived from program2.
      `filter` - the filter indicating what types of differences to merge.
      `monitor` - monitor for reporting merge status to the user.
    Returns:
      true if merge succeeds
    Throws:
      `MemoryAccessException` - if bytes can't be copied.
      `CancelledException` - if user cancels via the monitor.

  - ### ignore

    public void ignore(AddressSetView p1AddressSet)
    Ignore the differences for the indicated address set.
    Parameters:
      `p1AddressSet` - the address set to be merged. The addresses in this set should be derived from program1.

  - ### restrictResults

    public void restrictResults(AddressSetView p1AddressSet)
    Restrict the resulting differences to the indicated address set. Although the Diff will check for differences based on the limited set, the resulting differences from calls to getDifferences() will only return addresses contained in this restricted address set.
    Parameters:
      `p1AddressSet` - the address set to restrict the getFilteredDifferences() to. The addresses in this set are derived from program1.

  - ### getRestrictedAddressSet

    public AddressSetView getRestrictedAddressSet()
    Return the address set that is currently being used to restrict the differences that get returned.
    Returns:
      the address set being used to restrict the Diff results. The addresses in this set are derived from program1.

  - ### removeResultRestrictions

    public void removeResultRestrictions()
    Remove the restriction for the resulting differences to the indicated address set.

  - ### getErrorMessage

    public String getErrorMessage()
    Get the error messages that resulted from doing the merge.
    Returns:
      String empty string if there were no problems with the merge.

  - ### getInfoMessage

    public String getInfoMessage()
    Get the informational messages that resulted from doing the merge.
    Returns:
      String empty string if there were no information messages generated during the merge.

  - ### merge

    public boolean merge(AddressSetView p1MergeSet, ProgramMergeFilter filter) throws MemoryAccessException, CancelledException
    Merge the differences from the indicated program on the specified address set with the indicated filtering.
    Parameters:
      `p1MergeSet` - the address set to be merged. The addresses in this set should be derived from program1.
      `filter` - the filter indicating what types of differences to merge.
    Returns:
      true if merge succeeds
    Throws:
      `MemoryAccessException` - if bytes can't be copied.
      `CancelledException` - if user cancels via the monitor.

  - ### merge

    public boolean merge(AddressSetView p1MergeSet, TaskMonitor monitor) throws MemoryAccessException, CancelledException
    Merge the differences from the indicated program on the specified address set with the filtering that is currently set.
    Parameters:
      `p1MergeSet` - the address set to be merged The addresses in this set should be derived from program1.
      `monitor` - task monitor for reporting merge status to the user.
    Returns:
      true if merge succeeds
    Throws:
      `MemoryAccessException` - if bytes can't be copied.
      `CancelledException` - if user cancels via the monitor.

  - ### merge

    public boolean merge(AddressSetView p1MergeSet, ProgramMergeFilter filter, TaskMonitor monitor) throws MemoryAccessException, CancelledException
    Merge the differences from the indicated program on the specified address set with the indicated filtering.
    Parameters:
      `p1MergeSet` - the address set to be merged The addresses in this set should be derived from program1.
      `filter` - the filter indicating what types of differences to merge.
      `monitor` - task monitor for reporting merge status to the user.
    Returns:
      true if merge succeeds
    Throws:
      `MemoryAccessException` - if bytes can't be copied.
      `CancelledException` - if user cancels via the monitor.