javax.xml.validation

クラス ValidatorHandler

java.lang.Object

javax.xml.validation.ValidatorHandler

すべての実装されたインタフェース:

ContentHandler

public abstract class ValidatorHandler
extends Object
implements ContentHandler

SAX ストリームに有効なストリーミングバリデータ。

ValidatorHandler オブジェクトはスレッドに対して安全ではなく、再入不可能です。つまり、アプリケーション側で、どのような場合でも 1 つの ValidatorHandler オブジェクトが複数のスレッドから使用されることがないようにする必要があります。

ValidatorHandler は、SAX イベントが関連する Schema に記述された制約セットに従っているかどうかをチェックします。また、デフォルト値の追加などによって、SAX イベントを変更することもできます。

ValidatorHandler は ContentHandler からの拡張ですが、次のようにベースとなる ContentHandler を洗練させます。

1. startElement および endElement イベントは、uri、localName、および qname の null 以外の文字列を受け取る必要があります。SAX で null となることが許可されている場合でも当てはまります。同様に、ユーザー指定の ContentHandler がこれら 3 種類のパラメータの null 以外の文字列を受け取ります。
2. アプリケーションでは、ValidatorHandler の ContentHandler.startPrefixMapping(String,String) と ContentHandler.endPrefixMapping(String) が正しく呼び出されるようにする必要があります。同様に、ユーザー指定の ContentHandler が startPrefixMapping および endPrefixMapping イベントを受け取ります。ValidatorHandler が追加の名前空間バインディングを導入する場合、ユーザー指定の ContentHandler は追加の startPrefixMapping および endPrefixMapping イベントを受け取ります。
3. ContentHandler.startElement(String,String,String,Attributes) メソッドの Attributes には、xmlns* 属性が含まれる場合と、含まれない場合があります。

startDocument メソッドが呼び出されるたびに ValidatorHandler は自動的にリセットされます。

認識されるプロパティーと機能

この仕様では、ValidatorHandler のすべての実装で認識する必要がある次の機能を定義しています。

http://xml.org/sax/features/namespace-prefixes

この機能は ValidatorHandler が元の SAX イベントストリームに存在しない名前空間バインディングを取得する方法を制御します。この機能が true に設定されている場合は、ユーザーの ContentHandler で ContentHandler.startElement(String,String,String,Attributes) コールバックの Attributes オブジェクトの対応する xmlns* 属性を確認する必要があります。そうでない場合は、ユーザー指定の ContentHandler に渡される Attributes に xmlns* 属性が追加されません。

この切り替えにかかわらず、名前空間バインディングは、常にユーザー指定の ContentHandler の ContentHandler.startPrefixMapping(String,String) および ContentHandler.endPrefixMapping(String) メソッドを介してアプリケーションに通知されます。

この機能は ValidatorHandler で SAX イベントを受け取る方法には影響を与えません。SAX イベントの拡張方法を変更するだけです。

この機能はデフォルトで false に設定されます。

導入されたバージョン:

1.5

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

コンストラクタ

修飾子	コンストラクタと説明
protected	ValidatorHandler() 派生クラスのコンストラクタです。

メソッドのサマリー

メソッド

修飾子と型	メソッドと説明
abstract ContentHandler	getContentHandler() 拡張された検証結果を受け取る ContentHandler を取得します。
abstract ErrorHandler	getErrorHandler() この ValidatorHandler に設定されている現在の ErrorHandler を取得します。
boolean	getFeature(String name) 機能フラグの値を検索します。
Object	getProperty(String name) プロパティー値を検索します。
abstract LSResourceResolver	getResourceResolver() この ValidatorHandler に設定されている現在の LSResourceResolver を取得します。
abstract TypeInfoProvider	getTypeInfoProvider() この ValidatorHandler の TypeInfoProvider 実装を取得します。
abstract void	setContentHandler(ContentHandler receiver) 拡張された検証結果を受け取る ContentHandler を設定します。
abstract void	setErrorHandler(ErrorHandler errorHandler) 検証で発生したエラーを受け取るように ErrorHandler を設定します。
void	setFeature(String name, boolean value) この ValidatorHandler の機能を設定します。
void	setProperty(String name, Object object) プロパティー値を設定します。
abstract void	setResourceResolver(LSResourceResolver resourceResolver) 検証時のリソース解決をカスタマイズするように LSResourceResolver を設定します。

クラス java.lang.Object から継承されたメソッド

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

インタフェース org.xml.sax.ContentHandler から継承されたメソッド

characters, endDocument, endElement, endPrefixMapping, ignorableWhitespace, processingInstruction, setDocumentLocator, skippedEntity, startDocument, startElement, startPrefixMapping

コンストラクタの詳細

ValidatorHandler

protected ValidatorHandler()

派生クラスのコンストラクタです。

