JavaTM Platform
Standard Ed. 6

javax.xml.bind
インタフェース Unmarshaller

既知の実装クラスの一覧:
AbstractUnmarshallerImpl

public interface Unmarshaller

Unmarshaller クラスは、XML データを新規作成 Java コンテンツツリーに直列化復元し、オプションとして非整列化時に XML データを検証するプロセスを制御します。多数の異なる種類の入力に対する非整列化メソッドのオーバーロードを提供します。

ファイルから非整列化します。

       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
       Unmarshaller u = jc.createUnmarshaller();
       Object o = u.unmarshal( new File( "nosferatu.xml" ) );
    

InputStream から非整列化します。

       InputStream is = new FileInputStream( "nosferatu.xml" );
       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
       Unmarshaller u = jc.createUnmarshaller();
       Object o = u.unmarshal( is );
    

URL から非整列化します。

       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
       Unmarshaller u = jc.createUnmarshaller();
       URL url = new URL( "http://beaker.east/nosferatu.xml" );
       Object o = u.unmarshal( url );
    

javax.xml.transform.stream.StreamSource を使用して StringBuffer から非整列化します。

       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
       Unmarshaller u = jc.createUnmarshaller();
       StringBuffer xmlStr = new StringBuffer( "<?xml version="1.0"?>..." );
       Object o = u.unmarshal( new StreamSource( new StringReader( xmlStr.toString() ) ) );
    

org.w3c.dom.Node から非整列化します。

       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
       Unmarshaller u = jc.createUnmarshaller();
 
       DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
       dbf.setNamespaceAware(true);
       DocumentBuilder db = dbf.newDocumentBuilder();
       Document doc = db.parse(new File( "nosferatu.xml"));

       Object o = u.unmarshal( doc );
    

クライアントが指定した検証 SAX2.0 パーサーを使用して javax.xml.transform.sax.SAXSource から非整列化します。

       // configure a validating SAX2.0 parser (Xerces2)
       static final String JAXP_SCHEMA_LANGUAGE =
           "http://java.sun.com/xml/jaxp/properties/schemaLanguage";
       static final String JAXP_SCHEMA_LOCATION =
           "http://java.sun.com/xml/jaxp/properties/schemaSource";
       static final String W3C_XML_SCHEMA =
           "http://www.w3.org/2001/XMLSchema";

       System.setProperty( "javax.xml.parsers.SAXParserFactory",
                           "org.apache.xerces.jaxp.SAXParserFactoryImpl" );

       SAXParserFactory spf = SAXParserFactory.newInstance();
       spf.setNamespaceAware(true);
       spf.setValidating(true);
       SAXParser saxParser = spf.newSAXParser();
       
       try {
           saxParser.setProperty(JAXP_SCHEMA_LANGUAGE, W3C_XML_SCHEMA);
           saxParser.setProperty(JAXP_SCHEMA_LOCATION, "http://....");
       } catch (SAXNotRecognizedException x) {
           // exception handling omitted
       }

       XMLReader xmlReader = saxParser.getXMLReader();
       SAXSource source = 
           new SAXSource( xmlReader, new InputSource( "http://..." ) );

       // Setup JAXB to unmarshal
       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
       Unmarshaller u = jc.createUnmarshaller();
       ValidationEventCollector vec = new ValidationEventCollector();
       u.setEventHandler( vec );
       
       // turn off the JAXB provider's default validation mechanism to 
       // avoid duplicate validation
       u.setValidating( false )

       // unmarshal
       Object o = u.unmarshal( source );

       // check for events
       if( vec.hasEvents() ) {
          // iterate over events
       }
    

StAX XMLStreamReader から非整列化します。

       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
       Unmarshaller u = jc.createUnmarshaller();
 
       javax.xml.stream.XMLStreamReader xmlStreamReader = 
           javax.xml.stream.XMLInputFactory().newInstance().createXMLStreamReader( ... );
 
       Object o = u.unmarshal( xmlStreamReader );
    

StAX XMLEventReader から非整列化します。

       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
       Unmarshaller u = jc.createUnmarshaller();
 
       javax.xml.stream.XMLEventReader xmlEventReader = 
           javax.xml.stream.XMLInputFactory().newInstance().createXMLEventReader( ... );
 
       Object o = u.unmarshal( xmlEventReader );
    

XML データの非整列化

非整列化では、XML 文書全体または XML 文書のサブツリーを表す XML データを直列化復元できます。通常は、「グローバルに宣言されたルート要素の非整列化」で説明されている非整列化メソッドを使用すれば十分です。これらの非整列化メソッドは、グローバル XML 要素宣言および型宣言から JAXB マップクラスへの JAXBContext のマッピングを利用して、XML データのルート要素の非整列化処理を初期化します。JAXBContext のマッピングが XML データのルート要素を非整列化するのに不十分である場合、アプリケーションは declaredType による非整列化メソッドを使用して非整列化プロセスを支援することができます。これらのメソッドは、ルート要素がスキーマのローカル要素宣言に対応する XML データを非整列化するときに役立ちます。
非整列化メソッドは null を返しません。非整列化プロセスが XML コンテンツのルートを JAXB マップオブジェクトのルートに非整列化できない場合、JAXBException をスローすることによって致命的なエラーが報告され、処理が中止されます。

