Package ghidra.program.database

Class DatabaseObject

  • Direct Known Subclasses:
    BookmarkDB, EquateDB, FunctionDB, FunctionTagDB, InstructionDB, SourceArchiveDB, SymbolDB
    public abstract class DatabaseObject
extends java.lang.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

      All Methods Instance Methods Abstract Methods Concrete Methods 
      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.
      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 Detail

      • key

        protected long key

    • Constructor Detail

      • 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 Detail

      • getKey

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

      • 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. 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:
        java.util.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, 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, the record can not be used to refresh the object.
        Parameters:
        record - optional record which may be used to refresh invalid object
        Returns:
        true if the object is valid.

      • 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, then the lock will be used to refresh as needed.
        Parameters:
        lock - the lock that will be used if the object needs to be refreshed.
        Returns:
        true if object is valid, else 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.