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

      • DomainObjectAdapterDB

        protected DomainObjectAdapterDB​(DBHandle dbh,
                                        java.lang.String name,
                                        int timeInterval,
                                        int bufSize,
                                        java.lang.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.
        bufSize - initial size of event buffer
        consumer - the object that created this domain object
    • Method Detail

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

        public java.util.List<java.lang.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.
      • performPropertyListAlterations

        protected void performPropertyListAlterations​(java.util.Map<java.lang.String,​java.lang.String> propertyAlterations,
                                                      TaskMonitor monitor)
                                               throws java.io.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:
        java.io.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
        See Also:
        DomainObject.canLock()
      • lock

        public boolean lock​(java.lang.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.
        See Also:
        DomainObject.lock(String)
      • forceLock

        public void forceLock​(boolean rollback,
                              java.lang.String reason)
        Description copied from interface: DomainObject
        Cancels any previous lock and acquires it.
        Specified by:
        forceLock in interface DomainObject
        Parameters:
        rollback - if true, any changes in made with the previous lock should be discarded.
        reason - very short reason for requesting lock
        See Also:
        DomainObject.forceLock(boolean, String)
      • startTransaction

        public int startTransaction​(java.lang.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​(java.lang.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
        See Also:
        UndoableDomainObject.startTransaction(java.lang.String)
      • 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.
        See Also:
        UndoableDomainObject.endTransaction(int, boolean)
      • 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
        See Also:
        Undoable.canRedo()
      • 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
        See Also:
        Undoable.canUndo()
      • redo

        public void redo()
                  throws java.io.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:
        java.io.IOException - if an IO error occurs
        See Also:
        Undoable.redo()
      • undo

        public void undo()
                  throws java.io.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:
        java.io.IOException - if an IO error occurs
        See Also:
        Undoable.undo()
      • propertyChanged

        protected boolean propertyChanged​(java.lang.String propertyName,
                                          java.lang.Object oldValue,
                                          java.lang.Object newValue)
        Notification of property change
        Parameters:
        propertyName -
        oldValue -
        newValue -
        Returns:
        true if change is OK, false value should be reverted
      • 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
        See Also:
        DomainObject.canSave()
      • updateMetadata

        protected void updateMetadata()
                               throws java.io.IOException
        This method is called before a save, saveAs, or saveToPackedFile to update common meta data
        Throws:
        java.io.IOException
      • 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
        See Also:
        DomainObject.isClosed()
      • loadMetadata

        protected void loadMetadata()
                             throws java.io.IOException
        Throws:
        java.io.IOException
      • saveMetadata

        protected void saveMetadata()
                             throws java.io.IOException
        Throws:
        java.io.IOException