グローバルに宣言されたルート要素の非整列化

declaredType パラメータを含まない非整列化メソッドは、JAXBContext を使用して XML データのルート要素を非整列化します。JAXBContext インスタンスは、この Unmarshaller の作成に使用されたインスタンスです。JAXBContext インスタンスは、グローバルに宣言された XML 要素および型定義名から JAXB マップクラスへのマッピングを保持しています。非整列化メソッドは、ルート要素の XML 名または @xsi:type、あるいはその両方から JAXB マップクラスへのマッピングが JAXBContext に含まれるかどうかをチェックします。これを含む場合、適切な JAXB マップクラスを使用して XML データを非整列化します。ルート要素名が不明で、ルート要素に @xsi:type が含まれる場合、JAXBElement の値として JAXB マップクラスを使用して XML データは非整列化されます。JAXBContext オブジェクトに、ルート要素の名前またはその @xsi:type (これが存在する場合) に対するマッピングが含まれない場合、非整列化操作は UnmarshalException をスローすることによって直ちに強制終了されます。次のサブセクションで説明する declaredType による非整列化を使用することによって、この例外シナリオを回避することができます。

宣言型による非整列化

declaredType パラメータを使用した非整列化メソッドにより、JAXBContext にルート要素の XML 名のマッピングが含まれないときでも、XML データのルート要素を直列化復元することができます。unmarshaller は、アプリケーションが提供したマッピングを使用してルート要素を非整列化します。このマッピングは declaredType パラメータとして指定されます。これらの非整列化メソッドを使用する場合、ルート要素の要素名が JAXBContext でマップされている場合であっても、ルート要素を直列化復元するためのマッピングを declaredType パラメータがオーバーライドします。また、XML データのルート要素に xsi:type 属性があり、その属性の値が JAXBContext によって JAXB マップクラスにマップされている型定義を参照している場合は、ルート要素の xsi:type 属性が非整列化メソッドの declaredType パラメータよりも優先されます。これらのメソッドは通常、JAXBElement<declaredType> インスタンスを返します。次のテーブルは、戻り値の JAXBElement インスタンスのプロパティーがどのように設定されているかを示します。

宣言型による非整列化が返した JAXBElement
JAXBElement プロパティー
name XML 要素名
value declaredType のインスタンス
declaredType 非整列化メソッドの declaredType パラメータ
scope null (実際のスコープが不明)

declaredType による非整列化メソッドの例を次に示します。

org.w3c.dom.Node からの declaredType による非整列化を実行します。

       スキーマフラグメント例
       <xs:schema>
          <xs:complexType name="FooType">...<\xs:complexType>
          <!-- global element declaration "PurchaseOrder" -->
          <xs:element name="PurchaseOrder">
              <xs:complexType>
                 <xs:sequence>
                    <!-- local element declaration "foo" -->
                    <xs:element name="foo" type="FooType"/>
                    ...
                 </xs:sequence>
              </xs:complexType>
          </xs:element>
       </xs:schema>

       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
       Unmarshaller u = jc.createUnmarshaller();
 
       DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
       dbf.setNamespaceAware(true);
       DocumentBuilder db = dbf.newDocumentBuilder();
       Document doc = db.parse(new File( "nosferatu.xml"));
       Element  fooSubtree = ...; // traverse DOM till reach xml element foo, constrained by a 
                                  // local element declaration in schema.
 
       // FooType is the JAXB mapping of the type of local element declaration foo.
       JAXBElement<FooType> foo = u.unmarshal( fooSubtree, FooType.class);
    

SAX2.0 準拠パーサーのサポート

クライアントアプリケーションは、それぞれが選んだ SAX2.0 準拠パーサーを選択することができます。SAX パーサーが選択されない場合、JAXB プロバイダのデフォルトパーサーが使用されます。JAXB プロバイダのデフォルトパーサーが SAX2.0 準拠である必要はないものの、すべてのプロバイダはクライアントアプリケーションが SAX2.0 パーサーを指定できるようにする必要があります。プロバイダによっては、スキーマコンパイル時に SAX2.0 パーサーを指定することをクライアントアプリケーションに要求する場合もあります。詳細は、unmarshal(Source) を参照してください。

検証と整形式

クライアントアプリケーションは、setSchema(javax.xml.validation.Schema) API を介して JAXP 1.3 検証機構を有効または無効にできます。高度なクライアントは、unmarshal(Source) API を使用して、それ自身の検証 SAX 2.0 準拠パーサーを指定し、JAXP 1.3 検証機構を回避できます。

無効な XML コンテンツの非整列化は JAXB 2.0 で定義されているため、Unmarshaller のデフォルト検証イベントハンドラは JAXB 1.0 よりもより寛大に処理されます。JAXB 1.0 バインディングコンパイラによって生成されたスキーマ派生コードが JAXBContext に登録されている場合、デフォルト非整列化検証ハンドラは DefaultValidationEventHandler であり、致命的なエラーまたはエラーの発生後に整列化操作を終了させます。JAXB 2.0 クライアントアプリケーションの場合、明示的に定義されたデフォルト検証ハンドラがなく、デフォルトイベント処理は致命的なエラーの発生後に整列化操作を終了させるのみです。

サポートされているプロパティー

