Acquires a lock to begin mutating the document this lock
protects. There can be no writing, notification of changes, or
reading going on in order to gain the lock. Additionally a thread is
allowed to gain more than one
writeLock
,
as long as it doesn't attempt to gain additional
writeLock
s
from within document notification. Attempting to gain a
writeLock
from within a DocumentListener notification will
result in an
IllegalStateException
. The ability
to obtain more than one
writeLock
per thread allows
subclasses to gain a writeLock, perform a number of operations, then
release the lock.
Calls to writeLock
must be balanced with calls to writeUnlock
, else the
Document
will be left in a locked state so that no
reading or writing can be done.
Throws:
- IllegalStateException - thrown on illegal lock
attempt. If the document is implemented properly, this can
only happen if a document listener attempts to mutate the
document. This situation violates the bean event model
where order of delivery is not guaranteed and all listeners
should be notified before further mutations are allowed.