Package ghidra.program.database

# Class DatabaseObject

java.lang.Object
ghidra.program.database.DatabaseObject

Direct Known Subclasses:
  `BookmarkDB`, `DBAnnotatedObject`, `EquateDB`, `FunctionDB`, `FunctionTagDB`, `InstructionDB`, `PropertyMapDB`, `SourceArchiveDB`, `SymbolDB`

public abstract class DatabaseObject extends Object
Base class for an cached object in the database. Database objects have keys. They are marked as invalid when a database cache is cleared and can be revived on a refresh as long as they haven't been deleted. Instantiating an object will cause it to be added immediately to the associated cache.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected long`
  `key`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `DatabaseObject(DBObjectCache cache, long key)`
  Constructs a new DatabaseObject and adds it to the specified cache.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `checkDeleted()`
  Checks if this object has been deleted, in which case any use of the object is not allowed.
  `protected boolean`
  `checkIsValid()`
  Check whether this object is still valid.
  `protected boolean`
  `checkIsValid(DBRecord record)`
  Check whether this object is still valid.
  `long`
  `getKey()`
  Get the database key for this object.
  `boolean`
  `isDeleted(Lock lock)`
  Returns true if this object has been deleted.
  `protected boolean`
  `isInvalid()`
  Returns true if object is currently invalid and must be validated prior to further use.
  `protected void`
  `keyChanged(long newKey)`
  `protected abstract boolean`
  `refresh()`
  Tells the object to refresh its state from the database.
  `protected boolean`
  `refresh(DBRecord record)`
  Tells the object to refresh its state from the database using the specified record if not null.
  `protected void`
  `setDeleted()`
  Marks the object as deleted.
  `void`
  `setInvalid()`
  Invalidate this object.
  `protected boolean`
  `validate(Lock lock)`
  This method provides a cheap (lock free) way to test if an object is valid.

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

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

- ## Field Details

  - ### key

    protected long key

- ## Constructor Details

  - ### DatabaseObject

    protected DatabaseObject(DBObjectCache cache, long key)
    Constructs a new DatabaseObject and adds it to the specified cache.
    Parameters:
      `cache` - to be used for this object or null if object will not be cached
      `key` - database key to uniquely identify this object

- ## Method Details

  - ### getKey

    public long getKey()
    Get the database key for this object.

  - ### setDeleted

    protected void setDeleted()
    Marks the object as deleted.

  - ### setInvalid

    public void setInvalid()
    Invalidate this object. This does not necessarily mean that this object can never be used again. If the object can refresh itself, it may still be useable.

  - ### keyChanged

    protected void keyChanged(long newKey)

  - ### isInvalid

    protected boolean isInvalid()
    Returns true if object is currently invalid and must be validated prior to further use. A deleted object will be considered valid since it cannot be refreshed. An invalid object may result from a cache invalidation which corresponds to wide-spread record changes. A common situation where this can occur is an undo/redo operation against the underlying database. The methods `checkIsValid()`, `checkDeleted()`, `validate(Lock)` and `isDeleted(Lock)` are methods which will force a re-validation if required.
    Returns:
      true if this object is invalid and must be re-validated, else false if object state is currently valid which may include a deleted state.

  - ### checkDeleted

    protected void checkDeleted()
    Checks if this object has been deleted, in which case any use of the object is not allowed. This method should be invoked before any modifications to the object are performed to ensure it still exists and is in a valid state.
    Throws:
      `ConcurrentModificationException` - if the object has been deleted from the database.

  - ### checkIsValid

    protected boolean checkIsValid()
    Check whether this object is still valid. If the object is invalid, the object will attempt to refresh itself. If the refresh fails, the object will be marked as deleted.
    Returns:
      true if the object is valid, else false if deleted

  - ### checkIsValid

    protected boolean checkIsValid(DBRecord record)
    Check whether this object is still valid. If the object is invalid and not deleted, the object will attempt to refresh itself using the specified record. If the refresh fails, the object will be marked as deleted and removed from cache. If this object is already marked as deleted a refresh will not be perormed.

    This method may invoke `refresh(DBRecord)` to perform a refresh. It is important that such a refresh avoid recursing back into this method.

    Parameters:
      `record` - optional record which may be used to refresh invalid object
    Returns:
      true if the object is valid or false if it has been deleted.

  - ### validate

    protected boolean validate(Lock lock)
    This method provides a cheap (lock free) way to test if an object is valid. If this object is invalid and not deleted, then the lock will be used to refresh as needed. A deleted object will not be refreshed.
    Parameters:
      `lock` - the lock that will be used if the object needs to be refreshed.
    Returns:
      true if object is valid or false if deleted

  - ### isDeleted

    public boolean isDeleted(Lock lock)
    Returns true if this object has been deleted. Note: once an object has been deleted, it will never be "refreshed". For example, if an object is ever deleted and is resurrected via an "undo", you will have get a fresh instance of the object.
    Parameters:
      `lock` - object cache lock object
    Returns:
      true if this object has been deleted.

  - ### refresh

    protected abstract boolean refresh()
    Tells the object to refresh its state from the database.
    Returns:
      true if the object was able to refresh itself. Return false if the object was deleted. Objects that extend this class must implement a refresh method. If an object can never refresh itself, then it should always return false.

  - ### refresh

    protected boolean refresh(DBRecord record)
    Tells the object to refresh its state from the database using the specified record if not null. NOTE: The default implementation ignores the record and invokes refresh(). Implementations of this method must take care if multiple database tables are used since the record supplied could correspond to another object. In some cases it may be best not to override this method or ignore the record provided.
    Parameters:
      `record` - valid record associated with object's key (optional, may be null to force record lookup or other refresh technique)
    Returns:
      true if the object was able to refresh itself. Return false if record is null and object was deleted. Objects that extend this class must implement a refresh method. If an object can never refresh itself, then it should always return false.