001/** 002 * 003 * Copyright 2019 Florian Schmaus. 004 * 005 * Licensed under the Apache License, Version 2.0 (the "License"); 006 * you may not use this file except in compliance with the License. 007 * You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.jivesoftware.smack.xml; 018 019import java.io.IOException; 020 021import javax.xml.namespace.QName; 022 023/** 024 * Smack's interface for XML pull parsers. The main XML parser implementations are "Xml Pull Parser 3" (XPP3) on Android and "Streaming API for XML" (StAX, JSR 173) on Java. 025 * 026 * <p> 027 * Differences from StAX's XMLStreamReader are: 028 * </p> 029 * <ul> 030 * <li>{@link #getName()} and {@link #getAttributeName(int)} return localname, there is {@link #getQName()} and {@link #getAttributeQName(int)} to retrieve the qualified name ({@link javax.xml.namespace.QName QName}).</li> 031 * <li>{@link #nextText()} instead of {@code XMLStreamReader.getElementText()}. 032 * </ul> 033 * <p> 034 * Differences from XPP3's XmlPullParser are: 035 * </p> 036 * <ul> 037 * <li>Methods taking an attribute, like {@link #getAttributeName(int)} index return <code>null</code> instead of throwing an exception if no attribute with the given index exists.</li> 038 * </ul> 039 * 040 * <h2>Developer Information</h2> 041 * <p> 042 * The following table shows the mapping of Smack's XmlPullParser events to StAX and XPP3 events: 043 * </p> 044 * <table> 045 * <caption>XmlPullParser event mapping</caption> 046 * <tr><th>Smack's {@link XmlPullParser.Event}</th><th>StAX Event</th><th>XPP3 Event</th></tr> 047 * <tr><td>{@link XmlPullParser.Event#START_DOCUMENT}</td><td>START_DOCUMENT (7)</td><td>START_DOCUMENT (0)</td></tr> 048 * <tr><td>{@link XmlPullParser.Event#END_DOCUMENT}</td><td>END_DOCUMENT (8)</td><td>END_DOCUMENT (1)</td></tr> 049 * <tr><td>{@link XmlPullParser.Event#START_ELEMENT}</td><td>START_ELEMENT (1)</td><td>START_TAG (2)</td></tr> 050 * <tr><td>{@link XmlPullParser.Event#END_ELEMENT}</td><td>END_ELEMENT (2)</td><td>END_TAG (3)</td></tr> 051 * <tr><td>{@link XmlPullParser.Event#TEXT_CHARACTERS}</td><td>CHARACTERS (4)</td><td>TEXT (4)</td></tr> 052 * <tr><td>{@link XmlPullParser.Event#PROCESSING_INSTRUCTION}</td><td>PROCESSING_INSTRUCTION (3)</td><td>PROCESSING_INSTRUCTION (8)</td></tr> 053 * <tr><td>{@link XmlPullParser.Event#COMMENT}</td><td>COMMENT (5)</td><td>COMMENT (9)</td></tr> 054 * <tr><td>{@link XmlPullParser.Event#IGNORABLE_WHITESPACE}</td><td>SPACE (6)</td><td>IGNORABLE_WHITESPACE (7)</td></tr> 055 * <tr><td>{@link XmlPullParser.Event#ENTITY_REFERENCE}</td><td>ENTITY_REFERENCE (9)</td><td>ENTITY_REF (6)</td></tr> 056 * <tr><td>{@link XmlPullParser.Event#OTHER}</td><td>ENTITY_REFERENCE (9)</td><td>ENTITY_REF (6)</td></tr> 057 * </table> 058 * <p>{@link XmlPullParser.Event#OTHER} includes 059 * in case of StAX: ATTRIBUTE (10), DTD (11), CDATA (12), NAMESPACE (13), NOTATION_DECLARATION (14) and ENTITY_DECLRATION (15), 060 * in case of XPP3: CDSECT (5), DOCDECL (10). 061 * </p> 062 * 063 */ 064public interface XmlPullParser { 065 066 Object getProperty(String name); 067 068 String getInputEncoding(); 069 070 int getNamespaceCount() throws XmlPullParserException; 071 072 String getNamespacePrefix(int pos) throws XmlPullParserException; 073 074 String getNamespaceUri(int pos) throws XmlPullParserException; 075 076 String getNamespace(String prefix); 077 078 int getDepth(); 079 080 String getPositionDescription(); 081 082 int getLineNumber(); 083 084 int getColumnNumber(); 085 086 boolean isWhiteSpace() throws XmlPullParserException; 087 088 String getText(); 089 090 String getNamespace(); 091 092 /** 093 * Return the name for the current START_ELEMENT or END_ELEMENT event. This method must only be called if the 094 * current event is START_ELEMENT or END_ELEMENT. 095 * 096 * @return the name for the current START_ELEMETN or END_ELEMENT event. 097 */ 098 String getName(); 099 100 QName getQName(); 101 102 String getPrefix(); 103 104 int getAttributeCount(); 105 106 String getAttributeNamespace(int index); 107 108 /** 109 * Returns the loacalpart of the attribute's name or <code>null</code> in case the index does not refer to an 110 * attribute. 111 * 112 * @param index the attribute index. 113 * @return the localpart of the attribute's name or <code>null</code>. 114 */ 115 String getAttributeName(int index); 116 117 QName getAttributeQName(int index); 118 119 String getAttributePrefix(int index); 120 121 String getAttributeType(int index); 122 123 String getAttributeValue(int index); 124 125 String getAttributeValue(String namespace, String name); 126 127 default String getAttributeValue(String name) { 128 return getAttributeValue(null, name); 129 } 130 131 Event getEventType() throws XmlPullParserException; 132 133 Event next() throws IOException, XmlPullParserException; 134 135 /** 136 * Reads the content of a text-only element, an exception is thrown if this is 137 * not a text-only element. 138 * <ul> 139 * <li>Precondition: the current event is START_ELEMENT.</li> 140 * <li>Postcondition: the current event is the corresponding END_ELEMENT.</li> 141 * </ul> 142 * 143 * @return the textual content of the current element. 144 * @throws IOException in case of an IO error. 145 * @throws XmlPullParserException in case of an XML pull parser error. 146 */ 147 String nextText() throws IOException, XmlPullParserException; 148 149 TagEvent nextTag() throws IOException, XmlPullParserException; 150 151 enum TagEvent { 152 START_ELEMENT, 153 END_ELEMENT, 154 } 155 156 enum Event { 157 START_DOCUMENT, 158 END_DOCUMENT, 159 START_ELEMENT, 160 END_ELEMENT, 161 162 /** 163 * Replaces TEXT from XPP3. 164 */ 165 TEXT_CHARACTERS, 166 PROCESSING_INSTRUCTION, 167 COMMENT, 168 IGNORABLE_WHITESPACE, 169 ENTITY_REFERENCE, 170 OTHER, 171 } 172 173 boolean supportsRoundtrip(); 174}