Package ghidra.trace.database.target

Class DBTraceObject

java.lang.Object
ghidra.program.database.DatabaseObject
ghidra.util.database.DBAnnotatedObject
ghidra.trace.database.target.DBTraceObject
All Implemented Interfaces:
TraceObject, TraceUniqueObject
public class DBTraceObject extends DBAnnotatedObject implements TraceObject

  • Field Details

  • Constructor Details

  • Method Details

    • 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.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • freshIfaces

      protected void freshIfaces()

    • set

      protected void set(KeyPath path)

    • getTrace

      public DBTrace getTrace()
      Description copied from interface: TraceObject
      Get the trace containing this object
      Specified by:
      getTrace in interface TraceObject
      Returns:
      the trace

    • getManager

      public DBTraceObjectManager getManager()

    • getRoot

      public DBTraceObject getRoot()
      Description copied from interface: TraceObject
      Get the root of the tree containing this object
      Specified by:
      getRoot in interface TraceObject
      Returns:
      the root

    • getCanonicalPath

      public KeyPath getCanonicalPath()
      Description copied from interface: TraceObject
      Get the canonical path of this object
      Specified by:
      getCanonicalPath in interface TraceObject
      Returns:
      the path

    • ensureCachedLife

      protected Lifespan.LifeSet ensureCachedLife()

    • getLife

      public Lifespan.LifeSet getLife()
      Description copied from interface: TraceObject
      Get all ranges of this object's life

      Essentially, this is the union of the lifespans of all canonical parent values

      Specified by:
      getLife in interface TraceObject
      Returns:
      the range set for snaps at which this object is considered "inserted."

    • isAlive

      public boolean isAlive(long snap)
      Description copied from interface: TraceObject
      Check if the object is alive at the given snap

      This is preferable to TraceObject.getLife(), when we only need to check one snap

      Specified by:
      isAlive in interface TraceObject
      Parameters:
      snap - the snap
      Returns:
      true if alive, false if not

    • isAlive

      public boolean isAlive(Lifespan span)
      Description copied from interface: TraceObject
      Check if the object is alive at all in the given span
      Specified by:
      isAlive in interface TraceObject
      Parameters:
      span - the span
      Returns:
      true if alive, false if not

    • doCreateCanonicalParentObject

      protected DBTraceObject doCreateCanonicalParentObject()

    • doGetCanonicalParentObject

      protected DBTraceObject doGetCanonicalParentObject()

    • doInsert

      protected DBTraceObjectValPath doInsert(Lifespan lifespan, TraceObject.ConflictResolution resolution)

    • insert

      public DBTraceObjectValPath insert(Lifespan lifespan, TraceObject.ConflictResolution resolution)
      Description copied from interface: TraceObject
      Inserts this object at its canonical path for the given lifespan

      Any ancestor which does not exist is created. Values' lifespans are added or expanded to contain the given lifespan. Only the canonical path is considered when looking for existing ancestry.

      Specified by:
      insert in interface TraceObject
      Parameters:
      lifespan - the minimum lifespan of edges from the root to this object
      resolution - the rule for handling duplicate keys when setting values.
      Returns:
      the value path from root to the newly inserted object

    • doRemove

      protected void doRemove(Lifespan span)

    • remove

      public void remove(Lifespan span)
      Description copied from interface: TraceObject
      Remove this object from its canonical path for the given lifespan

      Truncate the lifespans of this object's canonical parent value by the given span. If the parent value's lifespan is contained in the given span, the parent value will be deleted.

      Specified by:
      remove in interface TraceObject
      Parameters:
      span - the span during which this object should be removed

    • doRemoveTree

      protected void doRemoveTree(Lifespan span)

    • removeTree

      public void removeTree(Lifespan span)
      Description copied from interface: TraceObject
      Remove this object and its successors from their canonical paths for the given span

      Truncate the lifespans of this object's parent values and all canonical values succeeding this object. If a truncated value's lifespan is contained in the given span, the value will be deleted.

      Specified by:
      removeTree in interface TraceObject
      Parameters:
      span - the span during which this object and its canonical successors should be removed

    • streamCanonicalParentsData

      protected Stream<DBTraceObjectValueData> streamCanonicalParentsData(Lifespan lifespan)

    • streamCanonicalParentsBehind

      protected Stream<DBTraceObjectValueBehind> streamCanonicalParentsBehind(Lifespan lifespan)

    • streamCanonicalParents

      protected Stream<DBTraceObjectValue> streamCanonicalParents(Lifespan lifespan)

    • getCanonicalParent

      public TraceObjectValue getCanonicalParent(long snap)
      Description copied from interface: TraceObject
      Get the parent value along this object's canonical path for a given snapshot

      To be the canonical parent value at a given snapshot, three things must be true: 1) The parent object must have this object's path with the final key removed. 2) The parent value's entry key must be equal to the final key of this object's path. 3) The value's lifespan must contain the given snapshot. If no value satisfies these, null is returned, and the object and its subtree are said to be "detached" at the given snapshot.

      Specified by:
      getCanonicalParent in interface TraceObject
      Parameters:
      snap - the snapshot key
      Returns:
      the canonical parent value, or null

    • getCanonicalParents

      public Stream<DBTraceObjectValue> getCanonicalParents(Lifespan lifespan)
      Description copied from interface: TraceObject
      Get the parent values along this object's canonical path for a given lifespan

      To be a canonical parent in a given lifespan, three things must be true: 1) The parent object must have this object's path with the final key removed. 2) The parent value's entry key must be equal to the final key of this object's path. 3) The value's lifespan must intersect the given lifespan. If the result is empty, the object and its subtree are said to be "detatched" during the given lifespan.

      Specified by:
      getCanonicalParents in interface TraceObject
      Parameters:
      lifespan - the lifespan to consider
      Returns:
      the stream of canonical parents

    • isRoot

      public boolean isRoot()
      Description copied from interface: TraceObject
      Check if this object is the root
      Specified by:
      isRoot in interface TraceObject
      Returns:
      true if root

    • getAllPaths

      public Stream<? extends TraceObjectValPath> getAllPaths(Lifespan span)
      Description copied from interface: TraceObject
      Get all paths actually leading to this object, from the root, within the given span

      Aliased keys are excluded.

      Specified by:
      getAllPaths in interface TraceObject
      Parameters:
      span - the span which every value entry on each path must intersect
      Returns:
      the paths

    • getInterfaces

      public Collection<Class<? extends TraceObjectInterface>> getInterfaces()
      Description copied from interface: TraceObject
      Get all the interface classes provided by this object, according to the schema
      Specified by:
      getInterfaces in interface TraceObject
      Returns:
      the collection of interface classes

    • queryInterface

      public <I extends TraceObjectInterface> I queryInterface(Class<I> ifCls)
      Description copied from interface: TraceObject
      Request the specified interface provided by this object
      Specified by:
      queryInterface in interface TraceObject
      Type Parameters:
      I - the type of the interface
      Parameters:
      ifCls - the class of the interface
      Returns:
      the interface, or null if not provided

    • streamParentsData

      protected Stream<DBTraceObjectValueData> streamParentsData(Lifespan lifespan)

    • streamParentsBehind

      protected Stream<DBTraceObjectValueBehind> streamParentsBehind(Lifespan lifespan)

    • streamParents

      protected Stream<DBTraceObjectValue> streamParents(Lifespan lifespan)

    • getParents

      public Collection<DBTraceObjectValue> getParents(Lifespan lifespan)
      Description copied from interface: TraceObject
      Get all values intersecting the given span and whose child is this object

      Aliased keys are excluded.

      Specified by:
      getParents in interface TraceObject
      Parameters:
      lifespan - the span
      Returns:
      the parent values

    • doHasAnyValues

      protected boolean doHasAnyValues()

    • streamValuesData

      protected Stream<DBTraceObjectValueData> streamValuesData(Lifespan lifespan)

    • streamValuesBehind

      protected Stream<DBTraceObjectValueBehind> streamValuesBehind(Lifespan lifespan)

    • streamValuesW

      protected Stream<DBTraceObjectValue> streamValuesW(Lifespan lifespan)

    • streamValuesR

      protected Stream<DBTraceObjectValue> streamValuesR(Lifespan lifespan)

    • doHasAnyParents

      protected boolean doHasAnyParents()

    • doIsConnected

      protected boolean doIsConnected()

    • getValues

      public Collection<DBTraceObjectValue> getValues(Lifespan lifespan)
      Description copied from interface: TraceObject
      Get all values (elements and attributes) of this object intersecting the given span

      Aliased keys are excluded.

      Specified by:
      getValues in interface TraceObject
      Parameters:
      lifespan - the span
      Returns:
      the values

    • getElements

      public Collection<DBTraceObjectValue> getElements(Lifespan lifespan)
      Description copied from interface: TraceObject
      Get all elements of this object intersecting the given span
      Specified by:
      getElements in interface TraceObject
      Parameters:
      lifespan - the span
      Returns:
      the element values

    • getAttributes

      public Collection<DBTraceObjectValue> getAttributes(Lifespan lifespan)
      Description copied from interface: TraceObject
      Get all attributes of this object intersecting the given span

      Aliased keys are excluded.

      Specified by:
      getAttributes in interface TraceObject
      Parameters:
      lifespan - the span
      Returns:
      the attribute values

    • doCheckConflicts

      protected void doCheckConflicts(Lifespan span, String key, Object value)

    • doAdjust

      protected Lifespan doAdjust(Lifespan span, String key, Object value)

    • streamValuesData

      protected Stream<DBTraceObjectValueData> streamValuesData(Lifespan span, String key, boolean forward)

    • streamValuesBehind

      protected Stream<DBTraceObjectValueBehind> streamValuesBehind(Lifespan span, String key, boolean forward)

    • streamValuesW

      protected Stream<DBTraceObjectValue> streamValuesW(Lifespan span, String key, boolean forward)

    • streamValuesR

      protected Stream<DBTraceObjectValue> streamValuesR(Lifespan span, String key, boolean forward)

    • getValues

      public Collection<? extends DBTraceObjectValue> getValues(Lifespan span, String key)
      Description copied from interface: TraceObject
      Get values with the given key intersecting the given span

      If the key is an alias, the target key's values are retrieved instead.

      Specified by:
      getValues in interface TraceObject
      Parameters:
      span - the span
      key - the key
      Returns:
      the collection of values

    • getValueW

      protected DBTraceObjectValue getValueW(long snap, String key)

    • getValueR

      protected DBTraceObjectValue getValueR(long snap, String key)

    • getValue

      public DBTraceObjectValue getValue(long snap, String key)
      Description copied from interface: TraceObject
      Get the value for the given snap and key

      If the key is an alias, the target key's value is retrieved instead.

      Specified by:
      getValue in interface TraceObject
      Parameters:
      snap - the snap
      key - the key
      Returns:
      the value entry

    • getOrderedValues

      public Stream<DBTraceObjectValue> getOrderedValues(Lifespan span, String key, boolean forward)
      Description copied from interface: TraceObject
      Get values with the given key intersecting the given span ordered by time

      If the key is an alias, the target key's values are retrieved instead.

      Specified by:
      getOrderedValues in interface TraceObject
      Parameters:
      span - the span
      key - the key
      forward - true to order from least- to most-recent, false for most- to least-recent
      Returns:
      the stream of values

    • getElement

      public DBTraceObjectValue getElement(long snap, String index)
      Description copied from interface: TraceObject
      Get the value for the given snap and element index

      This is equivalent to TraceObject.getValue(long, String), but converts index to a key, i.e., adds brackets.

      Specified by:
      getElement in interface TraceObject
      Parameters:
      snap - the snap
      index - the index
      Returns:
      the value entry

    • getElement

      public DBTraceObjectValue getElement(long snap, long index)
      Description copied from interface: TraceObject
      Get the value for the given snap and element index

      This is equivalent to TraceObject.getElement(long, String), but converts index to a string in decimal.

      Specified by:
      getElement in interface TraceObject
      Parameters:
      snap - the snap
      index - the index
      Returns:
      the value entry

    • getAttribute

      public TraceObjectValue getAttribute(long snap, String name)
      Description copied from interface: TraceObject
      Get the value for the given snap and attribute name

      This is equivalent to TraceObject.getValue(long, String), except it validates that name is not an index.

      Specified by:
      getAttribute in interface TraceObject
      Parameters:
      snap - the snap
      name - the name
      Returns:
      the value entry

    • doStreamVisitor

      protected Stream<? extends TraceObjectValPath> doStreamVisitor(Lifespan span, TreeTraversal.Visitor visitor)

    • getAncestors

      public Stream<? extends TraceObjectValPath> getAncestors(Lifespan span, PathFilter relativeFilter)
      Description copied from interface: TraceObject
      Stream all ancestor values of this object matching the given filter, intersecting the given span

      Aliased keys are excluded. The filter should be formulated to use the aliases' target attributes.

      Specified by:
      getAncestors in interface TraceObject
      Parameters:
      span - a span which values along the path must intersect
      relativeFilter - the filter for matching path keys, relative to this object
      Returns:
      the stream of matching paths to values

    • getAncestorsRoot

      public Stream<? extends TraceObjectValPath> getAncestorsRoot(Lifespan span, PathFilter rootFilter)
      Description copied from interface: TraceObject
      Stream all ancestor values of this object matching the given filter, intersecting the given span

      Aliased keys are excluded. The filter should be formulated to use the aliases' target attributes.

      Specified by:
      getAncestorsRoot in interface TraceObject
      Parameters:
      span - a span which values along the path must intersect
      rootFilter - the filter for matching path keys, relative to the root
      Returns:
      the stream of matching paths to values

    • getSuccessors

      public Stream<? extends TraceObjectValPath> getSuccessors(Lifespan span, PathFilter relativeFilter)
      Description copied from interface: TraceObject
      Stream all successor values of this object matching the given filter, intersecting the given span

      Aliased keys are excluded. The filter should be formulated to use the aliases' target attributes.

      Specified by:
      getSuccessors in interface TraceObject
      Parameters:
      span - a span which values along the path must intersect
      relativeFilter - the filter for matching path keys, relative to this object
      Returns:
      the stream of matching paths to values

    • getOrderedSuccessors

      public Stream<? extends TraceObjectValPath> getOrderedSuccessors(Lifespan span, KeyPath relativePath, boolean forward)
      Description copied from interface: TraceObject
      Stream all successor values of this object at the given relative path, intersecting the given span, ordered by time.

      Aliased keys are excluded. The filter should be formulated to use the aliases' target attributes.

      Specified by:
      getOrderedSuccessors in interface TraceObject
      Parameters:
      span - the span which values along the path must intersect
      relativePath - the path relative to this object
      forward - true to order from least- to most-recent, false for most- to least-recent
      Returns:
      the stream of value paths

    • getCanonicalSuccessors

      public Stream<? extends TraceObjectValPath> getCanonicalSuccessors(PathFilter relativeFilter)
      Description copied from interface: TraceObject
      Stream all canonical successor values of this object matching the given filter

      If an object has a disjoint life, i.e., multiple canonical parents, then only the least-recent of those is traversed. Aliased keys are excluded; those can't be canonical anyway. By definition, a primitive value is not canonical, even if it is the final value in the path.

      Specified by:
      getCanonicalSuccessors in interface TraceObject
      Parameters:
      relativeFilter - filter on the relative path from this object to desired successors
      Returns:
      the stream of value paths

    • doCreateValue

      protected DBTraceObjectValue doCreateValue(Lifespan lifespan, String key, Object value)

    • setValue

      public DBTraceObjectValue setValue(Lifespan lifespan, String key, Object value, TraceObject.ConflictResolution resolution)
      Description copied from interface: TraceObject
      Set a value for the given lifespan

      If the key is an alias, the target key's value is set instead.

      Specified by:
      setValue in interface TraceObject
      Parameters:
      lifespan - the lifespan of the value
      key - the key to set
      value - the new value
      resolution - determines how to resolve duplicate keys with intersecting lifespans
      Returns:
      the created value entry

    • setValue

      public TraceObjectValue setValue(Lifespan lifespan, String key, Object value)
      Description copied from interface: TraceObject
      Set a value for the given lifespan, truncating existing entries

      Setting a value of null effectively deletes the value for the given lifespan and returns null. Values of the same key intersecting the given lifespan or either truncated or deleted. If the key is an alias, the target key's value is set instead.

      Specified by:
      setValue in interface TraceObject
      Parameters:
      lifespan - the lifespan of the value
      key - the key to set
      value - the new value
      Returns:
      the created value entry, or null

    • setAttribute

      public TraceObjectValue setAttribute(Lifespan lifespan, String name, Object value)
      Description copied from interface: TraceObject
      Set an attribute for the given lifespan

      This is equivalent to TraceObject.setValue(Lifespan, String, Object), except it verifies the key is an attribute name.

      Specified by:
      setAttribute in interface TraceObject
      Parameters:
      lifespan - the lifespan of the attribute
      name - the name to set
      value - the new value
      Returns:
      the created value entry

    • setElement

      public TraceObjectValue setElement(Lifespan lifespan, String index, Object value)
      Description copied from interface: TraceObject
      Set an element for the given lifespan

      This is equivalent to TraceObject.setValue(Lifespan, String, Object), except it converts the index to a key, i.e., add brackets.

      Specified by:
      setElement in interface TraceObject
      Parameters:
      lifespan - the lifespan of the element
      index - the index to set
      value - the new value
      Returns:
      the created value entry

    • setElement

      public TraceObjectValue setElement(Lifespan lifespan, long index, Object value)
      Description copied from interface: TraceObject
      Set an element for the given lifespan
      Specified by:
      setElement in interface TraceObject
      Parameters:
      lifespan - the lifespan of the element
      index - the index to set
      value - the new value
      Returns:
      the created value entry

    • getSchema

      public TraceObjectSchema getSchema()
      Description copied from interface: TraceObject
      Get the schema for this object
      Specified by:
      getSchema in interface TraceObject
      Returns:
      the schema

    • findAncestorsInterface

      public Stream<? extends TraceObjectValPath> findAncestorsInterface(Lifespan span, Class<? extends TraceObjectInterface> iface)
      Description copied from interface: TraceObject
      Search for ancestors having the given interface
      Specified by:
      findAncestorsInterface in interface TraceObject
      Parameters:
      span - the span which the found objects must intersect
      iface - the interface class
      Returns:
      the stream of found paths to values

    • queryAncestorsInterface

      public <I extends TraceObjectInterface> Stream<I> queryAncestorsInterface(Lifespan span, Class<I> iface)
      Description copied from interface: TraceObject
      Search for ancestors having the given interface and retrieve those interfaces
      Specified by:
      queryAncestorsInterface in interface TraceObject
      Type Parameters:
      I - the interface type
      Parameters:
      span - the span which the found objects must intersect
      iface - the interface class
      Returns:
      the stream of interfaces

    • findOrCreateCanonicalAncestorInterface

      public TraceObject findOrCreateCanonicalAncestorInterface(Class<? extends TraceObjectInterface> iface)

    • queryOrCreateCanonicalAncestorInterface

      public <I extends TraceObjectInterface> I queryOrCreateCanonicalAncestorInterface(Class<I> iface)

    • findCanonicalAncestorsInterface

      public Stream<? extends TraceObject> findCanonicalAncestorsInterface(Class<? extends TraceObjectInterface> iface)
      Description copied from interface: TraceObject
      Search for ancestors on the canonical path having the given interface

      The object may not yet be inserted at its canonical path.

      Specified by:
      findCanonicalAncestorsInterface in interface TraceObject
      Parameters:
      iface - the interface class
      Returns:
      the stream of objects

    • queryCanonicalAncestorsInterface

      public <I extends TraceObjectInterface> Stream<I> queryCanonicalAncestorsInterface(Class<I> iface)
      Description copied from interface: TraceObject
      Search for ancestors on the canonical path having the given interface and retrieve those interfaces

      The object may not yet be inserted at its canonical path.

      Specified by:
      queryCanonicalAncestorsInterface in interface TraceObject
      Type Parameters:
      I - the interface type
      Parameters:
      iface - the interface class
      Returns:
      the stream of interfaces

    • findSuccessorsInterface

      public Stream<? extends TraceObjectValPath> findSuccessorsInterface(Lifespan span, Class<? extends TraceObjectInterface> iface, boolean requireCanonical)
      Description copied from interface: TraceObject
      Search for successors having the given interface
      Specified by:
      findSuccessorsInterface in interface TraceObject
      Parameters:
      span - the span which the found paths must intersect
      iface - the interface class
      requireCanonical - if the objects must be found within their canonical container
      Returns:
      the stream of found paths to values

    • querySuccessorsInterface

      public <I extends TraceObjectInterface> Stream<I> querySuccessorsInterface(Lifespan span, Class<I> iface, boolean requireCanonical)
      Description copied from interface: TraceObject
      Search for successors having the given interface and retrieve those interfaces
      Specified by:
      querySuccessorsInterface in interface TraceObject
      Type Parameters:
      I - the interface type
      Parameters:
      span - the span which the found objects must intersect
      iface - the interface class
      requireCanonical - if the objects must be found within their canonical container
      Returns:
      the stream of interfaces

    • doDelete

      protected void doDelete()

    • doDeleteReferringValues

      protected void doDeleteReferringValues()

    • delete

      public void delete()
      Description copied from interface: TraceObject
      Delete this object along with parent and child value entries referring to it

      Warning: This will remove the object from the manager entirely, not just over a given span. In general, this is used for cleaning and maintenance. Consider TraceObject.remove(Lifespan) or TraceObjectValue.delete() instead. Note, this does not delete the child objects or any successors. It is not recommended to invoke this on the root object, since it cannot be replaced without first clearing the manager.

      Specified by:
      delete in interface TraceObject

    • emitEvents

      protected void emitEvents(TraceChangeRecord<?,?> rec)

    • notifyValueCreated

      protected void notifyValueCreated(DBTraceObjectValue value)

    • notifyValueDeleted

      protected void notifyValueDeleted(DBTraceObjectValue value)

    • notifyParentValueCreated

      protected void notifyParentValueCreated(DBTraceObjectValue parent)

    • notifyParentValueDeleted

      protected void notifyParentValueDeleted(DBTraceObjectValue parent)