現在、Unmarshaller に関してすべての JAXB プロバイダがサポートする必要があるプロパティーはありません。しかし、一部のプロバイダは、プロバイダ固有のプロパティーの固有のセットをサポートする場合があります。

非整列化イベントコールバック

Unmarshaller は、2 つのスタイルのコールバック機構を提供します。これらにより、非整列化プロセスの重要な時点でのアプリケーション固有の処理が可能になります。「クラス定義された」イベントコールバックでは、JAXB マップクラスに置かれたアプリケーション固有のコードが非整列化中にトリガーされます。「外部リスナー」は、型のイベントコールバックを介するのではなく、一度のコールバックメソッドでの非整列化イベントの集中処理を可能にします。

「クラス定義された」イベントコールバックメソッドにより、任意の JAXB マップクラスは次のメソッドシグニチャーを持つメソッドを定義することによって、固有のコールバックメソッドを指定できます。

   // This method is called immediately after the object is created and before the unmarshalling of this 
   // object begins.The callback provides an opportunity to initialize JavaBean properties prior to unmarshalling.
   void beforeUnmarshal(Unmarshaller, Object parent);
 
   //This method is called after all the properties (except IDREF) are unmarshalled for this object, 
   //but before this object is set to the parent object.
   void afterUnmarshal(Unmarshaller, Object parent);
 
コールバックメソッドがクラスの public 以外のメソッドまたはフィールドへのアクセスを必要とする場合は、クラス定義コールバックメソッドを使用する必要があります。

外部リスナーコールバック機構では、setListener(Listener)Unmarshaller.Listener インスタンスを登録することができます。外部リスナーはすべてのコールバックイベントを受け取るため、クラスごとに定義されるコールバックメソッドよりも、より集中的な処理が可能になります。非整列化プロセスが JAXB 要素または JAXB マップクラスに整列化しようとした場合、外部リスナーはイベントを受け取ります。

「クラス定義された」イベントコールバックメソッドと外部リスナーイベントコールバックメソッドはそれぞれ独立しており、1 つのイベントに対し両方を呼び出すことができます。両方のリスナーコールバックメソッドが存在する場合の呼び出し順序は、Unmarshaller.Listener.beforeUnmarshal(Object, Object) および Unmarshaller.Listener.afterUnmarshal(Object, Object) で定義されます。

例外をスローしたイベントコールバックメソッドは、現在の整列化プロセスを終了させます。

導入されたバージョン:
JAXB1.0
関連項目:
JAXBContext, Marshaller, Validator

入れ子のクラスの概要
static class Unmarshaller.Listener
          

Unmarshaller にこのクラスの実装のインスタンスを登録し、非整列化イベントを外部的に待機します。

 
メソッドの概要
<A extends XmlAdapter>
A
getAdapter(Class<A> type)
          指定した型に関連付けられているアダプタを取得します。
 AttachmentUnmarshaller getAttachmentUnmarshaller()
           
 ValidationEventHandler getEventHandler()
          現在のイベントハンドラ、または、それが設定されていない場合はデフォルトイベントハンドラを返します。
 Unmarshaller.Listener getListener()
          この Unmarshaller に登録されている Unmarshaller.Listener を返します。
 Object getProperty(String name)
          Unmarshaller の基本となる実装の特定のプロパティーを取得します。
 Schema getSchema()
          非整列化時の検証に使用されている JAXP 1.3 Schema オブジェクトを取得します。
 UnmarshallerHandler getUnmarshallerHandler()
          XML パイプラインのコンポーネントとして使用できる、unmarshaller ハンドラオブジェクトを取得します。
 boolean isValidating()
          推奨されていません。 since JAXB2.0、getSchema() を参照
<A extends XmlAdapter>
void
setAdapter(Class<A> type, A adapter)
          XmlAdapter の設定済みのインスタンスをこの Unmarshaller に関連付けます。
 void setAdapter(XmlAdapter adapter)
          XmlAdapter の設定済みのインスタンスをこの Unmarshaller に関連付けます。
 void setAttachmentUnmarshaller(AttachmentUnmarshaller au)
          cid、コンテンツ ID URI を、添付として渡されたバイナリデータに解決するコンテキストを関連付けます。
 void setEventHandler(ValidationEventHandler handler)
          アプリケーションが ValidationEventHandler を登録することができます。
 void setListener(Unmarshaller.Listener listener)
           この Unmarshaller に非整列化イベントコールバック Unmarshaller.Listener を登録します。
 void setProperty(String name, Object value)
          Unmarshaller の基本となる実装に特定のプロパティーを設定します。
 void setSchema(Schema schema)
          後の非整列化操作の検証に使用する、JAXP 1.3 Schema オブジェクトを指定します。
 void setValidating(boolean validating)
          推奨されていません。 since JAXB2.0、setSchema(javax.xml.validation.Schema) を参照
 Object unmarshal(File f)
          指定されたファイルから XML データを非整列化し、結果のコンテンツツリーを返します。
 Object unmarshal(InputSource source)
          指定された SAX InputSource から XML データを非整列化し、結果のコンテンツツリーを返します。
 Object unmarshal(InputStream is)
          指定された InputStream から XML データを非整列化し、結果のコンテンツツリーを返します。
 Object unmarshal(Node node)
          指定された DOM ツリー からグローバル XML データを非整列化し、結果のコンテンツツリーを返します。
