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

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `protected static final class`
  `DBTraceObject.ObjectPathDBFieldCodec`

  ## Nested classes/interfaces inherited from interface ghidra.trace.model.target.TraceObject

  `TraceObject.ConflictResolution`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final DBTraceObjectManager`
  `manager`
  `protected static final String`
  `TABLE_NAME`

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

  `key`

  ### Fields inherited from interface ghidra.trace.model.target.TraceObject

  `EXTRA_INTERFACES_ATTRIBUTE_NAME`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DBTraceObject(DBTraceObjectManager manager, DBCachedObjectStore<?> store, DBRecord record)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `delete()`
  Delete this object along with parent and child value entries referring to it
  `protected Lifespan`
  `doAdjust(Lifespan span, String key, Object value)`
  `protected void`
  `doCheckConflicts(Lifespan span, String key, Object value)`
  `protected DBTraceObject`
  `doCreateCanonicalParentObject()`
  `protected DBTraceObjectValue`
  `doCreateValue(Lifespan lifespan, String key, Object value)`
  `protected void`
  `doDelete()`
  `protected void`
  `doDeleteReferringValues()`
  `protected DBTraceObject`
  `doGetCanonicalParentObject()`
  `protected boolean`
  `doHasAnyParents()`
  `protected boolean`
  `doHasAnyValues()`
  `protected DBTraceObjectValPath`
  `doInsert(Lifespan lifespan, TraceObject.ConflictResolution resolution)`
  `protected boolean`
  `doIsConnected()`
  `protected void`
  `doRemove(Lifespan span)`
  `protected void`
  `doRemoveTree(Lifespan span)`
  `protected Stream<? extends TraceObjectValPath>`
  `doStreamVisitor(Lifespan span, TreeTraversal.Visitor visitor)`
  `protected void`
  `emitEvents(TraceChangeRecord<?,?> rec)`
  `protected Lifespan.LifeSet`
  `ensureCachedLife()`
  `Stream<? extends TraceObjectValPath>`
  `findAncestorsInterface(Lifespan span, Class<? extends TraceObjectInterface> iface)`
  Search for ancestors having the given interface
  `Stream<? extends TraceObject>`
  `findCanonicalAncestorsInterface(Class<? extends TraceObjectInterface> iface)`
  Search for ancestors on the canonical path having the given interface
  `TraceObject`
  `findOrCreateCanonicalAncestorInterface(Class<? extends TraceObjectInterface> iface)`
  `Stream<? extends TraceObjectValPath>`
  `findSuccessorsInterface(Lifespan span, Class<? extends TraceObjectInterface> iface, boolean requireCanonical)`
  Search for successors having the given interface
  `protected void`
  `fresh(boolean created)`
  Extension point: Called when the object's fields are populated.
  `protected void`
  `freshIfaces()`
  `Stream<? extends TraceObjectValPath>`
  `getAllPaths(Lifespan span)`
  Get all paths actually leading to this object, from the root, within the given span
  `Stream<? extends TraceObjectValPath>`
  `getAncestors(Lifespan span, PathFilter relativeFilter)`
  Stream all ancestor values of this object matching the given filter, intersecting the given span
  `Stream<? extends TraceObjectValPath>`
  `getAncestorsRoot(Lifespan span, PathFilter rootFilter)`
  Stream all ancestor values of this object matching the given filter, intersecting the given span
  `TraceObjectValue`
  `getAttribute(long snap, String name)`
  Get the value for the given snap and attribute name
  `Collection<DBTraceObjectValue>`
  `getAttributes(Lifespan lifespan)`
  Get all attributes of this object intersecting the given span
  `TraceObjectValue`
  `getCanonicalParent(long snap)`
  Get the parent value along this object's canonical path for a given snapshot
  `Stream<DBTraceObjectValue>`
  `getCanonicalParents(Lifespan lifespan)`
  Get the parent values along this object's canonical path for a given lifespan
  `KeyPath`
  `getCanonicalPath()`
  Get the canonical path of this object
  `Stream<? extends TraceObjectValPath>`
  `getCanonicalSuccessors(PathFilter relativeFilter)`
  Stream all canonical successor values of this object matching the given filter
  `DBTraceObjectValue`
  `getElement(long snap, long index)`
  Get the value for the given snap and element index
  `DBTraceObjectValue`
  `getElement(long snap, String index)`
  Get the value for the given snap and element index
  `Collection<DBTraceObjectValue>`
  `getElements(Lifespan lifespan)`
  Get all elements of this object intersecting the given span
  `Collection<Class<? extends TraceObjectInterface>>`
  `getInterfaces()`
  Get all the interface classes provided by this object, according to the schema
  `Lifespan.LifeSet`
  `getLife()`
  Get all ranges of this object's life
  `DBTraceObjectManager`
  `getManager()`
  `Stream<? extends TraceObjectValPath>`
  `getOrderedSuccessors(Lifespan span, KeyPath relativePath, boolean forward)`
  Stream all successor values of this object at the given relative path, intersecting the given span, ordered by time.
  `Stream<DBTraceObjectValue>`
  `getOrderedValues(Lifespan span, String key, boolean forward)`
  Get values with the given key intersecting the given span ordered by time
  `Collection<DBTraceObjectValue>`
  `getParents(Lifespan lifespan)`
  Get all values intersecting the given span and whose child is this object
  `DBTraceObject`
  `getRoot()`
  Get the root of the tree containing this object
  `TraceObjectSchema`
  `getSchema()`
  Get the schema for this object
  `Stream<? extends TraceObjectValPath>`
  `getSuccessors(Lifespan span, PathFilter relativeFilter)`
  Stream all successor values of this object matching the given filter, intersecting the given span
  `DBTrace`
  `getTrace()`
  Get the trace containing this object
  `DBTraceObjectValue`
  `getValue(long snap, String key)`
  Get the value for the given snap and key
  `protected DBTraceObjectValue`
  `getValueR(long snap, String key)`
  `Collection<DBTraceObjectValue>`
  `getValues(Lifespan lifespan)`
  Get all values (elements and attributes) of this object intersecting the given span
  `Collection<? extends DBTraceObjectValue>`
  `getValues(Lifespan span, String key)`
  Get values with the given key intersecting the given span
  `protected DBTraceObjectValue`
  `getValueW(long snap, String key)`
  `DBTraceObjectValPath`
  `insert(Lifespan lifespan, TraceObject.ConflictResolution resolution)`
  Inserts this object at its canonical path for the given lifespan
  `boolean`
  `isAlive(long snap)`
  Check if the object is alive at the given snap
  `boolean`
  `isAlive(Lifespan span)`
  Check if the object is alive at all in the given span
  `boolean`
  `isRoot()`
  Check if this object is the root
  `protected void`
  `notifyParentValueCreated(DBTraceObjectValue parent)`
  `protected void`
  `notifyParentValueDeleted(DBTraceObjectValue parent)`
  `protected void`
  `notifyValueCreated(DBTraceObjectValue value)`
  `protected void`
  `notifyValueDeleted(DBTraceObjectValue value)`
  `<I extends TraceObjectInterface>
  Stream<I>`
  `queryAncestorsInterface(Lifespan span, Class<I> iface)`
  Search for ancestors having the given interface and retrieve those interfaces
  `<I extends TraceObjectInterface>
  Stream<I>`
  `queryCanonicalAncestorsInterface(Class<I> iface)`
  Search for ancestors on the canonical path having the given interface and retrieve those interfaces
  `<I extends TraceObjectInterface>
  I`
  `queryInterface(Class<I> ifCls)`
  Request the specified interface provided by this object
  `<I extends TraceObjectInterface>
  I`
  `queryOrCreateCanonicalAncestorInterface(Class<I> iface)`
  `<I extends TraceObjectInterface>
  Stream<I>`
  `querySuccessorsInterface(Lifespan span, Class<I> iface, boolean requireCanonical)`
  Search for successors having the given interface and retrieve those interfaces
  `void`
  `remove(Lifespan span)`
  Remove this object from its canonical path for the given lifespan
  `void`
  `removeTree(Lifespan span)`
  Remove this object and its successors from their canonical paths for the given span
  `protected void`
  `set(KeyPath path)`
  `TraceObjectValue`
  `setAttribute(Lifespan lifespan, String name, Object value)`
  Set an attribute for the given lifespan
  `TraceObjectValue`
  `setElement(Lifespan lifespan, long index, Object value)`
  Set an element for the given lifespan
  `TraceObjectValue`
  `setElement(Lifespan lifespan, String index, Object value)`
  Set an element for the given lifespan
  `TraceObjectValue`
  `setValue(Lifespan lifespan, String key, Object value)`
  Set a value for the given lifespan, truncating existing entries
  `DBTraceObjectValue`
  `setValue(Lifespan lifespan, String key, Object value, TraceObject.ConflictResolution resolution)`
  Set a value for the given lifespan
  `protected Stream<DBTraceObjectValue>`
  `streamCanonicalParents(Lifespan lifespan)`
  `protected Stream<DBTraceObjectValueBehind>`
  `streamCanonicalParentsBehind(Lifespan lifespan)`
  `protected Stream<DBTraceObjectValueData>`
  `streamCanonicalParentsData(Lifespan lifespan)`
  `protected Stream<DBTraceObjectValue>`
  `streamParents(Lifespan lifespan)`
  `protected Stream<DBTraceObjectValueBehind>`
  `streamParentsBehind(Lifespan lifespan)`
  `protected Stream<DBTraceObjectValueData>`
  `streamParentsData(Lifespan lifespan)`
  `protected Stream<DBTraceObjectValueBehind>`
  `streamValuesBehind(Lifespan lifespan)`
  `protected Stream<DBTraceObjectValueBehind>`
  `streamValuesBehind(Lifespan span, String key, boolean forward)`
  `protected Stream<DBTraceObjectValueData>`
  `streamValuesData(Lifespan lifespan)`
  `protected Stream<DBTraceObjectValueData>`
  `streamValuesData(Lifespan span, String key, boolean forward)`
  `protected Stream<DBTraceObjectValue>`
  `streamValuesR(Lifespan lifespan)`
  `protected Stream<DBTraceObjectValue>`
  `streamValuesR(Lifespan span, String key, boolean forward)`
  `protected Stream<DBTraceObjectValue>`
  `streamValuesW(Lifespan lifespan)`
  `protected Stream<DBTraceObjectValue>`
  `streamValuesW(Lifespan span, String key, boolean forward)`
  `String`
  `toString()`

  ### 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, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface ghidra.trace.model.target.TraceObject

  `findRegisterContainer, findSuitableContainerInterface, findSuitableInterface, findSuitableSchema, getExecutionState, getKey, isDeleted, isMethod`

  ### Methods inherited from interface ghidra.trace.model.TraceUniqueObject

  `getObjectKey`

- ## Field Details

  - ### TABLE_NAME

    protected static final String TABLE_NAME
    See Also:
      - Constant Field Values

  - ### manager

    protected final DBTraceObjectManager manager

- ## Constructor Details

  - ### DBTraceObject

    public DBTraceObject(DBTraceObjectManager manager, DBCachedObjectStore<?> store, DBRecord record)

- ## 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)