概要  パッケージ   クラス  使用  階層ツリー  非推奨 API  索引  ヘルプ 
JavaTM Platform
Standard Ed. 6
 前のクラス   次のクラス フレームあり    フレームなし    
概要: 入れ子 | フィールド | コンストラクタ | メソッド 詳細: フィールド | コンストラクタ | メソッド

javax.xml.bind
クラス JAXBContext

java.lang.Object
  上位を拡張 javax.xml.bind.JAXBContext

public abstract class JAXBContext
extends Object

JAXBContext クラスは、JAXB API へのクライアントのエントリポイントを提供します。これは、JAXB バインディングフレームワーク操作 (非整列化、整列化および検証) を実装する上で必要になる XML/Java バインディング情報を管理するための抽象化オブジェクトを提供しています。

 

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

仕様要件: プロバイダは、次のメソッドシグニチャーを含む実装クラスを提供する必要があります。  
 public static JAXBContext createContext( String contextPath, ClassLoader classLoader, Map properties ) throws JAXBException
 public static JAXBContext createContext( Class[] classes, Map 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 実行時バインディングフレームワークの互換性

次の JAXB 1.0 の制限は、スキーマとインタフェースまたは実装クラス間のバインディングにのみ適用されます。このバインディングは共通の実行システムを必要としないため、JAXB クライアントアプリケーションは、異なるプロバイダの実行時オブジェクト (JAXBContext、Marshaller など) を混合させようとしないでください。このことは、クライアントアプリケーションに移植性がないことを意味しません。スキーマをコンパイルするときに使用した同一プロバイダが提供する実行時システムをクライアントが使用しなければならないことを単に意味します。

導入されたバージョン:
JAXB1.0
関連項目:
Marshaller, Unmarshaller, 『Java 言語仕様第 3 版』 7.4.1.1 節「Package Annotations」

フィールドの概要
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()
          推奨されていません。 since 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 クラスの新しいインスタンスを取得します。
 
クラス java.lang.Object から継承されたメソッド
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

フィールドの詳細

JAXB_CONTEXT_FACTORY

public static final String JAXB_CONTEXT_FACTORY
新しい JAXBContext オブジェクトを作成可能なクラスの名前を含むプロパティーの名前です。

関連項目:
定数フィールド値
コンストラクタの詳細

JAXBContext

protected JAXBContext()
メソッドの詳細

newInstance

public static JAXBContext newInstance(String contextPath)
                               throws JAXBException

JAXBContext クラスの新しいインスタンスを取得します。

これは、newInstance メソッドの簡易メソッドです。現在のスレッドのコンテキストクラスローダーを使用します。別のクラスローダーの使用を指定するには、Thread.setContextClassLoader() API を介してそれを設定するか、newInstance メソッドを使用します。

例外:
JAXBException - JAXBContext の作成中に次のようなエラーが発生した場合
  1. パッケージ内で ObjectFactory.class または jaxb.index が見つからない
  2. contextPath に含まれるグローバル要素間であいまいさがある
  3. コンテキストファクトリプロバイダプロパティーの値が見つからない
  4. 同じ contextPath に異なるプロバイダからのスキーマ派生パッケージが混在している

newInstance

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 第 3 版、7.4.1 節「Package Annotations」を参照)。

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

  1. ObjectFactory.class を含むこと
  2. jaxb.index を含むこと

jaxb.index の形式

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

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

スキーマカスタマイズによって有効化される、JAXB 1.0 スキーマから Java へのインタフェース/実装バインディングとの互換性を維持するため、JAXB プロバイダはコンテキストパス上の各パッケージに javax.xml.bind.context.factory プロパティーの値を含む jaxb.properties ファイルが含まれ、すべての値が同じプロバイダに解決されることを保証します。この要件は、JAXB 注釈付きクラスには適用されません。

contextPath にリストされたさまざまなパッケージにまたがってグローバル XML 要素名の衝突が発生した場合、JAXBException がスローされます。

同じコンテキストパス内に複数の JAXB プロバイダから生成されたインタフェース/実装バインディングが混在する場合、JAXBException がスローされる可能性があります。

パラメータ:
contextPath - スキーマ派生クラス、または Java から JAXB 注釈付きスキーマへのマップクラス (あるいはその両方) を含む Java パッケージ名リスト
classLoader - このクラスローダーが実装クラスの場所の特定に使用される
戻り値:
JAXBContext の新しいインスタンス
例外:
JAXBException - JAXBContext の作成中に次のようなエラーが発生した場合
  1. パッケージ内で ObjectFactory.class または jaxb.index が見つからない
  2. contextPath に含まれるグローバル要素間であいまいさがある
  3. コンテキストファクトリプロバイダプロパティーの値が見つからない
  4. 同じ contextPath に異なるプロバイダからのスキーマ派生パッケージが混在している

newInstance

public static JAXBContext newInstance(String contextPath,
                                      ClassLoader classLoader,
                                      Map<String,?> properties)
                               throws JAXBException

JAXBContext クラスの新しいインスタンスを取得します。

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

プロパティーの解釈は、実装に委ねられます。

パラメータ:
contextPath - スキーマ派生クラスを含む Java パッケージ名のリスト
classLoader - このクラスローダーが実装クラスの場所の特定に使用される
properties - プロバイダ固有のプロパティー
戻り値:
JAXBContext の新しいインスタンス
例外:
JAXBException - JAXBContext の作成中に次のようなエラーが発生した場合
  1. パッケージ内で ObjectFactory.class または jaxb.index が見つからない
  2. contextPath に含まれるグローバル要素間であいまいさがある
  3. コンテキストファクトリプロバイダプロパティーの値が見つからない
  4. 同じ contextPath に異なるプロバイダからのスキーマ派生パッケージが混在している
