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.newInstance( com.acme.foo.Foo.class )
newInstance(Class...)
を参照してください。 次の JAXB 1.0 要件は、スキーマから java インターフェース / 実装バインディングにのみ必要です。Jakarta XML Binding アノテーション付きクラスには適用されません。Jakarta XML Binding Providers は、スキーマ派生クラスを含む各パッケージに jaxb.properties
ファイルを生成する必要があります。プロパティファイルには、createContext
API を実装するクラスの名前が値である jakarta.xml.bind.context.factory
という名前のプロパティが含まれている必要があります。
プロバイダーが提供するクラスは、jakarta.xml.bind.JAXBContext
に割り当て可能である必要はなく、createContext
API を実装するクラスを提供するだけです。
さらに、プロバイダーは、マーシャルメソッドとアンマーシャルメソッドをクライアントが呼び出す前に、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 );
JAXB 1.0 以降、検証が大幅に変更されました。Validator
クラスは非推奨になり、オプションになりました。つまり、このクラスは使用しないことをお勧めします。実際、Jakarta XML Binding プロバイダーによっては使用できない場合もあります。Validator
に依存する JAXB 1.0 クライアントアプリケーションは、JAXB1.0 ランタイムシステムでデプロイされた場合でも正しく機能します。Jakarta XML Binding では、Unmarshaller
には、JAXP 1.3 javax.xml.validation
SE フレームワークを公開する便利なメソッドが含まれています。詳細については、Unmarshaller.setSchema(javax.xml.validation.Schema)
API を参照してください。
次の JAXB 1.0 制限は、スキーマをインターフェース / 実装クラスにバインドする場合にのみ適用されます。このバインディングは共通のランタイムシステムを必要としないため、Jakarta XML Binding クライアントアプリケーションは、異なるプロバイダーからのランタイムオブジェクト(JAXBContext, Marshaller
など)を混在させようとしてはなりません。これは、クライアントアプリケーションが移植可能でないことを意味するのではなく、単に、クライアントがスキーマのコンパイルに使用されたのと同じプロバイダーによって提供されるランタイムシステムを使用する必要があることを意味します。
JAXBContext
のインスタンスを作成するために、JAXBContext.newInstance(...)
メソッドの 1 つが呼び出されます。JAX-B 実装が検出された後、呼び出しは、元の呼び出しからパラメーターを渡す適切なプロバイダーのメソッド createContext(...)
に委譲されます。
JAX-B 実装の検出は、JAXBContext.newInstance
が呼び出されるたびに発生します。ユーザー固有の構成が提供されていない場合は、デフォルトの JAX-B プロバイダーを返す必要があります。
実装の検出は、次の手順で構成されます。
newInstance(java.lang.String)
メソッドに明示的に渡されたパッケージ / クラスは、関連するクラスローダーを使用して、jaxb.properties
ファイルがパッケージ内で検索されるまで、指定された順序で処理されます。これは、Class
SE 引数の場合は the owner class loader
SE であり、パッケージの場合は指定された ClassLoader
SE です。 そのようなリソースが検出された場合、プロパティファイルとして loaded
SE であり、JAXB_CONTEXT_FACTORY
キーの値はプロバイダーファクトリクラスであると見なされます。値が見つからない場合は、下位互換性の理由から "jakarta.xml.bind.context.factory"
がキーとして使用されます。次に、このクラスは、上記で説明した関連するクラスローダーによってロードされます。
ルックアップのこのフェーズでは、一部のパッケージで特定の Jakarta XML Binding 実装の使用を強制できます。(例: スキーマコンパイラーがコードにベンダー拡張を生成した可能性があります。)
この構成方法は非推奨です。
JAXB_CONTEXT_FACTORY
が存在する場合、その値はプロバイダーファクトリクラスであると見なされます。そのようなプロパティが存在しない場合、下位互換性の理由から、プロパティ "jakarta.xml.bind.context.factory"
および "jakarta.xml.bind.JAXBContext"
も(この順序で)チェックされます。ルックアップのこのフェーズでは、Jakarta XML Binding 実装の JVM ごとのオーバーライドが有効になります。JAXBContextFactory
のプロバイダーは、ServiceLoader
SE クラスによって定義されたサービスプロバイダーのロード機能を使用してロードされ、デフォルトのロードメカニズムSEを使用してサービスの実装を見つけてロードしようとします。サービスプロバイダーのロード機能は、現在のスレッドのコンテキストクラスローダーSEを使用してロードを試みます。コンテキストファクトリ。コンテキストクラスローダーが null の場合、システムクラスローダーSEが使用されます。service configuration error
SE の場合、JAXBException
がスローされます。/META-INF/services/jakarta.xml.bind.JAXBContext
を探します。クラスローダーパラメーターのないメソッドは Thread.currentThread().getContextClassLoader()
を使用します。そのようなリソースが存在する場合、そのコンテンツはプロバイダーファクトリクラスであると見なされます。この構成方法は非推奨です。 プロバイダーファクトリクラスが検出されると、コンテキストの作成はその createContext(...)
メソッドの 1 つに委譲されます。下位互換性の理由から、プロバイダーファクトリクラスを実装する方法は 2 つあります。
JAXBContextFactory
の実装です。また、引数なしのコンストラクターを実装する必要があります。他のステップ 3 で検出された場合、引数なしのコンストラクターを使用する新しいインスタンスが最初に作成されます。その後、このインスタンスで適切なインスタンスメソッドが呼び出されます。public static JAXBContext createContext( String contextPath, ClassLoader classLoader, Map<String,Object> properties ) throws JAXBException public static JAXBContext createContext( Class[] classes, Map<String,Object> properties ) throws JAXBExceptionこのシナリオでは、インスタンスメソッドの代わりに適切な静的メソッドが使用されます。このアプローチは
ServiceLoader
SE と互換性がないため、ステップ 3 では使用できません。 アプローチ 1(JAXBContextFactory)を使用するか 2(インターフェースなし、静的メソッド)を使用するかに関係なく、特定のメソッド createContext(...)
の動作に違いはありません。
Marshaller
, Unmarshaller
, Java 言語仕様の S 7.4.1「名前付きパッケージ」SE修飾子と型 | フィールドと説明 |
---|---|
static StringSE | JAXB_CONTEXT_FACTORY 新しい JAXBContext オブジェクトを作成できるクラスの名前を含むプロパティの名前。 |
修飾子 | コンストラクターと説明 |
---|---|
protected | JAXBContext() |
修飾子と型 | メソッドと説明 |
---|---|
Binder<NodeSE> | createBinder() W3CDOM 用の Binder を作成します。 |
<T> Binder<T> | createBinder(ClassSE<T> domType) アソシエイティブ / インプレースアンマーシャリング / マーシャリングに使用できる Binder オブジェクトを作成します。 |
JAXBIntrospector | createJAXBIntrospector() Jakarta XML Binding オブジェクトのイントロスペクトに使用できる JAXBIntrospector オブジェクトを作成します。 |
abstract Marshaller | createMarshaller() java コンテンツツリーを XML データに変換するために使用できる Marshaller オブジェクトを作成します。 |
abstract Unmarshaller | createUnmarshaller() XML データを java コンテンツツリーに変換するために使用できる Unmarshaller オブジェクトを作成します。 |
abstract Validator | createValidator() 使用すべきではありません。 JAXB2.0 以降 |
void | generateSchema(SchemaOutputResolver outputResolver) このコンテキストのスキーマドキュメントを生成します。 |
static JAXBContext | newInstance(ClassSE<?>... classesToBeBound) JAXBContext クラスの新しいインスタンスを作成します。 |
static JAXBContext | newInstance(ClassSE<?>[] classesToBeBound, MapSE<StringSE,?> properties) JAXBContext クラスの新しいインスタンスを作成します。 |
static JAXBContext | newInstance(StringSE contextPath) JAXBContext クラスの新しいインスタンスを作成します。 |
static JAXBContext | newInstance(StringSE contextPath, ClassLoaderSE classLoader) JAXBContext クラスの新しいインスタンスを作成します。 |
static JAXBContext | newInstance(StringSE contextPath, ClassLoaderSE classLoader, MapSE<StringSE,?> properties) JAXBContext クラスの新しいインスタンスを作成します。 |
cloneSE, equalsSE, finalizeSE, getClassSE, hashCodeSE, notifySE, notifyAllSE, toStringSE, waitSE, waitSE, waitSE
public static JAXBContext newInstance(StringSE contextPath) throws JAXBException
JAXBContext
クラスの新しいインスタンスを作成します。 これは、現在のスレッドのコンテキストクラスローダーで newInstance(String,ClassLoader)
メソッドを呼び出すための便利なメソッドです。
JAXBException
- JAXBContext
の作成中に次のようなエラーが発生した場合jakarta.xml.bind
モジュールに対して開かれていません 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
がスローされます。
jaxb.index の形式
このファイルには、クラス名の改行で区切られたリストが含まれています。スペースとタブ文字、および空白行は無視されます。コメント文字は '#' (0x23); 各行で、最初のコメント文字に続くすべての文字は無視されます。ファイルは UTF-8 でエンコードする必要があります。リストされたクラスから newInstance(Class...)
で定義されているように到達可能なクラスも、JAXBContext に登録されます。
jaxb.index
ファイルで発生するクラス名の制約は次のとおりです。
jaxb.index
ファイルを含むパッケージに関連して解決されます。jaxb.index
ファイルを含むパッケージで直接発生するクラスのみが許可されます。 スキーマのカスタマイズ <jaxb:globalBindings valueClass="false">
によって有効化された JAXB 1.0 スキーマから java インターフェース / 実装バインディングとの互換性を維持するために、Jakarta XML Binding プロバイダーは、コンテキストパス上の各パッケージに jakarta.xml.bind.context.factory
プロパティの値を含む jaxb.properties
ファイルがあり、すべての値が同じプロバイダー。この要件は、Jakarta XML Binding アノテーション付きクラスには適用されません。
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
の作成中に次のようなエラーが発生した場合jakarta.xml.bind
モジュールに対して開かれていません 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
の作成中に次のようなエラーが発生した場合jakarta.xml.bind
モジュールに対して開かれていません 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
の作成中に次のようなエラーが発生した場合(ただしこれらに限定されません):classesToBeBound
は jakarta.xml.bind
モジュールに対して開かれていません IllegalArgumentExceptionSE
- パラメーターに null
が含まれている場合 (つまり、newInstance(null);
)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
の作成中に次のようなエラーが発生した場合(ただしこれらに限定されません):classesToBeBound
は jakarta.xml.bind
モジュールに対して開かれていません IllegalArgumentExceptionSE
- パラメーターに null
が含まれている場合 (つまり、newInstance(null,someMap);
)public abstract Unmarshaller createUnmarshaller() throws JAXBException
Unmarshaller
オブジェクトを作成します。Unmarshaller
オブジェクト JAXBException
- Unmarshaller
オブジェクトの作成中にエラーが発生した場合 public abstract Marshaller createMarshaller() throws JAXBException
Marshaller
オブジェクトを作成します。Marshaller
オブジェクト JAXBException
- Marshaller
オブジェクトの作成中にエラーが発生した場合 @DeprecatedSE public abstract Validator createValidator() throws JAXBException
Validator
はオプションになり、Jakarta XML Binding では非推奨になりました。詳細については、Validator
の javadoc を参照してください。 ソーススキーマに対して java コンテンツツリーを検証するために使用できる Validator
オブジェクトを作成します。
Validator
オブジェクト JAXBException
- Validator
オブジェクトの作成中にエラーが発生した場合 public <T> Binder<T> createBinder(ClassSE<T> domType)
Binder
オブジェクトを作成します。domType
- DOM Node クラスを渡して、使用する DOMAPI を選択します。Binder
オブジェクト。UnsupportedOperationExceptionSE
- domType
に対応する DOMAPI が実装でサポートされていない場合。public Binder<NodeSE> createBinder()
Binder
を作成します。Binder
オブジェクト。public JAXBIntrospector createJAXBIntrospector()
JAXBIntrospector
オブジェクトを作成します。JAXBIntrospector
オブジェクトを常に返します。UnsupportedOperationExceptionSE
- JAXB 1.0 実装でこのメソッドを呼び出すと、UnsupportedOperationException がスローされます。public void generateSchema(SchemaOutputResolver outputResolver) throws IOExceptionSE
outputResolver
- このオブジェクトは、スキーマの送信先となる出力を制御します。IOExceptionSE
- SchemaOutputResolver
が IOException
SE をスローした場合。UnsupportedOperationExceptionSE
- JAXB 1.0 実装でこのメソッドを呼び出すと、UnsupportedOperationException がスローされます。Copyright © 2018,2020 Eclipse Foundation.
Use is subject to license terms.