このコンストラクタは何も行いません。

派生クラスでは、null ErrorHandler および null LSResourceResolver を持つ ValidatorHandler オブジェクトを作成する必要があります。

メソッドの詳細

setContentHandler

public abstract void setContentHandler(ContentHandler receiver)

拡張された検証結果を受け取る ContentHandler を設定します。

ContentHandler が指定されると、ValidatorHandler はフィルタとして機能し、基本的には入力イベントを指定された ContentHandler にコピーします。

この実行で ValidatorHandler は、たとえばデフォルトの属性を追加して、イベントを変更することもできます。

ValidatorHandler は一定量のイベントをバッファーに格納することができますが、パーサーが ValidatorHandler を使用できるようにするために、次の要件を満たす必要があります。

1. ContentHandler.startElement(String, String, String, Attributes)、ContentHandler.endElement(String, String, String)、ContentHandler.startDocument()、または ContentHandler.endDocument() が ValidatorHandler で呼び出された場合、コールバックが戻る前に、ユーザー指定の ContentHandler の同じメソッドが同じイベントに対して呼び出される必要があります。
2. ValidatorHandler は、入力に存在しなかった新しい要素を導入しない可能性があります。
3. ValidatorHandler は、入力に存在した属性を削除しない可能性があります。

指定した ContentHandler のコールバックメソッドが例外をスローした場合、ValidatorHandler から同じ例外オブジェクトがスローされる必要があります。ErrorHandler にはそれらの例外を通知しないでください。

このメソッドは検証の途中でも呼び出すことができます。

パラメータ:

receiver - ContentHandler または null 値。

getContentHandler

public abstract ContentHandler getContentHandler()

拡張された検証結果を受け取る ContentHandler を取得します。

戻り値:

このメソッドは、getContentHandler() メソッドによって最後に設定されたオブジェクトを返す。または、この ValidatorHandler が作成されてから、そのメソッドが呼び出されていない場合は null を返す。

関連項目:

setContentHandler(ContentHandler)

setErrorHandler

public abstract void setErrorHandler(ErrorHandler errorHandler)

検証で発生したエラーを受け取るように ErrorHandler を設定します。

エラーハンドラを使用して、検証時のエラー処理プロセスをカスタマイズできます。ErrorHandler を設定すると、検証で発見されたエラーはまず ErrorHandler に送られます。

エラーハンドラはハンドラから SAXException をスローして、検証をただちに中断することができます。または、エラーを画面に出力したり、ErrorHandler から正常に戻って検証を続行させたりすることもできます。

Throwable が ErrorHandler からスローされると、呼び出しスタックのルートには同じ Throwable オブジェクトがスローされます。

ValidatorHandler は、最初に ErrorHandler へ報告してからでないと、SAXException をスローすることができません。

ErrorHandler が null の場合、実装は次の ErrorHandler が設定されたかのように動作します。

 class DraconianErrorHandler implements ErrorHandler {
     public void fatalError( SAXParseException e ) throws SAXException {
         throw e;
     }
     public void error( SAXParseException e ) throws SAXException {
         throw e;
     }
     public void warning( SAXParseException e ) throws SAXException {
         // noop
     }
 }
 

新しい ValidatorHandler オブジェクトが作成されると、最初にこのフィールドは null に設定されます。

パラメータ:

errorHandler - 設定する新しいエラーハンドラ。このパラメータは null も可。

getErrorHandler

public abstract ErrorHandler getErrorHandler()

この ValidatorHandler に設定されている現在の ErrorHandler を取得します。

戻り値:

このメソッドは、setErrorHandler(ErrorHandler) メソッドによって最後に設定されたオブジェクトを返す。または、この ValidatorHandler が作成されてから、そのメソッドが呼び出されていない場合は null を返す。

関連項目:

setErrorHandler(ErrorHandler)

setResourceResolver

public abstract void setResourceResolver(LSResourceResolver resourceResolver)

検証時のリソース解決をカスタマイズするように LSResourceResolver を設定します。

ValidatorHandler は、検証中に外部リソースの場所を確認する必要があるときに LSResourceResolver を使用しますが、「外部リソースの検索」を厳密に構成するものはスキーマ言語により異なります。

LSResourceResolver が null の場合、実装は次の LSResourceResolver が設定されたかのように動作します。

 class DumbLSResourceResolver implements LSResourceResolver {
     public LSInput resolveResource(
         String publicId, String systemId, String baseURI) {

         return null; // always return null
     }
 }
 

LSResourceResolver が RuntimeException (またはその派生クラスのインスタンス) をスローすると、ValidatorHandler は構文解析を異常終了し、validate メソッドの呼び出し元は同じ RuntimeException を受け取ります。

新しい ValidatorHandler オブジェクトが作成されると、最初にこのフィールドは null に設定されます。

