Package ghidra.trace.database.symbol

# Class AbstractDBTraceSymbol

java.lang.Object
ghidra.program.database.DatabaseObject
ghidra.util.database.DBAnnotatedObject
ghidra.trace.database.symbol.AbstractDBTraceSymbol

All Implemented Interfaces:
  `Symbol`, `DBTraceOverlaySpaceAdapter.DecodesAddresses`, `TraceSymbol`

Direct Known Subclasses:
  `DBTraceLabelSymbol`, `DBTraceNamespaceSymbol`

public abstract class AbstractDBTraceSymbol extends DBAnnotatedObject implements TraceSymbol, DBTraceOverlaySpaceAdapter.DecodesAddresses

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final DBTraceSymbolManager`
  `manager`
  `protected DBTraceNamespaceSymbol`
  `parent`

  ### Fields inherited from class ghidra.program.database.DatabaseObject

  `key`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AbstractDBTraceSymbol(DBTraceSymbolManager manager, DBCachedObjectStore<?> store, DBRecord record)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected DBTraceNamespaceSymbol`
  `assertIsNamespace(AbstractDBTraceSymbol symbol)`
  `protected void`
  `assertNotGlobal()`
  `protected DBTraceNamespaceSymbol`
  `checkCircular(DBTraceNamespaceSymbol newParent)`
  `boolean`
  `delete()`
  Delete the symbol and its associated resources.
  `protected void`
  `doCollectAddressSet(AddressSet set)`
  `protected boolean`
  `doDelete()`
  `protected TraceChangeRecord<?,?>`
  `doSetNameWithEvent(String newName)`
  `protected TraceChangeRecord<?,?>`
  `doSetParent(DBTraceNamespaceSymbol newParent)`
  Checks and sets the parent The caller must still call `DBAnnotatedObject.update(DBObjectColumn...)` for `PARENT_COLUMN`.
  `protected void`
  `doSetSource(SourceType newSource)`
  `protected TraceChangeRecord<?,?>`
  `doSetSourceWithEvent(SourceType newSource)`
  Sets the flags for the given source.
  `boolean`
  `equals(Object obj)`
  `protected void`
  `fresh(boolean created)`
  Extension point: Called when the object's fields are populated.
  `Address`
  `getAddress()`
  `AddressSet`
  `getAddressSet()`
  `protected AddressSpace`
  `getAddressSpace()`
  `long`
  `getID()`
  `Lifespan`
  `getLifespan()`
  `String`
  `getName()`
  `String`
  `getName(boolean includeNamespace)`
  Returns the symbol name, optionally prepended with the namespace path.
  `DBTraceOverlaySpaceAdapter`
  `getOverlaySpaceAdapter()`
  Get the space adapter for the trace containing the object
  `DBTraceNamespaceSymbol`
  `getParentNamespace()`
  Return the parent namespace for this symbol.
  `DBTraceNamespaceSymbol`
  `getParentSymbol()`
  Returns namespace symbol of the namespace containing this symbol
  `String[]`
  `getPath()`
  Gets the full path name for this symbol as an ordered array of strings ending with the symbol name.
  `DBTraceProgramView`
  `getProgram()`
  Get the program associated with this symbol
  `ProgramLocation`
  `getProgramLocation()`
  Returns a program location for this symbol; may be null.
  `protected Iterable<? extends TraceAddressSnapRange>`
  `getRanges()`
  `Collection<? extends DBTraceReference>`
  `getReferenceCollection()`
  Get all memory references to the address of this symbol.
  `int`
  `getReferenceCount()`
  Get the number of References to this symbol or its address.
  `DBTraceReference[]`
  `getReferences()`
  Returns all memory references to the address of this symbol.
  `DBTraceReference[]`
  `getReferences(TaskMonitor monitor)`
  Returns all memory references to the address of this symbol.
  `SourceType`
  `getSource()`
  Gets the source of this symbol.
  `TraceThread`
  `getThread()`
  If in register space, get the thread associated with this symbol.
  `DBTrace`
  `getTrace()`
  Get the trace to which this symbol belongs.
  `int`
  `hashCode()`
  `boolean`
  `hasReferences()`
  `boolean`
  `isDescendant(Namespace namespace)`
  Returns true if the given namespace symbol is a descendant of this symbol.
  `boolean`
  `isDynamic()`
  `boolean`
  `isExternal()`
  Returns true if this an external symbol.
  `boolean`
  `isGlobal()`
  `boolean`
  `isPinned()`
  Returns true if the symbol is pinned to its current address.
  `boolean`
  `isValidParent(Namespace ns)`
  Determines if the given parent is valid for this Symbol.
  `protected void`
  `set(String name, DBTraceNamespaceSymbol parent, SourceType source)`
  `void`
  `setName(String newName, SourceType newSource)`
  Sets the name this symbol.
  `void`
  `setNameAndNamespace(String newName, Namespace newNamespace, SourceType newSource)`
  Sets the symbols name and namespace.
  `void`
  `setNamespace(Namespace newNamespace)`
  Sets the symbols namespace
  `void`
  `setPinned(boolean pinned)`
  Sets whether or not this symbol is pinned to its associated address.
  `void`
  `setSource(SourceType newSource)`
  Sets the source of this symbol.
  `String`
  `toString()`
  `protected void`
  `validateNameAndParent(String newName, DBTraceNamespaceSymbol newParent)`
  `protected org.apache.commons.lang3.tuple.Pair<String,SourceType>`
  `validateNameAndSource(String newName, SourceType newSource)`

  ### Methods inherited from class ghidra.util.database.DBAnnotatedObject

  `doRefresh, doUpdateAll, doUpdated, doWrite, getObjectKey, getTableName, isDeleted, refresh, refresh, update, update, update, update`

  ### Methods inherited from class ghidra.program.database.DatabaseObject

  `checkDeleted, checkIsValid, checkIsValid, getKey, isDeleted, isInvalid, keyChanged, setDeleted, setInvalid, validate`

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

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface ghidra.program.model.symbol.Symbol

  `getObject, getSymbolType, isDeleted, isExternalEntryPoint, isPrimary, setPrimary`

