public abstract class JAXBContext extends Object
JAXBContext クラスは、JAXB API へのクライアントのエントリポイントを提供します。これは、JAXB バインディングフレームワーク操作 (非整列化、整列化および検証) を実装する上で必要になる XML/Java バインディング情報を管理するための抽象化オブジェクトを提供しています。
利用可能なほかの特殊なメソッドの形式はありますが、クライアントアプリケーションは通常、次の 2 つのスタイルの newInstance メソッドのいずれかを使用して、このクラスの新しいインスタンスを取得します。
JAXBContext.newInstance( "com.acme.foo:com.acme.bar" )
JAXBContext.newInstance( com.acme.foo.Foo.class )
newInstance(Class...)
を参照してください。
仕様要件: プロバイダは、次のメソッドシグニチャーを含む実装クラスを提供する必要があります。
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
次の JAXB 1.0 要件は、スキーマから Java へのインタフェースおよび実装バインディングでのみ必要になります。JAXB 注釈付きクラスには適用されません。JAXB プロバイダは、スキーマ派生クラスを含む各パッケージに jaxb.properties ファイルを生成する必要があります。このプロパティーファイルには、プロパティー名が javax.xml.bind.context.factory で、値が createContext API を実装するクラス名であるプロパティーが含まれる必要があります。
プロバイダが提供するクラスは javax.xml.bind.JAXBContext に割り当て可能でなくてもよく、単に createContext API を実装するクラスを提供することが求められます。
また、プロバイダは、クライアントの整列化および非整列化メソッド呼び出しの前に DatatypeConverter.setDatatypeConverter
API を呼び出す必要があります。これは、これらの操作中に使用されるデータ型コンバータを設定するために必要になります。
Unmarshaller
クラスは、XML データを Java コンテンツオブジェクトツリーに変換できる機能をクライアントアプリケーションに提供します。非整列化メソッドでは、スキーマ内で宣言された任意のグローバル XML 要素を、インスタンス文書のルートとして非整列化することができます。加えて、非整列化メソッドでは、スキーマで宣言された型定義を参照する 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 コンテンツツリーを明示的に生成することもできます。すべての JAXB 注釈付き値クラスに対し、アプリケーションはコンストラクタを使用してコンテンツを作成できます。スキーマから派生したインタフェースまたは実装クラスの場合、および、JAXB 注釈付きクラスにバインドされていない要素の作成の場合、アプリケーションは、contextPath に含まれる各 Java パッケージ内に存在するスキーマ派生 ObjectFactory クラスのそれぞれについてのアクセスと認識が必要になります。個々のスキーマ派生 Java クラスには、その型のオブジェクトを生成する static ファクトリメソッドが存在します。たとえば、スキーマをコンパイルしたあと、PurchaseOrder という名前のスキーマ派生インタフェースを含むパッケージ com.acme.foo があるとします。その型のオブジェクトを作成するために、クライアントアプリケーションは次のファクトリメソッドを使用します。
com.acme.foo.PurchaseOrder po = com.acme.foo.ObjectFactory.createPurchaseOrder();
スキーマ派生オブジェクトのインスタンスの作成後、クライアントアプリケーションは変更用メソッドを使用してそれのコンテンツを設定できます。
生成された ObjectFactory クラスの詳細は、JAXB 仕様のセクション 4.2「Java Package」を参照してください。
仕様要件: プロバイダは、そのパッケージに必要なすべてのオブジェクトファクトリメソッドを含むクラスを 1 つ、各パッケージに生成する必要があります。メソッド名は、ObjectFactory、および、static newInstance( javaContentInterface ) です。
Marshaller
クラスは、Java コンテンツツリーを変換して XML データに戻す機能をクライアントアプリケーションに提供します。ファクトリメソッドを使用して手動で作成されたコンテンツツリーの整列化処理と、unmarshal 操作で返されたコンテンツツリーの整列化処理の間に違いはありません。クライアントは、Java コンテンツツリーを XML データに整列化し、java.io.OutputStream または java.io.Writer に書き込むことができます。あるいは、整列化プロセスが SAX2 イベントストリームを生成して登録済みの ContentHandler に渡すか、DOM Node オブジェクトを生成することもできます。クライアントアプリケーションは、出力エンコーディングと、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
クラスは、非推奨になり、オプションとされています。これは、このクラスを使用しないことが推奨されていることを意味し、実際に、使用している JAXB プロバイダによっては利用できない場合もあります。Validator に依存する JAXB 1.0 クライアントアプリケーションは、JAXB 1.0 実行システムに配備された場合、まだ正常に動作します。
JAXB 2.0 では、JAXP 1.3 javax.xml.validation
フレームワークを公開する簡易メソッドが Unmarshaller
に含まれています。詳細は、Unmarshaller.setSchema(javax.xml.validation.Schema)
API を参照してください。
次の JAXB 1.0 の制限は、スキーマとインタフェースまたは実装クラス間のバインディングにのみ適用されます。このバインディングは共通の実行システムを必要としないため、JAXB クライアントアプリケーションは、異なるプロバイダの実行時オブジェクト (JAXBContext、Marshaller など) を混合させようとしないでください。このことは、クライアントアプリケーションに移植性がないことを意味しません。スキーマをコンパイルするときに使用した同一プロバイダが提供する実行時システムをクライアントが使用しなければならないことを単に意味します。
いずれかの newInstance メソッドが呼び出されると、次の手順で JAXB 実装が検出されます。
newInstance(java.lang.String)
メソッドに明示的に渡されたパッケージ/クラスごとに、指定された順序で、関連するクラスローダーを使用してそのパッケージ内の jaxb.properties ファイルが検索されます。これは、Class
引数の the owner class loader
であり、パッケージの場合は指定された ClassLoader
です。
このようなファイルが検出された場合は、そのファイルがプロパティーファイルとして loaded
、JAXB_CONTEXT_FACTORY
キーの値がプロバイダファクトリクラスと見なされます。このクラスは、すでに説明した関連するクラスローダーによってロードされます。
検索のこの段階では、一部のパッケージで強制的に特定の JAXB 実装を使用できます。(たとえば、スキーマコンパイラによってコード内に何らかのベンダー拡張機能が生成されている場合があります。)
JAXB_CONTEXT_FACTORY
が存在する場合は、その値がプロバイダファクトリクラスと見なされます。検索のこの段階では、JVM 単位で JAXB 実装をオーバーライドできます。
プロバイダファクトリクラスが検出されると、その public static JAXBContext createContext(String,ClassLoader,Map) メソッド (パラメータのセマンティクスについては、newInstance(String, ClassLoader, Map)
を参照) または public static JAXBContext createContet(Class[],Map) メソッド (パラメータのセマンティクスについては、newInstance(Class[], Map)
を参照) が呼び出され、JAXBContext
が作成されます。
Marshaller
, Unmarshaller
, 『Java 言語仕様』の 7.4.1「名前付きパッケージ」
修飾子と型 | フィールドと説明 |
---|---|
static String |
JAXB_CONTEXT_FACTORY
新しい JAXBContext オブジェクトを作成可能なクラスの名前を含むプロパティーの名前です。
|
修飾子 | コンストラクタと説明 |
---|---|
protected |
JAXBContext() |
修飾子と型 | メソッドと説明 |
---|---|
Binder<Node> |
createBinder()
W3C DOM 用の Binder を作成します。
|
<T> Binder<T> |
createBinder(Class<T> domType)
関連付けされた、またはインプレースの非整列化または整列化に使用できる Binder オブジェクトを作成します。
|
JAXBIntrospector |
createJAXBIntrospector()
JAXB オブジェクトをイントロスペクションするために使用できる 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(Class... classesToBeBound)
JAXBContext クラスの新しいインスタンスを取得します。
|
static JAXBContext |
newInstance(Class[] classesToBeBound, Map<String,?> properties)
JAXBContext クラスの新しいインスタンスを取得します。
|
static JAXBContext |
newInstance(String contextPath)
JAXBContext クラスの新しいインスタンスを取得します。
|
static JAXBContext |
newInstance(String contextPath, ClassLoader classLoader)
JAXBContext クラスの新しいインスタンスを取得します。
|
static JAXBContext |
newInstance(String contextPath, ClassLoader classLoader, Map<String,?> properties)
JAXBContext クラスの新しいインスタンスを取得します。
|
public static JAXBContext newInstance(String contextPath) throws JAXBException
JAXBContext クラスの新しいインスタンスを取得します。
これは、newInstance(String,ClassLoader)
メソッドを呼び出すための簡易メソッドです。現在のスレッドのコンテキストクラスローダーを使用します。
JAXBException
- JAXBContext の作成中に次のようなエラーが発生した場合
public static JAXBContext newInstance(String contextPath, ClassLoader classLoader) throws JAXBException
JAXBContext クラスの新しいインスタンスを取得します。
クライアントアプリケーションは、コロン (「:」、\u003A) で区切られた Java パッケージ名のリストであるコンテキストパスを提供する必要があります。これには、スキーマ派生クラスおよび完全指定された JAXB 注釈付きクラスの両方またはいずれか一方が含まれます。スキーマ派生コードは、パッケージごとに生成された ObjectFactory.class によって JAXBContext に登録されます。あるいは、コンテキストパスにリストするのではなく、プログラマが注釈を指定した JAXB マップクラスを下記の形式で jaxb.index リソースファイルにリストすることもできます。Java パッケージは、スキーマ派生クラスとユーザー注釈 JAXB クラスの両方を含むことができます。また、Java パッケージに、処理すべき JAXB パッケージ注釈が含まれることもあります(JLS のセクション 7.4.1「名前付きパッケージ」を参照)。
contextPath にリストされる各パッケージは、次の条件の 1 つまたは両方を満たす必要があります。これを満たさない場合、JAXBException がスローされます。
jaxb.index の形式
このファイルには、改行で区切れられたクラス名のリストが含まれます。空白文字とタブ文字、および空白行は無視されます。コメント文字は「#」(0x23) で、行の最初のコメント文字に続く文字はすべて無視されます。ファイルは UTF-8 でエンコードされる必要があります。また、newInstance(Class...)
で定義されたとおり、リストされたクラスから到達可能なクラスが JAXBContext に登録されます。
jaxb.index ファイルで発生するクラス名の制約は、次のとおりです。
スキーマカスタマイズ <jaxb:globalBindings valueClass="false"> によって有効化される、JAXB 1.0 スキーマから Java へのインタフェース/実装バインディングとの互換性を維持するため、JAXB プロバイダはコンテキストパス上の各パッケージに javax.xml.bind.context.factory プロパティーの値を含む jaxb.properties ファイルが含まれ、すべての値が同じプロバイダに解決されることを保証します。この要件は、JAXB 注釈付きクラスには適用されません。
contextPath にリストされたさまざまなパッケージにまたがってグローバル XML 要素名の競合が発生した場合、JAXBException がスローされます。
同じコンテキストパス内に複数の JAXB プロバイダから生成されたインタフェース/実装バインディングが混在する場合、JAXBException がスローされる可能性があります。
JAXB 実装の検出に関連する手順は、クラス javadoc で説明します。
contextPath
- スキーマ派生クラス、または Java から JAXB 注釈付きスキーマへのマップクラス (あるいはその両方) を含む Java パッケージ名リストclassLoader
- このクラスローダーが実装クラスの場所の特定に使用される。JAXBException
- JAXBContext の作成中に次のようなエラーが発生した場合
public static JAXBContext newInstance(String contextPath, ClassLoader classLoader, Map<String,?> properties) throws JAXBException
JAXBContext クラスの新しいインスタンスを取得します。
これは、newInstance(String, ClassLoader)
とほとんど同じですが、このバージョンでは JAXBContext
のインスタンス化を設定するためにプロバイダ固有のプロパティーを渡すことができます。
プロパティーの解釈は、実装に委ねられます。実装は、理解できないプロパティーを検出した場合、JAXBException をスローします。
contextPath
- スキーマ派生クラスを含む Java パッケージ名のリストclassLoader
- このクラスローダーが実装クラスの場所の特定に使用される。properties
- プロバイダ固有のプロパティー。null でもよいが、空マップで渡す場合と同じことを意味する。JAXBException
- JAXBContext の作成中に次のようなエラーが発生した場合
public static JAXBContext newInstance(Class... 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「名前付きパッケージ」を参照)。
JAXB 実装の検出に関連する手順は、クラス javadoc で説明します。
classesToBeBound
- 新しい JAXBContext
によって認識される Java クラスのリスト。空でもよいが、その場合は仕様定義済みクラスだけを認識している JAXBContext
が返される。JAXBException
- JAXBContext の作成中に次のようなエラーが発生した場合 (ただし、これらに限定されない)。
IllegalArgumentException
- パラメータに null
が含まれる場合 (つまり、newInstance(null);
)public static JAXBContext newInstance(Class[] classesToBeBound, Map<String,?> properties) throws JAXBException
JAXBContext クラスの新しいインスタンスを取得します。
JAXBContext
のこのインスタンス化に対して「properties」を設定する newInstance(Class...)
のオーバーロードです。
プロパティーの解釈は、実装に委ねられます。実装は、理解できないプロパティーを検出した場合、JAXBException をスローします。
classesToBeBound
- 新しい JAXBContext
によって認識される Java クラスのリスト。空でもよいが、その場合は仕様定義済みクラスだけを認識している JAXBContext
が返される。properties
- プロバイダ固有のプロパティー。null でもよいが、空マップで渡す場合と同じことを意味する。JAXBException
- JAXBContext の作成中に次のようなエラーが発生した場合 (ただし、これらに限定されない)。
IllegalArgumentException
- パラメータに null
が含まれる場合 (つまり、newInstance(null,someMap);
)public abstract Unmarshaller createUnmarshaller() throws JAXBException
JAXBException
- Unmarshaller オブジェクトの作成中にエラーが発生した場合public abstract Marshaller createMarshaller() throws JAXBException
JAXBException
- Marshaller オブジェクトの作成中にエラーが発生した場合public abstract Validator createValidator() throws JAXBException
Validator
は、JAXB 2.0 ではオプションであり、非推奨です。詳細は、Validator
に関する javadoc を参照してください。
Java コンテンツツリーをそれのソーススキーマに照らし合わせて検証するために使用できる Validator オブジェクトを作成します。
JAXBException
- Validator オブジェクトの作成中にエラーが発生した場合public <T> Binder<T> createBinder(Class<T> domType)
domType
- その DOM Node クラスを渡すことによって使用する DOM API を選択する。UnsupportedOperationException
- domType に対応する DOM API が実装によってサポートされていない場合。public Binder<Node> createBinder()
public JAXBIntrospector createJAXBIntrospector()
UnsupportedOperationException
- JAXB 1.0 実装でこのメソッドを呼び出した場合、UnsupportedOperationException がスローされる。public void generateSchema(SchemaOutputResolver outputResolver) throws IOException
outputResolver
- このオブジェクトは、スキーマの送信先となる出力を制御する。IOException
- SchemaOutputResolver
が IOException
をスローする場合。UnsupportedOperationException
- JAXB 1.0 実装でこのメソッドを呼び出した場合、UnsupportedOperationException がスローされる。 バグまたは機能を送信
詳細な API リファレンスおよび開発者ドキュメントについては、Java SE のドキュメントを参照してください。そのドキュメントには、概念的な概要、用語の定義、回避方法、有効なコード例などの、開発者を対象にしたより詳細な説明が含まれています。
Copyright © 1993, 2013, Oracle and/or its affiliates. All rights reserved.