モジュール java.xml.bind
パッケージ 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データのルート要素を直列化復元できます。 アンマーシャラは、アプリケーションが提供したマッピングを使用してルート要素を非整列化します。このマッピングはdeclaredTypeパラメータとして指定されます。 これらの非整列化メソッドを使用する場合、ルート要素の要素名がJAXBContextでマップされている場合であっても、declaredTypeパラメータが、ルート要素を直列化復元するためのマッピングをオーバーライドします。 また、XMLデータのルート要素にxsi:type属性があり、その属性の値がJAXBContextによってJAXBマップ・クラスにマップされている型定義を参照している場合は、ルート要素のxsi:type属性が非整列化メソッドのdeclaredTypeパラメータよりも優先されます。 これらのメソッドは常にJAXBElement<declaredType>インスタンスを返します。 次の表は、戻り値のJAXBElementインスタンスのプロパティがどのように設定されているかを示します。
    宣言型による非整列化が返したJAXBElement
    JAXBElementプロパティ 値
    name xml element name
    value instanceof declaredType
    declaredType 非整列化メソッドのdeclaredTypeパラメータ
    scope null (実際のスコープが不明)

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

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

    
       Schema fragment for example
       <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)で定義されます。

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

    導入されたバージョン:
    1.6, JAXB 1.0
    関連項目:
    JAXBContext, Marshaller, Validator

    • メソッドの詳細

      • unmarshal

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

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

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

      • unmarshal

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

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

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

      • unmarshal

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

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

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

        クライアント・アプリケーションは、そのJAXBプロバイダで提供されているデフォルト・パーサー・メカニズムを使用しないことを選択できます。 任意のSAX 2.0準拠パーサーを、JAXBプロバイダのデフォルト・メカニズムに置換できます。 これを行うため、クライアント・アプリケーションは、SAX 2.0パーサー・プロバイダが実装しているXMLReaderを含むSAXSourceを適切に構成する必要があります。 XMLReaderにorg.xml.sax.ErrorHandlerが登録されている場合、それがJAXBプロバイダによって置き換えられ、検証エラーはJAXBのValidationEventHandlerメカニズムを介して報告される可能性があります。 SAXSourceにXMLReaderが含まれない場合、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 - ValidationEventHandlerのhandleEventメソッドから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 - ValidationEventHandlerのhandleEventメソッドからfalseが返されるか、UnmarshallerがXMLからJavaへのバインディングを実行できない場合。 XMLデータの非整列化を参照
        IllegalArgumentException - 任意のパラメータがnullの場合
        導入されたバージョン:
        1.6, JAXB 2.0

      • unmarshal

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

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

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

        パラメータ:
        reader - 読み込まれるパーサー。
        戻り値:
        新しく作成されるJavaコンテンツ・ツリーのルート・オブジェクト。
        例外:
        JAXBException - 非整列化の実行中に予想外のエラーが発生した場合
        UnmarshalException - ValidationEventHandlerのhandleEventメソッドからfalseが返されるか、UnmarshallerがXMLからJavaへのバインディングを実行できない場合。 XMLデータの非整列化を参照
        IllegalArgumentException - readerパラメータがnullの場合
        IllegalStateException - readerがSTART_DOCUMENTまたはSTART_ELEMENTイベントをポイントしていない場合。
        導入されたバージョン:
        1.6, JAXB 2.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 - ValidationEventHandlerのhandleEventメソッドからfalseが返されるか、UnmarshallerがXMLからJavaへのバインディングを実行できない場合。 XMLデータの非整列化を参照
        IllegalArgumentException - 任意のパラメータがnullの場合
        導入されたバージョン:
        1.6, JAXB 2.0

      • unmarshal

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

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

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

        パラメータ:
        reader - 読み込まれるパーサー。
        戻り値:
        新しく作成されるJavaコンテンツ・ツリーのルート・オブジェクト。
        例外:
        JAXBException - 非整列化の実行中に予想外のエラーが発生した場合
        UnmarshalException - ValidationEventHandlerのhandleEventメソッドからfalseが返されるか、UnmarshallerがXMLからJavaへのバインディングを実行できない場合。 XMLデータの非整列化を参照
        IllegalArgumentException - readerパラメータがnullの場合
        IllegalStateException - readerがSTART_DOCUMENTまたはSTART_ELEMENTイベントをポイントしていない場合。
        導入されたバージョン:
        1.6, JAXB 2.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 - ValidationEventHandlerのhandleEventメソッドからfalseが返されるか、UnmarshallerがXMLからJavaへのバインディングを実行できない場合。 XMLデータの非整列化を参照
        IllegalArgumentException - 任意のパラメータがnullの場合
        導入されたバージョン:
        1.6, JAXB 2.0

      • getUnmarshallerHandler

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

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

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

      • setValidating

        void setValidating​(boolean validating)
            throws JAXBException
        非推奨。
        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
        非推奨。
        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 1.0マップ・クラスを参照しているJAXBContextから作成されたUnmarshallerでこのメソッドが呼び出された場合にスローされる可能性がある
        導入されたバージョン:
        1.6, JAXB 2.0

      • getSchema

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

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

        
   boolean isValidating = u.getSchema()!=null;
        戻り値:
        非整列化時の検証を実行するために使用されるSchemaオブジェクト。存在しない場合はnull
        例外:
        UnsupportedOperationException - JAXB 1.0マップ・クラスを参照しているJAXBContextから作成されたUnmarshallerでこのメソッドが呼び出された場合にスローされる可能性がある
        導入されたバージョン:
        1.6, JAXB 2.0

      • setAdapter

        <A extends XmlAdapter> void setAdapter​(Class<A> type,
                                       A adapter)
        XmlAdapterの構成済みのインスタンスをこのアンマーシャラに関連付けます。

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

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

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

      • setAttachmentUnmarshaller

        void setAttachmentUnmarshaller​(AttachmentUnmarshaller au)

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

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

        例外:
        IllegalStateException - 非整列化処理中にこのメソッドを並行して呼び出そうとした場合。

      • setListener

        void setListener​(Unmarshaller.Listener listener)

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

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

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