パッケージ jakarta.xml.bind

クラス JAXBContext

  • public abstract class JAXBContext
extends ObjectSE
    JAXBContext クラスは、Jakarta XML Binding API へのクライアントのエントリポイントを提供します。これは、Jakarta XML Binding バインディングフレームワーク操作（アンマーシャル、マーシャル、検証）を実装するために必要な XML/Java バインディング情報を管理するための抽象化を提供します。

    クライアントアプリケーションは通常、newInstance メソッドの次の 2 つのスタイルのいずれかを使用してこのクラスの新しいインスタンスを取得しますが、他の特殊な形式のメソッドも使用できます。

    • JAXBContext.newInstance( "com.acme.foo:com.acme.bar" )
      JAXBContext インスタンスは、コロンで区切られた Java パッケージ名のリストから初期化されます。各 java パッケージには、Jakarta XML Binding マップクラス、スキーマ派生クラス、/ またはユーザーアノテーション付きクラスが含まれています。さらに、java パッケージには、処理する必要のある Jakarta XML Binding パッケージアノテーションが含まれている場合があります。（JLS のセクション 7.4.1「名前付きパッケージ」を参照）。
    • JAXBContext.newInstance( com.acme.foo.Foo.class )
      JAXBContext インスタンスは、パラメーターとして渡されたクラスと、これらのクラスから静的に到達可能なクラスで初期化されます。詳細については、newInstance(Class...) を参照してください。

    プロバイダーは、整列化および非整列化メソッドのクライアント呼び出しの前に、DatatypeConverter.setDatatypeConverter API を呼び出す必要があります。これは、これらの操作中に使用されるデータ型コンバーターを構成するために必要です。

    マーシャリング解除

    Unmarshaller クラスは、クライアントアプリケーションに XML データを Java コンテンツオブジェクトのツリーに変換する機能を提供します。unmarshal メソッドを使用すると、スキーマで宣言されたグローバル XML 要素をインスタンスドキュメントのルートとしてアンマーシャリングできます。さらに、unmarshal メソッドを使用すると、スキーマで宣言された型定義を参照する xsi:type 属性の値を持つ認識されないルート要素を、インスタンスドキュメントのルートとして非マーシャリングできます。JAXBContext オブジェクトを使用すると、一連のスキーマ（contextPath にリストされている）全体でグローバル要素と型定義をマージできます。スキーマセット内の各スキーマは個別の名前空間に属することができるため、スキーマを非マーシャリングコンテキストに統合するには、名前空間に依存しない必要があります。これは、クライアントアプリケーションが、contextPath にリストされているスキーマのいずれかのインスタンスである XML ドキュメントをアンマーシャリングできることを意味します。例：

          JAXBContext jc = JAXBContext.newInstance( "com.acme.foo:com.acme.bar" );
      Unmarshaller u = jc.createUnmarshaller();
      FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) ); // ok
      BarObject barObj = (BarObject)u.unmarshal( new File( "bar.xml" ) ); // ok
      BazObject bazObj = (BazObject)u.unmarshal( new File( "baz.xml" ) ); // error, "com.acme.baz" not in contextPath

    クライアントアプリケーションは、既存の XML データをマーシャリング解除するのではなく、Java コンテンツツリーを明示的に生成することもできます。すべての Jakarta XML Binding アノテーション付き値クラスについて、アプリケーションはコンストラクターを使用してコンテンツを作成できます。スキーマから派生したインターフェース / 実装クラス、および Jakarta XML Binding アノテーション付きクラスにバインドされていない要素を作成する場合、アプリケーションは、に含まれる各 java パッケージに存在するスキーマから派生した ObjectFactory クラスのそれぞれについてアクセスおよび知識を持っている必要があります。contextPath。スキーマから派生した java クラスごとに、その型のオブジェクトを生成する静的ファクトリメソッドがあります。例: スキーマをコンパイルした後、PurchaseOrder という名前のスキーマ派生インターフェースを含むパッケージ com.acme.foo があると想定します。その型のオブジェクトを作成するために、クライアントアプリケーションは次のようなファクトリメソッドを使用します。

           com.acme.foo.PurchaseOrder po =
           com.acme.foo.ObjectFactory.createPurchaseOrder();

    クライアントアプリケーションがスキーマ派生オブジェクトのインスタンスを取得すると、ミューテーターメソッドを使用してコンテンツを設定できます。

    生成された ObjectFactory クラスの詳細については、仕様のセクション 4.2 Java パッケージを参照してください。

    プロバイダーは、各パッケージに、ObjectFactory という名前のそのパッケージに必要なすべてのオブジェクトファクトリメソッドと静的 newInstance( javaContentInterface ) メソッドを含むクラスを生成する必要があります。

    マーシャリング

    Marshaller クラスは、クライアントアプリケーションに Java コンテンツツリーを XML データに変換する機能を提供します。ファクトリメソッドを使用して手動で作成されたコンテンツツリーをマーシャリングすることと、unmarshal 操作の結果であるコンテンツツリーをマーシャリングすることの間に違いはありません。クライアントは、java コンテンツツリーを XML データにマーシャリングして java.io.OutputStream または java.io.Writer に戻すことができます。あるいは、マーシャリングプロセスは、登録された ContentHandler への SAX2 イベントストリームを生成するか、DOM ノードオブジェクトを生成することができます。クライアントアプリケーションは、出力エンコーディングと、XML データを完全なドキュメントとしてマーシャリングするかフラグメントとしてマーシャリングするかを制御できます。

    これは、XML ドキュメントをマーシャル解除してから、マーシャルして戻す簡単な例です。

            JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );

        // unmarshal from foo.xml
        Unmarshaller u = jc.createUnmarshaller();
        FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) );

        // marshal to System.out
        Marshaller m = jc.createMarshaller();
        m.marshal( fooObj, System.out );

    検証

    Jakarta XML Binding では、Unmarshaller に JAXP javax.xml.validationSE フレームワークを公開する便利なメソッドが含まれています。詳細については、Unmarshaller.setSchema(javax.xml.validation.Schema) API を参照してください。

    Jakarta XML Binding Runtime Framework Compatibility

    次の JAXB 1.0 制限は、スキーマをインターフェース / 実装クラスにバインドする場合にのみ適用されます。このバインディングは共通のランタイムシステムを必要としないため、Jakarta XML Binding クライアントアプリケーションは、異なるプロバイダーからのランタイムオブジェクト（JAXBContext, Marshaller など）を混在させようとしてはなりません。これは、クライアントアプリケーションが移植可能でないことを意味するのではなく、単に、クライアントがスキーマのコンパイルに使用されたのと同じプロバイダーによって提供されるランタイムシステムを使用する必要があることを意味します。

    Jakarta XML Binding 実装の発見

    JAXBContext のインスタンスを作成するために、JAXBContext.newInstance(...) メソッドの 1 つが呼び出されます。JAX-B 実装が検出された後、呼び出しは、元の呼び出しからパラメーターを渡す適切なプロバイダーのメソッド createContext(...) に委譲されます。

    JAX-B 実装の検出は、JAXBContext.newInstance が呼び出されるたびに発生します。ユーザー固有の構成が提供されていない場合は、デフォルトの JAX-B プロバイダーを返す必要があります。

    実装の検出は、次の手順で構成されます。

    1. システムプロパティ JAXB_CONTEXT_FACTORY が存在する場合、その値はプロバイダーファクトリクラスであると見なされます。ルックアップのこのフェーズでは、Jakarta XML Binding 実装の JVM ごとのオーバーライドを有効にします。
    2. newInstance(Class[], Map) または newInstance(String, ClassLoader, Map) に渡される Map<String, ?> にプロパティ JAXB_CONTEXT_FACTORY が存在する場合、その値は完全修飾プロバイダファクトリクラス名であると見なされます。ルックアップのこのフェーズでは、Jakarta XML Binding 実装の状況に応じた選択が可能になります。
    3. JAXBContextFactory のプロバイダーは、ServiceLoaderSE クラスによって定義されたサービスプロバイダーのロード機能を使用してロードされ、デフォルトのロードメカニズムSEを使用してサービスの実装を見つけてロードしようとします。サービスプロバイダーのロード機能は、現在のスレッドのコンテキストクラスローダーを使用してロードを試みます。コンテキストファクトリ。コンテキストクラスローダーが null の場合、システムクラスローダーが使用されます。
      service configuration errorSE の場合、JAXBException がスローされます。
    4. 最後に、上記のすべてのステップが失敗した場合、ルックアップの残りは指定されていません。とはいえ、推奨される動作は、ハードコードされたプラットフォームのデフォルトの Jakarta XML Binding 実装を単純に探すことです。ルックアップのこのフェーズは、環境が最後の手段として独自の Jakarta XML Binding 実装を持つことができるようにするためのものです。

    プロバイダーファクトリクラスが検出されると、コンテキストの作成がその createContext(...) メソッドの 1 つに委譲されます。

    導入:
    1.6、JAXB 1.0
    作成者:
    • Ryan Shoemaker, Sun Microsystems, Inc.
    • Kohsuke Kawaguchi, Sun Microsystems, Inc.
    • Joe Fialli, Sun Microsystems, Inc.
    関連事項:
    Marshaller, Unmarshaller, Java 言語仕様の S 7.4.1「名前付きパッケージ」SE

    • フィールドの詳細

      • JAXB_CONTEXT_FACTORY

        public static final StringSE JAXB_CONTEXT_FACTORY
        新しい JAXBContext オブジェクトを作成できるクラスの名前を含むプロパティの名前。
        関連事項:
        定数フィールド値

    • コンストラクターの詳細

      • JAXBContext

        protected JAXBContext()

    • メソッドの詳細

      • newInstance

        public static JAXBContext newInstance​(StringSE contextPath)
                               throws JAXBException
        JAXBContext クラスの新しいインスタンスを作成します。

        これは、現在のスレッドのコンテキストクラスローダーで newInstance(String,ClassLoader) メソッドを呼び出すための便利なメソッドです。

        パラメーター:
        contextPath - コンテキストパス
        戻り値:
        JAXBContext クラスの新しいインスタンス
        例外:
        JAXBException - JAXBContext の作成中に次のようなエラーが発生した場合
        1. パッケージ内で ObjectFactory.class または jaxb.index のいずれかが見つからない
        2. contextPath に含まれるグローバル要素間の曖昧さ
        3. コンテキストファクトリプロバイダープロパティの値が見つからない
        4. 同じ contextPath 上で異なるプロバイダからのスキーマ派生パッケージを混在させる
        5. パッケージは jakarta.xml.bind モジュールに対して開かれていません

      • newInstance

        public static JAXBContext newInstance​(StringSE contextPath,
                                      ClassLoaderSE classLoader)
                               throws JAXBException
        JAXBContext クラスの新しいインスタンスを作成します。

        クライアントアプリケーションは、コロン（':'、\ u003A）で区切られた java パッケージ名のリストであるコンテキストパスを提供する必要があります。これには、スキーマ派生クラスや完全修飾 Jakarta XML Binding アノテーション付きクラスが含まれます。スキーマから派生したコードは、パッケージごとに生成された ObjectFactory.class によって JAXBContext に登録されます。コンテキストパスにリストされる代わりに、プログラマーがアノテーションを付けた Jakarta XML Binding マップクラスを、以下に説明する形式の jaxb.index リソースファイルにリストすることもできます。java パッケージには、スキーマから派生したクラスとユーザーアノテーション付きの Jakarta XML Binding クラスの両方を含めることができることに注意してください。さらに、java パッケージには、処理する必要のある Jakarta XML Binding パッケージアノテーションが含まれている場合があります。（JLS のセクション 7.4.1「名前付きパッケージ」を参照）。

        contextPath にリストされているすべてのパッケージは、次の条件の 1 つまたは両方を満たす必要があります。そうでない場合は、JAXBException がスローされます。

        1. ObjectFactory.class が含まれている必要があります
        2. jaxb.index が含まれている必要があります

        jaxb.index の形式

        このファイルには、クラス名の改行で区切られたリストが含まれています。スペースとタブ文字、および空白行は無視されます。コメント文字は '#' (0x23）; 各行で、最初のコメント文字に続くすべての文字は無視されます。ファイルは UTF-8 でエンコードする必要があります。リストされたクラスから newInstance(Class...) で定義されているように到達可能なクラスも、JAXBContext に登録されます。

        jaxb.index ファイルで発生するクラス名の制約は次のとおりです。

        • ".class" で終わらせてはなりません。
        • クラス名は、jaxb.index ファイルを含むパッケージに関連して解決されます。jaxb.index ファイルを含むパッケージで直接発生するクラスのみが許可されます。
        • 完全修飾クラス名は許可されていません。現在のパッケージに関連する修飾クラス名は、ネストされたクラスまたは内部クラスのみを指定できます。

        contextPath にリストされているさまざまなパッケージ間でグローバル XML 要素名の衝突がある場合、JAXBException がスローされます。

        同じコンテキストパス内の複数の Jakarta XML Binding Providers から生成されたインターフェース / impl バインディングを混在させると、JAXBException がスローされる可能性があります。

        Jakarta XML Binding 実装の検出に関連する手順は、クラス javadoc で説明されています。

        パラメーター:
        contextPath - スキーマ派生クラスおよび / または java からスキーマ（Jakarta XML Binding アノテーション付き）にマップされたクラスを含む java パッケージ名のリスト。名前付きモジュールにある contextPath のパッケージは、少なくとも jakarta.xml.bind モジュールに対して open である必要があります。
        classLoader - このクラスローダーは、実装クラスを見つけるために使用されます。
        戻り値:
        JAXBContext の新しいインスタンス
        例外:
        JAXBException - JAXBContext の作成中に次のようなエラーが発生した場合
        1. パッケージ内で ObjectFactory.class または jaxb.index のいずれかが見つからない
        2. contextPath に含まれるグローバル要素間の曖昧さ
        3. コンテキストファクトリプロバイダープロパティの値が見つからない
        4. 同じ contextPath 上で異なるプロバイダからのスキーマ派生パッケージを混在させる
        5. パッケージは jakarta.xml.bind モジュールに対して開かれていません

      • newInstance

        public static JAXBContext newInstance​(StringSE contextPath,
                                      ClassLoaderSE classLoader,
                                      MapSE<StringSE,​?> properties)
                               throws JAXBException
        JAXBContext クラスの新しいインスタンスを作成します。

        これは newInstance(String, ClassLoader) とほとんど同じですが、このバージョンでは、プロバイダー固有のプロパティを渡して JAXBContext のインスタンス化を構成できます。

        プロパティの解釈は実装次第です。実装は、理解できないプロパティを見つけた場合、JAXBException をスローする必要があります。

        パラメーター:
        contextPath - スキーマ派生クラスおよび / または java からスキーマ（Jakarta XML Binding アノテーション付き）にマップされたクラスを含む java パッケージ名のリスト。名前付きモジュールにある contextPath のパッケージは、少なくとも jakarta.xml.bind モジュールに対して open である必要があります。
        classLoader - このクラスローダーは、実装クラスを見つけるために使用されます。
        properties - プロバイダー固有またはプロバイダー選択固有のプロパティ。null にすることができます。これは、空のマップを渡すことと同じことを意味します。
        戻り値:
        JAXBContext の新しいインスタンス
        例外:
        JAXBException - JAXBContext の作成中に次のようなエラーが発生した場合
        1. パッケージ内で ObjectFactory.class または jaxb.index のいずれかが見つからない
        2. contextPath に含まれるグローバル要素間の曖昧さ
        3. コンテキストファクトリプロバイダープロパティの値が見つからない
        4. 同じ contextPath 上で異なるプロバイダからのスキーマ派生パッケージを混在させる
        5. パッケージは jakarta.xml.bind モジュールに対して開かれていません
        導入:
        1.6、JAXB 2.0

      • newInstance

        public static JAXBContext newInstance​(ClassSE<?>... classesToBeBound)
                               throws JAXBException
        JAXBContext クラスの新しいインスタンスを作成します。

        クライアントアプリケーションは、新しいコンテキストオブジェクトが認識する必要のあるクラスのリストを提供する必要があります。新しいコンテキストは、指定されたすべてのクラスを認識するだけでなく、指定されたクラスから静的に直接 / 間接的に参照されるすべてのクラスも認識します。参照クラスのサブクラスも @XmlTransient 参照クラスも JAXBContext に登録されていません。例: 次の Java コードでは、newInstance(Foo.class) を実行すると、新しく作成された JAXBContext は Foo と Bar の両方を認識しますが、Zot または FooBar は認識しません。

         class Foo {
      @XmlTransient FooBar c;
      Bar b;
 }
 class Bar { int x; }
 class Zot extends Bar { int y; }
 class FooBar { }
        一般的なクライアントアプリケーションでは、最上位クラスを指定するだけで済みますが、注意が必要です。

        JAXBContext に登録されている java パッケージごとに、オプションのパッケージアノテーションが存在する場合は、処理する必要があることに注意してください。（JLS のセクション 7.4.1「名前付きパッケージ」を参照）。

        Jakarta XML Binding 実装の検出に関連する手順は、クラス javadoc で説明されています。

        パラメーター:
        classesToBeBound - 新しい JAXBContext によって認識される java クラスのリスト。名前付きモジュールにある classesToBeBound のクラスは、少なくとも jakarta.xml.bind モジュールに対して open であるパッケージに含まれている必要があります。空にすることができます。その場合、仕様で定義されたクラスについてのみ知っている JAXBContext が返されます。
        戻り値:
        JAXBContext の新しいインスタンス。
        例外:
        JAXBException - JAXBContext の作成中に次のようなエラーが発生した場合（ただしこれらに限定されません）:
        1. Jakarta XML Binding の実装は発見されませんでした
        2. クラスが Jakarta XML Binding アノテーションを誤って使用する
        3. クラスには衝突するアノテーションがあります (つまり、同じ型名の 2 つのクラス)
        4. Jakarta XML Binding 実装は、プロバイダー固有の帯域外情報を見つけることができませんでした (開発時に生成された追加ファイルなど。)
        5. classesToBeBound は jakarta.xml.bind モジュールに対して開かれていません
        IllegalArgumentExceptionSE - パラメーターに null が含まれている場合 (つまり、newInstance(null);)
        導入:
        1.6、JAXB 2.0

      • newInstance

        public static JAXBContext newInstance​(ClassSE<?>[] classesToBeBound,
                                      MapSE<StringSE,​?> properties)
                               throws JAXBException
        JAXBContext クラスの新しいインスタンスを作成します。

        この JAXBContext のインスタンス化のために「プロパティ」を構成するための newInstance(Class...) のオーバーロード。

        プロパティの解釈は実装次第です。実装は、理解できないプロパティを見つけた場合、JAXBException をスローする必要があります。

        パラメーター:
        classesToBeBound - 新しい JAXBContext によって認識される java クラスのリスト。名前付きモジュールにある classesToBeBound のクラスは、少なくとも jakarta.xml.bind モジュールに対して open であるパッケージに含まれている必要があります。空にすることができます。その場合、仕様で定義されたクラスについてのみ知っている JAXBContext が返されます。
        properties - プロバイダー固有またはプロバイダー選択固有のプロパティ。null にすることができます。これは、空のマップを渡すことと同じことを意味します。
        戻り値:
        JAXBContext の新しいインスタンス。
        例外:
        JAXBException - JAXBContext の作成中に次のようなエラーが発生した場合（ただしこれらに限定されません）:
        1. Jakarta XML Binding の実装は発見されませんでした
        2. クラスが Jakarta XML Binding アノテーションを誤って使用する
        3. クラスには衝突するアノテーションがあります (つまり、同じ型名の 2 つのクラス)
        4. Jakarta XML Binding 実装は、プロバイダー固有の帯域外情報を見つけることができませんでした (開発時に生成された追加ファイルなど。)
        5. classesToBeBound は jakarta.xml.bind モジュールに対して開かれていません
        IllegalArgumentExceptionSE - パラメーターに null が含まれている場合 (つまり、newInstance(null,someMap);)
        導入:
        1.6、JAXB 2.0

      • createUnmarshaller

        public abstract Unmarshaller createUnmarshaller()
                                         throws JAXBException
        XML データを java コンテンツツリーに変換するために使用できる Unmarshaller オブジェクトを作成します。
        戻り値:
        Unmarshaller オブジェクト
        例外:
        JAXBException - Unmarshaller オブジェクトの作成中にエラーが発生した場合

      • createMarshaller

        public abstract Marshaller createMarshaller()
                                     throws JAXBException
        java コンテンツツリーを XML データに変換するために使用できる Marshaller オブジェクトを作成します。
        戻り値:
        Marshaller オブジェクト
        例外:
        JAXBException - Marshaller オブジェクトの作成中にエラーが発生した場合

      • createBinder

        public <T> Binder<T> createBinder​(ClassSE<T> domType)
        アソシエイティブ / インプレースアンマーシャリング / マーシャリングに使用できる Binder オブジェクトを作成します。
        型パラメーター:
        T - DOM API 型
        パラメーター:
        domType - DOM Node クラスを渡して、使用する DOM API を選択します
        戻り値:
        常に新しい有効な Binder オブジェクト。
        例外:
        UnsupportedOperationExceptionSE - domType に対応する DOMAPI が実装でサポートされていない場合。
        導入:
        1.6、JAXB 2.0

      • createBinder

        public Binder<NodeSE> createBinder()
        W3CDOM 用の Binder を作成します。
        戻り値:
        常に新しい有効な Binder オブジェクト。
        導入:
        1.6、JAXB 2.0

      • createJAXBIntrospector

        public JAXBIntrospector createJAXBIntrospector()
        Jakarta XML Binding オブジェクトのイントロスペクトに使用できる JAXBIntrospector オブジェクトを作成します。
        戻り値:
        null 以外の有効な JAXBIntrospector オブジェクトを常に返します。
        例外:
        UnsupportedOperationExceptionSE - JAXB 1.0 実装でこのメソッドを呼び出すと、UnsupportedOperationException がスローされます。
        導入:
        1.6、JAXB 2.0

      • generateSchema

        public void generateSchema​(SchemaOutputResolver outputResolver)
                    throws IOExceptionSE
        このコンテキストのスキーマドキュメントを生成します。
        パラメーター:
        outputResolver - このオブジェクトは、スキーマの送信先となる出力を制御します。
        例外:
        IOExceptionSE - SchemaOutputResolver が IOExceptionSE をスローした場合。
        UnsupportedOperationExceptionSE - JAXB 1.0 実装でこのメソッドを呼び出すと、UnsupportedOperationException がスローされます。
        導入:
        1.6、JAXB 2.0