javax.xml.validation
クラス SchemaFactory

java.lang.Object
  javax.xml.validation.SchemaFactory

public abstract class SchemaFactory
extends Object

Schema オブジェクトを作成するファクトリ。検証 API へのエントリポイントです。

SchemaFactory はスキーマコンパイラです。スキーマの外部表現を読み取り、検証の準備をします。

SchemaFactory クラスはスレッドセーフではありません。つまり、常にアプリケーション側では、最大でも 1 つのスレッドだけが SchemaFactory オブジェクトを使用しており、複数のスレッドが同時に使用していないことを確認する必要があります。実装では、メソッドを synchronized とマークし、障害のあるクライアントから保護することをお勧めします。

SchemaFactory は再入不可能です。newSchema メソッドの 1 つが呼び出されている間、アプリケーションは同じスレッドからでも、newSchema メソッドを再帰的に呼び出すことはできません。

スキーマ言語

この仕様は名前空間 URI を使用して、スキーマ言語を指定します。次の表に、この仕様によって定義された値を示します。

仕様に準拠するために、実装でサポートする必要があるのは W3C XML Schema 1.0 のみです。ただし、ここに示したその他のスキーマ言語をサポートする場合は、この仕様に説明する関連の動作に従う必要があります。

ここに示していないスキーマ言語では、独自の URI を導入して、それらを表すことが期待されます。SchemaFactory クラスは実行時に、他のスキーマ言語の他の実装を見つけることができます。

XML DTD は、構文解析プロセスに強く結び付けられており、構文解析プロセスに大きな影響を与えるため、DTD 検証を構文解析から独立したプロセスとして定義することはできません。このため、この仕様では、XML DTD のセマンティクスを定義しません。これは、適切と思われる方法での実装を禁止するものではありませんが、このインタフェースに実装された DTD 検証を、必ず XML 1.0 で定義される XML DTD セマンティクスから引き離すようにしてください。

値	言語
XMLConstants.W3C_XML_SCHEMA_NS_URI ("http://www.w3.org/2001/XMLSchema")	W3C XML Schema 1.0
XMLConstants.RELAXNG_NS_URI ("http://relaxng.org/ns/structure/1.0")	RELAX NG 1.0

導入されたバージョン:

1.5

コンストラクタの概要

protected

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

メソッドの概要

abstract ErrorHandler	getErrorHandler() SchemaFactory に設定された現在の ErrorHandler を取得します。
boolean	getFeature(String name) 機能フラグの値を検索します。
Object	getProperty(String name) プロパティ値を検索します。
abstract LSResourceResolver	getResourceResolver() この SchemaFactory に設定された現在の LSResourceResolver を取得します。
abstract boolean	isSchemaLanguageSupported(String schemaLanguage) 指定されたスキーマがこの SchemaFactory にサポートされているかを返します。
static SchemaFactory	newInstance(String schemaLanguage) 指定されたスキーマ言語をサポートする SchemaFactory の実装を検索し、それを返します。
abstract Schema	newSchema() 特殊な Schema オブジェクトを作成します。
Schema	newSchema(File schema) 指定された File をスキーマとして構文解析し、それを Schema として返します。
Schema	newSchema(Source schema) 指定されたソースをスキーマとして構文解析し、それをスキーマとして返します。
abstract Schema	newSchema(Source[] schemas) 指定されたソースをスキーマとして構文解析し、それをスキーマとして返します。
Schema	newSchema(URL schema) 指定された URL をスキーマとして構文解析し、それを Schema として返します。
abstract void	setErrorHandler(ErrorHandler errorHandler) newSchema メソッドの呼び出しで発生したエラーを受け取るように ErrorHandler を設定します。
void	setFeature(String name, boolean value) 機能フラグの値を設定します。
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

コンストラクタの詳細

SchemaFactory

protected SchemaFactory()

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

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

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

メソッドの詳細

newInstance

public static final SchemaFactory newInstance(String schemaLanguage)