<T> JAXBElement<T>
unmarshal(Node node, Class<T> declaredType)
          JAXB マップ declaredType によって XML データを非整列化し、結果のコンテンツツリーを返します。
 Object unmarshal(Reader reader)
          指定された Reader から XML データを非整列化し、結果のコンテンツツリーを返します。
 Object unmarshal(Source source)
          指定された XML Source から XML データを非整列化し、結果のコンテンツツリーを返します。
<T> JAXBElement<T>
unmarshal(Source source, Class<T> declaredType)
          declaredType に基づき、指定された XML Source から XML データを非整列化し、結果のコンテンツツリーを返します。
 Object unmarshal(URL url)
          指定された URL から XML データを非整列化し、結果のコンテンツツリーを返します。
 Object unmarshal(XMLEventReader reader)
          指定されたプルパーサーから XML データを非整列化し、結果のコンテンツツリーを返します。
<T> JAXBElement<T>
unmarshal(XMLEventReader reader, Class<T> declaredType)
          JAXB マップ declaredType にルート要素を非整列化し、結果のコンテンツツリーを返します。
 Object unmarshal(XMLStreamReader reader)
          指定されたプルパーサーから XML データを非整列化し、結果のコンテンツツリーを返します。
<T> JAXBElement<T>
unmarshal(XMLStreamReader reader, Class<T> declaredType)
          JAXB マップ declaredType にルート要素を非整列化し、結果のコンテンツツリーを返します。
 

メソッドの詳細

unmarshal

Object unmarshal(File f)
                 throws JAXBException
指定されたファイルから XML データを非整列化し、結果のコンテンツツリーを返します。

グローバルルート要素の非整列化を実装します。

パラメータ:
f - 非整列化する XML データが含まれるファイル
戻り値:
新しく作成される Java コンテンツツリーのルートオブジェクト
例外:
JAXBException - 非整列化の実行中に予想外のエラーが発生した場合
UnmarshalException - ValidationEventHandlerhandleEvent メソッドから false が返されるか、または Unmarshaller が XML から Java へのバインディングを実行 できない場合。「XML データの非整列化」を参照
IllegalArgumentException - file パラメータが null の場合

unmarshal

Object unmarshal(InputStream is)
                 throws JAXBException
指定された InputStream から XML データを非整列化し、結果のコンテンツツリーを返します。この形式の非整列化 API を使用した場合、検証イベントの位置情報が不完全な場合があります。

グローバルルート要素の非整列化を実装します。

パラメータ:
is - 非整列化する XML データが含まれる InputStream
戻り値:
新しく作成される Java コンテンツツリーのルートオブジェクト
例外:
JAXBException - 非整列化の実行中に予想外のエラーが発生した場合
UnmarshalException - ValidationEventHandlerhandleEvent メソッドから false が返されるか、または Unmarshaller が XML から Java へのバインディングを実行 できない場合。「XML データの非整列化」を参照
IllegalArgumentException - InputStream パラメータが null の場合

unmarshal

Object unmarshal(Reader reader)
                 throws JAXBException
指定された Reader から XML データを非整列化し、結果のコンテンツツリーを返します。この形式の非整列化 API を使用した場合、Reader はシステム ID を提供しないため、検証イベントの位置情報が不完全な場合があります。

グローバルルート要素の非整列化を実装します。

パラメータ:
reader - 非整列化する XML データが含まれる Reader
戻り値:
新しく作成される Java コンテンツツリーのルートオブジェクト
例外:
JAXBException - 非整列化の実行中に予想外のエラーが発生した場合
UnmarshalException - ValidationEventHandlerhandleEvent メソッドから false が返されるか、または Unmarshaller が XML から Java へのバインディングを実行 できない場合。「XML データの非整列化」を参照
IllegalArgumentException - InputStream パラメータが null の場合
導入されたバージョン:
JAXB2.0

unmarshal

Object unmarshal(URL url)
                 throws JAXBException
指定された URL から XML データを非整列化し、結果のコンテンツツリーを返します。

グローバルルート要素の非整列化を実装します。

パラメータ:
url - 非整列化する XML データが含まれる URL
戻り値:
新しく作成される Java コンテンツツリーのルートオブジェクト
例外:
JAXBException - 非整列化の実行中に予想外のエラーが発生した場合
UnmarshalException - ValidationEventHandlerhandleEvent メソッドから false が返されるか、または Unmarshaller が XML から Java へのバインディングを実行 できない場合。「XML データの非整列化」を参照
IllegalArgumentException - URL パラメータが null の場合

unmarshal

Object unmarshal(InputSource source)
                 throws JAXBException
指定された SAX InputSource から XML データを非整列化し、結果のコンテンツツリーを返します。

グローバルルート要素の非整列化を実装します。

パラメータ:
source - 非整列化する XML データが含まれる入力ソース
戻り値:
新しく作成される Java コンテンツツリーのルートオブジェクト
例外:
JAXBException - 非整列化の実行中に予想外のエラーが発生した場合
UnmarshalException - ValidationEventHandlerhandleEvent メソッドから false が返されるか、または Unmarshaller が XML から Java へのバインディングを実行 できない場合。「XML データの非整列化」を参照
IllegalArgumentException - InputSource パラメータが null の場合

unmarshal

Object unmarshal(Node node)
                 throws JAXBException
