Package ghidra.util.database

Class DBCachedObjectStore<T extends DBAnnotatedObject>

java.lang.Object
ghidra.util.database.DBCachedObjectStore<T>
Type Parameters:
T - the type of objects stored
All Implemented Interfaces:
ErrorHandler
public class DBCachedObjectStore<T extends DBAnnotatedObject> extends Object implements ErrorHandler
An object store backed by a Table

Essentially, this provides object-based accessed to records in the table via DAOs. See DBAnnotatedObject for further documentation including an example object definition. The store keeps a cache of objects using DBObjectCache. See DBCachedObjectStoreFactory for documentation describing how to create a store, including for the example object definition.

The store provides views for locating, iterating, and retrieving its objects in a variety of fashions. This includes the primary key (object id), or any indexed column (see DBAnnotatedField.indexed()). These views generally implement an interface from Java's Collections API, providing for familiar semantics. A notable exception is that none of the interfaces support mutation, aside from deletion. The store is populated only via the create() methods.

  • Field Details

  • Constructor Details

  • Method Details

    • getRecordCount

      public int getRecordCount()
      Get the number of objects (records) in this store
      Returns:
      the record count

    • getMaxKey

      public Long getMaxKey()
      Get the maximum key which has ever existed in this store

      Note, the returned key may not actually be present

      Returns:
      the maximum, or null if the store is unused

    • getKeyCount

      protected int getKeyCount(KeySpan keySpan)
      Count the number of keys in a given range.

      This implementation is not very efficient. It must visit at least every record in the range.

      Parameters:
      keySpan - the range of keys
      Returns:
      the count of records whose keys fall within the range

    • getKeysExist

      protected boolean getKeysExist(KeySpan keySpan)
      Check if any keys exist within the given range.

      This implementation is more efficient than using getKeyCount(KeySpan) and comparing to 0, since there's no need to visit more than one record in the range.

      Parameters:
      keySpan - the range of keys
      Returns:
      true if at least one record has a key within the range

    • containsKey

      public boolean containsKey(long key)
      Check if an object with the given key exists in the store

      Using this is preferred to getObjectAt(long) and checking for null, if that object does not actually need to be retrieved.

      Parameters:
      key - the key
      Returns:
      true if it exists

    • contains

      public boolean contains(T obj)
      Check if the given object exists in the store

      No matter the definition of Object.equals(Object), this requires the identical object to be present.

      Parameters:
      obj - the object
      Returns:

    • doCreate

      protected T doCreate(long key) throws IOException
      Throws:
      IOException

    • create

      public T create(long key)
      Create a new object with the given key.

      If the key already exists in the table, the existing record is overwritten.

      Parameters:
      key - the key for the new object
      Returns:
      the new object

    • create

      public T create()
      Create a new object with the next available key.
      Returns:
      the new object

    • getColumnByName

      protected int getColumnByName(String name)
      Get the column number given a column name
      Parameters:
      name - the name
      Returns:
      the number (0-up index) for the column
      Throws:
      NoSuchElementException - if no column with the given name exists

    • getIndex

      protected <K> DBCachedObjectIndex<K,T> getIndex(Class<K> fieldClass, int columnIndex)
      Get the table index for the given column number
      Type Parameters:
      K - the type of the object field for the indexed column
      Parameters:
      fieldClass - the class specifying DBCachedObjectStore
      columnIndex - the column number
      Returns:
      the index
      Throws:
      IllegalArgumentException - if the column has a different type than DBCachedObjectStore

    • getIndex

      public <K> DBCachedObjectIndex<K,T> getIndex(Class<K> fieldClass, DBObjectColumn column)
      Get the index for a given column

      See DBCachedObjectStoreFactory for an example that includes use of an index

      Type Parameters:
      K - the type of the object field for the indexed column
      Parameters:
      fieldClass - the class specifying DBCachedObjectStore
      column - the indexed column
      Returns:
      the index
      Throws:
      IllegalArgumentException - if the column has a different type than DBCachedObjectStore

    • getIndex

      public <K> DBCachedObjectIndex<K,T> getIndex(Class<K> fieldClass, String columnName)
      Get the index for a given column by name

      See DBCachedObjectStoreFactory for an example that includes use of an index

      Type Parameters:
      K - the type of the object field for the indexed column
      Parameters:
      fieldClass - the class specifying DBCachedObjectStore
      columnName - the name of the indexed column
      Returns:
      the index
      Throws:
      IllegalArgumentException - if the given column is not indexed

    • delete

      public boolean delete(T obj)
      Delete the given object
      Parameters:
      obj - the object
      Returns:
      true if the object was removed, false for no effect

    • deleteKey

      public T deleteKey(long key)
      Delete the object with the given key
      Parameters:
      key - the key
      Returns:
      true if the key was removed, false for no effect

    • deleteAll

      public void deleteAll()
      Clear the entire table

    • deleteKeys

      protected void deleteKeys(KeySpan keySpan)

    • safe

      protected <U> U safe(Lock l, DBCachedObjectStore.SupplierAllowsIOException<U> supplier)
      Invoke the given supplier with a lock, directing IOExceptions to the domain object adapter
      Type Parameters:
      U - the type of the result
      Parameters:
      l - the lock to hold during invocation
      supplier - the supplier to invoke
      Returns:
      the result

    • getObjectAt

      public T getObjectAt(long key)
      Get the object having the given key
      Parameters:
      key - the key
      Returns:
      the object, or null

    • keyComparator

      protected Comparator<? super Long> keyComparator()
      Get the key comparator
      Returns:
      the comparator
      Implementation Notes:
      this is probably vestigial, left from when we attempted to allow customization of the primary key. This currently just gives the natural ordering of longs.

    • asMap

      public DBCachedObjectStoreMap<T> asMap()
      Provides access to the store as a NavigableMap.
      Returns:
      the map

    • findOneObject

      protected T findOneObject(int columnIndex, Field field) throws IOException
      Search a column index for a single object having the given value
      Parameters:
      columnIndex - the indexed column's number
      field - a field holding the value to seek
      Returns:
      the object, if found, or null
      Throws:
      IOException - if there's an issue reading the table
      IllegalStateException - if the object is not unique

    • findObjects

      protected DBCachedObjectStoreFoundKeysValueCollection<T> findObjects(int columnIndex, Field field) throws IOException
      Search a column index for all objects having the given value
      Parameters:
      columnIndex - the indexed column's number
      field - a field holding the value to seek
      Returns:
      the collection of objects found, possibly empty but never null
      Throws:
      IOException - if there's an issue reading the table

    • iterator

      protected Iterator<T> iterator(int columnIndex, FieldSpan fieldSpan, DirectedIterator.Direction direction) throws IOException
      Search a column index and iterate over objects having the given value
      Parameters:
      columnIndex - the indexed column's number
      fieldSpan - required: the range to consider
      direction - the direction of iteration
      Returns:
      the iterator, possibly empty but never null
      Throws:
      IOException - if there's an issue reading the table

    • readLock

      public Lock readLock()
      Get the read lock
      Returns:
      the lock

    • writeLock

      public Lock writeLock()
      Get the write lock
      Returns:
      the lock

    • getLock

      public ReadWriteLock getLock()
      Get the read-write lock
      Returns:
      the lock

    • dbError

      public void dbError(IOException e)
      Description copied from interface: ErrorHandler
      Notification that an IO exception occurred.
      Specified by:
      dbError in interface ErrorHandler
      Parameters:
      e - IOException which was cause of error

    • toString

      public String toString()
      Display useful information about this cached store

      Please avoid calling this except for debugging.

      Overrides:
      toString in class Object
      Returns:
      a string representation of the store's cache

    • getTableName

      public String getTableName()
      Get the name of the table backing this store
      Returns:
      the name

    • invalidateCache

      public void invalidateCache()
      Invalidate this store's cache

      This should be called whenever the table may have changed in a way not caused by the store itself, e.g., whenever DBHandle.undo() is called.