Package ghidra.trace.model.target

# Interface TraceObjectManager

All Known Implementing Classes:
  `DBTraceObjectManager`

public interface TraceObjectManager
A store of objects observed over time in a trace

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `clear()`
  Delete the entire object model, including the schema
  `TraceObject`
  `createObject(KeyPath path)`
  Create (or get) an object with the given canonical path
  `TraceObjectValue`
  `createRootObject(TraceObjectSchema schema)`
  Creates the root object of the model, fixing its schema
  `void`
  `cullDisconnectedObjects()`
  For maintenance, remove all disconnected objects
  `Stream<? extends TraceObject>`
  `getAllObjects()`
  Get all the objects in the database
  `Stream<? extends TraceObjectValue>`
  `getAllValues()`
  Get all the values (edges) in the database
  `TraceObject`
  `getObjectByCanonicalPath(KeyPath path)`
  Get objects in the database having the given canonical path
  `TraceObject`
  `getObjectById(long key)`
  Get the object with the given database key, if it exists
  `int`
  `getObjectCount()`
  Get the number of objects in the database
  `Stream<? extends TraceObject>`
  `getObjectsByPath(Lifespan span, KeyPath path)`
  Get objects in the database having the given path intersecting the given span
  `TraceObject`
  `getRootObject()`
  Get the root object, if it has been created
  `TraceObjectSchema`
  `getRootSchema()`
  Get the schema of the root object
  `Trace`
  `getTrace()`
  Get the trace to which the object manager belongs
  `Stream<? extends TraceObjectValPath>`
  `getValuePaths(Lifespan span, PathFilter predicates)`
  Get value entries in the database matching the given predicates intersecting the given span
  `default Collection<? extends TraceObjectValue>`
  `getValuesIntersecting(Lifespan span, AddressRange range)`
  Get all address-ranged values intersecting the given span and address range
  `Collection<? extends TraceObjectValue>`
  `getValuesIntersecting(Lifespan span, AddressRange range, String entryKey)`
  Get all address-ranged values intersecting the given span and address range
  `<I extends TraceObjectInterface>
  Stream<I>`
  `queryAllInterface(Lifespan span, Class<I> iface)`
  Get all interfaces of the given type in the database
  `TraceObjectSchema`
  `requireRootSchema()`
  Get the schema of the root object, failing if no root object exists

- ## Method Details

  - ### getTrace

    Trace getTrace()
    Get the trace to which the object manager belongs
    Returns:
      the trace

  - ### createRootObject

    TraceObjectValue createRootObject(TraceObjectSchema schema)
    Creates the root object of the model, fixing its schema

    Note the schema cannot be changed once the root object is created. The only means to "change" the schema is to delete the root object (and thus the entire tree) then re-create the root object with the new schema.

    Parameters:
      `schema` - the schema
    Returns:
      the new object

  - ### createObject

    TraceObject createObject(KeyPath path)
    Create (or get) an object with the given canonical path
    Parameters:
      `path` - the object's canonical path
    Returns:
      the new object

  - ### getRootSchema

    TraceObjectSchema getRootSchema()
    Get the schema of the root object
    Returns:
      the schema or null

  - ### requireRootSchema

    TraceObjectSchema requireRootSchema()
    Get the schema of the root object, failing if no root object exists
    Returns:
      the schema

  - ### getRootObject

    TraceObject getRootObject()
    Get the root object, if it has been created
    Returns:
      the root object, or null

  - ### getObjectById

    TraceObject getObjectById(long key)
    Get the object with the given database key, if it exists
    Parameters:
      `key` - the desired object's key
    Returns:
      the object, or null

  - ### getObjectByCanonicalPath

    TraceObject getObjectByCanonicalPath(KeyPath path)
    Get objects in the database having the given canonical path
    Parameters:
      `path` - the canonical path of the desired objects
    Returns:
      the collection of objects

  - ### getObjectsByPath

    Stream<? extends TraceObject> getObjectsByPath(Lifespan span, KeyPath path)
    Get objects in the database having the given path intersecting the given span
    Parameters:
      `span` - the span that desired objects' lifespans must intersect
      `path` - the path of the desired objects
    Returns:
      the iterable of objects

  - ### getValuePaths

    Stream<? extends TraceObjectValPath> getValuePaths(Lifespan span, PathFilter predicates)
    Get value entries in the database matching the given predicates intersecting the given span

    While the manager does not maintain integrity wrt. child lifespans and that of their parents, nor even the connectivity of objects to their canonical parents, this search depends on that consistency. An object may not be discovered unless it is properly connected to the root object. Furthermore, it will not be discovered unless it and its ancestors' lifespans all intersect the given span.

    Parameters:
      `span` - the span that desired objects' lifespans must intersect
      `predicates` - predicates to match the desired objects
    Returns:
      an iterator over the matching objects

  - ### getAllObjects

    Stream<? extends TraceObject> getAllObjects()
    Get all the objects in the database
    Returns:
      the stream of all objects

  - ### getObjectCount

    int getObjectCount()
    Get the number of objects in the database
    Returns:
      the number of objects

  - ### getAllValues

    Stream<? extends TraceObjectValue> getAllValues()
    Get all the values (edges) in the database
    Returns:
      the stream of all values

  - ### getValuesIntersecting

    Collection<? extends TraceObjectValue> getValuesIntersecting(Lifespan span, AddressRange range, String entryKey)
    Get all address-ranged values intersecting the given span and address range
    Parameters:
      `span` - the span that desired values lifespans must intersect
      `range` - the range that desired address-ranged values must intersect
      `entryKey` - the entry key if a single one should be matched, or null for any
    Returns:
      the collection of values

  - ### getValuesIntersecting

    default Collection<? extends TraceObjectValue> getValuesIntersecting(Lifespan span, AddressRange range)
    Get all address-ranged values intersecting the given span and address range
    Parameters:
      `span` - the span that desired values lifespans must intersect
      `range` - the range that desired address-ranged values must intersect
    Returns:
      the collection of values

  - ### queryAllInterface

    <I extends TraceObjectInterface> Stream<I> queryAllInterface(Lifespan span, Class<I> iface)
    Get all interfaces of the given type in the database
    Type Parameters:
      `I` - the type of the desired interface
    Parameters:
      `span` - the span that desired objects must intersect
      `iface` - the class of the desired interface
    Returns:
      the collection of all instances of the given interface

  - ### cullDisconnectedObjects

    void cullDisconnectedObjects()
    For maintenance, remove all disconnected objects

    An object is disconnected if it is neither the child nor parent of any value for any span. In other words, it's unused.

  - ### clear

    void clear()
    Delete the entire object model, including the schema

    This is the only mechanism to modify the schema. This should almost never be necessary, because a connector should provide its immutable schema immediately. Nevertheless, the database permits schema modification, but requires that the entire model be replaced.