モジュール java.xml

パッケージ 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セマンティックスから引き離すようにしてください。

サポートされているスキーマ言語のURI

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	newDefaultInstance()	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(URL schema)	指定されたURLをスキーマとして構文解析し、それをSchemaとして返します。
Schema	newSchema(Source schema)	指定されたソースをスキーマとして構文解析し、それをスキーマとして返します。
abstract Schema	newSchema(Source[] schemas)	指定されたソースをスキーマとして構文解析し、それをスキーマとして返します。
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オブジェクトを作成する必要があります。

メソッドの詳細

newDefaultInstance

public static SchemaFactory newDefaultInstance()

SchemaFactory組込みシステム・デフォルト実装の新しいインスタンスを作成します。

実装要件:

SchemaFactory組み込みシステムのデフォルト実装は、「W3C XMLスキーマ1.0」をサポートするためにのみ必要ですが、追加の「スキーマ言語」をサポートすることもできます。

戻り値:

SchemaFactory組込みシステム・デフォルト実装の新しいインスタンス。

導入されたバージョン:

9

newInstance

public static SchemaFactory newInstance(String schemaLanguage)

指定されたスキーマ言語をサポートするSchemaFactoryの新しいインスタンスを取得します。 このメソッドは、「JAXPルックアップ・メカニズム」を使用して、指定されたスキーマ言語をサポートするSchemaFactory実装を特定およびロードします。

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

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

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

パラメータ:

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

戻り値:

SchemaFactoryの新しいインスタンス

例外:

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

NullPointerException - schemaLanguageパラメータがnullである場合。

SchemaFactoryConfigurationError - 構成エラーが発生した場合。

関連項目:

• newInstance(String schemaLanguage, String factoryClassName, ClassLoader classLoader)

newInstance

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

クラス名からSchemaFactoryの新しいインスタンスを取得します。 指定されたファクトリ・クラス名が指定されたスキーマ言語をサポートする場合、SchemaFactoryが返されます。 この関数は、クラス・パスに複数のプロバイダがある場合に便利です。 どのプロバイダがロードされるかを指定できるため、アプリケーションをさらに制御できます。

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

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です。 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です。 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はプロパティ名を認識できますが、現在の値を変更することはできません。

JAXP 1.5またはそれ以降を実装する実装はすべて、XMLConstants.ACCESS_EXTERNAL_DTDおよびXMLConstants.ACCESS_EXTERNAL_SCHEMAプロパティをサポートしている必要があります。

• スキーマ・ファイル内の外部DTDへのアクセスが、XMLConstants.ACCESS_EXTERNAL_DTDプロパティで指定されたプロトコルに制限されます。 このプロパティの制限が原因で新しいスキーマの作成中にアクセスが拒否された場合は、newSchema(Source)、newSchema(File)、newSchema(URL)、またはnewSchema(Source[])メソッドによってSAXExceptionがスローされます。

  xmlソース・ファイル内の外部DTDへのアクセスが、XMLConstants.ACCESS_EXTERNAL_DTDプロパティで指定されたプロトコルに制限されます。 このプロパティの制限が原因で検証中にアクセスが拒否された場合は、Validator.validate(Source)またはValidator.validate(Source, Result)メソッドによってSAXExceptionがスローされます。

  schemaLocation属性によって設定された外部参照へのアクセスが、XMLConstants.ACCESS_EXTERNAL_SCHEMAプロパティで指定されたプロトコルに制限されます。 このプロパティの制限が原因で検証中にアクセスが拒否された場合は、Validator.validate(Source)またはValidator.validate(Source, Result)メソッドによってSAXExceptionがスローされます。

  ImportおよびInclude要素によって設定された外部参照へのアクセスが、XMLConstants.ACCESS_EXTERNAL_SCHEMAプロパティで指定されたプロトコルに制限されます。 このプロパティの制限が原因で新しいスキーマの作成中にアクセスが拒否された場合は、newSchema(Source)、newSchema(File)、newSchema(URL)、またはnewSchema(Source[])メソッドによってSAXExceptionがスローされます。

パラメータ:

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 - 解析される入力。 SchemaFactoryはSAXSource、StreamSource、StAXSource、およびDOMSource認識する必要がある。 入力スキーマは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 - この処理はサポートされているが、何らかの理由により失敗した場合。