指定された DOM ツリー からグローバル XML データを非整列化し、結果のコンテンツツリーを返します。

グローバルルート要素の非整列化を実装します。

パラメータ:
node - 非整列化する XML データが含まれる文書または要素。 呼び出し側は最低限、文書と要素をサポートする必要がある
戻り値:
新しく作成される Java コンテンツツリーのルートオブジェクト
例外:
JAXBException - 非整列化の実行中に予想外のエラーが発生した場合
UnmarshalException - ValidationEventHandlerhandleEvent メソッドから false が返されるか、または Unmarshaller が XML から Java へのバインディングを実行 できない場合。「XML データの非整列化」を参照
IllegalArgumentException - Node パラメータが null の場合
関連項目:
unmarshal(org.w3c.dom.Node, Class)

unmarshal

<T> JAXBElement<T> unmarshal(Node node,
                             Class<T> declaredType)
                         throws JAXBException
JAXB マップ declaredType によって XML データを非整列化し、結果のコンテンツツリーを返します。

宣言型による非整列化」を実装します。

パラメータ:
node - 非整列化する XML データが含まれる文書または要素。 呼び出し側は最低限、文書と要素をサポートする必要がある
declaredType - node の XML データを保持する、適切な JAXB マップクラス
戻り値:
nodeJAXB 要素表現
例外:
JAXBException - 非整列化の実行中に予想外のエラーが発生した場合
UnmarshalException - ValidationEventHandlerhandleEvent メソッドから false が返されるか、または Unmarshaller が XML から Java へのバインディングを実行 できない場合。「XML データの非整列化」を参照
IllegalArgumentException - 任意のパラメータが nullの場合
導入されたバージョン:
JAXB2.0

unmarshal

Object unmarshal(Source source)
                 throws JAXBException
指定された XML Source から XML データを非整列化し、結果のコンテンツツリーを返します。

グローバルルート要素の非整列化を実装します。

プラグイン可能な SAX 2.0 パーサー

クライアントアプリケーションは、その JAXB プロバイダで提供されているデフォルトパーサー機構を使用しないことを選択できます。任意の SAX 2.0 準拠パーサーを、JAXB プロバイダのデフォルト機構に置換することができます。これを行うため、クライアントアプリケーションは、SAX 2.0 パーサープロバイダが実装している XMLReader を含む SAXSource を適切に設定する必要があります。XMLReaderorg.xml.sax.ErrorHandler が登録されている場合、それが JAXB プロバイダによって置き換えられ、検証エラーは JAXB の ValidationEventHandler 機構を介して報告される可能性があります。SAXSourceXMLReader が含まれない場合、JAXB プロバイダのデフォルトパーサー機構が使用されます。

このパーサー置換機構は、JAXB プロバイダの非整列化時の検証エンジンの置換にも使用できます。クライアントアプリケーションは、(前述の例に示したように) その SAX 2.0 準拠パーサーが検証を実行するように適切に設定する必要があります。非整列化操作中にパーサーが SAXParserExceptions に遭遇すると、JAXB プロバイダがそれを処理し、JAXB ValidationEvent オブジェクトに変換されます。このオブジェクトは、Unmarshaller に登録されている ValidationEventHandler を介してクライアントに報告されます。注: 非整列化に代替の検証 SAX 2.0 パーサーを指定した場合でも、オンデマンドの検証を実行するために JAXB プロバイダが使用する検証エンジンは必ずしも置き換えられません。

非整列化中に使用される別のパーサー機構をクライアントアプリケーションが指定できる唯一の方法は、unmarshal(SAXSource) API を介する方法です。非整列化メソッドの他のすべての形式 (File、URL、Node など) は、JAXB プロバイダのデフォルトのパーサーとバリデータ機構を使用します。

パラメータ:
source - 非整列化する XML データが含まれる XML Source (プロバイダは、 SAXSource、DOMSource、StreamSource をサポートする必要があるのみ)
戻り値:
新しく作成される Java コンテンツツリーのルートオブジェクト
例外:
JAXBException - 非整列化の実行中に予想外のエラーが発生した場合
UnmarshalException - ValidationEventHandlerhandleEvent メソッドから false が返されるか、または Unmarshaller が XML から Java へのバインディングを実行 できない場合。「XML データの非整列化」を参照
IllegalArgumentException - Source パラメータが null の場合
関連項目:
unmarshal(javax.xml.transform.Source, Class)

unmarshal

<T> JAXBElement<T> unmarshal(Source source,
                             Class<T> declaredType)
                         throws JAXBException
declaredType に基づき、指定された XML Source から XML データを非整列化し、結果のコンテンツツリーを返します。

宣言型による非整列化」を実装します。

プラグイン可能な SAX 2.0 パーサー」を参照してください。

パラメータ:
source - 非整列化する XML データが含まれる XML Source (プロバイダは、 SAXSource、DOMSource、StreamSource をサポートする必要があるのみ)
declaredType - source の XML ルート要素を保持する、適切な JAXB マップクラス
戻り値:
JAXB 要素をルートとする Java コンテンツ
例外:
JAXBException - 非整列化の実行中に予想外のエラーが発生した場合
UnmarshalException - ValidationEventHandlerhandleEvent メソッドから false が返されるか、または Unmarshaller が XML から Java へのバインディングを実行 できない場合。「XML データの非整列化」を参照
IllegalArgumentException - 任意のパラメータが nullの場合
導入されたバージョン:
JAXB2.0

