モジュール 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の新しいインスタンスを取得します。 このメソッドは、「JAXPルックアップ・メカニズム」を使用して、ロードするDocumentBuilderFactory実装クラスを決定します。

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

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

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

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

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

戻り値:

DocumentBuilderFactoryの新しいインスタンス

例外:

FactoryConfigurationError - サービス構成エラーが発生した場合、または実装が使用できないかインスタンス化できない場合。

newInstance

public static DocumentBuilderFactory newInstance(String factoryClassName, ClassLoader classLoader)

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

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

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

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機能をサポートしている必要があります。 この機能については次のとおりです。

• true: 実装は実装限界に準拠するXML処理を制限します。 例は、エンティティ拡張制限や大容量のリソースを消費するXMLスキーマなど。 セキュリティ上の理由からXML処理が制限される場合は、登録済みのErrorHandler.fatalError(SAXParseException exception)へ呼出しを介して報告されます。 DocumentBuilder.setErrorHandler(org.xml.sax.ErrorHandler errorHandler)を参照してください。
• false: 実装は実装限界に関係なく、XML仕様に従ってXMLを処理します。

パラメータ:

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例外が発生します。

実装時のノート

パーサーは、あらゆる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