指定されたスキーマ言語をサポートする SchemaFactory の実装を検索し、それを返します。

指定されたスキーマ言語の SchemaFactory オブジェクトを検索する場合、このメソッドは「クラスローダ」がコンテキストクラスローダを参照する以下の順番で、次の場所を調べます。

1. システムプロパティ「javax.xml.validation.SchemaFactory:schemaLanguage」が存在する (schemaLanguage はこのメソッドのパラメータ) 場合、その値はクラス名として読み取られます。このメソッドは、クラスローダを使用してこのクラスの新しいインスタンスの作成を試み、成功した場合はそれを返します。
2. $java.home/lib/jaxp.properties が読み取られ、上記のシステムプロパティであるキーに関連付けられた値が検索されます。値が存在すれば、上記のように値が処理されます。

3. クラスローダは、リソースディレクトリ META-INF/services 内の javax.xml.validation.SchemaFactory に一致するサービスプロバイダのプロバイダ構成ファイルを要求されます。ファイル形式と構文解析規則については、JAR ファイルの仕様を参照してください。各サービスプロバイダは、次のメソッドを実装している必要があります。

    isSchemaLanguageSupported(String schemaLanguage) 

   指定されたスキーマ言語をサポートするクラスローダ内で最初に検出されたサービスプロバイダが返されます。
4. プラットフォームのデフォルト SchemaFactory は、実装固有の方法で配置されます。W3C XML Schema 用のプラットフォームのデフォルト SchemaFactory がある必要があります。

すべてが失敗した場合、IllegalArgumentException がスローされます。

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

プロパティファイルがどのように構文解析されるかについては、Properties.load(java.io.InputStream) を参照してください。特に、コロン「:」は、プロパティファイル内でエスケープされる必要があるため、スキーマ言語 URI が適切にエスケープされていることを確認してください。次に例を示します。

 http\://www.w3.org/2001/XMLSchema=org.acme.foo.XSSchemaFactory
 

パラメータ:

schemaLanguage - 返される SchemaFactory が理解するスキーマ言語を指定する。指定できる値については使用可能なスキーマ言語のリストを参照

戻り値:

SchemaFactory の新しいインスタンス

例外:

IllegalArgumentException - 使用可能なスキーマ言語の実装がない場合

NullPointerException - schemLanguage パラメータが null の場合

isSchemaLanguageSupported

public abstract boolean isSchemaLanguageSupported(String schemaLanguage)

指定されたスキーマがこの SchemaFactory にサポートされているかを返します。

パラメータ:

schemaLanguage - 返される SchemaFactory が理解するスキーマ言語を指定する。schemaLanguage は、有効なスキーマ言語を指定する必要がある

戻り値:

SchemaFactory が schemaLanguage をサポートしている場合は true、そうでない場合は false

例外:

NullPointerException - schemaLanguage が null の場合

IllegalArgumentException - schemaLanguage.length() == 0 または schemaLanguage が有効なスキーマ言語を指定しない場合

getFeature

public boolean getFeature(String name)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException

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

機能名は完全修飾 URI です。SchemaFactory は機能名を認識できますが、一時的にその値を返すことはできません。

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

パラメータ:

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

戻り値:

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

例外:

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

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

NullPointerException - name パラメータが null の場合

関連項目:

setFeature(String, boolean)

setFeature

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

機能フラグの値を設定します。

機能を使用して、SchemaFactory がスキーマを構文解析する方法を制御できますが、SchemaFactory は特定の機能名を認識する必要はありません。

機能名は完全修飾 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 - SchemaFactory が機能名を認識するだけで要求された値を設定できない場合

NullPointerException - name パラメータが null の場合

関連項目:

getFeature(String)

setProperty

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

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

プロパティ名は完全修飾 URI です。SchemaFactory はプロパティ名を認識できますが、現在の値を変更することはできません。

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

パラメータ:

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

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

例外:

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

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

NullPointerException - name パラメータが null の場合

getProperty

public Object getProperty(String name)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException

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