unmarshal

Object unmarshal(XMLStreamReader reader)
                 throws JAXBException
指定されたプルパーサーから XML データを非整列化し、結果のコンテンツツリーを返します。

グローバルルート要素の非整列化を実装します。

このメソッドは、パーサーでの START_DOCUMENT または START_ELEMENT イベントの発生を前提としています。非整列化は、この start イベントから、対応する end イベントまでの間に実行されます。このメソッドが正常な結果を返す場合、reader は、end イベントの直後のトークンをポイントします。

パラメータ:
reader - 読み込まれるパーサー
戻り値:
新しく作成される Java コンテンツツリーのルートオブジェクト
例外:
JAXBException - 非整列化の実行中に予想外のエラーが発生した場合
UnmarshalException - ValidationEventHandlerhandleEvent メソッドから false が返されるか、または Unmarshaller が XML から Java へのバインディングを実行 できない場合。「XML データの非整列化」を参照
IllegalArgumentException - reader パラメータが null の場合
IllegalStateException - reader が START_DOCUMENT または START_ELEMENT イベントをポイントしていない場合
導入されたバージョン:
JAXB2.0
関連項目:
unmarshal(javax.xml.stream.XMLStreamReader, Class)

unmarshal

<T> JAXBElement<T> unmarshal(XMLStreamReader reader,
                             Class<T> declaredType)
                         throws JAXBException
JAXB マップ declaredType にルート要素を非整列化し、結果のコンテンツツリーを返します。

このメソッドは、宣言型による非整列化を実装します。

このメソッドは、パーサーでの START_DOCUMENT または START_ELEMENT イベントの発生を前提としています。非整列化は、この start イベントから、対応する end イベントまでの間に実行されます。このメソッドが正常な結果を返す場合、reader は、end イベントの直後のトークンをポイントします。

パラメータ:
reader - 読み込まれるパーサー
declaredType - reader の START_ELEMENT XML データを保持する、適切な JAXB マップクラス
戻り値:
JAXB 要素表現をルートとするコンテンツツリー
例外:
JAXBException - 非整列化の実行中に予想外のエラーが発生した場合
UnmarshalException - ValidationEventHandlerhandleEvent メソッドから false が返されるか、または Unmarshaller が XML から Java へのバインディングを実行 できない場合。「XML データの非整列化」を参照
IllegalArgumentException - 任意のパラメータが nullの場合
導入されたバージョン:
JAXB2.0

unmarshal

Object unmarshal(XMLEventReader reader)
                 throws JAXBException
指定されたプルパーサーから XML データを非整列化し、結果のコンテンツツリーを返します。

このメソッドは、グローバルルートの非整列化メソッドです。

このメソッドは、パーサーでの START_DOCUMENT または START_ELEMENT イベントの発生を前提としています。非整列化は、この start イベントから、対応する end イベントまでの間に実行されます。このメソッドが正常な結果を返す場合、reader は、end イベントの直後のトークンをポイントします。

パラメータ:
reader - 読み込まれるパーサー
戻り値:
新しく作成される Java コンテンツツリーのルートオブジェクト
例外:
JAXBException - 非整列化の実行中に予想外のエラーが発生した場合
UnmarshalException - ValidationEventHandlerhandleEvent メソッドから false が返されるか、または Unmarshaller が XML から Java へのバインディングを実行 できない場合。「XML データの非整列化」を参照
IllegalArgumentException - reader パラメータが null の場合
IllegalStateException - reader が START_DOCUMENT または START_ELEMENT イベントをポイントしていない場合
導入されたバージョン:
JAXB2.0
関連項目:
unmarshal(javax.xml.stream.XMLEventReader, Class)

unmarshal

<T> JAXBElement<T> unmarshal(XMLEventReader reader,
                             Class<T> declaredType)
                         throws JAXBException
JAXB マップ declaredType にルート要素を非整列化し、結果のコンテンツツリーを返します。

このメソッドは、宣言型による非整列化を実装します。

このメソッドは、パーサーでの START_DOCUMENT または START_ELEMENT イベントの発生を前提としています。非整列化は、この start イベントから、対応する end イベントまでの間に実行されます。このメソッドが正常な結果を返す場合、reader は、end イベントの直後のトークンをポイントします。

パラメータ:
reader - 読み込まれるパーサー
declaredType - reader の START_ELEMENT XML データを保持する、適切な JAXB マップクラス
戻り値:
JAXB 要素表現をルートとするコンテンツツリー
例外:
JAXBException - 非整列化の実行中に予想外のエラーが発生した場合
UnmarshalException - ValidationEventHandlerhandleEvent メソッドから false が返されるか、または Unmarshaller が XML から Java へのバインディングを実行 できない場合。「XML データの非整列化」を参照
IllegalArgumentException - 任意のパラメータが nullの場合
導入されたバージョン:
JAXB2.0

getUnmarshallerHandler

UnmarshallerHandler getUnmarshallerHandler()
XML パイプラインのコンポーネントとして使用できる、unmarshaller ハンドラオブジェクトを取得します。

