JavaTM Platform
Standard Ed. 6

javax.xml.parsers
クラス DocumentBuilderFactory

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

public abstract class DocumentBuilderFactory
extends Object

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


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

インスタンス化を妨げる protected コンストラクタです。newInstance() を使用します。

メソッドの詳細

newInstance

public static DocumentBuilderFactory newInstance()
DocumentBuilderFactory の新しいインスタンスを取得します。この static メソッドは新しいファクトリインスタンスを作成します。このメソッドは次の順序の検索手順で、ロードする 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 - ファクトリクラスのロードに使用される ClassLoadernull の場合は 現在の Thread のコンテキスト classLoader が、ファクトリクラスのロードに使用されます。
戻り値:
DocumentBuilderFactory の新しいインスタンス
例外:
FactoryConfigurationError - factoryClassNamenull、または、 ファクトリクラスがロード、インスタンス化できない場合。
導入されたバージョン:
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
ユーザーが基本となる実装に特定の属性を設定できるようにします。

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

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 ツリーをアプリケーションが受け取ることを確認する必要があります。

最初に、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 - 実装がこのメソッドを オーバーライドしない場合
導入されたバージョン:
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

JavaTM Platform
Standard Ed. 6

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

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