/** * * Copyright 2019-2021 Florian Schmaus. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.jivesoftware.smack.xml; import java.io.IOException; import javax.xml.namespace.QName; /** * 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. * *
* Differences from StAX's XMLStreamReader are: *
** Differences from XPP3's XmlPullParser are: *
*null
instead of throwing an exception if no attribute with the given index exists.* The following table shows the mapping of Smack's XmlPullParser events to StAX and XPP3 events: *
*Smack's {@link XmlPullParser.Event} | StAX Event | XPP3 Event |
---|---|---|
{@link XmlPullParser.Event#START_DOCUMENT} | START_DOCUMENT (7) | START_DOCUMENT (0) |
{@link XmlPullParser.Event#END_DOCUMENT} | END_DOCUMENT (8) | END_DOCUMENT (1) |
{@link XmlPullParser.Event#START_ELEMENT} | START_ELEMENT (1) | START_TAG (2) |
{@link XmlPullParser.Event#END_ELEMENT} | END_ELEMENT (2) | END_TAG (3) |
{@link XmlPullParser.Event#TEXT_CHARACTERS} | CHARACTERS (4) | TEXT (4) |
{@link XmlPullParser.Event#PROCESSING_INSTRUCTION} | PROCESSING_INSTRUCTION (3) | PROCESSING_INSTRUCTION (8) |
{@link XmlPullParser.Event#COMMENT} | COMMENT (5) | COMMENT (9) |
{@link XmlPullParser.Event#IGNORABLE_WHITESPACE} | SPACE (6) | IGNORABLE_WHITESPACE (7) |
{@link XmlPullParser.Event#ENTITY_REFERENCE} | ENTITY_REFERENCE (9) | ENTITY_REF (6) |
{@link XmlPullParser.Event#OTHER} | ENTITY_REFERENCE (9) | ENTITY_REF (6) |
{@link XmlPullParser.Event#OTHER} includes * in case of StAX: ATTRIBUTE (10), DTD (11), CDATA (12), NAMESPACE (13), NOTATION_DECLARATION (14) and ENTITY_DECLRATION (15), * in case of XPP3: CDSECT (5), DOCDECL (10). *
* */ public interface XmlPullParser { Object getProperty(String name); String getInputEncoding(); int getNamespaceCount() throws XmlPullParserException; String getNamespacePrefix(int pos) throws XmlPullParserException; String getNamespaceUri(int pos) throws XmlPullParserException; String getNamespace(String prefix); default String getDefaultNamespace() { return getNamespace(null); } int getDepth(); String getPositionDescription(); int getLineNumber(); int getColumnNumber(); boolean isWhiteSpace() throws XmlPullParserException; String getText(); String getNamespace(); /** * Return the name for the current START_ELEMENT or END_ELEMENT event. This method must only be called if the * current event is START_ELEMENT or END_ELEMENT. * * @return the name for the current START_ELEMETN or END_ELEMENT event. */ String getName(); QName getQName(); String getPrefix(); int getAttributeCount(); String getAttributeNamespace(int index); /** * Returns the loacalpart of the attribute's name ornull
in case the index does not refer to an
* attribute.
*
* @param index the attribute index.
* @return the localpart of the attribute's name or null
.
*/
String getAttributeName(int index);
QName getAttributeQName(int index);
String getAttributePrefix(int index);
String getAttributeType(int index);
String getAttributeValue(int index);
String getAttributeValue(String namespace, String name);
default String getAttributeValue(String name) {
return getAttributeValue(null, name);
}
Event getEventType() throws XmlPullParserException;
Event next() throws IOException, XmlPullParserException;
/**
* Reads the content of a text-only element, an exception is thrown if this is
* not a text-only element.
*