- ## Field Details

  - ### parent

    protected DBTraceNamespaceSymbol parent

  - ### manager

    protected final DBTraceSymbolManager manager

- ## Constructor Details

  - ### AbstractDBTraceSymbol

    public AbstractDBTraceSymbol(DBTraceSymbolManager manager, DBCachedObjectStore<?> store, DBRecord record)

- ## Method Details

  - ### equals

    public boolean equals(Object obj)

    NOTE: If the IDs match, then the symbols are considered equal, regardless of their other attributes. This mechanic seems required to support the whole "placeholder" idea. TODO: The "placeholder" thing may no longer be applicable.

    Overrides:
      `equals` in class `Object`

  - ### hashCode

    public int hashCode()
    Overrides:
      `hashCode` in class `Object`

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`

  - ### assertNotGlobal

    protected void assertNotGlobal()

  - ### assertIsNamespace

    protected DBTraceNamespaceSymbol assertIsNamespace(AbstractDBTraceSymbol symbol)

  - ### fresh

    protected void fresh(boolean created) throws IOException
    Description copied from class: `DBAnnotatedObject`
    Extension point: Called when the object's fields are populated.

    This provides an opportunity for the object to initialize any non-database-backed fields that depend on the database-backed fields. Note that its use may indicate a situation better solved by a custom `DBCachedObjectStoreFactory.DBFieldCodec`. If both the database-backed and non-database-backed fields are used frequently, then a codec may not be indicated. If the database-backed fields are only used in this method or to encode another frequently-used field, then a codec is likely better.

    For a new object, the database-backed fields remain at their initial values. They will be saved after this method returns, so they may be further initialized with custom logic.

    For an object loaded from the database, the database-backed fields are already populated from the record when this method is called. They are not automatically saved after this method returns. This method should not further initialize database-backed fields in this case.

    Overrides:
      `fresh` in class `DBAnnotatedObject`
    Parameters:
      `created` - `true` when object is being created, or `false` when it is being loaded.
    Throws:
      `IOException` - if further initialization fails.

  - ### getOverlaySpaceAdapter

    public DBTraceOverlaySpaceAdapter getOverlaySpaceAdapter()
    Description copied from interface: `DBTraceOverlaySpaceAdapter.DecodesAddresses`
    Get the space adapter for the trace containing the object
    Specified by:
      `getOverlaySpaceAdapter` in interface `DBTraceOverlaySpaceAdapter.DecodesAddresses`
    Returns:
      the adapter

  - ### getTrace

    public DBTrace getTrace()
    Description copied from interface: `TraceSymbol`
    Get the trace to which this symbol belongs.
    Specified by:
      `getTrace` in interface `TraceSymbol`
    Returns:
      the trace

  - ### getThread

    public TraceThread getThread()
    Description copied from interface: `TraceSymbol`
    If in register space, get the thread associated with this symbol.
    Specified by:
      `getThread` in interface `TraceSymbol`
    Returns:
      the thread

  - ### getAddressSpace

    protected AddressSpace getAddressSpace()

  - ### getID

    public long getID()
    Specified by:
      `getID` in interface `Symbol`
    Returns:
      this symbol's ID.

  - ### getName

    public String getName()
    Specified by:
      `getName` in interface `Symbol`
    Returns:
      the name of this symbol.

  - ### getAddress

    public Address getAddress()
    Specified by:
      `getAddress` in interface `Symbol`
    Returns:
      the address for the symbol.

  - ### getRanges

    protected Iterable<? extends TraceAddressSnapRange> getRanges()

  - ### getLifespan

    public Lifespan getLifespan()

  - ### doCollectAddressSet

    protected void doCollectAddressSet(AddressSet set)

  - ### getAddressSet

    public AddressSet getAddressSet()

  - ### getPath

    public String[] getPath()
    Description copied from interface: `Symbol`
    Gets the full path name for this symbol as an ordered array of strings ending with the symbol name.
    Specified by:
      `getPath` in interface `Symbol`
    Returns:
      the array indicating the full path name for this symbol.

  - ### getName

    public String getName(boolean includeNamespace)
    Description copied from interface: `Symbol`
    Returns the symbol name, optionally prepended with the namespace path.
    Specified by:
      `getName` in interface `Symbol`
    Parameters:
      `includeNamespace` - if true, the namespace path is prepended to the name.
    Returns:
      formatted name

  - ### getParentNamespace

    public DBTraceNamespaceSymbol getParentNamespace()
    Description copied from interface: `Symbol`
    Return the parent namespace for this symbol.
    Specified by:
      `getParentNamespace` in interface `Symbol`
    Specified by:
      `getParentNamespace` in interface `TraceSymbol`
    Returns:
      the namespace that contains this symbol.

  - ### getParentSymbol

    public DBTraceNamespaceSymbol getParentSymbol()
    Description copied from interface: `Symbol`
    Returns namespace symbol of the namespace containing this symbol
    Specified by:
      `getParentSymbol` in interface `Symbol`
    Specified by:
      `getParentSymbol` in interface `TraceSymbol`
    Returns:
      parent namespace symbol

  - ### isDescendant

    public boolean isDescendant(Namespace namespace)
    Description copied from interface: `Symbol`
    Returns true if the given namespace symbol is a descendant of this symbol.
    Specified by:
      `isDescendant` in interface `Symbol`
    Parameters:
      `namespace` - to test as descendant symbol of this Symbol
    Returns:
      true if this symbol is an ancestor of the given namespace symbol

  - ### getReferenceCollection

    public Collection<? extends DBTraceReference> getReferenceCollection()
    Description copied from interface: `TraceSymbol`
    Get all memory references to the address of this symbol.
    Specified by:
      `getReferenceCollection` in interface `TraceSymbol`
    Returns:
      the references

  - ### getReferenceCount

    public int getReferenceCount()
    Description copied from interface: `Symbol`
    Get the number of References to this symbol or its address.

    NOTE: this method differ from `Symbol.hasReferences()` behavior for memory symbols since this method will return `ReferenceManager.getReferenceCountTo(Address)` if this is the only symbol at its address.

    Specified by:
      `getReferenceCount` in interface `Symbol`
    Returns:
      the number of References to this symbol or its address.

  - ### hasReferences

    public boolean hasReferences()
    Specified by:
      `hasReferences` in interface `Symbol`
    Returns:
      true if this symbol has at least one reference to it. Explicit references to other symbols at the same address are not considered (see `Reference.getSymbolID()` which indicates a specific symbol reference).

  - ### getReferences

    public DBTraceReference[] getReferences(TaskMonitor monitor)
    Description copied from interface: `TraceSymbol`
    Returns all memory references to the address of this symbol. If you do not have a `TaskMonitor` instance, then you can pass `TaskMonitor.DUMMY` or `null`. For traces, `TraceSymbol.getReferenceCollection()` is preferred, as it will retrieve the references lazily.
    Specified by:
      `getReferences` in interface `Symbol`
    Specified by:
      `getReferences` in interface `TraceSymbol`
    Parameters:
      `monitor` - the monitor that is used to report progress and to cancel this potentially long-running call
    Returns:
      all memory references to the address of this symbol.

  - ### getReferences

    public DBTraceReference[] getReferences()
    Description copied from interface: `TraceSymbol`
    Returns all memory references to the address of this symbol. For traces, `TraceSymbol.getReferenceCollection()` is preferred, as it will retrieve the references lazily.
    Specified by:
      `getReferences` in interface `Symbol`
    Specified by:
      `getReferences` in interface `TraceSymbol`
    Returns:
      all memory references to the address of this symbol
    See Also:
      - `Symbol.getReferences(TaskMonitor)`

  - ### set

    protected void set(String name, DBTraceNamespaceSymbol parent, SourceType source)

  - ### doSetNameWithEvent

    protected TraceChangeRecord<?,?> doSetNameWithEvent(String newName) throws InvalidInputException
    Throws:
      `InvalidInputException`

  - ### doSetParent

    protected TraceChangeRecord<?,?> doSetParent(DBTraceNamespaceSymbol newParent) throws CircularDependencyException
    Checks and sets the parent The caller must still call `DBAnnotatedObject.update(DBObjectColumn...)` for `PARENT_COLUMN`.
    Parameters:
      `newParent` - the parent namespace
    Throws:
      `CircularDependencyException`

  - ### doSetSource

    protected void doSetSource(SourceType newSource)

  - ### doSetSourceWithEvent

    protected TraceChangeRecord<?,?> doSetSourceWithEvent(SourceType newSource)
    Sets the flags for the given source. The caller must still call `DBAnnotatedObject.update(DBObjectColumn...)` for `FLAGS_COLUMN`. The update should be called before the returned event, if applicable, is fired.
    Parameters:
      `newSource` - the source type
    Returns:
      the appropriate change event, if a change was actually made

  - ### isValidParent

    public boolean isValidParent(Namespace ns)
    Description copied from interface: `Symbol`
    Determines if the given parent is valid for this Symbol. Specified namespace must belong to the same symbol table as this symbol.
    Specified by:
      `isValidParent` in interface `Symbol`
    Parameters:
      `ns` - prospective parent namespace for this symbol
    Returns:
      true if parent is valid

  - ### checkCircular

    protected DBTraceNamespaceSymbol checkCircular(DBTraceNamespaceSymbol newParent) throws CircularDependencyException
    Throws:
      `CircularDependencyException`

  - ### validateNameAndSource

    protected org.apache.commons.lang3.tuple.Pair<String,SourceType> validateNameAndSource(String newName, SourceType newSource) throws InvalidInputException
    Throws:
      `InvalidInputException`

  - ### setName

    public void setName(String newName, SourceType newSource) throws DuplicateNameException, InvalidInputException
    Description copied from interface: `Symbol`
    Sets the name this symbol. If this symbol is dynamic, then the name is set and the symbol is no longer dynamic.
    Specified by:
      `setName` in interface `Symbol`
    Parameters:
      `newName` - the new name for this symbol.
      `newSource` - the source of this symbol
      Some symbol types, such as function symbols, can set the source to Symbol.DEFAULT.
    Throws:
      `DuplicateNameException` - if name conflicts with another symbol.
      `InvalidInputException` - if an invalid or null name specified (see `SymbolUtilities.validateName(java.lang.String)`).

  - ### validateNameAndParent

    protected void validateNameAndParent(String newName, DBTraceNamespaceSymbol newParent) throws DuplicateNameException
    Throws:
      `DuplicateNameException`

  - ### setNamespace

    public void setNamespace(Namespace newNamespace) throws DuplicateNameException, InvalidInputException, CircularDependencyException
    Description copied from interface: `Symbol`
    Sets the symbols namespace
    Specified by:
      `setNamespace` in interface `Symbol`
    Parameters:
      `newNamespace` - new parent namespace
    Throws:
      `DuplicateNameException` - if newNamespace already contains a symbol with this symbol's name
      `InvalidInputException` - is newNamespace is not a valid parent for this symbol
      `CircularDependencyException` - if this symbol is an ancestor of newNamespace

  - ### setNameAndNamespace

    public void setNameAndNamespace(String newName, Namespace newNamespace, SourceType newSource) throws DuplicateNameException, InvalidInputException, CircularDependencyException
    Description copied from interface: `Symbol`
    Sets the symbols name and namespace. This is provided to allow the caller to avoid a name conflict by creating an autonomous action.
    Specified by:
      `setNameAndNamespace` in interface `Symbol`
    Parameters:
      `newName` - new symbol name
      `newNamespace` - new parent namespace
      `newSource` - the source of this symbol
      Some symbol types, such as function symbols, can set the source to Symbol.DEFAULT.
    Throws:
      `DuplicateNameException` - if newNamespace already contains a symbol with this symbol's name
      `InvalidInputException` - is newNamespace is not a valid parent for this symbol
      `CircularDependencyException` - if this symbol is an ancestor of newNamespace

  - ### setSource

    public void setSource(SourceType newSource)
    Description copied from interface: `Symbol`
    Sets the source of this symbol. `SourceType`
    Specified by:
      `setSource` in interface `Symbol`
    Parameters:
      `newSource` - the new source of this symbol

  - ### getSource

    public SourceType getSource()
    Description copied from interface: `Symbol`
    Gets the source of this symbol. `SourceType`
    Specified by:
      `getSource` in interface `Symbol`
    Returns:
      the source of this symbol

  - ### delete

    public boolean delete()
    Description copied from interface: `Symbol`
    Delete the symbol and its associated resources. Any references symbol associations will be discarded.
    Specified by:
      `delete` in interface `Symbol`
    Returns:
      true if successful

  - ### doDelete

    protected boolean doDelete()

  - ### isDynamic

    public boolean isDynamic()
    Specified by:
      `isDynamic` in interface `Symbol`
    Returns:
      true if this symbol is a dynamic symbol (not actually defined in the database).

  - ### isGlobal

    public boolean isGlobal()
    Specified by:
      `isGlobal` in interface `Symbol`
    Returns:
      true if the symbol is contained within the global namespace

  - ### getProgram

    public DBTraceProgramView getProgram()
    Description copied from interface: `Symbol`
    Get the program associated with this symbol
    Specified by:
      `getProgram` in interface `Symbol`
    Returns:
      the program associated with this symbol.

  - ### getProgramLocation

    public ProgramLocation getProgramLocation()
    Description copied from interface: `Symbol`
    Returns a program location for this symbol; may be null. This allows implementations to return a more specific program location than what is typically used by the system.
    Specified by:
      `getProgramLocation` in interface `Symbol`
    Returns:
      the location

  - ### isPinned

    public boolean isPinned()
    Returns true if the symbol is pinned to its current address. If it is pinned, then moving or removing the memory associated with that address will not affect this symbol. Traces do not support moving memory, so pinning is meaningless and unsupported. Since blocks cannot be relocated as they can in a `Program`, it's tempting to say all symbols are pinned; however, this presents in the UI and is a bit confusing and/or distracting.
    Specified by:
      `isPinned` in interface `Symbol`
    Specified by:
      `isPinned` in interface `TraceSymbol`
    Returns:
      true if the symbol is pinned to its current address.

  - ### setPinned

    public void setPinned(boolean pinned)
    Description copied from interface: `TraceSymbol`

    Sets whether or not this symbol is pinned to its associated address.

    If the symbol is pinned then moving or removing the memory associated with its address will not cause this symbol to be removed and will not cause its address to change. If the symbol is not pinned, then removing the memory at its address will also remove this symbol.

    Likewise, moving a memory block containing a symbol that is not anchored will change the address for that symbol to keep it associated with the same byte in the memory block.

    Traces do not support moving memory, so pinning is meaningless and unsupported.
    Specified by:
      `setPinned` in interface `Symbol`
    Specified by:
      `setPinned` in interface `TraceSymbol`
    Parameters:
      `pinned` - true indicates this symbol is anchored to its address. false indicates this symbol is not anchored to its address.

  - ### isExternal

    public boolean isExternal()
    Description copied from interface: `Symbol`
    Returns true if this an external symbol.
    Specified by:
      `isExternal` in interface `Symbol`
    Returns:
      true if this an external symbol.
    See Also:
      - `Address.isExternalAddress()`