模块  java.desktop
软件包  javax.swing.text

Class AbstractDocument

  • 实现的所有接口
    Serializable ， Document
    已知直接子类：
    DefaultStyledDocument ， PlainDocument 
    public abstract class AbstractDocument
extends Object
implements Document, Serializable
    文档接口的实现，作为实现各种文档的基础。 在这个级别上，政策很少，因此使用难度也相应增加。

    此类实现文档的锁定机制。 它允许多个读者或一个作者，并且作者必须等到文档的所有观察者在开始对文档的另一个变异之前已经通知先前的变化。 使用render方法获取并释放读锁定。 通过改变文档的方法获取写锁定，并在方法调用期间保持写锁定。 通知在产生突变的线程上完成，并且线程在通知期间具有对文档的完全读取访问权限，但是其他读取器在通知完成之前保持不变。 通知是一个bean事件通知，在通知所有侦听器之前不允许任何进一步的突变。

    从此类子类化并与具有从BasicTextUI派生的外观实现的文本组件结合使用的任何模型都可以安全地异步更新，因为如果文档类型为AbstractDocument则对AbstractDocument所有对View层次结构的访问都是序列化的。 锁定假定独立线程仅从DocumentListener方法访问View层次结构，并且一次只有一个事件线程处于活动状态。

    如果需要并发支持，则还有以下其他含义。 任何DocumentListener实现和任何UndoListener实现的代码路径必须是线程安全的，如果尝试从死锁中安全，则不能访问组件锁。 JComponent上的repaint和revalidate方法是安全的。

    AbstractDocument模拟文档末尾的隐含中断。 除此之外，这允许您在最后一个字符后定位插入符号。 因此， getLength返回的内容少于内容的长度。 如果您创建自己的内容，请确保并初始化它以具有其他角色。 有关此示例，请参阅StringContent和GapContent。 另一个含义是，对隐含结束字符建模的元素将具有endOffset ==（getLength（）+ 1）。 例如，在DefaultStyledDocument getParagraphElement(getLength()).getEndOffset() == getLength() + 1 。

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

    另请参见：
    Serialized Form

    • 字段详细信息

      • 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 - 内容

    • 方法详细信息

      • fireInsertUpdate

        protected void fireInsertUpdate​(DocumentEvent e)
        通知所有已注册对此事件类型的通知感兴趣的听众。 使用传递给fire方法的参数延迟创建事件实例。
        参数
        e - 此活动
        另请参见：
        EventListenerList

      • fireChangedUpdate

        protected void fireChangedUpdate​(DocumentEvent e)
        通知所有已注册对此事件类型的通知感兴趣的听众。 使用传递给fire方法的参数延迟创建事件实例。
        参数
        e - 活动
        另请参见：
        EventListenerList

      • fireRemoveUpdate

        protected void fireRemoveUpdate​(DocumentEvent e)
        通知所有已注册对此事件类型的通知感兴趣的听众。 使用传递给fire方法的参数延迟创建事件实例。
        参数
        e - 此次活动
        另请参见：
        EventListenerList

      • fireUndoableEditUpdate

        protected void fireUndoableEditUpdate​(UndoableEditEvent e)
        通知所有已注册对此事件类型的通知感兴趣的听众。 使用传递给fire方法的参数延迟创建事件实例。
        参数
        e - 此活动
        另请参见：
        EventListenerList

      • getListeners

        public <T extends EventListener> T[] getListeners​(类<T> listenerType)
        返回此文档上当前注册为FooListener的所有对象的数组。 FooListener s使用addFooListener方法注册。

        您可以使用类文字指定listenerType参数，例如FooListener.class 。 例如，您可以使用以下代码查询文档d以获取其文档侦听器： 

          DocumentListener[] mls = (DocumentListener[])(d.getListeners(DocumentListener.class));
        如果不存在此类侦听器，则此方法返回空数组。
        参数类型
        T - 侦听器类型
        参数
        listenerType - 请求的侦听器类型
        结果
        此组件上注册为 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)
        设置DocumentFilter 。 DocumentFilter通过insert和remove以有条件地允许插入/删除文本。 值null表示不会进行过滤。
        参数
        filter - 用于约束文本的 DocumentFilter
        从以下版本开始：
        1.4
        另请参见：
        getDocumentFilter()

      • render

        public void render​(Runnable r)
        如果模型支持异步更新，则允许在存在货币的情况下安全地呈现模型。 给定的runnable将以允许它在执行runnable时安全地读取模型而不进行任何更改的方式执行。 可运行本身可能不会发生任何突变。

        实现此操作是为了在runnables执行期间获取读锁定。 可能有多个runnable同时执行，并且所有编写器将在有活动渲染runnable时被阻止。 如果runnable抛出异常，它的锁将被安全释放。 对于永不退出的runnable没有任何保护，这将有效地使文档在其生命周期内被锁定。

        如果给定的runnable尝试在此实现中进行任何突变，则会发生死锁。 没有跟踪单个渲染线程来启用检测这种情况，但是子类可能会产生跟踪它们并引发错误的开销。

        虽然大多数Swing方法都不是，但这种方法是线程安全的。 有关更多信息，请参阅Concurrency in Swing 。

        Specified by:
        render在界面 Document
        参数
        r - 要执行的渲染器

      • getLength

        public int getLength()
        返回数据的长度。 这是表示用户数据的内容字符数。
        Specified by:
        getLength在界面 Document
        结果
        长度> = 0
        另请参见：
        Document.getLength()

      • getProperty

        public final Object getProperty​(Object key)
        查找属性值的便捷方法。 它相当于： 
          getDocumentProperties().get(key);
        Specified by:
        getProperty在界面 Document
        参数
        key - 非 null属性键
        结果
        该物业的价值或 null
        另请参见：
        getDocumentProperties()

      • putProperty

        public final void putProperty​(Object key,
                              Object value)
        用于存储属性值的便利方法。 它相当于： 
          getDocumentProperties().put(key, value);
        如果value是null此方法将删除该属性。
        Specified by:
        putProperty在界面 Document
        参数
        key - 非 null密钥
        value - 该物业价值
        另请参见：
        getDocumentProperties()

      • remove

        public void remove​(int offs,
                   int len)
            throws BadLocationException
        从文档中删除一些内容。 删除内容会导致在实际更改发生时保持写锁定。 观察者会通知调用此方法的线程的更改。

        虽然大多数Swing方法都不是，但这种方法是线程安全的。 有关更多信息，请参阅Concurrency in Swing 。

        Specified by:
        remove在界面 Document
        参数
        offs - 起始偏移量> = 0
        len - 要删除的字符数> = 0
        异常
        BadLocationException - 给定的删除位置不是文档中的有效位置
        另请参见：
        Document.remove(int, int)

      • replace

        public void replace​(int offset,
                    int length,
                    String text,
                    AttributeSet attrs)
             throws BadLocationException
        删除文本区域offset到offset + length ，并将其替换为text 。 由实现如何实现，一些实现可以将其视为两个不同的操作：删除后跟插入，其他可以将替换视为一个原子操作。
        参数
        offset - 子元素的索引
        length - 要删除的文本长度，可能为0表示不删除任何内容
        text - 要插入的文本， null表示不插入文本
        attrs - 表示插入文本属性的AttributeSet， null是合法的，通常被视为空属性集，但是精确解释留给子类
        异常
        BadLocationException - 给定位置不是文档中的有效位置
        从以下版本开始：
        1.4

      • 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;
   }
        Specified by:
        getText在界面 Document
        参数
        offset - 起始偏移量> = 0
        length - 要检索的字符数> = 0
        txt - 要将文本检索到的Segment对象
        异常
        BadLocationException - 给定的范围包括不在文档中的有效位置的位置

      • getStartPosition

        public final Position getStartPosition()
        返回表示文档开头的位置。 返回的位置可以计入跟踪更改并保持位于文档的开头。
        Specified by:
        getStartPosition在界面 Document
        结果
        这个职位

      • getEndPosition

        public final Position getEndPosition()
        返回表示文档末尾的位置。 返回的位置可以计入跟踪更改并保持位于文档的末尾。
        Specified by:
        getEndPosition在界面 Document
        结果
        这个职位

      • getRootElements

        public Element[] getRootElements()
        获取定义的所有根元素。 通常，只有一个，因此默认实现是返回默认的根元素。
        Specified by:
        getRootElements在界面 Document
        结果
        根元素

      • getBidiRootElement

        public Element getBidiRootElement()
        返回此文档的双向结构的根元素。 它的子代表具有给定的Unicode bidi级别的字符运行。
        结果
        此文档的双向结构的根元素

      • 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)
        作为文本删除的结果更新任何文档结构。 在实际从内容中删除文本之前调用此方法。 这将发生在写锁定中。 如果此类的子类重新实现此方法，则它也应该委托给超类。
        参数
        chng - 更改说明

      • postRemoveUpdate

        protected void postRemoveUpdate​(AbstractDocument.DefaultDocumentEvent chng)
        作为文本删除的结果更新任何文档结构。 从内容中删除文本后调用此方法。 这将发生在写锁定中。 如果此类的子类重新实现此方法，则它也应该委托给超类。
        参数
        chng - 更改说明

      • dump

        public void dump​(PrintStream out)
        提供诊断转储。
        参数
        out - 输出流

      • 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获得的写锁定。 如果没有未完成的锁定，则在减少锁定计数后，这将允许新的作者或读者。
        另请参见：
        writeLock()

      • readLock

        public final void readLock()
        获取锁以开始从文档中读取某些状态。 可以同时有多个读者。 写入会阻止读者，直到完成对听众的更改通知。 应该非常小心地使用此方法，以避免文档的意外泄露。 它应始终与readUnlock平衡。
        另请参见：
        readUnlock()

      • readUnlock

        public final void readUnlock()
        读取是否解锁。 这表示其中一个读者完成了。 如果没有更多的读者，那么写作可以再次开始。 这应该与readLock平衡，并且应该在finally语句中进行，以便保证平衡。 以下是一个例子。 
             readLock();   try {   // do something   } finally {   readUnlock();   }
        另请参见：
        readLock()