JavaTM 2 Platform
Standard Ed. 5.0

javax.swing.text
类 AbstractDocument

java.lang.Object
  继承者 javax.swing.text.AbstractDocument
所有已实现的接口:
Serializable, Document
直接已知子类:
DefaultStyledDocument, PlainDocument

public abstract class AbstractDocument
extends Object
implements Document, Serializable

文档接口的实现,可作为实现各种文档的基础。在此级别上几乎没有策略,所以相应地增加了使用难度。

此类实现了文档的锁定机制。它允许多个 reader 或一个 writer,并且在 writer 开始对文档的另一次改变前,必须等到将以前的更改已通知该文档的所有观察者。使用 render 方法获取和释放读取锁定。通过改变文档的那些方法来获取写入锁定,并且在该方法调用期间保持锁定。在生成改变的线程上完成通知,并且在通知期间该线程对文件具有完全的读取访问权限,不过在通知结束前其他 reader 无法读取。该通知是一个 bean 事件通知,只有通知所有侦听器之后才允许进一步的改变。

所有根据此类创建子类且与文本组件(该组件具有派生自 BasicTextUI 的外观实现)一起使用的模型都可安全地进行异步更新,因为如果该文档的类型是 AbstractDocument,则对 View 层次结构的所有访问都是由 BasicTextUI 序列化的。锁定机制假定独立的线程仅从 DocumentListener 方法访问 View 层次结构,并且同一时间只有一个事件线程处于活动状态。

如果需要并发支持,则有下列额外的含义。所有 DocumentListener 实现和所有 UndoListener 实现的代码路径必须是线程安全的,并且如果要避免死锁,则不能访问组件锁定。在 JComponent 上执行 repaintrevalidate 方法是安全的。

AbstractDocument 在文档的结尾模拟了一个隐含的分隔。除了其他作用,这一功能允许您在最后一个字符的后面定位插入符。因此,getLength 返回一个比 Content 的长度小的值。如果创建自己的 Content,一定要有一个额外的字符并且初始化它。有关此内容的示例,请参见 StringContent 和 GapContent。另一个含义是模拟该隐含结束字符的 Element 具有 endOffset == (getLength() + 1)。例如,在 DefaultStyledDocument 中,getParagraphElement(getLength()).getEndOffset() == getLength() + 1

警告:此类的已序列化对象与以后的 Swing 版本不兼容。当前的序列化支持适用于短期存储或运行相同 Swing 版本的应用程序之间的 RMI。从 1.4 版本开始,已在 java.beans 包中添加了支持所有 JavaBeansTM 长期存储的功能。请参见 XMLEncoder


嵌套类摘要
 class AbstractDocument.AbstractElement
          实现元素的抽象部分。
static interface AbstractDocument.AttributeContext
          一个接口,它用于允许 MutableAttributeSet 的实现使用可插入属性压缩技术。
 class AbstractDocument.BranchElement
          实现一个包含其他元素的复合元素。
static interface AbstractDocument.Content
          描述可编辑的字符序列内容的接口。
 class AbstractDocument.DefaultDocumentEvent
          存储修改文档时发生的文档更改。
static class AbstractDocument.ElementEdit
          一个 ElementChange 实现,可将其添加到文档事件中。
 class AbstractDocument.LeafElement
          实现可直接表示某类内容的元素。
 
字段摘要
protected static String BAD_LOCATION
          指示位置错误的错误消息。
static String BidiElementName
          用于保存单向操作的元素名。
static String ContentElementName
          用于表示内容的元素名
static String ElementNameAttribute
          用于指定元素名的属性名。
protected  EventListenerList listenerList
          文档的事件侦听器列表。
static String ParagraphElementName
          用于表示段落的元素名
static String SectionElementName
          用于保存各节(行/段落)的元素名。
 
从接口 javax.swing.text.Document 继承的字段
StreamDescriptionProperty, TitleProperty
 
构造方法摘要
protected AbstractDocument(AbstractDocument.Content data)
          构造具有某种指定内容存储机制的新 AbstractDocument
