Interface UndoableDomainObject

All Superinterfaces:
DomainObject, Undoable
All Known Subinterfaces:
DataTypeArchive, DataTypeManagerDomainObject, Program
All Known Implementing Classes:
DataTypeArchiveDB, DomainObjectAdapterDB, ProgramDB, URLLinkObject

public interface UndoableDomainObject extends DomainObject, Undoable
UndoableDomainObject extends a domain object to provide transaction support and the ability to undo and 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.

See Also:
  • Method Details

    • 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