Package ghidra.program.database.sourcemap

# Class SourceFileManagerDB

java.lang.Object
ghidra.program.database.sourcemap.SourceFileManagerDB

All Implemented Interfaces:
  `ErrorHandler`, `ManagerDB`, `SourceFileManager`

public class SourceFileManagerDB extends Object implements SourceFileManager, ManagerDB, ErrorHandler
Database Manager for managing source files and source map information.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final Lock`
  `lock`

  ### Fields inherited from interface ghidra.program.model.sourcemap.SourceFileManager

  `DUMMY`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `SourceFileManagerDB(DBHandle dbh, AddressMapDB addrMap, OpenMode openMode, Lock lock, TaskMonitor monitor)`
  Constructor

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `addSourceFile(SourceFile sourceFile)`
  Adds a `SourceFile` to this manager.
  `SourceMapEntry`
  `addSourceMapEntry(SourceFile sourceFile, int lineNumber, Address baseAddr, long length)`
  Creates a `SourceMapEntry` with `SourceFile` `sourceFile`, line number `lineNumber`, and non-negative length `length` and adds it to the program database.
  `boolean`
  `containsSourceFile(SourceFile sourceFile)`
  Returns true precisely when this manager contains `sourceFile`.
  `void`
  `dbError(IOException e)`
  Notification that an IO exception occurred.
  `void`
  `deleteAddressRange(Address start, Address end, TaskMonitor monitor)`
  Delete all objects which have been applied to the address range startAddr to endAddr and update the database accordingly.
  `List<SourceFile>`
  `getAllSourceFiles()`
  Returns a `List` containing all `SourceFile`s of the program.
  `List<SourceFile>`
  `getMappedSourceFiles()`
  Returns a `List` containing `SourceFile`s which are mapped to at least one address in the program
  `List<SourceMapEntry>`
  `getSourceMapEntries(SourceFile sourceFile, int minLine, int maxLine)`
  Returns the sorted list of `SourceMapEntry`s for `sourceFile` with line number between `minLine` and `maxLine`, inclusive.
  `List<SourceMapEntry>`
  `getSourceMapEntries(Address addr)`
  Returns a sorted list of `SourceMapEntry`s associated with an address `addr`.
  `SourceMapEntryIterator`
  `getSourceMapEntryIterator(Address address, boolean forward)`
  Returns a `SourceMapEntryIterator` starting at `address`.
  `boolean`
  `intersectsSourceMapEntry(AddressSetView addrs)`
  Returns `true` precisely when at least one `Address` in `addrs` has source map information.
  `void`
  `invalidateCache(boolean all)`
  Clears all data caches.
  `void`
  `moveAddressRange(Address fromAddr, Address toAddr, long length, TaskMonitor monitor)`
  Move all objects within an address range to a new location.
  `void`
  `programReady(OpenMode openMode, int currentRevision, TaskMonitor monitor)`
  Callback from program made to each manager after the program has completed initialization.
  `boolean`
  `removeSourceFile(SourceFile sourceFile)`
  Removes a `SourceFile` from this manager.
  `boolean`
  `removeSourceMapEntry(SourceMapEntry entry)`
  Removes a `SourceMapEntry` from this manager.
  `void`
  `setProgram(ProgramDB program)`
  Callback from program used to indicate all manager have been created.
  `void`
  `transferSourceMapEntries(SourceFile source, SourceFile target)`
  Changes the source map so that any `SourceMapEntry` associated with `source` is associated with `target` instead.

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

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

  ### Methods inherited from interface ghidra.program.database.ManagerDB

  `dispose`

  ### Methods inherited from interface ghidra.program.model.sourcemap.SourceFileManager

  `addSourceMapEntry, getSourceMapEntries, getSourceMapEntries`

- ## Field Details

  - ### lock

    protected final Lock lock

- ## Constructor Details

  - ### SourceFileManagerDB

    public SourceFileManagerDB(DBHandle dbh, AddressMapDB addrMap, OpenMode openMode, Lock lock, TaskMonitor monitor) throws VersionException
    Constructor
    Parameters:
      `dbh` - database handle
      `addrMap` - map longs to addresses
      `openMode` - mode
      `lock` - program synchronization lock
      `monitor` - task monitor
    Throws:
      `VersionException` - if the database is incompatible with the current schema

- ## Method Details

  - ### setProgram

    public void setProgram(ProgramDB program)
    Description copied from interface: `ManagerDB`
    Callback from program used to indicate all manager have been created. When this method is invoked, all managers have been instantiated but may not be fully initialized.
    Specified by:
      `setProgram` in interface `ManagerDB`
    Parameters:
      `program` - the program is set when all the initializations have been completed.

  - ### programReady

    public void programReady(OpenMode openMode, int currentRevision, TaskMonitor monitor) throws IOException, CancelledException
    Description copied from interface: `ManagerDB`
    Callback from program made to each manager after the program has completed initialization. This method may be used by managers to perform additional upgrading which may have been deferred.
    Specified by:
      `programReady` in interface `ManagerDB`
    Parameters:
      `openMode` - the mode that the program is being opened.
      `currentRevision` - current program revision. If openMode is UPGRADE, this value reflects the pre-upgrade value.
      `monitor` - the task monitor to use in any upgrade operations.
    Throws:
      `IOException` - if a database io error occurs.
      `CancelledException` - if the user cancelled the operation via the task monitor.

  - ### invalidateCache

    public void invalidateCache(boolean all) throws IOException
    Description copied from interface: `ManagerDB`
    Clears all data caches.
    Specified by:
      `invalidateCache` in interface `ManagerDB`
    Parameters:
      `all` - if false, some managers may not need to update their cache if they can tell that its not necessary. If this flag is true, then all managers should clear their cache no matter what.
    Throws:
      `IOException` - if a database io error occurs.

  - ### deleteAddressRange

    public void deleteAddressRange(Address start, Address end, TaskMonitor monitor) throws CancelledException
    Delete all objects which have been applied to the address range startAddr to endAddr and update the database accordingly. The specified start and end addresses must form a valid range within a single `AddressSpace`.
    Note: this method will split any source map entries that intersect the address range but are not entirely contained within it. Parts within the range to delete will be deleted.
    Specified by:
      `deleteAddressRange` in interface `ManagerDB`
    Parameters:
      `start` - first address in range
      `end` - last address in range
      `monitor` - task monitor
    Throws:
      `CancelledException` - if `monitor` is cancelled

  - ### moveAddressRange

    public void moveAddressRange(Address fromAddr, Address toAddr, long length, TaskMonitor monitor) throws AddressOverflowException, CancelledException
    Move all objects within an address range to a new location.
    Note: this method will move any source map entry which is entirely contained within the source address range. Entries which also contain addresses outside of this range will be split and parts within the range to move will be moved.
    Specified by:
      `moveAddressRange` in interface `ManagerDB`
    Parameters:
      `fromAddr` - first address of range to be moved
      `toAddr` - target address
      `length` - number of addresses to move
      `monitor` - task monitor
    Throws:
      `AddressOverflowException` - if overflow occurs when computing new addresses
      `CancelledException` - if `monitor` is cancelled

  - ### addSourceFile

    public boolean addSourceFile(SourceFile sourceFile) throws LockException
    Description copied from interface: `SourceFileManager`
    Adds a `SourceFile` to this manager. A SourceFile must be added before it can be associated with any source map information.
    Specified by:
      `addSourceFile` in interface `SourceFileManager`
    Parameters:
      `sourceFile` - source file to add (can't be null)
    Returns:
      true if this manager did not already contain sourceFile
    Throws:
      `LockException` - if invoked without exclusive access

  - ### removeSourceFile

    public boolean removeSourceFile(SourceFile sourceFile) throws LockException
    Description copied from interface: `SourceFileManager`
    Removes a `SourceFile` from this manager. Any associated `SourceMapEntry`s will also be removed.
    Specified by:
      `removeSourceFile` in interface `SourceFileManager`
    Parameters:
      `sourceFile` - source file to remove
    Returns:
      true if sourceFile was in the manager
    Throws:
      `LockException` - if invoked without exclusive access

  - ### getSourceMapEntries

    public List<SourceMapEntry> getSourceMapEntries(Address addr)
    Description copied from interface: `SourceFileManager`
    Returns a sorted list of `SourceMapEntry`s associated with an address `addr`.
    Specified by:
      `getSourceMapEntries` in interface `SourceFileManager`
    Parameters:
      `addr` - address
    Returns:
      line number

  - ### addSourceMapEntry

    public SourceMapEntry addSourceMapEntry(SourceFile sourceFile, int lineNumber, Address baseAddr, long length) throws LockException, AddressOverflowException
    Description copied from interface: `SourceFileManager`
    Creates a `SourceMapEntry` with `SourceFile` `sourceFile`, line number `lineNumber`, and non-negative length `length` and adds it to the program database.

    Entries with non-zero lengths must either cover the same address range or be disjoint.

    Specified by:
      `addSourceMapEntry` in interface `SourceFileManager`
    Parameters:
      `sourceFile` - source file
      `lineNumber` - line number
      `baseAddr` - minimum address of range
      `length` - number of addresses in range
    Returns:
      created SourceMapEntry
    Throws:
      `LockException` - if invoked without exclusive access
      `AddressOverflowException` - if baseAddr + length-1 overflows

  - ### intersectsSourceMapEntry

    public boolean intersectsSourceMapEntry(AddressSetView addrs)
    Description copied from interface: `SourceFileManager`
    Returns `true` precisely when at least one `Address` in `addrs` has source map information.
    Specified by:
      `intersectsSourceMapEntry` in interface `SourceFileManager`
    Parameters:
      `addrs` - addresses to check
    Returns:
      true when at least one address has source map info

  - ### dbError

    public void dbError(IOException e) throws RuntimeException
    Description copied from interface: `ErrorHandler`
    Notification that an IO exception occurred.
    Specified by:
      `dbError` in interface `ErrorHandler`
    Parameters:
      `e` - `IOException` which was cause of error
    Throws:
      `RuntimeException` - optional exception which may be thrown when responding to error condition.

  - ### getMappedSourceFiles

    public List<SourceFile> getMappedSourceFiles()
    Description copied from interface: `SourceFileManager`
    Returns a `List` containing `SourceFile`s which are mapped to at least one address in the program
    Specified by:
      `getMappedSourceFiles` in interface `SourceFileManager`
    Returns:
      mapped source file list

  - ### getAllSourceFiles

    public List<SourceFile> getAllSourceFiles()
    Description copied from interface: `SourceFileManager`
    Returns a `List` containing all `SourceFile`s of the program.
    Specified by:
      `getAllSourceFiles` in interface `SourceFileManager`
    Returns:
      source file list

  - ### transferSourceMapEntries

    public void transferSourceMapEntries(SourceFile source, SourceFile target) throws LockException
    Description copied from interface: `SourceFileManager`
    Changes the source map so that any `SourceMapEntry` associated with `source` is associated with `target` instead. Any entries associated with `target` before invocation will still be associated with `target` after invocation. `source` will not be associated with any entries after invocation (unless `source` and `target` are the same). Line number information is not changed.
    Specified by:
      `transferSourceMapEntries` in interface `SourceFileManager`
    Parameters:
      `source` - source file to get info from
      `target` - source file to move info to
    Throws:
      `LockException` - if invoked without exclusive access

  - ### getSourceMapEntryIterator

    public SourceMapEntryIterator getSourceMapEntryIterator(Address address, boolean forward)
    Description copied from interface: `SourceFileManager`
    Returns a `SourceMapEntryIterator` starting at `address`.
    Specified by:
      `getSourceMapEntryIterator` in interface `SourceFileManager`
    Parameters:
      `address` - starting address
      `forward` - direction of iterator (true = forward)
    Returns:
      iterator

  - ### containsSourceFile

    public boolean containsSourceFile(SourceFile sourceFile)
    Description copied from interface: `SourceFileManager`
    Returns true precisely when this manager contains `sourceFile`.
    Specified by:
      `containsSourceFile` in interface `SourceFileManager`
    Parameters:
      `sourceFile` - source file
    Returns:
      true if source file already added

  - ### getSourceMapEntries

    public List<SourceMapEntry> getSourceMapEntries(SourceFile sourceFile, int minLine, int maxLine)
    Description copied from interface: `SourceFileManager`
    Returns the sorted list of `SourceMapEntry`s for `sourceFile` with line number between `minLine` and `maxLine`, inclusive.
    Specified by:
      `getSourceMapEntries` in interface `SourceFileManager`
    Parameters:
      `sourceFile` - source file
      `minLine` - minimum line number
      `maxLine` - maximum line number
    Returns:
      source map entries

  - ### removeSourceMapEntry

    public boolean removeSourceMapEntry(SourceMapEntry entry) throws LockException
    Description copied from interface: `SourceFileManager`
    Removes a `SourceMapEntry` from this manager.
    Specified by:
      `removeSourceMapEntry` in interface `SourceFileManager`
    Parameters:
      `entry` - entry to remove
    Returns:
      true if entry was in the manager
    Throws:
      `LockException` - if invoked without exclusive access