JavaTM 2 Platform
Standard Ed. 5.0

javax.xml.parsers
クラス DocumentBuilderFactory

java.lang.Object
  上位を拡張 javax.xml.parsers.DocumentBuilderFactory

public abstract class DocumentBuilderFactory
extends Object

アプリケーションで XML ドキュメントから DOM オブジェクトツリーを生成するパーサを取得できるファクトリ API を定義します。


コンストラクタの概要
protected DocumentBuilderFactory()
           
 
メソッドの概要
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 処理の状態を取得します。
abstract  DocumentBuilder newDocumentBuilder()
          現在設定されているパラメータを使用して DocumentBuilder の新しいインスタンスを作成します。
static DocumentBuilderFactory newInstance()
          DocumentBuilderFactory の新しいインスタンスを取得します。
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()
メソッドの詳細

newInstance

public static DocumentBuilderFactory newInstance()
DocumentBuilderFactory の新しいインスタンスを取得します。この static メソッドは新しいファクトリインスタンスを作成します。このメソッドは次の順序の検索手順で、ロードする DocumentBuilderFactory 実装クラスを決定します。 アプリケーションが DocumentBuilderFactory への参照を取得すると、ファクトリを使用してパーサのインスタンスを設定および取得することができます。

トラブルシューティングのヒント

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

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


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

戻り値:
DocumentBuilderFactory の新しいインスタンス
例外:
FactoryConfigurationError - 実装が使用できないかインスタンス化できない場合

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
ユーザが基本となる実装に特定の属性を設定できるようにします。

パラメータ:
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 - 機能の状態が truefalse
例外:
ParserConfigurationException - 作成する DocumentBuilderFactory または DocumentBuilder がこの機能をサポートできない場合
NullPointerException - name パラメータが null の場合

getFeature

public abstract boolean getFeature(String name)
                            throws ParserConfigurationException

名前が付けられた機能の状態を取得します。

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

パラメータ:
name - 機能名
戻り値:
名前が付けられた機能の状態
例外:
ParserConfigurationException - 作成する XPathFactory または XPath がこの機能をサポートできない場合

getSchema

public Schema getSchema()
setSchema(Schema schema) メソッドによって指定された Schema オブジェクトを取得します。

戻り値:
setSchema(Schema) メソッドによって、最後に設定された Schema オブジェクト、または SAXParserFactory が作成されてから、メソッドが呼び出されていない場合は null
例外:
UnsupportedOperationException - 下位互換性のため、JAXP の以前のバージョンを使用している場合に、この例外がスローされる
導入されたバージョン:
1.5

setSchema

public void setSchema(Schema schema)

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

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

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

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

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

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

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

実装時の注意

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

パラメータ:
schema - 使用する Schema またはスキーマを削除する場合は null
例外:
UnsupportedOperationException - 下位互換性のため、JAXP の以前のバージョンを使用している場合に、この例外がスローされる
導入されたバージョン:
1.5

setXIncludeAware

public void setXIncludeAware(boolean state)

XInclude 処理の状態を設定します。

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

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

パラメータ:
state - XInclude 処理を true または false に設定する
例外:
UnsupportedOperationException - 下位互換性のため、JAXP の以前のバージョンを使用している場合に、この例外がスローされる
導入されたバージョン:
1.5

isXIncludeAware

public boolean isXIncludeAware()

XInclude 処理の状態を取得します。

戻り値:
XInclude 処理の現在の状態
例外:
UnsupportedOperationException - 下位互換性のため、JAXP の以前のバージョンを使用している場合に、この例外がスローされる
導入されたバージョン:
1.5

JavaTM 2 Platform
Standard Ed. 5.0

バグの報告と機能のリクエスト
さらに詳しい API リファレンスおよび開発者ドキュメントについては、Java 2 SDK SE 開発者用ドキュメントを参照してください。開発者向けの詳細な解説、概念の概要、用語の定義、バグの回避策、およびコード実例が含まれています。

Copyright 2004 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。