protected AbstractDocument(AbstractDocument.Content data, AbstractDocument.AttributeContext context)
          构造具有某种指定内容存储机制的新 AbstractDocument
 
方法摘要
 void addDocumentListener(DocumentListener listener)
          添加负责通知任何更改的文档侦听器。
 void addUndoableEditListener(UndoableEditListener listener)
          添加负责通知任何更改的撤消侦听器。
protected  Element createBranchElement(Element parent, AttributeSet a)
          创建文档分支元素,它可包含其他元素。
protected  Element createLeafElement(Element parent, AttributeSet a, int p0, int p1)
          创建文档叶元素。
 Position createPosition(int offs)
          返回更改文档时,将跟踪更改的位置。
 void dump(PrintStream out)
          提供诊断转储 (dump)。
protected  void fireChangedUpdate(DocumentEvent e)
          通知已注册对获得此事件类型通知感兴趣的所有侦听器。
protected  void fireInsertUpdate(DocumentEvent e)
          通知已注册对获得此事件类型通知感兴趣的所有侦听器。
protected  void fireRemoveUpdate(DocumentEvent e)
          通知已注册对获得此事件类型通知感兴趣的所有侦听器。
protected  void fireUndoableEditUpdate(UndoableEditEvent e)
          通知已注册对获得此事件类型通知感兴趣的所有侦听器。
 int getAsynchronousLoadPriority()
          获得异步加载优先级。
protected  AbstractDocument.AttributeContext getAttributeContext()
          获取管理属性的上下文。
 Element getBidiRootElement()
          返回此文档双向结构的根元素。
protected  AbstractDocument.Content getContent()
          获得文档的内容。
protected  Thread getCurrentWriter()
          获取当前的写入线程(如果有的话)。
abstract  Element getDefaultRootElement()
          返回视图赖依存在的根元素,除非提供了向元素结构指派视图的其他机制。
 DocumentFilter getDocumentFilter()
          返回负责进行插入/移除过滤的 DocumentFilter
 DocumentListener[] getDocumentListeners()
          返回在此文档上注册的所有文档侦听器的数组。
 Dictionary<Object,Object> getDocumentProperties()
          支持管理属性集。
 Position getEndPosition()
          返回表示文档结尾的位置。
 int getLength()
          返回数据的长度。
<T extends EventListener>
T[]
getListeners(Class<T> listenerType)
          返回目前已在此文档上注册为 FooListener 的所有对象组成的数组。
abstract  Element getParagraphElement(int pos)
          获得包含给定位置的段落元素。
 Object getProperty(Object key)
          查找属性值的便捷方法。
 Element[] getRootElements()
          获得已定义的所有根元素。
 Position getStartPosition()
          返回表示文档开始的位置。
 String getText(int offset, int length)
          从文档中获得文本序列。
 void getText(int offset, int length, Segment txt)
          获取文档给定部分内包含的文本。
 UndoableEditListener[] getUndoableEditListeners()
          返回在此文档上注册的所有可撤消编辑侦听器的数组。
 void insertString(int offs, String str, AttributeSet a)
          将某些内容插入文档。
protected  void insertUpdate(AbstractDocument.DefaultDocumentEvent chng, AttributeSet attr)
          在文本插入后更新文档结构。
protected  void postRemoveUpdate(AbstractDocument.DefaultDocumentEvent chng)
          随文本的移除更新任何文档结构。
 void putProperty(Object key, Object value)
          存储属性值的便捷方法。
 void readLock()
          获取一个锁定,以开始读取文档的某个状态。
 void readUnlock()
          执行读取解除锁定。
 void remove(int offs, int len)
          从文档中移除某些内容。
 void removeDocumentListener(DocumentListener listener)
          移除文档侦听器。
 void removeUndoableEditListener(UndoableEditListener listener)
          移除撤消侦听器。
