javax.xml.validation
クラス SchemaFactory

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

public abstract class SchemaFactory
extends Object

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

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

SchemaFactory クラスはスレッドに対して安全ではありません。つまり、アプリケーション側で、どのような場合も SchemaFactory オブジェクトを使用するスレッドが 1 つだけであるようにする必要があります。実装では、メソッドに synchronized のマークを付けて、障害のあるクライアントから保護することをお勧めします。

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

スキーマ言語

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

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

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

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

value	language
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 の実装を検索し、それを返します。
static SchemaFactory	newInstance(String schemaLanguage, String factoryClassName, ClassLoader classLoader) クラス名から 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) この SchemaFactory、このファクトリによって作成された Schema、さらにそれらの Schema によって作成された Validator および 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

コンストラクタの詳細

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 - schemaLanguage パラメータが null の場合

関連項目:

newInstance(String schemaLanguage, String factoryClassName, ClassLoader classLoader)

newInstance

public static SchemaFactory newInstance(String schemaLanguage,
                                        String factoryClassName,
                                        ClassLoader classLoader)

クラス名から SchemaFactory の新しいインスタンスを取得します。指定されたファクトリクラス名が指定されたスキーマ言語をサポートする場合、SchemaFactory が返されます。この機能は、classpath に複数のプロバイダが存在する場合に便利です。ロードするプロバイダを指定できるので、アプリケーションで詳細に制御できるようになります。

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

　

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

　

問題がある場合は次のコマンドを試してください。

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

パラメータ:

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

factoryClassName - javax.xml.validation.SchemaFactory の実装を提供する完全修飾のファクトリクラス名

classLoader - ファクトリクラスのロードに使用する ClassLoader。null の場合、 ファクトリクラスのロードには現在の Thread のコンテキスト classLoader が使用される

戻り値:

SchemaFactory の新しいインスタンス

例外:

IllegalArgumentException - factoryClassName が null の場合。または、 ファクトリクラスをロードおよびインスタンス化できない場合。または、 ファクトリクラスが schemLanguage パラメータで指定されたスキーマ言語を サポートしない場合

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

導入されたバージョン:

1.6

関連項目:

newInstance(String schemaLanguage)

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 です。機能名は完全修飾 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、このファクトリによって作成された Schema、さらにそれらの Schema によって作成された Validator および ValidatorHandler の機能を設定します。

　

実装時および開発時には、newSchema() によって返される特別な Schema オブジェクトの処理方法に特に注意するようにします。たとえば、場合によっては、SchemaFactory とクラスが、異なる実装からのスキーマを実際にロードするときに、SchemaFactory の機能を自動的に継承できないことがあります。開発時には、セキュリティー処理などの機能を両方の場所で明示的に設定するようにしてください。

　

機能名は完全修飾 URI です。機能名は完全修飾 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 から正常に戻って処理を続行させたりすることもできます。

Throwable (またはその派生クラスのインスタンス) が ErrorHandler からスローされると、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 - 解析される入力。SAXSource、 StreamSource、 StAXSource、 および DOMSource を認識するために SchemaFactory が必要。 入力スキーマは XML ドキュメントまたは XML 要素であることが必要で null は不可。下位互換性のために、 ドキュメントと要素以外のすべてを受け渡した結果は 実装に依存している。 実装は、入力を認識し処理するか、 IllegalArgumentException をスローする必要がある

戻り値:

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

例外:

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

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

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

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

newSchema

public abstract Schema newSchema()
                          throws SAXException

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

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

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

　

実装時および開発時には、この特殊な Schema による SchemaFactory の機能セットの処理方法に特に注意するようにします。たとえば、場合によっては、SchemaFactory とクラスが、異なる実装からのスキーマを実際にロードするときに、SchemaFactory の機能を自動的に継承できないことがあります。開発時には、セキュリティー処理などの機能を両方の場所で明示的に設定するようにしてください。

W3C XML Schema 1.0

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

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

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

RELAX NG

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

戻り値:

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

例外:

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

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