Class DomainObjectAdapterDB

java.lang.Object
ghidra.framework.data.DomainObjectAdapter
ghidra.framework.data.DomainObjectAdapterDB
All Implemented Interfaces:
DBConstants, ErrorHandler, DomainObject, Undoable, UndoableDomainObject
Direct Known Subclasses:
DataTypeArchiveDB, ProgramDB

public abstract class DomainObjectAdapterDB extends DomainObjectAdapter implements UndoableDomainObject, ErrorHandler, DBConstants
Database version of the DomainObjectAdapter; this version adds the concept of starting a transaction before a change is made to the domain object and ending the transaction. The transaction allows for undo/redo changes. The implementation class must also satisfy the following requirements:

 1. The following constructor signature must be implemented:

                 **
                 * Constructs new Domain Object
                 * @param dbh a handle to an open domain object database.
                 * @param openMode one of:
                 *              READ_ONLY: the original database will not be modified
                 *              UPDATE: the database can be written to.
                 *              UPGRADE: the database is upgraded to the latest schema as it is opened.
                 * @param monitor TaskMonitor that allows the open to be cancelled.
             * @param consumer the object that keeping the program open.
                 *
                 * @throws IOException if an error accessing the database occurs.
                 * @throws VersionException if database version does not match implementation. UPGRADE may be possible.
                 **
                 public DomainObjectAdapterDB(DBHandle dbh, int openMode, TaskMonitor monitor, Object consumer) throws IOException, VersionException

 2. The following static field must be provided:

                 public static final String CONTENT_TYPE

 
  • Field Details

  • Constructor Details

    • DomainObjectAdapterDB

      protected DomainObjectAdapterDB(DBHandle dbh, String name, int timeInterval, Object consumer)
      Construct a new DomainObjectAdapterDB object. If construction of this object fails, be sure to release with consumer
      Parameters:
      dbh - database handle
      name - name of the domain object
      timeInterval - the time (in milliseconds) to wait before the event queue is flushed. If a new event comes in before the time expires, the timer is reset.
      consumer - the object that created this domain object
  • Method Details

    • flushWriteCache

      public void flushWriteCache()
      Flush any pending database changes. This method will be invoked by the transaction manager prior to closing a transaction.
    • invalidateWriteCache

      public void invalidateWriteCache()
      Invalidate (i.e., clear) any pending database changes not yet written. This method will be invoked by the transaction manager prior to aborting a transaction.
    • getSynchronizedDomainObjects

      public DomainObject[] getSynchronizedDomainObjects()
      Return array of all domain objects synchronized with a shared transaction manager.
      Specified by:
      getSynchronizedDomainObjects in interface UndoableDomainObject
      Returns:
      returns array of synchronized domain objects or null if this domain object is not synchronized with others.
    • addSynchronizedDomainObject

      public void addSynchronizedDomainObject(DomainObject domainObj) throws LockException
      Synchronize the specified domain object with this domain object using a shared transaction manager. If either or both is already shared, a transition to a single shared transaction manager will be performed.
      Specified by:
      addSynchronizedDomainObject in interface UndoableDomainObject
      Parameters:
      domainObj -
      Throws:
      LockException - if lock or open transaction is active on either this or the specified domain object
    • releaseSynchronizedDomainObject

      public void releaseSynchronizedDomainObject() throws LockException
      Release this domain object from a shared transaction manager. If this object has not been synchronized with others via a shared transaction manager, this method will have no affect.
      Specified by:
      releaseSynchronizedDomainObject in interface UndoableDomainObject
      Throws:
      LockException - if lock or open transaction is active
    • getDBHandle

      public DBHandle getDBHandle()
      Returns the open handle to the underlying database.
    • getUserData

      protected DomainObjectAdapterDB getUserData()
      Returns the user data object or null if not supported by this domain object.
    • getChangeSet

      public DomainObjectDBChangeSet getChangeSet()
      Returns the change set corresponding to all unsaved changes in this domain object.
      Returns:
      the change set corresponding to all unsaved changes in this domain object
    • dbError

      public void dbError(IOException e)
      Description copied from interface: ErrorHandler
      Notification that an IO exception occurred.
      Specified by:
      dbError in interface ErrorHandler
    • getOptionsNames

      public List<String> getOptionsNames()
      Returns all properties lists contained by this domain object.
      Specified by:
      getOptionsNames in interface DomainObject
      Returns:
      all property lists contained by this domain object.
    • getOptions

      public Options getOptions(String propertyListName)
      Description copied from interface: DomainObject
      Get the property list for the given name.
      Specified by:
      getOptions in interface DomainObject
      Parameters:
      propertyListName - name of property list
      Returns:
      the options
    • performPropertyListAlterations

      protected void performPropertyListAlterations(Map<String,String> propertyAlterations, TaskMonitor monitor) throws IOException
      This method can be used to perform property list alterations resulting from renamed or obsolete property paths. This should only be invoked during an upgrade. WARNING! Should only be called during construction of domain object
      Throws:
      IOException
      See Also:
      • OptionsDB.performAlterations(Map)
    • canLock

      public boolean canLock()
      Description copied from interface: DomainObject
      Returns true if a modification lock can be obtained on this domain object. Care should be taken with using this method since this will not prevent another thread from modifying the domain object.
      Specified by:
      canLock in interface DomainObject
      Returns:
      true if can lock
    • isLocked

      public boolean isLocked()
      Description copied from interface: DomainObject
      Returns true if the domain object currently has a modification lock enabled.
      Specified by:
      isLocked in interface DomainObject
      Returns:
      true if locked
    • lock

      public boolean lock(String reason)
      Description copied from interface: DomainObject
      Attempt to obtain a modification lock on the domain object. Multiple locks may be granted on this domain object, although all lock owners must release their lock in a timely fashion.
      Specified by:
      lock in interface DomainObject
      Parameters:
      reason - very short reason for requesting lock
      Returns:
      true if lock obtained successfully, else false which indicates that a modification is in process.
    • forceLock

      public void forceLock(boolean rollback, String reason)
      Description copied from interface: DomainObject
      Force transaction lock and terminate current transaction.
      Specified by:
      forceLock in interface DomainObject
      Parameters:
      rollback - true if rollback of non-commited changes should occurs, false if commit should be done. NOTE: it can be potentially detrimental to commit an incomplete transaction which should be avoided.
      reason - very short reason for requesting lock
    • unlock

      public void unlock()
      Description copied from interface: DomainObject
      Release a modification lock previously granted with the lock method.
      Specified by:
      unlock in interface DomainObject
    • startTransaction

      public int startTransaction(String description)
      Description copied from interface: UndoableDomainObject
      Start a new transaction in order to make changes to this domain object. All changes must be made in the context of a transaction. If a transaction is already in progress, a sub-transaction of the current transaction will be returned.
      Specified by:
      startTransaction in interface UndoableDomainObject
      Parameters:
      description - brief description of transaction
      Returns:
      transaction ID
    • startTransaction

      public int startTransaction(String description, AbortedTransactionListener listener)
      Description copied from interface: UndoableDomainObject
      Start a new transaction in order to make changes to this domain object. All changes must be made in the context of a transaction. If a transaction is already in progress, a sub-transaction of the current transaction will be returned.
      Specified by:
      startTransaction in interface UndoableDomainObject
      Parameters:
      description - brief description of transaction
      listener - listener to be notified if the transaction is aborted.
      Returns:
      transaction ID
    • endTransaction

      public void endTransaction(int transactionID, boolean commit)
      Description copied from interface: UndoableDomainObject
      Terminate the specified transaction for this domain object.
      Specified by:
      endTransaction in interface UndoableDomainObject
      Parameters:
      transactionID - transaction ID obtained from startTransaction method
      commit - if true the changes made in this transaction will be marked for commit, if false this and any concurrent transaction will be rolled-back.
    • addTransactionListener

      public void addTransactionListener(TransactionListener listener)
      Adds the given transaction listener to this domain object
      Specified by:
      addTransactionListener in interface Undoable
      Parameters:
      listener - the new transaction listener to add
    • removeTransactionListener

      public void removeTransactionListener(TransactionListener listener)
      Removes the given transaction listener from this domain object.
      Specified by:
      removeTransactionListener in interface Undoable
      Parameters:
      listener - the transaction listener to remove
    • getUndoStackDepth

      public int getUndoStackDepth()
      Returns the undo stack depth. (The number of items on the undo stack) This method is for JUnits.
      Returns:
      the undo stack depth
    • canRedo

      public boolean canRedo()
      Description copied from interface: Undoable
      Returns true if there is a later state to "redo" to.
      Specified by:
      canRedo in interface Undoable
    • canUndo

      public boolean canUndo()
      Description copied from interface: Undoable
      Returns true if there is a previous state to "undo" to.
      Specified by:
      canUndo in interface Undoable
    • getRedoName

      public String getRedoName()
      Description copied from interface: Undoable
      Returns a description of the change that would be "redone".
      Specified by:
      getRedoName in interface Undoable
    • getUndoName

      public String getUndoName()
      Description copied from interface: Undoable
      Returns a description of the chanage that would be "undone".
      Specified by:
      getUndoName in interface Undoable
    • getCurrentTransaction

      public Transaction getCurrentTransaction()
      Description copied from interface: UndoableDomainObject
      Returns the current transaction
      Specified by:
      getCurrentTransaction in interface UndoableDomainObject
      Returns:
      the current transaction
    • redo

      public void redo() throws IOException
      Description copied from interface: Undoable
      Returns to a latter state that exists because of an undo. Normally, this will cause the current state to appear on the "undo" stack. This method will do nothing if there are no latter states to "redo".
      Specified by:
      redo in interface Undoable
      Throws:
      IOException - if an IO error occurs
    • undo

      public void undo() throws IOException
      Description copied from interface: Undoable
      Returns to the previous state. Normally, this will cause the current state to appear on the "redo" stack. This method will do nothing if there are no previous states to "undo".
      Specified by:
      undo in interface Undoable
      Throws:
      IOException - if an IO error occurs
    • isChanged

      public boolean isChanged()
      Description copied from interface: DomainObject
      Returns whether the object has changed.
      Specified by:
      isChanged in interface DomainObject
      Overrides:
      isChanged in class DomainObjectAdapter
      Returns:
      whether the object has changed.
    • setChanged

      protected void setChanged(boolean b)
      Overrides:
      setChanged in class DomainObjectAdapter
    • propertyChanged

      protected boolean propertyChanged(String propertyName, Object oldValue, Object newValue)
      Notification of property change
      Parameters:
      propertyName -
      oldValue -
      newValue -
      Returns:
      true if change is OK, false value should be reverted
    • clearUndo

      public void clearUndo()
      Description copied from interface: Undoable
      Clear all undoable/redoable transactions
      Specified by:
      clearUndo in interface Undoable
    • clearUndo

      protected void clearUndo(boolean notifyListeners)
    • clearCache

      protected void clearCache(boolean all)
    • canSave

      public boolean canSave()
      Description copied from interface: DomainObject
      Returns true if this object can be saved; a read-only file cannot be saved.
      Specified by:
      canSave in interface DomainObject
      Returns:
      true if this object can be saved
    • save

      public void save(String comment, TaskMonitor monitor) throws IOException, CancelledException
      Description copied from interface: DomainObject
      Saves changes to the DomainFile.
      Specified by:
      save in interface DomainObject
      Parameters:
      comment - comment used for new version
      monitor - monitor that shows the progress of the save
      Throws:
      IOException - thrown if there was an error accessing this domain object
      ReadOnlyException - thrown if this DomainObject is read only and cannot be saved
      CancelledException - thrown if the user canceled the save operation
    • saveToPackedFile

      public void saveToPackedFile(File outputFile, TaskMonitor monitor) throws IOException, CancelledException
      Description copied from interface: DomainObject
      Saves (i.e., serializes) the current content to a packed file.
      Specified by:
      saveToPackedFile in interface DomainObject
      Parameters:
      outputFile - packed output file
      monitor - progress monitor
      Throws:
      IOException - if an exception occurs
      CancelledException - if the user cancels
    • updateMetadata

      protected void updateMetadata() throws IOException
      This method is called before a save, saveAs, or saveToPackedFile to update common meta data
      Throws:
      IOException
    • close

      protected void close()
      Overrides:
      close in class DomainObjectAdapter
    • isClosed

      public boolean isClosed()
      Description copied from interface: DomainObject
      Returns true if this domain object has been closed as a result of the last release
      Specified by:
      isClosed in interface DomainObject
      Returns:
      true if closed
    • hasTerminatedTransaction

      public boolean hasTerminatedTransaction()
      Description copied from interface: UndoableDomainObject
      Returns true if the last transaction was terminated externally from the action that started it.
      Specified by:
      hasTerminatedTransaction in interface UndoableDomainObject
    • loadMetadata

      protected void loadMetadata() throws IOException
      Throws:
      IOException
    • saveMetadata

      protected void saveMetadata() throws IOException
      Throws:
      IOException