protected  void removeUpdate(AbstractDocument.DefaultDocumentEvent chng)
          随文本的移除更新任何文档结构。
 void render(Runnable r)
          如果模型支持被异步更新,则此方法允许在并发情况下安全地呈现该模型。
 void replace(int offset, int length, String text, AttributeSet attrs)
          删除从 offsetoffset + length 的文本区域,并用 text 替换它。
 void setAsynchronousLoadPriority(int p)
          设置异步加载优先级。
 void setDocumentFilter(DocumentFilter filter)
          设置 DocumentFilter
 void setDocumentProperties(Dictionary<Object,Object> x)
          替换此文档的文档属性字典。
protected  void writeLock()
          获取一个锁定,以开始改变此锁定保护的文档。
protected  void writeUnlock()
          释放以前通过 writeLock 所获得的写入锁定。
 
从类 java.lang.Object 继承的方法
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

字段详细信息

listenerList

protected EventListenerList listenerList
文档的事件侦听器列表。


BAD_LOCATION

protected static final String BAD_LOCATION
指示位置错误的错误消息。

另请参见:
常量字段值

ParagraphElementName

public static final String ParagraphElementName
用于表示段落的元素名

另请参见:
常量字段值

ContentElementName

public static final String ContentElementName
用于表示内容的元素名

另请参见:
常量字段值

SectionElementName

public static final String SectionElementName
用于保存各节(行/段落)的元素名。

另请参见:
常量字段值

BidiElementName

public static final String BidiElementName
用于保存单向操作的元素名。

另请参见:
常量字段值

ElementNameAttribute

public static final String ElementNameAttribute
用于指定元素名的属性名。

另请参见:
常量字段值
构造方法详细信息

AbstractDocument

protected AbstractDocument(AbstractDocument.Content data)
构造具有某种指定内容存储机制的新 AbstractDocument

参数:
data - 内容

AbstractDocument

protected AbstractDocument(AbstractDocument.Content data,
                           AbstractDocument.AttributeContext context)
构造具有某种指定内容存储机制的新 AbstractDocument

参数:
data - 内容
context - 属性上下文
方法详细信息

getDocumentProperties

public Dictionary<Object,Object> getDocumentProperties()
支持管理属性集。调用方可以使用 documentProperties 字典通过文档范围内起作用的属性注释文档。

返回:
nullDictionary
另请参见:
setDocumentProperties(java.util.Dictionary)

setDocumentProperties

public void setDocumentProperties(Dictionary<Object,Object> x)
替换此文档的文档属性字典。

参数:
x - 新字典
另请参见:
getDocumentProperties()

fireInsertUpdate

protected void fireInsertUpdate(DocumentEvent e)
通知已注册对获得此事件类型通知感兴趣的所有侦听器。使用传入此触发方法的参数延后 (lazily) 创建事件实例。

参数:
e - 事件
另请参见:
EventListenerList

fireChangedUpdate

protected void fireChangedUpdate(DocumentEvent e)
通知已注册对获得此事件类型通知感兴趣的所有侦听器。使用传入此触发方法的参数延后创建事件实例。

参数:
e - 事件
另请参见:
EventListenerList

fireRemoveUpdate

protected void fireRemoveUpdate(DocumentEvent e)
通知已注册对获得此事件类型通知感兴趣的所有侦听器。使用传入此触发方法的参数延后创建事件实例。

参数:
e - 事件
另请参见:
EventListenerList

fireUndoableEditUpdate

protected void fireUndoableEditUpdate(UndoableEditEvent e)
通知已注册对获得此事件类型通知感兴趣的所有侦听器。使用传入此触发方法的参数延后创建事件实例。

参数:
e - 事件
另请参见:
EventListenerList

getListeners

public <T extends EventListener> T[] getListeners(Class<T> listenerType)
返回目前已在此文档上注册为 FooListener 的所有对象组成的数组。FooListener 是用 addFooListener 方法注册的。

可以使用 class 字面值来指定 listenerType 参数,如 FooListener.class。例如,可以使用以下代码查询文档 d,以获得该文档的侦听器:

