-
- 既知のすべての実装クラス:
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要素宣言および型宣言から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);
外部リスナー・コールバック・メカニズムでは、
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
-
-
ネストされたクラスのサマリー
ネストされたクラス 修飾子と型 インタフェース 説明 static class
Unmarshaller.Listener
Unmarshaller
にこのクラスの実装のインスタンスを登録し、非整列化イベントを外部的に待機します。
-
メソッドのサマリー
すべてのメソッド インスタンス・メソッド 抽象メソッド 非推奨のメソッド 修飾子と型 メソッド 説明 <A extends XmlAdapter>
AgetAdapter(Class<A> type)
指定した型に関連付けられているアダプタを取得します。AttachmentUnmarshaller
getAttachmentUnmarshaller()
ValidationEventHandler
getEventHandler()
現在のイベント・ハンドラ、または、それが設定されていない場合はデフォルト・イベント・ハンドラを返します。Unmarshaller.Listener
getListener()
このUnmarshaller
に登録されたUnmarshaller.Listener
を返します。Object
getProperty(String name)
Unmarshaller
の基本となる実装の特定のプロパティを取得します。Schema
getSchema()
非整列化時の検証に使用されるJAXP 1.3Schema
オブジェクトを取得します。UnmarshallerHandler
getUnmarshallerHandler()
XMLパイプラインのコンポーネントとして使用できる、unmarshallerハンドラ・オブジェクトを取得します。boolean
isValidating()
非推奨。JAXB2.0以降は、次を参照してくださいgetSchema()
<A extends XmlAdapter>
voidsetAdapter(Class<A> type, A adapter)
XmlAdapter
の構成済みのインスタンスをこのアンマーシャラに関連付けます。void
setAdapter(XmlAdapter adapter)
XmlAdapter
の構成済みのインスタンスをこのアンマーシャラに関連付けます。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.3Schema
オブジェクトを指定します。void
setValidating(boolean validating)
非推奨。JAXB2.0以降は、次を参照してくださいsetSchema(javax.xml.validation.Schema)
Object
unmarshal(File f)
指定されたファイルからXMLデータを非整列化し、結果として得られるコンテンツ・ツリーを返します。Object
unmarshal(InputStream is)
指定されたInputStreamからXMLデータを非整列化し、結果として得られるコンテンツ・ツリーを返します。Object
unmarshal(Reader reader)
指定されたReaderから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
にルート要素を非整列化し、結果として得られるコンテンツ・ツリーを返します。Object
unmarshal(Source source)
指定されたXML SourceからXMLデータを非整列化し、結果として得られるコンテンツ・ツリーを返します。<T> JAXBElement<T>
unmarshal(Source source, Class<T> declaredType)
declaredType
に基づき、指定されたXML SourceからXMLデータを非整列化し、結果として得られるコンテンツ・ツリーを返します。Object
unmarshal(Node node)
指定されたDOMツリーからグローバルXMLデータを非整列化し、結果として得られるコンテンツ・ツリーを返します。<T> JAXBElement<T>
unmarshal(Node node, Class<T> declaredType)
JAXBマップdeclaredType
によってXMLデータを非整列化し、結果として得られるコンテンツ・ツリーを返します。Object
unmarshal(InputSource source)
指定されたSAX InputSourceからXMLデータを非整列化し、結果として得られるコンテンツ・ツリーを返します。
-
-
-
メソッドの詳細
-
unmarshal
Object unmarshal(File f) throws JAXBException
指定されたファイルからXMLデータを非整列化し、結果として得られるコンテンツ・ツリーを返します。グローバル・ルート要素の非整列化を実装します。
- パラメータ:
f
- 非整列化するXMLデータが含まれるファイル- 戻り値:
- 新しく作成されるJavaコンテンツ・ツリーのルート・オブジェクト
- 例外:
JAXBException
- 非整列化の実行中に予想外のエラーが発生した場合UnmarshalException
-ValidationEventHandler
のhandleEvent
メソッドからfalseが返されるか、Unmarshaller
がXMLからJavaへのバインディングを実行できない場合。 XMLデータの非整列化を参照IllegalArgumentException
- fileパラメータがnullの場合
-
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
Object unmarshal(URL url) throws JAXBException
指定されたURLからXMLデータを非整列化し、結果として得られるコンテンツ・ツリーを返します。グローバル・ルート要素の非整列化を実装します。
- パラメータ:
url
- 非整列化するXMLデータが含まれるURL- 戻り値:
- 新しく作成されるJavaコンテンツ・ツリーのルート・オブジェクト
- 例外:
JAXBException
- 非整列化の実行中に予想外のエラーが発生した場合UnmarshalException
-ValidationEventHandler
のhandleEvent
メソッドからfalseが返されるか、Unmarshaller
がXMLからJavaへのバインディングを実行できない場合。 XMLデータの非整列化を参照IllegalArgumentException
- URLパラメータがnullの場合
-
unmarshal
Object unmarshal(InputSource source) throws JAXBException
指定されたSAX InputSourceからXMLデータを非整列化し、結果として得られるコンテンツ・ツリーを返します。グローバル・ルート要素の非整列化を実装します。
- パラメータ:
source
- 非整列化するXMLデータが含まれる入力ソース- 戻り値:
- 新しく作成されるJavaコンテンツ・ツリーのルート・オブジェクト
- 例外:
JAXBException
- 非整列化の実行中に予想外のエラーが発生した場合UnmarshalException
-ValidationEventHandler
のhandleEvent
メソッドからfalseが返されるか、Unmarshaller
がXMLからJavaへのバインディングを実行できない場合。 XMLデータの非整列化を参照IllegalArgumentException
- InputSourceパラメータがnullの場合
-
unmarshal
Object unmarshal(Node node) throws JAXBException
指定されたDOMツリーからグローバルXMLデータを非整列化し、結果として得られるコンテンツ・ツリーを返します。グローバル・ルート要素の非整列化を実装します。
- パラメータ:
node
- 非整列化するXMLデータが含まれるドキュメントまたは要素。 呼出し側は最低限、文書と要素をサポートする必要がある。- 戻り値:
- 新しく作成されるJavaコンテンツ・ツリーのルート・オブジェクト
- 例外:
JAXBException
- 非整列化の実行中に予想外のエラーが発生した場合UnmarshalException
-ValidationEventHandler
のhandleEvent
メソッドから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マップ・クラス。- 戻り値:
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データを非整列化し、結果として得られるコンテンツ・ツリーを返します。グローバル・ルート要素の非整列化を実装します。
クライアント・アプリケーションは、その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プロバイダによって処理され、JAXBValidationEvent
オブジェクトに変換され、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.3Schema
オブジェクトを指定します。 このメソッドにnullを渡すと、検証は無効になります。このメソッドは、非推奨の
setValidating(boolean)
APIに置き換わるものです。このプロパティは最初に
null
に設定されます。- パラメータ:
schema
- 非整列化操作の検証に使用するスキーマ・オブジェクト。検証を無効にする場合はnull- 例外:
UnsupportedOperationException
- JAXB 1.0マップ・クラスを参照しているJAXBContextから作成されたUnmarshallerでこのメソッドが呼び出された場合にスローされる可能性がある- 導入されたバージョン:
- 1.6, JAXB 2.0
-
getSchema
Schema getSchema()
非整列化時の検証に使用されるJAXP 1.3Schema
オブジェクトを取得します。 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
void setAdapter(XmlAdapter adapter)
XmlAdapter
の構成済みのインスタンスをこのアンマーシャラに関連付けます。これは
setAdapter(adapter.getClass(),adapter);
を呼び出す簡易メソッドです。- 例外:
IllegalArgumentException
- adapterパラメータがnullの場合。UnsupportedOperationException
- JAXB 1.0実装に対して呼び出された場合。- 導入されたバージョン:
- 1.6, JAXB 2.0
- 関連項目:
setAdapter(Class,XmlAdapter)
-
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
-
getAdapter
<A extends XmlAdapter> A getAdapter(Class<A> type)
指定した型に関連付けられているアダプタを取得します。 これは、setAdapter(javax.xml.bind.annotation.adapters.XmlAdapter)
メソッドの逆の操作です。- 例外:
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
- 非整列化処理中にこのメソッドを並行して呼び出そうとした場合。
-
getAttachmentUnmarshaller
AttachmentUnmarshaller getAttachmentUnmarshaller()
-
setListener
void setListener(Unmarshaller.Listener listener)
この
Unmarshaller
に非整列化イベント・コールバックUnmarshaller.Listener
を登録します。各UnmarshallerにListenerは1つだけです。 Listenerを設定すると、前に設定されていたListenerと置き換わります。 Listenerに
null
を設定することにより、現在のListenerの登録を解除できます。- パラメータ:
listener
- このUnmarshaller
に非整列化イベント・コールバックを提供する- 導入されたバージョン:
- 1.6, JAXB 2.0
-
getListener
Unmarshaller.Listener getListener()
この
Unmarshaller
に登録されたUnmarshaller.Listener
を返します。- 戻り値:
- 登録されている
Unmarshaller.Listener
、またはこのUnmarshallerに登録されているListenerがない場合null
。 - 導入されたバージョン:
- 1.6, JAXB 2.0
-
-