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

Class AbstractDocument

  • All Implemented Interfaces:
    SerializableDocument
    已知直接子类:
    DefaultStyledDocumentPlainDocument


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

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

    任何从该类子类化并与从BasicTextUI导出的外观实现结合使用的模型可能会被异步地安全更新,因为如果文档的类型为AbstractDocument ,则BasicTextUI的所有访问都将被BasicTextUI序列化。 锁定假定一个独立的线程只能从DocumentListener方法访问View层次结构,并且一次只有一个事件线程处于活动状态。

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

    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通过了insertremove以有条件地允许插入/删除文本。 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); 
        如果valuenull这个方法将删除该属性。
        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()