導入されたバージョン:
JAXB2.0

newInstance

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 第 3 版、7.4.1 節「Package Annotations」を参照)。

パラメータ:
classesToBeBound - 新しい JAXBContext によって認識される Java クラスのリスト。空でもよいが、その場合は仕様定義済みクラスだけを認識している JAXBContext が返される
戻り値:
JAXBContext の新しいインスタンス。常に null 以外の有効なオブジェクト
例外:
JAXBException - JAXBContext の作成中に次のようなエラー が発生した場合 (ただし、これらに限定されない)
  1. JAXB 実装が検出されない
  2. クラスが JAXB 注釈を誤って使用している
  3. クラス間に重複する注釈がある (たとえば、同じ型名を持つ 2 つのクラス)
  4. JAXB 実装がプロバイダ固有の帯域外情報を見つけられない場合 (開発時に生成された追加ファイルなど)
IllegalArgumentException - パラメータに null が含まれる場合 (つまり、newInstance(null);)
導入されたバージョン:
JAXB2.0

newInstance

public static JAXBContext newInstance(Class[] classesToBeBound,
                                      Map<String,?> properties)
                               throws JAXBException

JAXBContext クラスの新しいインスタンスを取得します。

JAXBContext のこのインスタンス化に対し properties を設定する、newInstance(Class...) のオーバーロードです。

プロパティーの解釈は、実装固有です。

パラメータ:
classesToBeBound - 新しい JAXBContext によって認識される Java クラスのリスト。空でもよいが、その場合は仕様定義済みクラスだけを認識している JAXBContext が返される
戻り値:
JAXBContext の新しいインスタンス。常に null 以外の有効なオブジェクト
例外:
JAXBException - JAXBContext の作成中に次のようなエラー が発生した場合 (ただし、これらに限定されない)
  1. JAXB 実装が検出されない
  2. クラスが JAXB 注釈を誤って使用している
  3. クラス間に重複する注釈がある (たとえば、同じ型名を持つ 2 つのクラス)
  4. JAXB 実装がプロバイダ固有の帯域外情報を見つけられない場合 (開発時に生成された追加ファイルなど)
IllegalArgumentException - パラメータに null が含まれる場合 (つまり、newInstance(null);)
導入されたバージョン:
JAXB2.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 オブジェクトの作成中にエラーが発生した場合

createValidator

public abstract Validator createValidator()
                                   throws JAXBException
推奨されていません。 since JAXB2.0

Validator は、JAXB 2.0 ではオプションとされ、推奨されていません。詳細は、Validator に関する javadoc を参照してください。

Java コンテンツツリーをそれのソーススキーマに照らし合わせて検証するために使用できる Validator オブジェクトを作成します。

戻り値:
Validator オブジェクト
例外:
JAXBException - Validator オブジェクトの作成中にエラーが発生した場合

createBinder

public <T> Binder<T> createBinder(Class<T> domType)
関連付けされた、またはインプレースの非整列化または整列化に使用できる Binder オブジェクトを作成します。

パラメータ:
domType - その DOM Node クラスを渡すことによって使用する DOM API を選択する
戻り値:
常に新しい有効な Binder オブジェクト
例外:
UnsupportedOperationException - domType に対応する DOM API が実装によってサポートされていない場合
導入されたバージョン:
JAXB2.0

createBinder

public Binder<Node> createBinder()
W3C DOM 用の Binder を作成します。

戻り値:
常に新しい有効な Binder オブジェクト
導入されたバージョン:
JAXB2.0

createJAXBIntrospector

public JAXBIntrospector createJAXBIntrospector()
JAXB オブジェクトのイントロスペクションに使用できる JAXBIntrospector オブジェクトを作成します。

戻り値:
常に null 以外の有効な JAXBIntrospector オブジェクトを返す
例外:
UnsupportedOperationException - JAXB 1.0 実装でこのメソッドを呼び出した場合、UnsupportedOperationException がスローされる
導入されたバージョン:
JAXB2.0

generateSchema

public void generateSchema(SchemaOutputResolver outputResolver)
                    throws IOException
このコンテキストのスキーマ文書を生成します。

パラメータ:
outputResolver - このオブジェクトは、スキーマの送信先となる出力を制御する
例外:
IOException - SchemaOutputResolver が IOException をスローする場合
UnsupportedOperationException - JAXB 1.0 実装でこのメソッドを呼び出した場合、UnsupportedOperationException がスローされる
導入されたバージョン:
JAXB 2.0
概要  パッケージ   クラス  使用  階層ツリー  非推奨 API  索引  ヘルプ 
JavaTM Platform
Standard Ed. 6
 前のクラス   次のクラス フレームあり    フレームなし    
概要: 入れ子 | フィールド | コンストラクタ | メソッド 詳細: フィールド | コンストラクタ | メソッド
バグの報告と機能のリクエスト
さらに詳しい API リファレンスおよび開発者ドキュメントについては、Java SE 開発者用ドキュメントを参照してください。開発者向けの詳細な解説、概念の概要、用語の定義、バグの回避策、およびコード実例が含まれています。

Copyright 2009 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。