プロパティ名は完全修飾 URI です。SchemaFactory はプロパティ名を認識できますが、一時的にその値を返すことはできません。

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

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

パラメータ:

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

戻り値:

現在のプロパティ値

例外:

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

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

NullPointerException - name パラメータが null の場合

関連項目:

setProperty(String, Object)

setErrorHandler

public abstract void setErrorHandler(ErrorHandler errorHandler)

newSchema メソッドの呼び出しで発生したエラーを受け取るように ErrorHandler を設定します。

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

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

ErrorHandler から Throwable (またはその派生クラスのインスタンス) がスローされた場合、newSchema メソッドの呼び出し側に同じ Throwable オブジェクトがスローされます。

SchemaFactory は ErrorHandler に最初に報告する前に SAXException をスローできません。

アプリケーションでは Schema の構文解析中でもこのメソッドを呼び出すことができます。

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
     }
 }
 

新しい SchemaFactory オブジェクトが作成されると、最初にこのフィールドは null に設定されます。このフィールドは、この SchemaFactory から作成された Schema、Validator、または ValidatorHandler に継承されません。

パラメータ:

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

getErrorHandler

public abstract ErrorHandler getErrorHandler()

SchemaFactory に設定された現在の ErrorHandler を取得します。

戻り値:

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

関連項目:

setErrorHandler(ErrorHandler)

setResourceResolver

public abstract void setResourceResolver(LSResourceResolver resourceResolver)

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

SchemaFactory はスキーマの構文解析時に外部リソースを検索する必要がある場合に LSResourceResolver を使用しますが、厳密に「外部リソースの検索」を構成するものは、スキーマ言語により異なります。たとえば、W3C XML Schema の場合、<include> または <import> されたファイル、およびスキーマファイルから参照された DTD などが含まれます。

アプリケーションでは Schema の構文解析中でもこのメソッドを呼び出すことができます。

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

 class DumbDOMResourceResolver implements LSResourceResolver {
     public LSInput resolveResource(
         String publicId, String systemId, String baseURI) {
         
         return null; // always return null
     }
 }
 

LSResourceResolver が RuntimeException (またはその派生クラスのインスタンス) をスローすると、SchemaFactory は構文解析を中止し、newSchema メソッドの呼び出し側は同じ RuntimeException を受け取ります。

新しい SchemaFactory オブジェクトが作成されると、最初にこのフィールドは null に設定されます。このフィールドは、この SchemaFactory から作成された Schema、Validator、または ValidatorHandler に継承されません。

パラメータ:

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

getResourceResolver

public abstract LSResourceResolver getResourceResolver()

この SchemaFactory に設定された現在の LSResourceResolver を取得します。

戻り値:

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

関連項目:

setErrorHandler(ErrorHandler)

newSchema

public Schema newSchema(Source schema)
                 throws SAXException

指定されたソースをスキーマとして構文解析し、それをスキーマとして返します。

これは newSchema(Source[] schemas) の簡易メソッドです。

パラメータ:

schema - スキーマを表すソース

戻り値:

schema の構文解析からの新しい Schema

例外:

SAXException - 構文解析時に SAX エラーが発生した場合

NullPointerException - schema が null の場合

newSchema

public Schema newSchema(File schema)
                 throws SAXException

指定された File をスキーマとして構文解析し、それを Schema として返します。

これは newSchema(Source schema) の簡易メソッドです。

パラメータ:

schema - スキーマを表すファイル

戻り値:

schema の構文解析からの新しい Schema

例外:

SAXException - 構文解析時に SAX エラーが発生した場合

NullPointerException - schema が null の場合

newSchema

public Schema newSchema(URL schema)
                 throws SAXException

指定された URL をスキーマとして構文解析し、それを Schema として返します。

これは newSchema(Source schema) の簡易メソッドです。

パラメータ:

schema - スキーマを表す URL

戻り値:

schema の構文解析からの新しい Schema

例外:

SAXException - 構文解析時に SAX エラーが発生した場合

