Package ghidra.framework.model

Interface DomainObject

All Known Subinterfaces:
DataTypeArchive, DataTypeManagerDomainObject, Program
All Known Implementing Classes:
DataTypeArchiveDB, DomainObjectAdapter, DomainObjectAdapterDB, ProgramDB, URLLinkObject
public interface DomainObject
DomainObject is the interface that must be supported by data objects that are persistent. DomainObjects maintain an association with a DomainFile. A DomainObject that has never been saved will have a null DomainFile.

Supports transactions and the ability to undo/redo changes made within a stack of recent transactions. Each transactions may contain many sub-transactions which reflect concurrent changes to the domain object. If any sub-transaction fails to commit, all concurrent sub-transaction changes will be rolled-back.

NOTE: A transaction must be started in order to make any change to this domain object - failure to do so will result in a IOException.

Note: Previously (before 11.1), domain object change event types were defined in this file as integer constants. Event ids have since been converted to enum types. The defines in this file have been converted to point to the new enum values to make it easier to convert to this new way and to clearly see how the old values map to the new enums. In future releases, these defines will be removed.

  • Field Details

    • DO_OBJECT_SAVED

      @Deprecated static final EventType DO_OBJECT_SAVED
      Deprecated.
      Event type numeric constants have been changed to enums. Use the enum directly.
      Event type generated when the domain object is saved.

    • DO_DOMAIN_FILE_CHANGED

      @Deprecated static final EventType DO_DOMAIN_FILE_CHANGED
      Deprecated.
      Event type numeric constants have been changed to enums. Use the enum directly.
      Event type generated when the domain file associated with the domain object changes.

    • DO_OBJECT_RENAMED

      @Deprecated static final EventType DO_OBJECT_RENAMED
      Deprecated.
      Event type numeric constants have been changed to enums. Use the enum directly.
      Event type generated when the object name changes.

    • DO_OBJECT_RESTORED

      @Deprecated static final EventType DO_OBJECT_RESTORED
      Deprecated.
      Event type numeric constants have been changed to enums. Use the enum directly.
      Event type generated when domain object is restored.

    • DO_PROPERTY_CHANGED

      @Deprecated static final EventType DO_PROPERTY_CHANGED
      Deprecated.
      Event type numeric constants have been changed to enums. Use the enum directly.
      Event type generated when a property on this DomainObject is changed.

    • DO_OBJECT_CLOSED

      @Deprecated static final EventType DO_OBJECT_CLOSED
      Deprecated.
      Event type numeric constants have been changed to enums. Use the enum directly.
      Event type generated when this domain object is closed.

    • DO_OBJECT_ERROR

      @Deprecated static final EventType DO_OBJECT_ERROR
      Deprecated.
      Event type numeric constants have been changed to enums. Use the enum directly.
      Event type generated when a fatal error occurs which renders the domain object invalid.

    • undoLock

      static final Object undoLock
      Object to synchronize on for undo/redo operations.

  • Method Details

    • isChanged

      boolean isChanged()
      Returns whether the object has changed.
      Returns:
      whether the object has changed.

    • setTemporary

      void setTemporary(boolean state)
      Set the temporary state of this object. If this object is temporary, the isChanged() method will always return false. The default temporary state is false.
      Parameters:
      state - if true object is marked as temporary

    • isTemporary

      boolean isTemporary()
      Returns true if this object has been marked as Temporary.
      Returns:
      true if this object has been marked as Temporary.

    • isChangeable

      boolean isChangeable()
      Returns true if changes are permitted.
      Returns:
      true if changes are permitted.

    • canSave

      boolean canSave()
      Returns true if this object can be saved; a read-only file cannot be saved.
      Returns:
      true if this object can be saved

    • save

      void save(String comment, TaskMonitor monitor) throws IOException, CancelledException
      Saves changes to the DomainFile.
      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

      void saveToPackedFile(File outputFile, TaskMonitor monitor) throws IOException, CancelledException
      Saves (i.e., serializes) the current content to a packed file.
      Parameters:
      outputFile - packed output file
      monitor - progress monitor
      Throws:
      IOException - if an exception occurs
      CancelledException - if the user cancels
      UnsupportedOperationException - if not supported by object implementation

    • release

      void release(Object consumer)
      Notify the domain object that the specified consumer is no longer using it. When the last consumer invokes this method, the domain object will be closed and will become invalid.
      Parameters:
      consumer - the consumer (e.g., tool, plugin, etc) of the domain object previously established with the addConsumer method.

    • addListener

      void addListener(DomainObjectListener dol)
      Adds a listener for this object.
      Parameters:
      dol - listener notified when any change occurs to this domain object

    • removeListener

      void removeListener(DomainObjectListener dol)
      Remove the listener for this object.
      Parameters:
      dol - listener

    • addCloseListener

      void addCloseListener(DomainObjectClosedListener listener)
      Adds a listener that will be notified when this DomainObject is closed. This is meant for clients to have a chance to cleanup, such as reference removal.
      Parameters:
      listener - the reference to add

    • removeCloseListener

      void removeCloseListener(DomainObjectClosedListener listener)
      Removes the given close listener.
      Parameters:
      listener - the listener to remove.

    • addDomainFileListener

      void addDomainFileListener(DomainObjectFileListener listener)
      Adds a listener that will be notified when this DomainFile associated with this DomainObject changes, such as when a 'Save As' action occurs. Unlike DomainObject events, these notifications are not buffered and happen immediately when the DomainFile is changed.
      Parameters:
      listener - the listener to be notified when the associated DomainFile changes

    • removeDomainFileListener

      void removeDomainFileListener(DomainObjectFileListener listener)
      Removes the given DomainObjectFileListener listener.
      Parameters:
      listener - the listener to remove.

    • createPrivateEventQueue

      EventQueueID createPrivateEventQueue(DomainObjectListener listener, int maxDelay)
      Creates a private event queue that can be flushed independently from the main event queue.
      Parameters:
      listener - the listener to be notified of domain object events.
      maxDelay - the time interval (in milliseconds) used to buffer events.
      Returns:
      a unique identifier for this private queue.

    • removePrivateEventQueue

      boolean removePrivateEventQueue(EventQueueID id)
      Removes the specified private event queue
      Parameters:
      id - the id of the queue to remove.
      Returns:
      true if the id represents a valid queue that was removed.

    • getDescription

      String getDescription()
      Returns a word or short phrase that best describes or categorizes the object in terms that a user will understand.
      Returns:
      the description

    • getName

      String getName()
      Get the name of this domain object.
      Returns:
      the name

    • setName

      void setName(String name)
      Set the name for this domain object.
      Parameters:
      name - object name

    • getDomainFile

      DomainFile getDomainFile()
      Get the domain file for this domain object.
      Returns:
      the associated domain file

    • addConsumer

      boolean addConsumer(Object consumer)
      Adds the given object as a consumer. The release method must be invoked with this same consumer instance when this domain object is no longer in-use.
      Parameters:
      consumer - domain object consumer
      Returns:
      false if this domain object has already been closed

    • getConsumerList

      List<Object> getConsumerList()
      Returns the list of consumers on this domainObject
      Returns:
      the list of consumers.

    • isUsedBy

      boolean isUsedBy(Object consumer)
      Returns true if the given consumer is using (has open) this domain object.
      Parameters:
      consumer - the object to test to see if it is a consumer of this domain object.
      Returns:
      true if the given consumer is using (has open) this domain object;

    • setEventsEnabled

      void setEventsEnabled(boolean enabled)
      If true, domain object change events are sent. If false, no events are sent.

      NOTE: disabling events could cause plugins to be out of sync!

      NOTE: when re-enabling events, an event will be sent to the system to signal that every listener should update.

      Parameters:
      enabled - true means to enable events

    • isSendingEvents

      boolean isSendingEvents()
      Returns true if this object is sending out events as it is changed. The default is true. You can change this value by calling setEventsEnabled(boolean).
      Returns:
      true if sending events
      See Also:

    • flushEvents

      void flushEvents()
      Makes sure all pending domainEvents have been sent.

    • flushPrivateEventQueue

      void flushPrivateEventQueue(EventQueueID id)
      Flush events from the specified event queue.
      Parameters:
      id - the id specifying the event queue to be flushed.

    • canLock

      boolean canLock()
      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.
      Returns:
      true if can lock

    • isLocked

      boolean isLocked()
      Returns true if the domain object currently has a modification lock enabled.
      Returns:
      true if locked

    • lock

      boolean lock(String reason)
      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.
      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

      void forceLock(boolean rollback, String reason)
      Force transaction lock and terminate current transaction.
      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

      void unlock()
      Release a modification lock previously granted with the lock method.

    • getOptionsNames

      List<String> getOptionsNames()
      Returns all properties lists contained by this domain object.
      Returns:
      all property lists contained by this domain object.

    • getOptions

      Options getOptions(String propertyListName)
      Get the property list for the given name.
      Parameters:
      propertyListName - name of property list
      Returns:
      the options

    • isClosed

      boolean isClosed()
      Returns true if this domain object has been closed as a result of the last release
      Returns:
      true if closed

    • hasExclusiveAccess

      boolean hasExclusiveAccess()
      Returns true if the user has exclusive access to the domain object. Exclusive access means either the object is not shared or the user has an exclusive checkout on the object.
      Returns:
      true if has exclusive access

    • getMetadata

      Map<String,String> getMetadata()
      Returns a map containing all the stored metadata associated with this domain object. The map contains key,value pairs and are ordered by their insertion order.
      Returns:
      a map containing all the stored metadata associated with this domain object.

    • getModificationNumber

      long getModificationNumber()
      Returns a long value that gets incremented every time a change, undo, or redo takes place. Useful for implementing a lazy caching system.
      Returns:
      a long value that is incremented for every change to the program.

    • openTransaction

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

    • withTransaction

      default <E extends Exception> void withTransaction(String description, ExceptionalCallback<E> callback) throws E
      Performs the given callback inside of a transaction. Use this method in place of the more verbose try/catch/finally semantics. 

       program.withTransaction("My Description", () -> {
        // ... Do something
 });

      Note: the transaction created by this method will always be committed when the call is finished. If you need the ability to abort transactions, then you need to use the other methods on this interface.

      Parameters:
      description - brief description of transaction
      callback - the callback that will be called inside of a transaction
      Throws:
      E - any exception that may be thrown in the given callback

    • withTransaction

      default <E extends Exception, T> T withTransaction(String description, ExceptionalSupplier<T,E> supplier) throws E
      Calls the given supplier inside of a transaction. Use this method in place of the more verbose try/catch/finally semantics. 

       program.withTransaction("My Description", () -> {
        // ... Do something
        return result;
 });

      If you do not need to supply a result, then use withTransaction(String, ExceptionalCallback) instead.

      Type Parameters:
      E - the exception that may be thrown from this method
      T - the type of result returned by the supplier
      Parameters:
      description - brief description of transaction
      supplier - the supplier that will be called inside of a transaction
      Returns:
      the result returned by the supplier
      Throws:
      E - any exception that may be thrown in the given callback

    • startTransaction

      int startTransaction(String description)
      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.
      Parameters:
      description - brief description of transaction
      Returns:
      transaction ID
      Throws:
      DomainObjectLockedException - the domain object is currently locked
      TerminatedTransactionException - an existing transaction which has not yet ended was terminated early. Sub-transactions are not permitted until the terminated transaction ends.

    • startTransaction

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

    • endTransaction

      void endTransaction(int transactionID, boolean commit)
      Terminate the specified transaction for this domain object.
      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.

    • getCurrentTransactionInfo

      TransactionInfo getCurrentTransactionInfo()
      Returns the current transaction info
      Returns:
      the current transaction info

    • hasTerminatedTransaction

      boolean hasTerminatedTransaction()
      Returns true if the last transaction was terminated from the action that started it.
      Returns:
      true if the last transaction was terminated from the action that started it.

    • getSynchronizedDomainObjects

      DomainObject[] getSynchronizedDomainObjects()
      Return array of all domain objects synchronized with a shared transaction manager.
      Returns:
      returns array of synchronized domain objects or null if this domain object is not synchronized with others.

    • addSynchronizedDomainObject

      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.
      Parameters:
      domainObj - the domain object
      Throws:
      LockException - if lock or open transaction is active on either this or the specified domain object

    • releaseSynchronizedDomainObject

      void releaseSynchronizedDomainObject() throws LockException
      Remove 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.
      Throws:
      LockException - if lock or open transaction is active

    • canUndo

      boolean canUndo()
      Returns true if there is a previous state to "undo" to.

    • canRedo

      boolean canRedo()
      Returns true if there is a later state to "redo" to.

    • clearUndo

      void clearUndo()
      Clear all undoable/redoable transactions

    • undo

      void undo() throws IOException
      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".
      Throws:
      IOException - if an IO error occurs

    • redo

      void redo() throws IOException
      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".
      Throws:
      IOException - if an IO error occurs

    • getUndoName

      String getUndoName()
      Returns a description of the change that would be "undone".
      Returns:
      a description of the change that would be "undone".

    • getRedoName

      String getRedoName()
      Returns a description of the change that would be "redone".
      Returns:
      a description of the change that would be "redone".

    • getAllUndoNames

      List<String> getAllUndoNames()
      Returns a list of the names of all current undo transactions
      Returns:
      a list of the names of all current undo transactions

    • getAllRedoNames

      List<String> getAllRedoNames()
      Returns a list of the names of all current redo transactions
      Returns:
      a list of the names of all current redo transactions

    • addTransactionListener

      void addTransactionListener(TransactionListener listener)
      Adds the given transaction listener to this domain object
      Parameters:
      listener - the new transaction listener to add

    • removeTransactionListener

      void removeTransactionListener(TransactionListener listener)
      Removes the given transaction listener from this domain object.
      Parameters:
      listener - the transaction listener to remove