このメソッドを複数回呼び出した場合、同じハンドラオブジェクトが返される可能性があります。つまり、このメソッドは必ずしも新しい UnmarshallerHandler インスタンスを作成しません。アプリケーションが複数の UnmarshallerHandler を使用する必要がある場合、複数の Unmarshaller を作成するようにしてください。

戻り値:
Unmarshaller ハンドラオブジェクト
関連項目:
UnmarshallerHandler

setValidating

void setValidating(boolean validating)
                   throws JAXBException
推奨されていません。 since JAXB2.0、setSchema(javax.xml.validation.Schema) を参照

非整列化操作中に Unmarshaller のデフォルト検証機構が検証を行うかどうかを指定します。デフォルトでは、Unmarshaller は検証を行いません。

このメソッドは、非整列化メソッドのいずれかを呼び出す前、または呼び出したあとにのみ、呼び出すことができます。

このメソッドは、JAXB プロバイダのデフォルト非整列化時検証機構を制御するのみです。クライアント独自の検証 SAX 2.0 準拠パーサーの指定には影響を与えません。各自の非整列化時検証機構を指定するクライアントがこの API を介して JAXB プロバイダのデフォルト検証機構をオフにし、「二重検証」を回避することがあります。

このメソッドは、JAXB 2.0 の時点で非推奨のメソッドです。新しい setSchema(javax.xml.validation.Schema) API を使用してください。

パラメータ:
validating - Unmarshaller が非整列化中に検証すべき場合、true。 それ以外の場合、false
例外:
JAXBException - 非整列化時の検証を有効または無効にしている途中で エラーが発生した場合
UnsupportedOperationException - JAXB 2.0 マップクラスを参照している JAXBContext から作成された Unmarshaller に対してこのメソッドが呼び出された場合、 スローされる可能性がある

isValidating

boolean isValidating()
                     throws JAXBException
推奨されていません。 since JAXB2.0、getSchema() を参照

非整列化操作中に検証するように Unmarshaller が設定されているかどうかを示します。

この API は、JAXB プロバイダのデフォルト非整列化時検証機構の状態を返します。

このメソッドは、JAXB 2.0 の時点で非推奨のメソッドです。新しい getSchema() API を使用してください。

戻り値:
Unmarshaller が非整列化操作中に検証を実行するように設定されている 場合、true。それ以外の場合、false
例外:
JAXBException - 検証フラグの取得中にエラーが発生した場合
UnsupportedOperationException - JAXB 2.0 マップクラスを参照している JAXBContext から作成された Unmarshaller に対してこのメソッドが呼び出された場合、 スローされる可能性がある

setEventHandler

void setEventHandler(ValidationEventHandler handler)
                     throws JAXBException
アプリケーションが ValidationEventHandler を登録することができます。

ValidationEventHandler は、いずれかの非整列化メソッドを呼び出している途中で検証エラーが発生した場合、JAXB プロバイダによって呼び出されます。非整列化メソッドを呼び出す前にクライアントアプリケーションが ValidationEventHandler を登録していない場合、ValidationEvents はデフォルトイベントハンドラによって処理されます。デフォルトイベントハンドラは、最初のエラーまたは致命的なエラーの発生後に非整列化操作を終了させます。

このメソッドを null パラメータとともに呼び出した場合、Unmarshaller はデフォルトイベントハンドラに戻ります。

パラメータ:
handler - 検証イベントハンドラ
例外:
JAXBException - イベントハンドラの設定中にエラーが発生した場合

getEventHandler

ValidationEventHandler getEventHandler()
                                       throws JAXBException
現在のイベントハンドラ、または、それが設定されていない場合はデフォルトイベントハンドラを返します。

戻り値:
現在の ValidationEventHandler、または、それが設定されていない場合、 デフォルトイベントハンドラ
例外:
JAXBException - 現在のイベントハンドラの取得中にエラーが発生した場合

setProperty

void setProperty(String name,
                 Object value)
                 throws PropertyException
Unmarshaller の基本となる実装に特定のプロパティーを設定します。このメソッドは、先に述べた定義済みの標準 JAXB プロパティーまたはプロバイダ固有のプロパティーの 1 つを設定する目的にのみ使用できます。未定義のプロパティーを設定しようとした場合、PropertyException がスローされます。「サポートされているプロパティー」を参照してください。

パラメータ:
name - 設定するプロパティーの名前。この値は、定数フィールドの 1 つか ユーザー指定文字列を使用して指定できる
value - 設定するプロパティーの値
例外:
PropertyException - 与えられたプロパティーまたは値の処理中にエラーが 発生した場合
IllegalArgumentException - name パラメータが null の場合

getProperty

Object getProperty(String name)
                   throws PropertyException
Unmarshaller の基本となる実装の特定のプロパティーを取得します。このメソッドは、先に述べた定義済みの標準 JAXB プロパティーまたはプロバイダ固有のプロパティーの 1 つを取得する目的にのみ使用できます。未定義のプロパティーを取得しようとした場合、PropertyException がスローされます。「サポートされているプロパティー」を参照してください。

パラメータ:
name - 取得するプロパティーの名前
戻り値:
要求されたプロパティーの値
例外:
PropertyException - 指定したプロパティー、またはプロパティー名値の取得中にエラーが発生 した場合
IllegalArgumentException - name パラメータが null の場合

setSchema