DocumentListener[] mls = (DocumentListener[])(d.getListeners(DocumentListener.class));
如果不存在这样的侦听器,则此方法将返回一个空数组。

参数:
listenerType - 所请求的侦听器类型;此参数应该指定一个从 java.util.EventListener 继承的接口
返回:
返回一个在此组件上作为 FooListener 注册的所有对象的数组,如果尚未添加这样的侦听器,则返回一个空数组
抛出:
ClassCastException - 如果 listenerType 未指定一个实现 java.util.EventListener 的类或接口
从以下版本开始:
1.3
另请参见:
getDocumentListeners(), getUndoableEditListeners()

getAsynchronousLoadPriority

public int getAsynchronousLoadPriority()
获得异步加载优先级。如果小于零,则不应异步加载该文档。

返回:
异步加载优先级,如果不应异步加载该文档,则返回 -1

setAsynchronousLoadPriority

public void setAsynchronousLoadPriority(int p)
设置异步加载优先级。

参数:
p - 新异步加载优先级;小于零的值指示不应异步加载该文档

setDocumentFilter

public void setDocumentFilter(DocumentFilter filter)
设置 DocumentFilterDocumentFilter 被传递到 insertremove,以便有条件地允许文本的插入/删除。null 值指示不进行过滤。

参数:
filter - 用于限制文本的 DocumentFilter
从以下版本开始:
1.4
另请参见:
getDocumentFilter()

getDocumentFilter

public DocumentFilter getDocumentFilter()
返回负责进行插入/移除过滤的 DocumentFilternull 返回值意味着不进行过滤。

返回:
the DocumentFilter
从以下版本开始:
1.4
另请参见:
setDocumentFilter(javax.swing.text.DocumentFilter)

render

public void render(Runnable r)
如果模型支持被异步更新,则此方法允许在并发情况下安全地呈现该模型。给定的 runnable 的执行方式是,在 runnable 执行时安全读取模型且不作任何更改。该 runnable 本身可能 进行任何改变。

实现此方法以便为 runnable 执行期间获取一个读取锁定。在同一时间,可能有多个 runnable 在执行,并且当存在活动呈现的 runnable 时将会阻塞所有 writer。如果该 runnable 抛出异常,则将安全地释放其锁定。对于从不退出的 runnable 没有保护,在其生命周期中会有效地保持文档的锁定。

如果给定的 runnable 试图在此实现中对文档进行任何改变,则会发生死锁。没有为每个呈现线程进行跟踪以便允许检测此种情况的机制,但是子类可以通过额外的开销对呈现线程进行跟踪,并在死锁时抛出错误。

虽然大多数 Swing 方法不是线程安全的,但此方法是线程安全的。有关更多信息,请参阅 Threads and Swing

指定者:
接口 Document 中的 render
参数:
r - 要执行的渲染器

getLength

public int getLength()
返回数据的长度。这是表示用户数据的内容字符数。

指定者:
接口 Document 中的 getLength
返回:
长度,该值 >= 0
另请参见:
Document.getLength()

addDocumentListener

public void addDocumentListener(DocumentListener listener)
添加负责通知任何更改的文档侦听器。

指定者:
接口 Document 中的 addDocumentListener
参数:
listener - 要添加的 DocumentListener
另请参见:
Document.addDocumentListener(javax.swing.event.DocumentListener)

removeDocumentListener

public void removeDocumentListener(DocumentListener listener)
移除文档侦听器。

指定者:
接口 Document 中的 removeDocumentListener
参数:
listener - 要移除的 DocumentListener
另请参见:
Document.removeDocumentListener(javax.swing.event.DocumentListener)

getDocumentListeners

public DocumentListener[] getDocumentListeners()
返回在此文档上注册的所有文档侦听器的数组。

返回:
此文档的所有 DocumentListener,如果当前没有注册的文档侦听器,则返回一个空数组
从以下版本开始:
1.4
另请参见:
addDocumentListener(javax.swing.event.DocumentListener), removeDocumentListener(javax.swing.event.DocumentListener)

