Module  java.desktop
软件包  javax.swing.text

Class AbstractDocument

  • All Implemented Interfaces:
    Serializable ， Document
    已知直接子类：
    DefaultStyledDocument ， PlainDocument 

    public abstract class AbstractDocument
extends Object
implements Document, Serializable
    实现文档界面，作为实施各种文件的基础。 在这个级别上，政策很少，所以使用难度相应增加。

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

    任何从该类子类化并与从BasicTextUI导出的外观实现结合使用的模型可能会被异步地安全更新，因为如果文档的类型为AbstractDocument ，则BasicTextUI的所有访问都将被BasicTextUI序列化。 锁定假定一个独立的线程只能从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版本开始，支持所有JavaBeans的长期存储已被添加到java.beans包中。 请参阅XMLEncoder 。

    另请参见：
    Serialized Form

    • 字段详细信息

      • listenerList

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

      • ParagraphElementName

        public static final String ParagraphElementName
        用于表示段落的元素的名称
        另请参见：
        Constant Field Values

      • ContentElementName

        public static final String ContentElementName
        用于表示内容的元素的名称
        另请参见：
        Constant Field Values

      • SectionElementName

        public static final String SectionElementName
        用于保存部分的元素名称（行/段落）。
        另请参见：
        Constant Field Values

      • BidiElementName

        public static final String BidiElementName
        用于保持单向运行的元素的名称
        另请参见：
        Constant Field Values

      • ElementNameAttribute

        public static final String ElementNameAttribute
        用于指定元素名称的属性的名称。
        另请参见：
        Constant Field Values

    • 构造方法详细信息

      • 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​(Class<T> listenerType)
        返回此文档上当前注册为FooListener的所有对象的数组。 FooListener使用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以有条件地允许插入/删除文本。 A null值表示不会发生过滤。
        参数
        filter - 用于约束文本的 DocumentFilter
        从以下版本开始：
        1.4
        另请参见：
        getDocumentFilter()

      • render

        public void render​(Runnable r)
        如果模型支持异步更新，则可以在存在货币的情况下安全地呈现模型。 给定的可运行程序将以允许其在执行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，则在段中返回的数据将是所请求的整个长度，并且根据数据的存储方式可以复制或不复制。 如果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()