Package ghidra.trace.model.property

# Interface TraceAddressPropertyManager

All Known Implementing Classes:
  `DBTraceAddressPropertyManager`

public interface TraceAddressPropertyManager
The manager for user properties of a trace

Clients may create property maps of various value types. Each map is named, also considered the "property name," and can be retrieve by that name.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `<T> TracePropertyMap<T>`
  `createPropertyMap(String name, Class<T> valueClass)`
  Create a property map with the given name having the given type
  `Map<String,TracePropertyMap<?>>`
  `getAllProperties()`
  Get a copy of all the defined properties
  `<T> TracePropertyMap<T>`
  `getOrCreatePropertyMap(String name, Class<T> valueClass)`
  Get the property map with the given name, creating it if necessary, of the given type
  `<T> TracePropertyMap<? super T>`
  `getOrCreatePropertyMapSuper(String name, Class<T> valueClass)`
  Get the property map with the given name, creating it if necessary, of the given type
  `TracePropertyMap<?>`
  `getPropertyMap(String name)`
  Get the property map with the given name.
  `<T> TracePropertyMap<T>`
  `getPropertyMap(String name, Class<T> valueClass)`
  Get the property map with the given name, if it has the given type
  `<T> TracePropertyMap<? extends T>`
  `getPropertyMapExtends(String name, Class<T> valueClass)`
  Get the property map with the given name, if its values extend the given type

- ## Method Details

  - ### createPropertyMap

    <T> TracePropertyMap<T> createPropertyMap(String name, Class<T> valueClass) throws DuplicateNameException
    Create a property map with the given name having the given type

    The following types are supported for valueClass:

    - `Integer`
    - `Long`
    - `String`
    - `Void`: presence or absence of entry satisfies "boolean" use case
    - `? extends` `Saveable`

    Note that for maps of user-defined `Saveable` type, only the specified type is accepted by the map. Attempting to save an extension of that type may lead to undefined behavior, esp., if it attempts to save additional fields. When the value is restored, it will have the type given in `valueClass`, not the extended type.

    Parameters:
      `name` - the name
      `valueClass` - the type of values
    Returns:
      the new property map
    Throws:
      `DuplicateNameException` - if a map of the given name already exists

  - ### getPropertyMap

    <T> TracePropertyMap<T> getPropertyMap(String name, Class<T> valueClass)
    Get the property map with the given name, if it has the given type
    Parameters:
      `name` - the name
      `valueClass` - the expected type of values
    Returns:
      the property map, or null if it does not exist
    Throws:
      `TypeMismatchException` - if it exists but does not have the expected type

  - ### getPropertyMapExtends

    <T> TracePropertyMap<? extends T> getPropertyMapExtends(String name, Class<T> valueClass)
    Get the property map with the given name, if its values extend the given type
    Parameters:
      `name` - the name
      `valueClass` - the expected type of values
    Returns:
      the property map, or null if it does not exist
    Throws:
      `TypeMismatchException` - if it exists but does not have the expected type

  - ### getOrCreatePropertyMap

    <T> TracePropertyMap<T> getOrCreatePropertyMap(String name, Class<T> valueClass)
    Get the property map with the given name, creating it if necessary, of the given type
    Parameters:
      `name` - the name
      `valueClass` - the expected type of values
    Returns:
      the (possibly new) property map
    See Also:
      - `createPropertyMap(String, Class)`

  - ### getOrCreatePropertyMapSuper

    <T> TracePropertyMap<? super T> getOrCreatePropertyMapSuper(String name, Class<T> valueClass)
    Get the property map with the given name, creating it if necessary, of the given type

    If the map already exists, then its values' type must be a super type of that given.

    Parameters:
      `name` - the name
      `valueClass` - the expected type of values
    Returns:
      the (possibly new) property map
    See Also:
      - `getOrCreatePropertyMap(String, Class)`

  - ### getPropertyMap

    TracePropertyMap<?> getPropertyMap(String name)
    Get the property map with the given name.

    Note that no type checking is performed (there is no `valueClass` parameter). Thus, the returned map is suitable only for clearing and querying where the property is present. The caller may perform run-time type checking via the `TracePropertyMapOperations.getValueClass()` method.

    Parameters:
      `name` - the name
    Returns:
      the property map

  - ### getAllProperties

    Map<String,TracePropertyMap<?>> getAllProperties()
    Get a copy of all the defined properties
    Returns:
      the set of names