モジュール java.xml
パッケージ javax.xml.parsers

クラスDocumentBuilderFactory

java.lang.Object
javax.xml.parsers.DocumentBuilderFactory
public abstract class DocumentBuilderFactory
extends Object
アプリケーションでXMLドキュメントからDOMオブジェクト・ツリーを生成するパーサーを取得できるファクトリAPIを定義します。
導入されたバージョン:
1.4

  • コンストラクタのサマリー

    コンストラクタ 
    修飾子 コンストラクタ 説明
    protected DocumentBuilderFactory()
    インスタンス化を妨げるprotectedコンストラクタです。

  • メソッドのサマリー

    修飾子と型 メソッド 説明
    abstract Object getAttribute​(String name)
    ユーザーがベースとなる実装の特定の属性を取り出すことができるようにします。
    abstract boolean getFeature​(String name)
    名前が付けられた機能の状態を取得します。
    Schema getSchema()
    setSchema(Schema schema)メソッドによって指定されたSchemaオブジェクトを取得します。
    boolean isCoalescing()
    CDATAノードをTextノードに変換し、それを隣接(存在する場合) Textノードに追加するパーサーを作成するようにファクトリが構成されているかどうかを示します。
    boolean isExpandEntityReferences()
    エンティティ参照ノードを展開するパーサーを作成するようにファクトリが構成されているかどうかを示します。
    boolean isIgnoringComments()
    コメントを無視するパーサーを作成するようにファクトリが構成されているかどうかを示します。
    boolean isIgnoringElementContentWhitespace()
    要素の内容の無視できる空白を無視するパーサーを作成するようにファクトリが構成されているかどうかを示します。
    boolean isNamespaceAware()
    ファクトリが名前空間を認識するパーサーを作成するように構成されているかどうかを示します。
    boolean isValidating()
    構文解析時にXMLコンテンツを検証するパーサーを作成するようにファクトリが構成されているかどうかを示します。
    boolean isXIncludeAware()
    XInclude処理の状態を取得します。
    static DocumentBuilderFactory newDefaultInstance()
    DocumentBuilderFactory組み込みシステムのデフォルト実装の新しいインスタンスを作成します。
    static DocumentBuilderFactory newDefaultNSInstance()
    DocumentBuilderFactory組込みシステムのデフォルト実装の新しいNamespaceAwareインスタンスを作成します。
    abstract DocumentBuilder newDocumentBuilder()
    現在構成されているパラメータを使用してDocumentBuilderの新しいインスタンスを作成します。
    static DocumentBuilderFactory newInstance()
    DocumentBuilderFactoryの新しいインスタンスを取得します。
    static DocumentBuilderFactory newInstance​(String factoryClassName, ClassLoader classLoader)
    クラス名からDocumentBuilderFactoryの新しいインスタンスを取得します。
    static DocumentBuilderFactory newNSInstance()
    DocumentBuilderFactoryの新しいNamespaceAwareインスタンスを作成します。
    static DocumentBuilderFactory newNSInstance​(String factoryClassName, ClassLoader classLoader)
    クラス名からDocumentBuilderFactoryの新しいNamespaceAwareインスタンスを作成します。
    abstract void setAttribute​(String name, Object value)
    ユーザーがベースとなる実装に特定の属性を設定できるようにします。
    void setCoalescing​(boolean coalescing)
    このファクトリで作成されたパーサーがCDATAノードをTextノードに変換し、それを隣接(存在する場合) Textノードに追加するように指定します。
    void setExpandEntityReferences​(boolean expandEntityRef)
    このファクトリで作成されたパーサーがエンティティ参照ノードを展開するように指定します。
    abstract void setFeature​(String name, boolean value)
    このファクトリによって生成されたDocumentBuilderFactoryおよびDocumentBuilderの機能を設定します。
    void setIgnoringComments​(boolean ignoreComments)
    このコードで作成されたパーサーがコメントを無視するように指定します。
    void setIgnoringElementContentWhitespace​(boolean whitespace)
    このファクトリで作成されたパーサーが、XMLドキュメントの構文解析時に要素の内容の空白(大まかに「無視できる空白」と呼ばれることがある)を排除するように指定します(XML Rec 2.10を参照)。
    void setNamespaceAware​(boolean awareness)
    このファクトリで作成されたパーサーがXML名前空間をサポートするように指定します。
    void setSchema​(Schema schema)
    このファクトリから作成されたパーサーによって使用されるSchemaを設定します。
    void setValidating​(boolean validating)
    このファクトリで作成されたパーサーが構文解析時にドキュメントの妥当性を検証するように指定します。
    void setXIncludeAware​(boolean state)
    XInclude処理の状態を設定します。

    クラス java.lang.Objectで宣言されたメソッド

    clone、equals、finalize、getClass、hashCode、notify、notifyAll、toString、wait、wait、wait

  • コンストラクタの詳細

    • DocumentBuilderFactory

      protected DocumentBuilderFactory()
      インスタンス化を妨げるprotectedコンストラクタです。 newInstance()を使用してください。

  • メソッドの詳細

    • newDefaultNSInstance

      public static DocumentBuilderFactory newDefaultNSInstance()
      DocumentBuilderFactory組込みシステムのデフォルト実装の新しいNamespaceAwareインスタンスを作成します。 ファクトリ・インスタンスによって生成されたパーサーは、デフォルトでXMLネームスペースのサポートを提供します。
      実装要件:
      このメソッドは、newDefaultInstance()と同じプロセスを使用してファクトリ・インスタンスを作成するだけでなく、NamespaceAwareをtrueに設定する必要があります。
      戻り値:
      DocumentBuilderFactory組込みシステムのデフォルトの実装の新しいインスタンス。
      導入されたバージョン:
      13

    • newNSInstance

      public static DocumentBuilderFactory newNSInstance()
      DocumentBuilderFactoryの新しいNamespaceAwareインスタンスを作成します。 ファクトリ・インスタンスによって生成されたパーサーは、デフォルトでXMLネームスペースのサポートを提供します。
      実装要件:
      このメソッドは、newInstance()と同じプロセスを使用してファクトリ・インスタンスを作成するだけでなく、NamespaceAwareをtrueに設定する必要があります。
      戻り値:
      DocumentBuilderFactoryの新しいインスタンス
      例外:
      FactoryConfigurationError - サービス構成エラーが発生した場合、または実装が使用できないかインスタンス化できない場合。
      導入されたバージョン:
      13

    • newNSInstance

      public static DocumentBuilderFactory newNSInstance​(String factoryClassName, ClassLoader classLoader)
      クラス名からDocumentBuilderFactoryの新しいNamespaceAwareインスタンスを作成します。 ファクトリ・インスタンスによって生成されたパーサーは、デフォルトでXMLネームスペースのサポートを提供します。
      実装要件:
      このメソッドは、newInstance(java.lang.String, java.lang.ClassLoader)と同じプロセスを使用してファクトリ・インスタンスを作成するだけでなく、NamespaceAwareをtrueに設定する必要があります。
      パラメータ:
      factoryClassName - javax.xml.parsers.DocumentBuilderFactoryの実装を提供する完全修飾ファクトリ・クラス名。
      classLoader - ファクトリ・クラスをロードするために使用するClassLoader。 nullの場合、現在のThreadコンテキストclassLoaderがファクトリ・クラスをロードするために使用されます。
      戻り値:
      DocumentBuilderFactoryの新しいインスタンス
      例外:
      FactoryConfigurationError - factoryClassNameがnull、またはファクトリ・クラスをロードまたはインスタンス化できない場合。
      導入されたバージョン:
      13

    • newDefaultInstance

      public static DocumentBuilderFactory newDefaultInstance()
      DocumentBuilderFactory組み込みシステムのデフォルト実装の新しいインスタンスを作成します。
      戻り値:
      DocumentBuilderFactory組み込みシステムのデフォルト実装の新しいインスタンス。
      導入されたバージョン:
      9

    • newInstance

      public static DocumentBuilderFactory newInstance()
      DocumentBuilderFactoryの新しいインスタンスを取得します。 このstaticメソッドは新しいファクトリ・インスタンスを作成します。 このメソッドは次の順序の検索手順で、ロードするDocumentBuilderFactory実装クラスを決定します。
      • javax.xml.parsers.DocumentBuilderFactoryシステム・プロパティを使用する。

      • 構成ファイル"jaxp.properties"を使用します。 このファイルは標準のProperties形式であり、通常Javaインストールのconfディレクトリにあります。 これには、実装クラスの完全修飾名が格納されています。

        jaxp.propertiesファイルはJAXP実装によって一度だけ読み込まれ、その値は将来の使用のためにキャッシュされます。 最初の読込み時にファイルが存在しないと、そのあとにその存在がチェックされることはない。 最初に読み込まれたあと、jaxp.propertiesのプロパティの値を変更することはできない。

      • ServiceLoaderクラスで定義されているサービス・プロバイダ・ローディング機能を使用して、デフォルトのロード・メカニズムを使用してサービスの実装を特定してロード: サービス・プロバイダ・ローディング機能は、現在のスレッド・コンテキスト・クラス・ローダーを使用してサービスをロードしようとします。 コンテキスト・クラス・ローダーがnullの場合、システム・クラス・ローダーが使用されます。

      • それ以外の場合は、system-default実装が返されます。

      アプリケーションがDocumentBuilderFactoryへの参照を取得すると、ファクトリを使用してパーサーのインスタンスを構成および取得できます。

      Tip for Trouble-shooting

      jaxp.debugシステム・プロパティを設定すると、このメソッドは実行中の処理や検索している場所に関する大量のデバッグ・メッセージをSystem.errに出力します。

      DocumentBuilderのロードに問題がある場合、次のようにします。 

       java -Djaxp.debug=1 YourProgram ....

      戻り値:
      DocumentBuilderFactoryの新しいインスタンス
      例外:
      FactoryConfigurationError - サービス構成エラーが発生した場合、または実装が使用できないかインスタンス化できない場合。

    • newInstance

      public static DocumentBuilderFactory newInstance​(String factoryClassName, ClassLoader classLoader)
      クラス名からDocumentBuilderFactoryの新しいインスタンスを取得します。 この関数は、クラス・パスに複数のプロバイダがある場合に便利です。 どのプロバイダがロードされるかを指定できるため、アプリケーションをさらに制御できます。

      アプリケーションがDocumentBuilderFactoryへの参照を取得すると、ファクトリを使用してパーサーのインスタンスを構成および取得できます。

      Tip for Trouble-shooting

      jaxp.debugシステム・プロパティを設定すると、このメソッドは実行中の処理や検索している場所に関する大量のデバッグ・メッセージをSystem.errに出力します。

      問題がある場合、次のようにします。 

       java -Djaxp.debug=1 YourProgram ....

      パラメータ:
      factoryClassName - javax.xml.parsers.DocumentBuilderFactoryの実装を提供する完全指定のファクトリ・クラス名。
      classLoader - ファクトリ・クラスのロードに使用されるClassLoader。 nullの場合は、現在のThreadのコンテキストclassLoaderが、ファクトリ・クラスのロードに使用されます。
      戻り値:
      DocumentBuilderFactoryの新しいインスタンス
      例外:
      FactoryConfigurationError - factoryClassNameがnull、またはファクトリ・クラスをロードまたはインスタンス化できない場合。
      導入されたバージョン:
      1.6
      関連項目:
      newInstance()

    • newDocumentBuilder

      public abstract DocumentBuilder newDocumentBuilder() throws ParserConfigurationException
      現在構成されているパラメータを使用してDocumentBuilderの新しいインスタンスを作成します。
      戻り値:
      DocumentBuilderの新しいインスタンス。
      例外:
      ParserConfigurationException - 要求された構成を満たすDocumentBuilderを作成できない場合。

    • setNamespaceAware

      public void setNamespaceAware​(boolean awareness)
      このファクトリで作成されたパーサーがXML名前空間をサポートするように指定します。 デフォルトでは、この値はfalseに設定されます。
      パラメータ:
      awareness - 作成されたパーサーがXML名前空間をサポートする場合はtrue、そうでない場合はfalse。

    • setValidating

      public void setValidating​(boolean validating)
      このファクトリで作成されたパーサーが構文解析時にドキュメントの妥当性を検証するように指定します。 デフォルトでは、この値はfalseに設定されます。

      ここで言う「検証」とは、XML勧告で定義されている妥当性を検証するパーサーという意味です。 つまり、実質的にはDTD検証を制御するだけということです。ただし、JAXP 1.2に定義されている従来の2つのプロパティを除きます。

      DTDではなく、W3C XML SchemaまたはRELAX NGなどの新しいスキーマ言語を使用する場合は、setValidating(boolean)メソッドをfalseにして妥当性を検証しないパーサーとして構成してから、setSchema(Schema)メソッドでスキーマをパーサーに関連付けます。

      パラメータ:
      validating - 作成されたパーサーが構文解析時にドキュメントの妥当性を検証する場合はtrue、そうでない場合はfalse。

    • setIgnoringElementContentWhitespace

      public void setIgnoringElementContentWhitespace​(boolean whitespace)
      このファクトリで作成されたパーサーが、XMLドキュメントの構文解析時に要素の内容の空白(大まかに「無視できる空白」と呼ばれることがある)を排除するように指定します(XML Rec 2.10を参照)。 要素だけのコンテンツ・モデル(XML Rec 3.2.1を参照)を持つ要素の内容に直接含まれる空白だけが排除されます。 コンテンツ・モデルに依存しているために、この設定ではパーサーが検証モードであることが必要です。 デフォルトでは、この値はfalseに設定されます。
      パラメータ:
      whitespace - 作成されたパーサーがXMLドキュメントの構文解析時に要素の内容の空白を排除する必要がある場合はtrue、そうでない場合はfalse。

    • setExpandEntityReferences

      public void setExpandEntityReferences​(boolean expandEntityRef)
      このファクトリで作成されたパーサーがエンティティ参照ノードを展開するように指定します。 デフォルトでは、この値はtrueに設定されます。
      パラメータ:
      expandEntityRef - 作成されたパーサーがエンティティ参照ノードを展開する場合はtrue、そうでない場合はfalse。

    • setIgnoringComments

      public void setIgnoringComments​(boolean ignoreComments)
      このコードで作成されたパーサーがコメントを無視するように指定します。 デフォルトでは、この値はfalseに設定されます。
      パラメータ:
      ignoreComments - 処理時にコメントを無視するboolean値

    • setCoalescing

      public void setCoalescing​(boolean coalescing)
      このファクトリで作成されたパーサーがCDATAノードをTextノードに変換し、それを隣接(存在する場合) Textノードに追加するように指定します。 デフォルトでは、この値はfalseに設定されます。
      パラメータ:
      coalescing - 作成されたパーサーがCDATAノードをTextノードに変換し、それを隣接(存在する場合) Textノードに追加する場合はtrue、そうでない場合はfalse。

    • isNamespaceAware

      public boolean isNamespaceAware()
      ファクトリが名前空間を認識するパーサーを作成するように構成されているかどうかを示します。
      戻り値:
      ファクトリが名前空間を認識するパーサーを作成するように構成されている場合はtrue、そうでない場合はfalse。

    • isValidating

      public boolean isValidating()
      構文解析時にXMLコンテンツを検証するパーサーを作成するようにファクトリが構成されているかどうかを示します。
      戻り値:
      構文解析時にXMLコンテンツを検証するパーサーを作成するようにファクトリが構成されている場合はtrue、そうでない場合はfalse。

    • isIgnoringElementContentWhitespace

      public boolean isIgnoringElementContentWhitespace()
      要素の内容の無視できる空白を無視するパーサーを作成するようにファクトリが構成されているかどうかを示します。
      戻り値:
      要素の内容の無視できる空白を無視するパーサーを作成するようにファクトリが構成されている場合はtrue、そうでない場合はfalse。

    • isExpandEntityReferences

      public boolean isExpandEntityReferences()
      エンティティ参照ノードを展開するパーサーを作成するようにファクトリが構成されているかどうかを示します。
      戻り値:
      エンティティ参照ノードを展開するパーサーを構成するようにファクトリが設定されている場合はtrue、そうでない場合はfalse。

    • isIgnoringComments

      public boolean isIgnoringComments()
      コメントを無視するパーサーを作成するようにファクトリが構成されているかどうかを示します。
      戻り値:
      コメントを無視するパーサーを作成するようにファクトリが構成されている場合はtrue、そうでない場合はfalse。

    • isCoalescing

      public boolean isCoalescing()
      CDATAノードをTextノードに変換し、それを隣接(存在する場合) Textノードに追加するパーサーを作成するようにファクトリが構成されているかどうかを示します。
      戻り値:
      CDATAノードをTextノードに変換し、それを隣接(存在する場合) Textノードに追加するパーサーを構成するようにファクトリが設定されている場合はtrue、そうでない場合はfalse。

    • setAttribute

      public abstract void setAttribute​(String name, Object value) throws IllegalArgumentException
      ユーザーがベースとなる実装に特定の属性を設定できるようにします。

      JAXP 1.5またはそれ以降を実装する実装はすべて、XMLConstants.ACCESS_EXTERNAL_DTDおよびXMLConstants.ACCESS_EXTERNAL_SCHEMAプロパティをサポートしている必要があります。

      • XMLConstants.ACCESS_EXTERNAL_DTDプロパティを設定すると、外部DTDおよび外部エンティティ参照へのアクセスが、そのプロパティで指定されたプロトコルに制限されます。 このプロパティの制限が原因で構文解析中にアクセスが拒否された場合は、DocumentBuilderで定義された解析メソッドによってSAXExceptionがスローされます。
      • XMLConstants.ACCESS_EXTERNAL_SCHEMAプロパティを設定すると、schemaLocation属性によって設定された外部スキーマへのアクセスが、そのプロパティで指定されたプロトコルに制限されます。 このプロパティの制限が原因で構文解析中にアクセスが拒否された場合は、DocumentBuilderで定義された解析メソッドによってSAXExceptionがスローされます。

      パラメータ:
      name - 属性の名前。
      value - 属性の値。
      例外:
      IllegalArgumentException - ベースとなる実装が属性を認識しない場合にスローされる。

    • getAttribute

      public abstract Object getAttribute​(String name) throws IllegalArgumentException
      ユーザーがベースとなる実装の特定の属性を取り出すことができるようにします。
      パラメータ:
      name - 属性の名前。
      戻り値:
      属性の値。
      例外:
      IllegalArgumentException - ベースとなる実装が属性を認識しない場合にスローされる。

    • setFeature

      public abstract void setFeature​(String name, boolean value) throws ParserConfigurationException
      このファクトリによって生成されたDocumentBuilderFactoryおよびDocumentBuilderの機能を設定します。

      機能名は完全修飾URIです。 実装が独自の機能を定義することもできます。 生成するこのDocumentBuilderFactoryまたはDocumentBuilderがその機能をサポートできない場合は、ParserConfigurationExceptionがスローされます。 DocumentBuilderFactoryは機能の値を表示できますが、その状態を変更することはできません。

      実装はすべて、XMLConstants.FEATURE_SECURE_PROCESSING機能をサポートしている必要があります。 この機能については次のとおりです。

      パラメータ:
      name - 機能名。
      value - 機能の状態がtrueかfalseか。
      例外:
      ParserConfigurationException - このDocumentBuilderFactoryまたはそれによって作成されるDocumentBuilderがこの機能をサポートできない場合。
      NullPointerException - nameパラメータがnullである場合。
      導入されたバージョン:
      1.5

    • getFeature

      public abstract boolean getFeature​(String name) throws ParserConfigurationException
      名前が付けられた機能の状態を取得します。

      機能名は完全修飾URIです。 実装が独自の機能を定義することもできます。 生成するDocumentBuilderFactoryまたはDocumentBuilderがその機能をサポートできない場合は、ParserConfigurationExceptionがスローされます。 DocumentBuilderFactoryは機能の値を表示できますが、その状態を変更することはできません。

      パラメータ:
      name - 機能名。
      戻り値:
      名前が付けられた機能の状態。
      例外:
      ParserConfigurationException - このDocumentBuilderFactoryまたはそれによって作成されるDocumentBuilderがこの機能をサポートできない場合。
      導入されたバージョン:
      1.5

    • getSchema

      public Schema getSchema()
      setSchema(Schema schema)メソッドによって指定されたSchemaオブジェクトを取得します。
      戻り値:
      setSchema(Schema)メソッドを介して最後に設定されたSchemaオブジェクト、またはDocumentBuilderFactoryが作成されてからメソッドが呼び出されていない場合はnull。
      例外:
      UnsupportedOperationException - 実装がこのメソッドをオーバーライドしない場合。
      導入されたバージョン:
      1.5

    • setSchema

      public void setSchema​(Schema schema)
      このファクトリから作成されたパーサーによって使用されるSchemaを設定します。

      Schemaがnull以外の場合、パーサーは、情報をアプリケーションに渡す前に、ドキュメントを検証するために作成されたバリデータを使用します。

      バリデータによってエラーが検出されると、パーサー自身がエラーを検出した場合と同様に、パーサーがそのエラーをユーザー指定のErrorHandlerへ報告します(エラー・ハンドラが設定されていない場合は、そのエラーは無視されるか、スローされます)。 つまり、ユーザー指定のErrorHandlerが設定されている場合は、これらのエラーを受け取り、そうでない場合は実装固有のデフォルトのエラー処理規則に従って処理される必要があります。

      バリデータは解析の結果を変更することがあり(たとえば、ドキュメントから失われていたデフォルト値を追加するなど)、パーサー側で変更済みのDOMツリーをアプリケーションが受け取ることを確認する必要があります。

      最初は、nullがSchemaとして設定されます。

      この処理はisValidating()メソッドがfalseを返した場合でも有効です。

      http://java.sun.com/xml/jaxp/properties/schemaSourceプロパティまたはhttp://java.sun.com/xml/jaxp/properties/schemaLanguageプロパティをSchemaオブジェクトと一緒に使用するとエラーになります。 newDocumentBuilder()の呼出し時に、そのような構成によってParserConfigurationException例外が発生します。

      Note for implementors

      パーサーは、あらゆるSchema実装で動作できる必要があります。 ただし、パーサーおよびスキーマが仕様に記載されている結果を出すかぎり、実装固有のカスタム・メカニズムを使用できます。

      パラメータ:
      schema - 使用するSchema、またはスキーマを削除するにはnull。
      例外:
      UnsupportedOperationException - 実装がこのメソッドをオーバーライドしない場合。
      導入されたバージョン:
      1.5

    • setXIncludeAware

      public void setXIncludeAware​(boolean state)
      XInclude処理の状態を設定します。

      ドキュメント・インスタンスにXIncludeマークアップが見つかった場合、「XML Inclusions (XInclude) Version 1.0」に指定されているとおりに処理する必要があります。

      XInclude処理のデフォルトはfalseに設定されます。

      パラメータ:
      state - XInclude処理をtrueまたはfalseに設定する
      例外:
      UnsupportedOperationException - 実装がこのメソッドをオーバーライドしない場合。
      導入されたバージョン:
      1.5

    • isXIncludeAware

      public boolean isXIncludeAware()
      XInclude処理の状態を取得します。
      戻り値:
      XInclude処理の現在の状態
      例外:
      UnsupportedOperationException - 実装がこのメソッドをオーバーライドしない場合。
      導入されたバージョン:
      1.5