NullPointerException - schema が null の場合

newSchema

public abstract Schema newSchema(Source[] schemas)
                          throws SAXException

指定されたソースをスキーマとして構文解析し、それをスキーマとして返します。

呼び出される側はすべての Source を読み取り、それらを 1 つのスキーマに結合します。この組み合わせの正確なセマンティクスは、この SchemaFactory オブジェクトが作成されたスキーマ言語によって異なります。

ErrorHandler を設定した場合、呼び出される側はソースに発見されたすべてのエラーをハンドラに報告します。ハンドラが例外をスローした場合、スキーマのコンパイルを中止し、このメソッドから同じ例外がスローされます。さらに、エラーをハンドラに報告したあと、呼び出される側は、それをスローしてこれ以降の処理を中止できます。エラーハンドラを設定しない場合、呼び出される側はソースに発見された最初のエラーをスローします。

W3C XML Schema 1.0

結果として得られるスキーマには、指定されたソースからのコンポーネントが含まれます。これらすべてのソースを、schemaLocation と名前空間の適切な値を使用して、 異なる targetNamespace を持つ固有のコンポーネントを持たない 1 つのスキーマドキュメントにインポートした場合でも、インポート要素がソースとして同じ順序になっていれば同じ結果が得られます。XML Schema 勧告のセクション 4.2.3 に、これに関するプロセッサのオプションが記載されています。プロセッサは JAXP スキーマソースと XML スキーマのインポートを一貫して扱う必要がありますが、JAXP 準拠のパーサ間の動作は異なってもかまいません。特に、schemaLocation で提供される情報にかかわらず、パーサは指定された名前空間の最初の <import > 以外をすべて無視できます。

解析された一連のスキーマに、XML Schema 仕様のセクション 5.1 に示すようなエラーが含まれる場合、エラーを ErrorHandler に報告する必要があります。

RELAX NG

RELAX NG の場合で schemas.length!=1 のとき、このメソッドは UnsupportedOperationException をスローする必要があります。

パラメータ:

schemas - 解析される入力。SchemaFactory は SAXSource、StreamSource、および DOMSource を認識する必要がある

戻り値:

常に null 以外の有効な Schema オブジェクトを返す。エラーが報告された場合、返された Schema オブジェクトが意味をなす保証はない

例外:

SAXException - 指定された入力の処理時にエラーが発見された場合。ErrorHandler が設定されている場合、エラーは最初にそれらに報告される。setErrorHandler(ErrorHandler) を参照

NullPointerException - schemas パラメータ自体が null か、配列内の項目が null である場合

IllegalArgumentException - 配列内の項目がこのメソッドによって認識されない場合

UnsupportedOperationException - スキーマ言語がこの処理をサポートしていない場合

newSchema

public abstract Schema newSchema()
                          throws SAXException

特殊な Schema オブジェクトを作成します。

返される Schema オブジェクトの正確なセマンティクスは、この SchemaFactory が作成されたスキーマ言語によって異なります。

さらに、実装では実装固有のプロパティまたは機能を使用して、このメソッドのセマンティクスを変更できます。

W3C XML Schema 1.0

XML Schema の場合、このメソッドはドキュメントに指定された場所のヒントを使用して、検証を実行する Schema オブジェクトを作成します。

返される Schema オブジェクトは、ドキュメントでスキーマの場所のヒントの同じ URL を参照している場合、それらは常に同じスキーマドキュメントに解決されるものとみなします。この想定によって、実装ではスキーマドキュメントの解析結果を再利用できるため、同じスキーマに対する複数の検証の実行が速くなります。

スキーマの場所のヒントを使用することで、サービス妨害攻撃を受けやすくなるので注意してください。

RELAX NG

RELAX NG ではこの処理をサポートしていません。

戻り値:

常に null 以外の有効な Schema オブジェクトを返す

例外:

UnsupportedOperationException - この処理が呼び出される側によってサポートされていない場合

SAXException - この処理はサポートされているが、何らかの理由により失敗した場合