void setSchema(Schema schema)
後の非整列化操作の検証に使用する、JAXP 1.3 Schema オブジェクトを指定します。このメソッドに null を渡すと、検証は無効になります。

このメソッドは、推奨されなくなった setValidating(boolean) API に置き換わるものです。

このプロパティーは最初に null に設定されます。

パラメータ:
schema - 非整列化操作の検証に使用するスキーマオブジェクト。検証を無効にする場合は null
例外:
UnsupportedOperationException - JAXB 2.0 マップクラスを参照している JAXBContext から作成された Unmarshaller に対してこのメソッドが呼び出された場合、 スローされる可能性がある
導入されたバージョン:
JAXB2.0

getSchema

Schema getSchema()
非整列化時の検証に使用されている JAXP 1.3 Schema オブジェクトを取得します。Unmarshaller にスキーマが設定されていない場合、このメソッドは、非整列化時に検証を実行しないことを示す、null を返します。

このメソッドは、推奨されなくなった isValidating() API に置き換わるとともに、Schema オブジェクトへのアクセスを提供します。Unmarshaller が検証を有効にしているかどうかを判断するには、戻り値の型と null を照らし合わせてチェックすれば簡単にわかります。

boolean isValidating = u.getSchema()!=null;

戻り値:
非整列化時の検証を実行するために使用されるスキーマオブジェクト、 または、存在しない場合、null
例外:
UnsupportedOperationException - JAXB 2.0 マップクラスを参照している JAXBContext から作成された Unmarshaller に対してこのメソッドが呼び出された場合、 スローされる可能性がある
導入されたバージョン:
JAXB2.0

setAdapter

void setAdapter(XmlAdapter adapter)
XmlAdapter の設定済みのインスタンスをこの Unmarshaller に関連付けます。

これは、setAdapter(adapter.getClass(),adapter); を呼び出す簡易メソッドです。

例外:
IllegalArgumentException - adapter パラメータが null の場合
UnsupportedOperationException - JAXB 1.0 実装に対して呼び出された場合
導入されたバージョン:
JAXB2.0
関連項目:
setAdapter(Class,XmlAdapter)

setAdapter

<A extends XmlAdapter> void setAdapter(Class<A> type,
                                       A adapter)
XmlAdapter の設定済みのインスタンスをこの Unmarshaller に関連付けます。

すべての Unmarshaller は、内部的に Map<Class,XmlAdapter> を保持しており、フィールドまたはメソッドが XmlJavaTypeAdapter で注釈されたクラスを非整列化するために使用します。

このメソッドにより、アプリケーションは XmlAdapter の設定済みのインスタンスを使用することができます。アダプタのインスタンスが与えられない場合、Unmarshaller はそのデフォルトコンストラクタを呼び出してインスタンスを作成します。

パラメータ:
type - アダプタの型。XmlJavaTypeAdapter.value() がこの型を参照している場合、指定されたインスタンスが使用される
adapter - 使用するアダプタのインスタンス。null の場合、この型の現在のアダプタ セットの登録を取り消す
例外:
IllegalArgumentException - type パラメータが null の場合
UnsupportedOperationException - JAXB 1.0 実装に対して呼び出された場合
導入されたバージョン:
JAXB2.0

getAdapter

<A extends XmlAdapter> A getAdapter(Class<A> type)
指定した型に関連付けられているアダプタを取得します。 このメソッドは、setAdapter(javax.xml.bind.annotation.adapters.XmlAdapter) メソッドの逆の操作です。

例外:
IllegalArgumentException - type パラメータが null の場合
UnsupportedOperationException - JAXB 1.0 実装に対して呼び出された場合
導入されたバージョン:
JAXB2.0

setAttachmentUnmarshaller

void setAttachmentUnmarshaller(AttachmentUnmarshaller au)

cid、コンテンツ ID URI を、添付として渡されたバイナリデータに解決するコンテキストを関連付けます。

非整列化時の検証は、setSchema(Schema) を介して有効化され、Unmarshaller が XOP 処理を実行する場合でもサポートする必要があります。

例外:
IllegalStateException - 整列化操作中に、このメソッドを同時に 呼び出そうとした場合

getAttachmentUnmarshaller

AttachmentUnmarshaller getAttachmentUnmarshaller()

setListener

void setListener(Unmarshaller.Listener listener)

この Unmarshaller に非整列化イベントコールバック Unmarshaller.Listener を登録します。

各 Unmarshaller に Listener は 1 つだけです。Listener を設定すると、前に設定されていた Listener と置き換わります。Listener に null を設定することにより、現在の Listener の登録を解除できます。

パラメータ:
listener - この Unmarshaller に非整列化イベントコールバックを提供する
導入されたバージョン:
JAXB2.0

getListener

Unmarshaller.Listener getListener()

この Unmarshaller に登録されている Unmarshaller.Listener を返します。

戻り値:
登録されている Unmarshaller.Listener、または、この Unmarshaller に登録されている Listener がない場合、null
導入されたバージョン:
JAXB2.0

JavaTM Platform
Standard Ed. 6

バグの報告と機能のリクエスト
さらに詳しい API リファレンスおよび開発者ドキュメントについては、Java SE 開発者用ドキュメントを参照してください。開発者向けの詳細な解説、概念の概要、用語の定義、バグの回避策、およびコード実例が含まれています。

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