モジュール java.desktop
パッケージ javax.swing.text

クラスAbstractDocument

  • すべての実装されたインタフェース:
    Serializable, Document
    直系の既知のサブクラス:
    DefaultStyledDocument, PlainDocument
    public abstract class AbstractDocument
extends Object
implements Document, Serializable
    ドキュメント・インタフェースの実装であり、各種のドキュメントを実装するときのベースになります。 このレベルではポリシーがごくわずかなので、それに応じて使用が難しくなります。

    このクラスはドキュメントのロック・メカニズムを実装します。 これによって、複数の読取りまたは1つの書込みを扱えるようになり、複数の書込みがあっても、ドキュメントのオブザーバ全員に以前の変更が通知されるまで、ドキュメントに別の変更を加えることができません。 読取りロックの取得および解放には、renderメソッドを使用します。 書込みロックは、ドキュメントを変更するメソッドによって取得され、そのメソッド呼出しの間は保持されます。 通知は、ドキュメントを変更するスレッド上で行われます。このスレッドは、通知の間はドキュメントへの完全な読取りアクセス権を持っています。一方で、その他の読取り側は、通知が完了するまではアクセスを許されません。 通知はBeansイベント通知であり、すべてのリスナーが通知を受け取るまでは他の変更を許可しません。

    このクラスからサブクラス化された任意のモデルで、BasicTextUIから派生したLook & Feelの実装を持つテキスト・コンポーネントと関連して使用されるものは、非同期に更新しても問題ありません。これは、ドキュメントのタイプがAbstractDocumentの場合には、View階層へのすべてのアクセスがBasicTextUIによって直列化されるからです。 ロックでは、独立したスレッドのView階層へのアクセスは必ずDocumentListenerメソッドを介して行われ、また、1回につきアクティブなイベント・スレッドは1つしか存在しないと見なします。

    同期のサポートが必要な場合は、さらに次の前提条件があります。 任意のDocumentListenerおよびUndoListenerの実装に対するコード・パスがスレッドに対して安全であること、また、デッドロックを避ける場合には、コンポーネントのロックにアクセスしないこと、という条件です。 JComponentのrepaintメソッドおよびrevalidateメソッドは安全です。

    AbstractDocumentはドキュメントの最後に暗黙のブレークをモデル化します。 さまざまなことが可能ですが、その1つとして最後の文字のあとにキャレットを配置できます。 その結果、Contentより短いgetLengthを返します。 独自のContentを生成する場合は、文字を追加して初期化するようにしてください。 この例についてはStringContentとGapContentを参照してください。 別の前提条件は、暗黙の最終文字をモデル化するElementsはendOffset ==(getLength()+1)となることです。 たとえば、DefaultStyledDocumentの場合はgetParagraphElement(getLength()).getEndOffset()== getLength()+1 です。

    警告: このクラスの直列化されたオブジェクトは、今後のSwingリリースとの互換性がなくなる予定です。 現在の直列化のサポートは、短期間の格納や、同じバージョンのSwingを実行するアプリケーション間のRMIに適しています。 1.4以降、すべてのJavaBeans™用の長期間の格納サポートがjava.beansパッケージに追加されています。 XMLEncoderを参照してください。

    • フィールドの詳細

      • listenerList

        protected EventListenerList listenerList
        ドキュメントのイベント・リスナーです。

      • BAD_LOCATION

        protected static final String BAD_LOCATION
        不正な位置を示すエラー・メッセージです。
        関連項目:
        定数フィールド値

      • ParagraphElementName

        public static final String ParagraphElementName
        段落を示す要素の名前です。
        関連項目:
        定数フィールド値

      • 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 - 属性のコンテキスト

    • メソッドの詳細

      • setDocumentProperties

        public void setDocumentProperties​(Dictionary<Object,​Object> x)
        このドキュメントのドキュメント・プロパティの辞書を置き換えます。
        パラメータ:
        x - 新規辞書
        関連項目:
        getDocumentProperties()

      • 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メソッドを使用して登録されます。

        FooListener.classなどのクラス・リテラルを使用してlistenerType引数を指定できます。 たとえば、次のコードを使用すると、ドキュメントdをそのドキュメント・リスナーに照会できます。 

        DocumentListener[] mls = (DocumentListener[])(d.getListeners(DocumentListener.class));
        このようなリスナーがない場合は空の配列を返します。

        型パラメータ:
        T - リスナー型
        パラメータ:
        listenerType - リクエストされたリスナーの型
        戻り値:
        このコンポーネント上でFooListenerとして登録されたすべてのオブジェクトの配列、またはこのようなリスナーが追加されていない場合は空の配列
        例外:
        ClassCastException - listenerTypeで、java.util.EventListenerを実装するクラスまたはインタフェースが指定されなかった場合
        導入されたバージョン:
        1.3
        関連項目:
        getDocumentListeners(), getUndoableEditListeners()

      • getAsynchronousLoadPriority

        public int getAsynchronousLoadPriority()
        非同期ロードの優先順位を取得します。 0より小さい値の場合、ドキュメントは非同期にはロードされません。
        戻り値:
        非同期ロードの優先順位。ドキュメントが非同期でロードされない場合は-1

      • setAsynchronousLoadPriority

        public void setAsynchronousLoadPriority​(int p)
        非同期ロードの優先順位を設定します。
        パラメータ:
        p - 新しい非同期ロードの優先順位。0より小さい値の場合、ドキュメントは非同期でロードされない

      • setDocumentFilter

        public void setDocumentFilter​(DocumentFilter filter)
        DocumentFilterを設定します。 DocumentFilterがinsertとremoveに渡され、条件付きでテキストの挿入や削除が可能になります。 null値は、フィルタが実行されないことを表します。
        パラメータ:
        filter - テキストの制約に使用されるDocumentFilter
        導入されたバージョン:
        1.4
        関連項目:
        getDocumentFilter()

      • getDocumentFilter

        public DocumentFilter getDocumentFilter()
        挿入または削除のフィルタを行うDocumentFilterを返します。 戻り値nullは、フィルタが実行されないことを表します。
        戻り値:
        DocumentFilter
        導入されたバージョン:
        1.4
        関連項目:
        setDocumentFilter(javax.swing.text.DocumentFilter)

      • render

        public void render​(Runnable r)
        モデルが非同期的な更新をサポートしている場合、並行性に直面してモデルを安全に描画できるようにします。 指定された実行可能ファイルは、その実行中に何の変更もなくモデルを安全に読み取る方法で実行されます。 実行可能ファイルは、それ自身で変更を加えることはできません。

        この実装は、Runnableオブジェクトを実行している間、読取りロックを取得するためのものです。 複数を同時に実行している場合、アクティブに描画中のオブジェクトがある間は、すべての書込みがブロックされます。 オブジェクトが例外をスローした場合、そのロックは安全に解放されます。 決して終了しないオブジェクトに対する保護はなく、事実上、ドキュメントは自身が存在する間ずっとロックされます。

        指定されたRunnableオブジェクトがこの実装でどのような変更を試みても、デッドロックが発生します。 この状況を検知できるようにするために個々の描画スレッドを追跡することはできません。また、サブクラスは、描画スレッドの追跡、およびエラーのスローのオーバーヘッドを発生させる可能性があります。

        このメソッドはスレッド・セーフですが、ほとんどのSwingメソッドは違います。 詳細は、Swingでの並行性に関連しているサイトを参照してください。

        定義:
        render、インタフェース: Document
        パラメータ:
        r - 実行するレンダラ

      • getLength

        public int getLength()
        データの長さを返します。 ユーザーのデータを示す内容の文字数です。
        定義:
        getLength、インタフェース: Document
        戻り値:
        長さ>= 0
        関連項目:
        Document.getLength()

      • getProperty

        public final Object getProperty​(Object key)
        プロパティの値を調べるのに便利なメソッドです。 これは次と同等です。 
         getDocumentProperties().get(key);
        定義:
        getProperty、インタフェース: Document
        パラメータ:
        key - null以外のプロパティ・キー
        戻り値:
        このプロパティの値またはnull
        関連項目:
        getDocumentProperties()

      • putProperty

        public final void putProperty​(Object key,
                              Object value)
        プロパティの値を格納するのに便利なメソッドです。 これは次と同等です。 
         getDocumentProperties().put(key, value);
        valueがnullの場合、このメソッドはプロパティを削除します。
        定義:
        putProperty、インタフェース: Document
        パラメータ:
        key - null以外のキー
        value - プロパティ値
        関連項目:
        getDocumentProperties()

      • remove

        public void remove​(int offs,
                   int len)
            throws BadLocationException
        ドキュメントから内容を削除します。 内容の削除によって、実際の変更が起きるまでの書込みロックが発生します。 オブザーバは、このメソッドを呼び出したスレッド上で変更の通知を受けます。

        このメソッドはスレッド・セーフですが、ほとんどのSwingメソッドは違います。 詳細は、Swingでの並行性に関連しているサイトを参照してください。

        定義:
        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に置き換えます。 この動作がどのように実装されるかはその実装に左右され、削除してから挿入を行うというように別々の2つの操作として実装することもあれば、置換えを行うというように1つの基本操作として実装することもあります。
        パラメータ:
        offset - 子要素のインデックス
        length - 削除するテキストの長さ。0の場合は何も削除されない
        text - 挿入するテキスト。nullの場合、テキストは挿入されない
        attrs - 挿入されたテキストの属性を示すAttributeSet。nullも可。空の属性セットとして扱われるが、サブクラスで正確な解釈をする
        例外:
        BadLocationException - 指定された位置がドキュメント内の有効な位置でない場合
        導入されたバージョン:
        1.4

      • insertString

        public void insertString​(int offs,
                         String str,
                         AttributeSet a)
                  throws BadLocationException
        ドキュメントに内容を挿入します。 内容の挿入によって、実際の変更が起きるまでは書込みロックが保持されます。その後で、書込みロックをグラブしているスレッド上のオブザーバに通知が行われます。

        このメソッドはスレッド・セーフですが、ほとんどのSwingメソッドは違います。 詳細は、Swingでの並行性に関連しているサイトを参照してください。

        定義:
        insertString、インタフェース: Document
        パラメータ:
        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
        ドキュメントからテキストのシーケンスを取得します。
        定義:
        getText、インタフェース: Document
        パラメータ:
        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;
   }

        定義:
        getText、インタフェース: Document
        パラメータ:
        offset - 開始オフセット>= 0
        length - 取得対象の文字数>= 0
        txt - テキストを取得するSegmentオブジェクト
        例外:
        BadLocationException - 指定された範囲に、ドキュメント内の無効な位置が含まれる場合

      • createPosition

        public Position createPosition​(int offs)
                        throws BadLocationException
        ドキュメントが変更されたときに、変更を追跡する位置を返します。

        このメソッドはスレッド・セーフですが、ほとんどのSwingメソッドは違います。 詳細は、Swingでの並行性に関連しているサイトを参照してください。

        定義:
        createPosition、インタフェース: Document
        パラメータ:
        offs - モデル内の位置>= 0
        戻り値:
        位置
        例外:
        BadLocationException - 指定された位置が、関連するドキュメント内の有効な位置を示さない場合
        関連項目:
        Document.createPosition(int)

      • getStartPosition

        public final Position getStartPosition()
        ドキュメントの先頭を表す位置を返します。 返された位置は、変更を追跡してドキュメントの先頭に常に位置するために利用できます。
        定義:
        getStartPosition、インタフェース: Document
        戻り値:
        位置

      • getEndPosition

        public final Position getEndPosition()
        ドキュメントの末尾を表す位置を返します。 返された位置は、変更を追跡してドキュメントの末尾に常に位置するために利用できます。
        定義:
        getEndPosition、インタフェース: Document
        戻り値:
        位置

      • getRootElements

        public Element[] getRootElements()
        定義されているルート要素をすべて取得します。 通常、ルート要素は1つしかありません。そのため、デフォルトの実装ではデフォルト・ルート要素が返されます。
        定義:
        getRootElements、インタフェース: Document
        戻り値:
        ルート要素

      • getDefaultRootElement

        public abstract Element getDefaultRootElement()
        ルート要素を返します。要素の構造にビューを割り当てる別のメカニズムが提供されないかぎり、このルート要素がビューのベースになります。
        定義:
        getDefaultRootElement、インタフェース: Document
        戻り値:
        ルート要素
        関連項目:
        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)
        診断用のダンプを出力します。
        パラメータ:
        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経由で取得された書込みロックを解除します。 ロック数を1つ減らした後、未処理のロックがない場合は、新しい書込み側または読取り側が許可されます。
        関連項目:
        writeLock()

      • readLock

        public final void readLock()
        ロックを取得して、ドキュメントからなんらかの状態の読込みを開始できるようにします。 複数のリーダーが同時に存在できます。 リスナーに対する変更の通知が完了するまで書込みは読込みをブロックします。 ドキュメント・ロックが誤って取得されないように、このメソッドは注意深く使用する必要があります。 readLockメソッドと同じ数だけ、readUnlockを呼び出してください。
        関連項目:
        readUnlock()

      • readUnlock

        public final void readUnlock()
        読込みのロックを解除します。 読込みの1つが完了したことを通知します。 ほかにリーダーがなければ、書込みを再開できます。 このメソッドの呼出し回数は、readLockの呼出し回数と同じにする必要があるので、これを保証するためにfinally文の中で使います。 次に例を示します。 
        
     readLock();
     try {
         // do something
     } finally {
         readUnlock();
     }
        関連項目:
        readLock()