モジュール java.xml

パッケージ 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, declaration, 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)。

throws:

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)。

throws:

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 - 要求されたプロパティ値。

throws:

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

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

NullPointerException - nameがnullである場合。

getProperty

public Object getProperty(String name) throws SAXNotRecognizedException, SAXNotSupportedException

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

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

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

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

パラメータ:

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

戻り値:

現在のプロパティ値。

throws:

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

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

NullPointerException - nameがnullである場合。

関連項目:

• setProperty(String, Object)