addUndoableEditListener

public void addUndoableEditListener(UndoableEditListener listener)
添加负责通知任何更改的撤消侦听器。在 UndoableEdit 上执行撤消/重复操作将激发适当的 DocumentEvent,以让视图与模型保持同步。

指定者:
接口 Document 中的 addUndoableEditListener
参数:
listener - 要添加的 UndoableEditListener
另请参见:
Document.addUndoableEditListener(javax.swing.event.UndoableEditListener)

removeUndoableEditListener

public void removeUndoableEditListener(UndoableEditListener listener)
移除撤消侦听器。

指定者:
接口 Document 中的 removeUndoableEditListener
参数:
listener - 要移除的 UndoableEditListener
另请参见:
Document.removeDocumentListener(javax.swing.event.DocumentListener)

getUndoableEditListeners

public UndoableEditListener[] getUndoableEditListeners()
返回在此文档上注册的所有可撤消编辑侦听器的数组。

返回:
此文档的所有 UndoableEditListener,如果当前没有注册的可撤消编辑侦听器,则返回一个空数组。
从以下版本开始:
1.4
另请参见:
addUndoableEditListener(javax.swing.event.UndoableEditListener), removeUndoableEditListener(javax.swing.event.UndoableEditListener)

getProperty

public final Object getProperty(Object key)
查找属性值的便捷方法。它等效于:
 getDocumentProperties().get(key);
 

指定者:
接口 Document 中的 getProperty
参数:
key - 非 null 的属性键
返回:
此属性的值,或者为 null
另请参见:
getDocumentProperties()

putProperty

public final void putProperty(Object key,
                              Object value)
存储属性值的便捷方法。它等效于:
 getDocumentProperties().put(key, value);
 
如果 valuenull,则此方法将移除该属性。

指定者:
接口 Document 中的 putProperty
参数:
key - 非 null 的键
value - 属性值
另请参见:
getDocumentProperties()

remove

public void remove(int offs,
                   int len)
            throws BadLocationException
从文档中移除某些内容。移除内容会导致在进行实际更改时保持写入锁定。将会把更改通知调用此方法的线程上的观察者。

虽然大多数 Swing 方法不是线程安全的,但此方法是线程安全的。有关更多信息,请参阅 Threads and Swing

指定者:
接口 Document 中的 remove
参数:
offs - 起始偏移量,该值 >= 0
len - 要移除的字符数,该值 >= 0
抛出:
BadLocationException - 给定的移除位置不是文档内的有效位置
另请参见:
Document.remove(int, int)

replace

public void replace(int offset,
                    int length,
                    String text,
                    AttributeSet attrs)
             throws BadLocationException
删除从 offsetoffset + length 的文本区域,并用 text 替换它。由实现决定如何实现该替换,某些实现可能将该替换当作两个不同的操作:一次移除,后跟一次插入,其他实现可能将该替换当作一个原子操作。

参数:
offset - 子元素的索引
length - 要删除的文本长度,可能为 0,指示不删除任何内容
text - 要插入的文本,null 指示不插入文本
attrs - AttributeSet 指示所插入文本的属性,null 是合法值,通常作为空 attributeset 对待,但是具体的解释由子类负责
抛出:
BadLocationException - 给定的位置不是文档内的有效位置
从以下版本开始:
1.4

insertString

public void insertString(int offs,
                         String str,
                         AttributeSet a)
                  throws BadLocationException
将某些内容插入文档。插入内容会导致在实际发生改变时存储写锁定,接着会向线程上抓取该写入锁定的观察者发出通知。

虽然大多数 Swing 方法不是线程安全的,但此方法是线程安全的。有关更多信息,请参阅 Threads and Swing

指定者:
接口 Document 中的 insertString
参数:
offs - 起始偏移量,该值 >= 0
str - 要插入的字符串;null/空字符串不执行任何操作
a - 插入内容的属性
抛出:
BadLocationException - 如果给定的插入位置不是文档中的有效位置
另请参见:
Document.insertString(int, java.lang.String, javax.swing.text.AttributeSet)

