Package ghidra.framework.data

Class DomainObjectAdapterDB

java.lang.Object
ghidra.framework.data.DomainObjectAdapter
ghidra.framework.data.DomainObjectAdapterDB
All Implemented Interfaces:
ErrorHandler, DomainObject
Direct Known Subclasses:
DataTypeArchiveDB, ProgramDB, URLLinkObject
public abstract class DomainObjectAdapterDB extends DomainObjectAdapter implements ErrorHandler
Database version of the DomainObjectAdapter. 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.

  • Field Details

  • Constructor Details

    • DomainObjectAdapterDB

      protected DomainObjectAdapterDB(DBHandle dbh, String name, int timeInterval, Object consumer)
      Construct a new DomainObjectAdapterDB object.
      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 DomainObject
      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 DomainObject
      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 DomainObject
      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
      Parameters:
      e - IOException which was cause of error

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

    • setImmutable

      protected void setImmutable()
      Set instance as immutable by disabling use of transactions. Attempts to start a transaction will result in a TerminatedTransactionException. This method should invoked at the end of instance instatiation OpenMode.IMMUTABLE was used.

    • 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

    • openTransaction

      public Transaction openTransaction(String description) throws TerminatedTransactionException, IllegalStateException
      Description copied from interface: DomainObject
      Open new transaction. This should generally be done with a try-with-resources block: 
       try (Transaction tx = dobj.openTransaction(description)) {
        // ... Do something
 }
      Specified by:
      openTransaction in interface DomainObject
      Parameters:
      description - a short description of the changes to be made.
      Returns:
      transaction object
      Throws:
      IllegalStateException - if this DomainObject has already been closed.
      TerminatedTransactionException

    • startTransaction

      public int startTransaction(String description) throws TerminatedTransactionException
      Description copied from interface: DomainObject
      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 DomainObject
      Parameters:
      description - brief description of transaction
      Returns:
      transaction ID
      Throws:
      TerminatedTransactionException - an existing transaction which has not yet ended was terminated early. Sub-transactions are not permitted until the terminated transaction ends.

    • startTransaction

      public int startTransaction(String description, AbortedTransactionListener listener) throws TerminatedTransactionException
      Description copied from interface: DomainObject
      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 DomainObject
      Parameters:
      description - brief description of transaction
      listener - listener to be notified if the transaction is aborted.
      Returns:
      transaction ID
      Throws:
      TerminatedTransactionException - an existing transaction which has not yet ended was terminated early. Sub-transactions are not permitted until the terminated transaction ends.

    • endTransaction

      public void endTransaction(int transactionID, boolean commit) throws IllegalStateException
      Description copied from interface: DomainObject
      Terminate the specified transaction for this domain object.
      Specified by:
      endTransaction in interface DomainObject
      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.
      Throws:
      IllegalStateException

    • addTransactionListener

      public void addTransactionListener(TransactionListener listener)
      Adds the given transaction listener to this domain object
      Specified by:
      addTransactionListener in interface DomainObject
      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 DomainObject
      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: DomainObject
      Returns true if there is a later state to "redo" to.
      Specified by:
      canRedo in interface DomainObject

    • canUndo

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

    • getRedoName

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

    • getUndoName

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

    • getAllUndoNames

      public List<String> getAllUndoNames()
      Description copied from interface: DomainObject
      Returns a list of the names of all current undo transactions
      Specified by:
      getAllUndoNames in interface DomainObject
      Returns:
      a list of the names of all current undo transactions

    • getAllRedoNames

      public List<String> getAllRedoNames()
      Description copied from interface: DomainObject
      Returns a list of the names of all current redo transactions
      Specified by:
      getAllRedoNames in interface DomainObject
      Returns:
      a list of the names of all current redo transactions

    • getCurrentTransactionInfo

      public TransactionInfo getCurrentTransactionInfo()
      Description copied from interface: DomainObject
      Returns the current transaction info
      Specified by:
      getCurrentTransactionInfo in interface DomainObject
      Returns:
      the current transaction info

    • redo

      public void redo() throws IOException
      Description copied from interface: DomainObject
      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 DomainObject
      Throws:
      IOException - if an IO error occurs

    • undo

      public void undo() throws IOException
      Description copied from interface: DomainObject
      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 DomainObject
      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: DomainObject
      Clear all undoable/redoable transactions
      Specified by:
      clearUndo in interface DomainObject

    • clearUndo

      protected void clearUndo(boolean notifyListeners)

    • invalidate

      public void invalidate()
      Description copied from class: DomainObjectAdapter
      Invalidates any caching in a program and generate a DomainObjectEvent.RESTORED event. NOTE: Over-using this method can adversely affect system performance.
      Overrides:
      invalidate in class DomainObjectAdapter

    • clearCache

      protected void clearCache(boolean all)

    • domainObjectRestored

      protected void domainObjectRestored()
      Indicates that this domain object has been restored to a completely different state due to a transaction undo/redo/rollback or a database merge operation.

    • 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
      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: DomainObject
      Returns true if the last transaction was terminated from the action that started it.
      Specified by:
      hasTerminatedTransaction in interface DomainObject
      Returns:
      true if the last transaction was terminated from the action that started it.

    • loadMetadata

      protected void loadMetadata() throws IOException
      Throws:
      IOException

    • saveMetadata

      protected void saveMetadata() throws IOException
      Throws:
      IOException