Package ghidra.util.database

# Class DBCachedObjectStoreFactory

java.lang.Object
ghidra.util.database.DBCachedObjectStoreFactory

public class DBCachedObjectStoreFactory extends Object
A factory for creating object stores for classes extending `DBAnnotatedObject`

See `DBAnnotatedObject` for more documentation, including an example object definition. To create a store, e.g., for `Person`:

     interface MyDomainObject {
     	Person createPerson(String name, String address);

     	Person getPerson(long id);

     	Collection<? extends Person> getPeopleNamed(String name);
     }

     public class DBMyDomainObject extends DBCachedDomainObjectAdapter implements MyDomainObject {
     	private final DBCachedObjectStoreFactory factory;
     	private final DBCachedObjectStore<DBPerson> people;
     	private final DBCachedObjectIndex<String, DBPerson> peopleByName;

     	public DBMyDomainObject() { // Constructor parameters elided
     		// super() invocation elided
     		factory = new DBCachedObjectStoreFactory(this);
     		try {
     			people = factory.getOrCreateCachedStore(DBPerson.TABLE_NAME, DBPerson.class,
     				DBPerson::new, false);
     			peopleByName = people.getIndex(String.class, DBPerson.NAME_COLUMN);
     		}
     		catch (VersionException e) {
     			// ...
     		}
     		catch (IOException e) {
     			// ...
     		}
     	}

     	@Override
     	public Person createPerson(String name, String address) {
     		// Locking details elided
     		DBPerson person = people.create();
     		person.set(name, address);
     		return person;
     	}

     	@Override
     	public Person getPerson(int id) {
     		// Locking details elided
     		return people.getAt(id);
     	}

     	@Override
     	public Collection<Person> getPeopleNamed(String name) {
     		// Locking details elided
     		return peopleByName.get(name);
     	}
     }

The factory manages tables on behalf of the domain object, so it is typically the first thing constructed. In practice, complex domain objects should be composed of several managers, each of which constructs its own stores, but for simplicity in this example, we construct the people store in the domain object. This will check the schema and could throw a `VersionException`. Typically, immediately after constructing the store, all desired indexes of the store are retrieved. The domain object then provides API methods for creating and retrieving people. Providing direct API client access to the store from a domain object is highly discouraged.

Implementation Notes:
  This class bears the responsibility of processing the `DBAnnotatedField`, `DBAnnotatedColumn`, and `DBAnnotatedObjectInfo` annotations. The relevant entry point is {`buildInfo(Class)`. It creates a `DBCachedObjectStoreFactory.TableInfo` for the given class, which builds the schema for creating the `Table` that backs an object store for that class.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `DBCachedObjectStoreFactory.AbstractDBFieldCodec<VT,OT extends DBAnnotatedObject,FT extends Field>`
  An abstract implementation of `DBCachedObjectStoreFactory.DBFieldCodec`
  `static class`
  `DBCachedObjectStoreFactory.BooleanDBFieldCodec<OT extends DBAnnotatedObject>`
  The built-in codec for `boolean`
  `static class`
  `DBCachedObjectStoreFactory.ByteArrayDBFieldCodec<OT extends DBAnnotatedObject>`
  The built-in codec for `byte[]`
  `static class`
  `DBCachedObjectStoreFactory.ByteDBFieldCodec<OT extends DBAnnotatedObject>`
  The built-in codec for `byte`
  `static interface`
  `DBCachedObjectStoreFactory.DBFieldCodec<VT,OT extends DBAnnotatedObject,FT extends Field>`
  A codec for encoding alternative data types
  `static class`
  `DBCachedObjectStoreFactory.EnumDBByteFieldCodec<OT extends DBAnnotatedObject,E extends Enum<E>>`
  The built-in codec for `Enum`
  `static class`
  `DBCachedObjectStoreFactory.IntDBFieldCodec<OT extends DBAnnotatedObject>`
  The built-in codec for `int`
  `static class`
  `DBCachedObjectStoreFactory.LongArrayDBFieldCodec<OT extends DBAnnotatedObject>`
  The built-in codec for `long[]`
  `static class`
  `DBCachedObjectStoreFactory.LongDBFieldCodec<OT extends DBAnnotatedObject>`
  The built-in codec for `long`
  `static interface`
  `DBCachedObjectStoreFactory.PrimitiveCodec<T>`
  Codec for a primitive type
  `static final record`
  `DBCachedObjectStoreFactory.RecAddress`
  `static final record`
  `DBCachedObjectStoreFactory.RecRange`
  `static class`
  `DBCachedObjectStoreFactory.ShortDBFieldCodec<OT extends DBAnnotatedObject>`
  The built-in codec for `short`
  `static class`
  `DBCachedObjectStoreFactory.StringDBFieldCodec<OT extends DBAnnotatedObject>`
  The built-in codec for `String`
  `static class`
  `DBCachedObjectStoreFactory.VariantDBFieldCodec<OT extends DBAnnotatedObject>`
  A custom codec for field of "variant" type

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DBCachedObjectStoreFactory(DBCachedDomainObjectAdapter adapter)`
  Construct an object store factory

- ## Method Summary

  Modifier and Type
  Method
  Description
  `<T extends DBAnnotatedObject>
  DBCachedObjectStore<T>`
  `getOrCreateCachedStore(String tableName, Class<T> cls, DBAnnotatedObjectFactory<T> factory, boolean upgradable)`
  Get or create a cached store of objects of the given class
  `Table`
  `getOrCreateTable(String name, Class<? extends DBAnnotatedObject> cls, boolean upgradable)`
  Get or create the table needed to store objects of the given class

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

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### DBCachedObjectStoreFactory

    public DBCachedObjectStoreFactory(DBCachedDomainObjectAdapter adapter)
    Construct an object store factory
    Parameters:
      `adapter` - the object whose tables to manage

- ## Method Details

  - ### getOrCreateTable

    public Table getOrCreateTable(String name, Class<? extends DBAnnotatedObject> cls, boolean upgradable) throws IOException, VersionException
    Get or create the table needed to store objects of the given class

    See `getOrCreateCachedStore(String, Class, DBAnnotatedObjectFactory, boolean)`

    Parameters:
      `name` - the table name
      `cls` - the type of objects to store
      `upgradable` - true if `VersionException`s should be marked upgradable when an existing table's version is earlier than expected
    Returns:
      the table
    Throws:
      `IOException` - if there's an issue accessing the database
      `VersionException` - if an existing table's version does not match that expected

  - ### getOrCreateCachedStore

    public <T extends DBAnnotatedObject> DBCachedObjectStore<T> getOrCreateCachedStore(String tableName, Class<T> cls, DBAnnotatedObjectFactory<T> factory, boolean upgradable) throws VersionException, IOException
    Get or create a cached store of objects of the given class
    Type Parameters:
      `T` - the type of objects in the store
    Parameters:
      `tableName` - the table name
      `cls` - the class describing `DBCachedObjectStoreFactory`
      `factory` - the object's constructor, usually a method reference or lambda
      `upgradable` - true if `VersionException`s should be marked upgradable when an existing table's version is earlier than expected
    Returns:
      the table
    Throws:
      `IOException` - if there's an issue accessing the database
      `VersionException` - if an existing table's version does not match that expected