今回は XMLStreamReader#require() メソッド。 このメソッドは、現在の XML イベントが要求したものと一致するかどうかをチェックし、一致すればそのまま、一致しなければ XMLStreamException を投げます。
引数
require() メソッドの定義は以下のようになっています:
void require(int type, String namespaceURI, String localName) throws XMLStreamException;
引数の簡単な説明は下表のようになります:
引数 | 引数の型 | 説明 | 備考 |
---|---|---|---|
type | int | 要求される XML イベントの型 (XMLStreamConstants のフィールド) | |
namespaceURI | String | 要求される名前空間 URI | null が渡された場合は名前空間 URI が等しいかどうかの検証は行われません。 |
localName | String | 要求されるローカル名 | null が渡された場合はローカル名が等しいかどうかの検証は行われません。 |
前回見たように、getLocalName() メソッドの返り値は「要素のローカル名」もしくは「実体参照名」ですが、この require() メソッドでローカル名として実体参照名の検証が行われるのかどうかは謎。 まぁ、どっちでもいいですけど。
使用例
サンプルをいくつか見ていきましょう。 Java コード中の変数 reader は XMLStreamReader のインスタンスとします。
★XML イベントの型のみを検証する★
XML 文書の断片
<?xml version="1.0" encoding="UTF-8"?>
Java コード:
reader.require(XMLStreamConstants.START_DOCUMENT, null, null);
★要素の開始と名前空間 URI を検証する★
XML 文書の断片
<p:element xmlns:p="ns">
Java コード:
reader.require(XMLStreamConstants.START_ELEMENT, "ns", null);
★要素の開始と QName を検証する★
XML 文書の断片
<element xmlns="ns"> <p:element xmlns:p="ns">
Java コード:
reader.require(XMLStreamConstants.START_ELEMENT, "ns", "element");
上記のどちらの要素に対しても、この検証は成功します。
★要素の開始と QName を検証する★
XML 文書の断片
&entity;
Java コード:
reader.require(XMLStreamConstants.ENTITY_REFERENCE, null, "entity");
これは成功するんでしょうか?
実装例
require() メソッドの実装例:
public void require(int type, String uri, String localName) throws XMLStreamException { if(type != getEventType()) throw new XMLStreamException(); if(uri != null && !uri.equals(getNamespaceURI())) throw new XMLStreamException(); if(localName != null && !localName.equals(getLocalName())) throw new XMLStreamException(); }
例外が発生した際のメッセージなどは、簡単のため省略しています。