getText

public String getText(int offset,
                      int length)
               throws BadLocationException
从文档中获得文本序列。

指定者:
接口 Document 中的 getText
参数:
offset - 起始偏移量,该值 >= 0
length - 要检索的字符数,该值 >= 0
返回:
文本
抛出:
BadLocationException - 给定范围内包括的位置不是文档内的有效位置
另请参见:
Document.getText(int, int)

getText

public void getText(int offset,
                    int length,
                    Segment txt)
             throws BadLocationException
获取文档给定部分内包含的文本。

如果 txt 参数的 partialReturn 属性为 false,Segment 中返回的数据将是请求的整个长度,根据数据存储的方式可能是副本,也可能不是。如果 partialReturn 属性为 true,则只能返回不需要创建副本即能返回的文本量。使用部分返回在需要扫描大部分文档的情况下具有更好的效果。下面是使用部分返回访问整个文档的示例:

   int nleft = doc.getDocumentLength();
   Segment text = new Segment();
   int offs = 0;
   text.setPartialReturn(true);   
   while (nleft > 0) {
       doc.getText(offs, nleft, text);
       // do something with text
       nleft -= text.count;
       offs += text.count;
   }
 

指定者:
接口 Document 中的 getText
参数:
offset - 起始偏移量,该值 >= 0
length - 要检索的字符数,该值 >= 0
txt - 所检索到的文本被放入的 Segment 对象
抛出:
BadLocationException - 给定范围内包括的位置不是文档内的有效位置

createPosition

public Position createPosition(int offs)
                        throws BadLocationException
返回更改文档时,将跟踪更改的位置。

虽然大多数 Swing 方法不是线程安全的,但此方法是线程安全的。有关更多信息,请参阅 Threads and Swing

指定者:
接口 Document 中的 createPosition
参数:
offs - 模型中的位置,该值 >= 0
返回:
位置
抛出:
BadLocationException - 如果给定的位置不表示关联文档内的有效位置
另请参见:
Document.createPosition(int)

getStartPosition

public final Position getStartPosition()
返回表示文档开始的位置。可对返回的位置进行计数以便跟踪更改,也可以让其保留在文档起始位置。

指定者:
接口 Document 中的 getStartPosition
返回:
位置

getEndPosition

public final Position getEndPosition()
返回表示文档结尾的位置。可对返回的位置进行计数以便跟踪更改,也可以让其保留在文档结束位置。

指定者:
接口 Document 中的 getEndPosition
返回:
位置

getRootElements

public Element[] getRootElements()
获得已定义的所有根元素。通常只有一个根元素,所以默认实现将返回默认的根元素。

指定者:
接口 Document 中的 getRootElements
返回:
根元素

getDefaultRootElement

public abstract Element getDefaultRootElement()
返回视图赖依存在的根元素,除非提供了向元素结构指派视图的其他机制。

指定者:
接口 Document 中的 getDefaultRootElement
返回:
根元素
另请参见:
Document.getDefaultRootElement()

getBidiRootElement

public Element getBidiRootElement()
返回此文档双向结构的根元素。其子级表示以给定的 Unicode 双向层次进行字符操作。


getParagraphElement

public abstract Element getParagraphElement(int pos)
获得包含给定位置的段落元素。子类必须为其自身定义准确的段落组成。但是应该要记住,一个段落至少应该是在其上可运行 Unicode 双向算法的文本单元。

参数:
pos - 起始偏移量,该值 >= 0
返回:
元素

getAttributeContext

protected final AbstractDocument.AttributeContext getAttributeContext()
获取管理属性的上下文。此方法高效地建立了用于压缩 AttributeSet 信息的策略。

返回:
上下文

insertUpdate

protected void insertUpdate(AbstractDocument.DefaultDocumentEvent chng,
                            AttributeSet attr)
在文本插入后更新文档结构。这将在写锁定内发生。如果此类的子类重新实现此方法,则还应该委托给超类。

