モジュール java.xml
パッケージ 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

    • コンストラクタの詳細

      • 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の実装を検索し、それを返します。

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

        1. システム・プロパティ"javax.xml.validation.SchemaFactory:<i>schemaLanguage</i>"が(schemaLanguageはこのメソッドのパラメータです)である場合、その値はクラス名として読み取られます。 このメソッドは、クラス・ローダーを使用してこのクラスの新しいインスタンスの作成を試み、成功した場合はそれを返します。

        2. 構成ファイル"jaxp.properties"を使用します。 このファイルは標準のProperties形式であり、通常Javaインストールのconfディレクトリにあります。 これには、実装クラスの完全修飾名が格納されています。

          jaxp.propertiesファイルはJAXP実装によって一度だけ読み込まれ、その値は将来の使用のためにキャッシュされます。 最初の読込み時にファイルが存在しないと、そのあとにその存在がチェックされることはない。 最初に読み込まれたあと、jaxp.propertiesのプロパティの値を変更することはできない。

        3. ServiceLoaderクラスで定義されているサービス・プロバイダ・ローディング機能を使用して、デフォルトのロード・メカニズムを使用してサービスの実装を特定してロード: サービス・プロバイダ・ローディング機能は、現在のスレッド・コンテキスト・クラス・ローダーを使用してサービスをロードしようとします。 コンテキスト・クラス・ローダーがnullの場合、システム・クラス・ローダーが使用されます。
          使用される可能性のある各サービス・プロバイダは、メソッドisSchemaLanguageSupported(String schemaLanguage)を実装している必要があります。
          指定されたスキーマ言語をサポートする最初に検出されたサービス・プロバイダが返されます。
          ServiceConfigurationErrorが発生した場合、SchemaFactoryConfigurationErrorがスローされます。

        4. プラットフォームのデフォルトSchemaFactoryは、実装固有の方法で配置されています。 W3C XMLスキーマ用の「プラットフォームのデフォルト」 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である場合。
        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)

      • 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も可。

      • 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も可。

      • 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 - この処理はサポートされているが、何らかの理由により失敗した場合。