EditorDocumentLocking
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
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 is 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() {
document-modifications...
}
});
As a side effect each transaction represents a single undoable compound edit in the undo manager's queue.
org.openide.text.NbDocument.runAtomic(Runnable)
- A stronger variant of runAtomicAsUser(). It is allowed to modify guarded sections content too.
Document Implementations
- 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) {
do-something...
}
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.
- extends AbstractDocument; basic document implementation that extends javax.swing.text.AbstractDocument.
- 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
baseDoc.atomicLock();
try {
... document-modifications ...
} finally {
baseDoc.atomicUnlock();
}
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.
- extends BaseDocument; implements guarded sections management.
- extends GuardedDocument; implements NetBeans IDE specific features such as annotations support.