参数:
chng - 更改的描述
attr - 更改的属性

removeUpdate

protected void removeUpdate(AbstractDocument.DefaultDocumentEvent chng)
随文本的移除更新任何文档结构。从 Content 中实际移除文本前调用此方法。这将在写锁定内发生。如果此类的子类重新实现此方法,则还应该委托给超类。

参数:
chng - 更改的描述

postRemoveUpdate

protected void postRemoveUpdate(AbstractDocument.DefaultDocumentEvent chng)
随文本的移除更新任何文档结构。从 Content 中移除文本后调用此方法。这将在写锁定内发生。如果此类的子类重新实现此方法,则还应该委托给超类。

参数:
chng - 更改的描述

dump

public void dump(PrintStream out)
提供诊断转储 (dump)。

参数:
out - 输出流

getContent

protected final AbstractDocument.Content getContent()
获得文档的内容。

返回:
内容

createLeafElement

protected Element createLeafElement(Element parent,
                                    AttributeSet a,
                                    int p0,
                                    int p1)
创建文档叶元素。使用此操作来创建那些表示文档结构的元素。因为此实现分别保存结构和内容,所以扩展内容时元素会自动增加,然后会拆分现有的元素。文档本身决定如何生成元素,从而在使用的元素类型上提供了灵活性。

参数:
parent - 父元素
a - 元素的属性
p0 - 范围的开始,该值 >= 0
p1 - 范围的结尾,该值 >= p0
返回:
新元素

createBranchElement

protected Element createBranchElement(Element parent,
                                      AttributeSet a)
创建文档分支元素,它可包含其他元素。

参数:
parent - 父元素
a - 属性
返回:
元素

getCurrentWriter

protected final Thread getCurrentWriter()
获取当前的写入线程(如果有的话)。这可用于区分被调用的方法是否为现有修改的一部分,或者是否需要获得锁定并开始新事务。

返回:
正在修改文档的线程,如果没有正在进行修改,则返回 null

writeLock

protected final void writeLock()
获取一个锁定,以开始改变此锁定保护的文档。为了获得锁定,不能有正在进行的写入、更改通知或读取。另外,只要某个线程不尝试从文档通知内获得其他 writeLock,就允许它获得多个 writeLock。尝试从 DocumentListener 通知内获得 writeLock 将导致 IllegalStateException。每个线程可获得多个 writeLock 的功能允许子类获得一个 writeLock、执行多个操作,然后释放该锁定。

writeLock 的调用必须与对 writeUnlock 的调用对称,否则 Document 将被保持在锁定状态,从而无法进行读取或写入。

抛出:
IllegalStateException - 如果尝试非法锁定。如果正确实现了文档,则仅在文档侦听器尝试改变该文档时才出现此异常。此情况违反了 bean 事件模型,此模型中不保证传递顺序,在允许进一步改变前应通知所有侦听器。

writeUnlock

protected final void writeUnlock()
释放以前通过 writeLock 所获得的写入锁定。将锁定计数减一后,如果没有其他未解锁的锁定,则允许新的 writer 或多个 reader 执行操作。

另请参见:
writeLock()

readLock

public final void readLock()
获取一个锁定,以开始读取文档的某个状态。同时可以有多个 reader。完成对侦听器的更改通知前,写入锁定会阻塞各个 reader。使用此方法应该非常小心,以避免对文档的无意破坏。此方法应该始终与 readUnlock 保持对称。

另请参见:
readUnlock()

readUnlock

public final void readUnlock()
执行读取解除锁定。该操作通知某个 reader 已完成操作。如果没有其他 reader,则又可以开始写入。此方法应该与 readLock 保持对称,并且应该在最后的语句中出现,这样才能保证对称性。下面是一个示例:

     readLock();
     try {
        // do something
     } finally {
         readUnlock();
     }
 

另请参见:
readLock()

JavaTM 2 Platform
Standard Ed. 5.0

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java 2 SDK SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2004 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策