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 |
修飾子 | コンストラクタと説明 |
---|---|
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 を設定します。 |
protected SchemaFactory()
派生クラスのコンストラクタです。
このコンストラクタは何も行いません。
派生クラスでは、null
ErrorHandler
および null
LSResourceResolver
を持つ SchemaFactory
オブジェクトを作成する必要があります。
public static final SchemaFactory newInstance(String schemaLanguage)
指定されたスキーマ言語をサポートする SchemaFactory
の実装を検索し、それを返します。
指定されたスキーマ言語の SchemaFactory
オブジェクトを検索する場合、このメソッドは「クラスローダー」がコンテキストクラスローダーを参照する次の順番で、次の場所を調べます。
"javax.xml.validation.SchemaFactory:schemaLanguage"
が存在する (schemaLanguage はこのメソッドのパラメータ) 場合、その値はクラス名として読み取られます。このメソッドは、クラスローダーを使用してこのクラスの新しいインスタンスの作成を試み、成功した場合はそれを返します。
$java.home/lib/jaxp.properties
が読み取られ、上記のシステムプロパティーであるキーに関連付けられている値が検索されます。値が存在すれば、上記のように値が処理されます。
クラスローダーは、リソースディレクトリ META-INF/services 内の javax.xml.validation.SchemaFactory
に一致するサービスプロバイダのプロバイダ構成ファイルを要求されます。ファイル形式と構文解析規則については、JAR ファイルの仕様を参照してください。各サービスプロバイダは、次のメソッドを実装している必要があります。
isSchemaLanguageSupported(String schemaLanguage)
指定されたスキーマ言語をサポートするクラスローダー内で最初に検出されたサービスプロバイダが返されます。
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)
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 である場合。newInstance(String schemaLanguage)
public abstract boolean isSchemaLanguageSupported(String schemaLanguage)
指定されたスキーマがこの SchemaFactory
にサポートされているかを返します。
schemaLanguage
- 返される SchemaFactory
が理解するスキーマ言語を指定する。schemaLanguage
は有効なスキーマ言語を指定する必要がある。SchemaFactory
が schemaLanguage
をサポートしている場合は true
、そうでない場合は false
。NullPointerException
- schemaLanguage
が null
の場合。IllegalArgumentException
- schemaLanguage.length() == 0
または schemaLanguage
が有効なスキーマ言語を指定しない場合。public boolean getFeature(String name) throws SAXNotRecognizedException, SAXNotSupportedException
機能名は完全指定 URI です。SchemaFactory
は機能名を認識できますが、一時的にその値を返すことはできません。
独自の URI に基づいて作成された名前を使って、実装者が独自の機能を作成することもできます (推奨)。
name
- 機能名。null 以外の完全指定 URI で表される。SAXNotRecognizedException
- 機能値を割り当てられない、または取得できない場合。SAXNotSupportedException
- SchemaFactory
が機能名を認識するだけで、現時点ではその値を判断できない場合。NullPointerException
- name
が null
の場合。setFeature(String, boolean)
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)
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
の場合。public Object getProperty(String name) throws SAXNotRecognizedException, SAXNotSupportedException
プロパティー名は完全指定 URI です。SchemaFactory
はプロパティー名を認識できますが、一時的にその値を返すことはできません。
SchemaFactory
は特定のプロパティー名を認識する必要はありません。
独自の URI に基づいて作成された名前を使って、実装者が独自のプロパティーを作成することもできます (推奨)。
name
- プロパティー名。null 以外の完全指定 URI で表される。SAXNotRecognizedException
- プロパティー値を割り当てられない、または取得できない場合。SAXNotSupportedException
- XMLReader がプロパティー名を認識するだけで、現時点ではその値を判断できない場合。NullPointerException
- name
が null
の場合。setProperty(String, Object)
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 implementsErrorHandler
{ public void fatalError(SAXParseException
e ) throwsSAXException
{ throw e; } public void error(SAXParseException
e ) throwsSAXException
{ throw e; } public void warning(SAXParseException
e ) throwsSAXException
{ // noop } }
新しい SchemaFactory
オブジェクトが作成されると、最初にこのフィールドは null に設定されます。このフィールドは、この SchemaFactory
から作成された Schema
、Validator
、または ValidatorHandler
に継承されません。
errorHandler
- 設定する新しいエラーハンドラ。このパラメータは null
も可。public abstract ErrorHandler getErrorHandler()
SchemaFactory
に設定されている現在の ErrorHandler
を取得します。setErrorHandler(ErrorHandler)
メソッドによって最後に設定されたオブジェクトを返す。または、この SchemaFactory
が作成されてから、そのメソッドが呼び出されていない場合は null を返す。setErrorHandler(ErrorHandler)
public abstract void setResourceResolver(LSResourceResolver resourceResolver)
LSResourceResolver
を設定します。
SchemaFactory
は、スキーマの解析中に外部リソースの場所を確認する必要があるときに LSResourceResolver
を使用しますが、「外部リソースの検索」を厳密に構成するものはスキーマ言語により異なります。たとえば、W3C XML Schema では、<include>
または <import>
されたファイル、およびスキーマファイルから参照された DTD などが含まれます。
アプリケーションでは Schema
の構文解析中でもこのメソッドを呼び出すことができます。
LSResourceResolver
が null の場合、実装は次の LSResourceResolver
が設定されたかのように動作します。
class DumbDOMResourceResolver implementsLSResourceResolver
{ publicLSInput
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 も可。public abstract LSResourceResolver getResourceResolver()
SchemaFactory
に設定されている現在の LSResourceResolver
を取得します。setResourceResolver(LSResourceResolver)
メソッドによって最後に設定されたオブジェクトを返す。または、この SchemaFactory
が作成されてから、そのメソッドが呼び出されていない場合は null を返す。setErrorHandler(ErrorHandler)
public Schema newSchema(Source schema) throws SAXException
指定されたソースをスキーマとして構文解析し、それをスキーマとして返します。
これは newSchema(Source[] schemas)
の簡易メソッドです。
schema
- スキーマを表すソース。schema
の構文解析からの新しい Schema
。SAXException
- 構文解析時に SAX エラーが発生した場合。NullPointerException
- schema
が null である場合。public Schema newSchema(File schema) throws SAXException
指定された File
をスキーマとして構文解析し、それを Schema
として返します。
これは newSchema(Source schema)
の簡易メソッドです。
schema
- スキーマを表すファイル。schema
の構文解析からの新しい Schema
。SAXException
- 構文解析時に SAX エラーが発生した場合。NullPointerException
- schema
が null である場合。public Schema newSchema(URL schema) throws SAXException
指定された URL
をスキーマとして構文解析し、それを Schema
として返します。
これは newSchema(Source schema)
の簡易メソッドです。
schema
- スキーマを表す URL
。schema
の構文解析からの新しい Schema
。SAXException
- 構文解析時に SAX エラーが発生した場合。NullPointerException
- schema
が null である場合。public abstract Schema newSchema(Source[] schemas) throws SAXException
呼び出される側はすべての Source
を読み取り、それらを 1 つのスキーマに結合します。この組み合わせの正確なセマンティクスは、この SchemaFactory
オブジェクトが作成されたスキーマ言語によって異なります。
ErrorHandler
が設定されている場合、呼び出される側はソースに見つかったすべてのエラーをハンドラに報告します。ハンドラは例外をスローすると、スキーマのコンパイルを中断します。そして同じ例外がこのメソッドからスローされます。また、エラーがハンドラに報告されたあと、呼び出される側はエラーをスローすることによって以降の処理を中断することができます。エラーハンドラが設定されていない場合は、呼び出される側がソースに見つかった最初のエラーをスローします。
結果として得られるスキーマには、指定されたソースからのコンポーネントが含まれます。これらすべてのソースを、schemaLocation と名前空間の適切な値を使用して、異なる targetNamespace を持つ固有のコンポーネントを持たない 1 つのスキーマドキュメントにインポートした場合でも、インポート要素がソースとして同じ順序になっていれば同じ結果が得られます。XML Schema 勧告のセクション 4.2.3 に、これに関するプロセッサのオプションが記載されています。プロセッサは JAXP スキーマソースと XML スキーマのインポートを一貫して扱う必要がありますが、JAXP 準拠のパーサー間の動作は異なってもかまいません。特に、schemaLocation で提供される情報にかかわらず、パーサーは指定された名前空間の最初の <import> 以外をすべて無視できます。
解析された一連のスキーマに、XML Schema 仕様のセクション 5.1 に示すようなエラーが含まれる場合、エラーを ErrorHandler
に報告する必要があります。
RELAX NG の場合で schemas.length!=1
のとき、このメソッドは UnsupportedOperationException
をスローする必要があります。
schemas
- 解析される入力。SchemaFactory
は SAXSource
、StreamSource
、StAXSource
、および DOMSource
認識する必要がある。入力スキーマは XML ドキュメントまたは XML 要素であることが必要で null は不可。下位互換性のために、ドキュメントと要素以外のすべてを受け渡した結果は実装に依存している。実装は、入力を認識し処理するか、IllegalArgumentException をスローする必要がある。Schema
オブジェクトを返す。エラーが報告された場合、返された Schema
オブジェクトが意味を持つことは保証されない。SAXException
- 指定された入力の処理時にエラーが発見された場合。ErrorHandler
が設定されている場合、エラーは最初にそれらに報告される。setErrorHandler(ErrorHandler)
を参照してください。NullPointerException
- schemas
パラメータ自体が null か、配列内の項目が null である場合。IllegalArgumentException
- 配列内の項目がこのメソッドによって認識されない場合。UnsupportedOperationException
- スキーマ言語がこの処理をサポートしていない場合。public abstract Schema newSchema() throws SAXException
Schema
オブジェクトを作成します。
返される Schema
オブジェクトの正確なセマンティクスは、この SchemaFactory
が作成されたスキーマ言語によって異なります。
さらに、実装では実装固有のプロパティーまたは機能を使用して、このメソッドのセマンティクスを変更できます。
実装時および開発時には、この特殊な Schema
による SchemaFactory
の機能セットの処理方法に特に注意するようにします。たとえば、場合によっては、SchemaFactory
とクラスが、異なる実装からのスキーマを実際にロードするときに、SchemaFactory
の機能を自動的に継承できないことがあります。開発時には、セキュリティー処理などの機能を両方の場所で明示的に設定するようにしてください。
XML Schema の場合、このメソッドはドキュメントに指定された場所のヒントを使用して、検証を実行する Schema
オブジェクトを作成します。
返される Schema
オブジェクトは、ドキュメントでスキーマの場所のヒントの同じ URL を参照している場合、それらは常に同じスキーマドキュメントに解決されるものとみなします。この想定によって、実装ではスキーマドキュメントの解析結果を再利用できるため、同じスキーマに対する複数の検証の実行が速くなります。
スキーマの場所のヒントを使用することで、サービス妨害攻撃を受けやすくなるので注意してください。
RELAX NG ではこの処理をサポートしていません。
Schema
オブジェクトを返す。UnsupportedOperationException
- この処理が呼び出される側によってサポートされていない場合。SAXException
- この処理はサポートされているが、何らかの理由により失敗した場合。 バグまたは機能を送信
詳細な API リファレンスおよび開発者ドキュメントについては、Java SE のドキュメントを参照してください。そのドキュメントには、概念的な概要、用語の定義、回避方法、有効なコード例などの、開発者を対象にしたより詳細な説明が含まれています。
Copyright © 1993, 2013, Oracle and/or its affiliates. All rights reserved.