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, 2014, Oracle and/or its affiliates. All rights reserved.