パラメータ:

resourceResolver - 設定する新しいリソースリゾルバ。このパラメータは null も可。

getResourceResolver

public abstract LSResourceResolver getResourceResolver()

この ValidatorHandler に設定されている現在の LSResourceResolver を取得します。

戻り値:

このメソッドは、setResourceResolver(LSResourceResolver) メソッドによって最後に設定されたオブジェクトを返す。または、この ValidatorHandler が作成されてから、そのメソッドが呼び出されていない場合は null を返す。

関連項目:

setErrorHandler(ErrorHandler)

getTypeInfoProvider

public abstract TypeInfoProvider getTypeInfoProvider()

この ValidatorHandler の TypeInfoProvider 実装を取得します。

取得した TypeInfoProvider は構文解析時に照会し、バリデータによって判断された型情報にアクセスできます。

スキーマ言語によっては、型の概念を定義していないものもあり、そうした言語の場合、このメソッドがサポートされないこともあります。しかし、この仕様に準拠するため、W3C XML Schema 1.0 の実装ではこの処理をサポートする必要があります。

戻り値:

バリデータ/スキーマ言語で TypeInfo の概念をサポートしていない場合は null。それ以外の場合は、null 以外の有効な TypeInfoProvider。

getFeature

public boolean getFeature(String name)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException

機能フラグの値を検索します。

機能名は完全指定 URI です。ValidatorHandler は機能名を認識できますが、一時的にその値を返すことはできません。機能の値によっては、検証の実行前、実行中、実行後などの特定のコンテキストでしか使用できない場合があります。

独自の URI に基づいて作成された名前を使って、実装者が独自の機能を作成することもできます (推奨)。

パラメータ:

name - 機能名。null 以外の完全指定 URI で表される。

戻り値:

機能の現在の値 (true または false)。

例外:

SAXNotRecognizedException - 機能値を割り当てられない、または取得できない場合。

SAXNotSupportedException - ValidatorHandler が機能名を認識するだけで、現時点ではその値を判断できない場合。

NullPointerException - name が null である場合。

関連項目:

setFeature(String, boolean)

setFeature

public void setFeature(String name,
              boolean value)
                throws SAXNotRecognizedException,
                       SAXNotSupportedException

この ValidatorHandler の機能を設定します。

機能を使用して、ValidatorHandler がスキーマを解析する方法を制御することができます。機能名は完全指定 URI です。SchemaFactory は機能の値を表示できますが、現在の値を変更することはできません。機能の値によっては、検証の実行前、実行中、実行後などの特定のコンテキストでのみ不変または可変である場合があります。

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

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

パラメータ:

name - 機能名。null 以外の完全指定 URI で表される。

value - 機能の要求された値 (true または false)。

例外:

SAXNotRecognizedException - 機能値を割り当てられない、または取得できない場合。

SAXNotSupportedException - ValidatorHandler が機能名を認識するだけで、要求された値を設定できない場合。

NullPointerException - name が null である場合。

関連項目:

getFeature(String)

setProperty

public void setProperty(String name,
               Object object)
                 throws SAXNotRecognizedException,
                        SAXNotSupportedException

プロパティー値を設定します。

プロパティー名は完全指定 URI です。ValidatorHandler はプロパティー名を認識できますが、現在の値を変更することはできません。プロパティーの値によっては、検証の実行前、実行中、実行後などの特定のコンテキストでのみ不変または可変である場合があります。

ValidatorHandler は特定のプロパティー名の設定を認識する必要はありません。

パラメータ:

name - プロパティー名。null 以外の完全指定 URI で表される。

object - 要求されたプロパティー値。

例外:

SAXNotRecognizedException - プロパティー値を割り当てられない、または取得できない場合。

SAXNotSupportedException - ValidatorHandler がプロパティー名を認識するだけで、要求された値を設定できない場合。

NullPointerException - name が null である場合。

getProperty

public Object getProperty(String name)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException

プロパティー値を検索します。

プロパティー名は完全指定 URI です。ValidatorHandler はプロパティー名を認識できますが、一時的にその値を返すことはできません。プロパティーの値によっては、検証の実行前、実行中、実行後などの特定のコンテキストでしか使用できない場合があります。

ValidatorHandler は特定のプロパティー名を認識する必要はありません。

独自の URI に基づいて作成された名前を使って、実装者が独自のプロパティーを作成することもできます (推奨)。

パラメータ:

name - プロパティー名。null 以外の完全指定 URI で表される。

戻り値:

現在のプロパティー値。

例外:

SAXNotRecognizedException - プロパティー値を割り当てられない、または取得できない場合。

SAXNotSupportedException - XMLReader がプロパティー名を認識するだけで、現時点ではその値を判断できない場合。

NullPointerException - name が null である場合。

関連項目:

setProperty(String, Object)