• Home
• org.igniterealtime.smack
• smack-xmlparser
• 4.4.6
• source code
• XmlPullParser.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

org.jivesoftware.smack.xml.XmlPullParser Maven / Gradle / Ivy

/**
 *
 * 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:
 * 
 * 

 *  
{@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}).
 *  
{@link #nextText()} instead of {@code XMLStreamReader.getElementText()}.
 * 
 * 

 * Differences from XPP3's XmlPullParser are:
 * 
 * 

 *  
Methods taking an attribute, like {@link #getAttributeName(int)} index return null instead of throwing an exception if no attribute with the given index exists.
 * 
 *
 * 
Developer Information
 * 

 * The following table shows the mapping of Smack's XmlPullParser events to StAX and XPP3 events:
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
XmlPullParser event mapping
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 or null 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.
     * 

     * 
Precondition: the current event is START_ELEMENT.
     * 
Postcondition: the current event is the corresponding END_ELEMENT.
     * 
     *
     * @return the textual content of the current element.
     * @throws IOException in case of an IO error.
     * @throws XmlPullParserException in case of an XML pull parser error.
     */
    String nextText() throws IOException, XmlPullParserException;

    TagEvent nextTag() throws IOException, XmlPullParserException;

    enum TagEvent {
        START_ELEMENT,
        END_ELEMENT,
    }

    enum Event {
        START_DOCUMENT,
        END_DOCUMENT,
        START_ELEMENT,
        END_ELEMENT,

        /**
         * Replaces TEXT from XPP3.
         */
        TEXT_CHARACTERS,
        PROCESSING_INSTRUCTION,
        COMMENT,
        IGNORABLE_WHITESPACE,
        ENTITY_REFERENCE,
        OTHER,
    }

    boolean supportsRoundtrip();
}