Editor Document Locking

In order to perform operations with a Swing document safely the javax.swing.text.Document instance must be properly locked. A regular document only supports read-locking through Document.render(Runnable). Write-locking is done internally within Document.insertString() and Document.remove() methods. In order to support more complex document modifications NetBeans Text API supports atomic transactions over a document.

Atomic Transactions over Document

  • org.openide.text.NbDocument.runAtomicAsUser(Runnable) - Create an atomic transaction possibly containing a series of a document modifications. If a modification inside a guarded section is attempted then the whole transaction gets rolled back and an instance of BadLocationException is thrown. If any of the modifications fails then the whole transaction gets rolled back too (the model is transactional).
    doc.runAtomicAsUser(new Runnable() {
        public void run() {

As a side effect each transaction represents a single undoable compound edit in the undo manager's queue.

Document Implementations

  • javax.swing.text.AbstractDocument - basic implementation of the Document interface. All mature Swing's document implementations (including PlainDocument and DefaultStyledDocument) are based on it. Since there are many occurrences of
    if (doc instanceof AbstractDocument) {

throughout Swing's code. Therefore the NetBeans document implementations are also AbstractDocument-based. One deficiency of being AbstractDocument-based is that read/write-locking methods are all final (public final readLock()/Unlock() and protected final writeLock()/Unlock()) which prevents adding an extra logging for finding of missing unlocks etc.

  • BaseDocument.runAtomicAsUser(Runnable)
  • BaseDocument.runAtomic(Runnable) - implementation of NbDocument.WriteLockable interface. The methods can also be used directly by clients.
  • BaseDocument.atomicLock()
  • BaseDocument.atomicUnlock() - deprecated methods that were used in a try-finally manner
    try {
        ... document-modifications ...
    } finally {

Now these methods are deprecated since it was difficult to track a potential misuse of them. For the same reasons AbstractDocument.readLock()/Unlock() should be avoided and Document.render(Runnable) used instead.

Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo