XmlPullParser

CDSECT

int CDSECT

刚刚读过CDATA部分; 此令牌只能从调用nextToken() 。 对next（）的调用会将各种文本事件累加到TEXT类型的单个事件中。 包含在CDATA部分中的文本可以通过调用getText（）来获得。

常量值：5（0x00000005）

COMMENT

int COMMENT

刚刚阅读了XML评论。 此事件类型是此令牌仅可通过nextToken()获得 ; 对next（）的调用会自动跳过评论。 评论的内容可以使用getText（）方法访问。

常量值：9（0x00000009）

DOCDECL

int DOCDECL

刚刚阅读了XML文档类型声明。 该令牌仅适用于nextToken() 。 doctype中未解析的文本可以通过getText（）方法获得。

常量值：10（0x0000000a）

END_DOCUMENT

int END_DOCUMENT

xml文档的逻辑结尾。 当达到输入文档的末尾时，从getEventType，next（）和nextToken（）返回。

注：对 next()或 nextToken()的后续调用可能会导致抛出异常。

常数值：1（0x00000001）

END_TAG

int END_TAG

当读取结束标签时，从getEventType（）， next()或nextToken()返回。 开始标记的名称可从getName（）获得，其名称空间和前缀可从getNamespace（）和getPrefix（）中获得。

常量值：3（0x00000003）

ENTITY_REF

int ENTITY_REF

刚刚阅读了实体参考; 此令牌仅适用于nextToken() 。 通过调用getName（）可以获得实体名称。 如果可用，则可以通过调用getText（）来获得替换文本; 否则，用户负责解析实体引用。 这个事件类型永远不会从next（）返回; next（）会将替换文本和其他文本事件累加到单个TEXT事件中。

常数值：6（0x00000006）

FEATURE_PROCESS_DOCDECL

String FEATURE_PROCESS_DOCDECL

此功能确定是否处理文档声明。 如果设置为false，则DOCDECL事件类型由nextToken（）报告，并由next（）忽略。 如果此功能被激活，则文档声明必须由解析器处理。

请注意：如果文档类型声明被忽略，实体引用可能会在解析过程中稍后导致异常。 此功能的默认值为false。 解析过程中不能更改。

常量值：“http://xmlpull.org/v1/doc/features.html#process-docdecl”

FEATURE_PROCESS_NAMESPACES

String FEATURE_PROCESS_NAMESPACES

此功能确定解析器是否处理名称空间。 至于所有功能，默认值为false。

注意：解析期间不能更改该值，必须先设置解析值。

常量值：“http://xmlpull.org/v1/doc/features.html#process-namespaces”

FEATURE_REPORT_NAMESPACE_ATTRIBUTES

String FEATURE_REPORT_NAMESPACE_ATTRIBUTES

此功能确定是否通过属性访问方法显示名称空间属性。 像所有功能一样，默认值为false。 此功能在解析过程中无法更改。

常量值：“http://xmlpull.org/v1/doc/features.html#report-namespace-prefixes”

FEATURE_VALIDATION

String FEATURE_VALIDATION

如果激活此功能，则会报告XML 1.0规范中定义的所有验证错误。 这意味着FEATURE_PROCESS_DOCDECL为true，并且将处理内部和外部文档类型声明。

请注意：此功能在解析过程中无法更改。 默认值是false。

常量值：“http://xmlpull.org/v1/doc/features.html#validation”

IGNORABLE_WHITESPACE

int IGNORABLE_WHITESPACE

刚刚读取了可忽略的空白。 该令牌只能从nextToken()获得 ）。 对于非验证解析器，此事件仅在根元素外部由nextToken（）报告。 验证解析器可能能够在其他位置检测到可忽略的空白。 可忽略的空白字符串可通过调用getText（）

注意：这与调用isWhitespace（）方法不同，因为文本内容可能是空白但不可忽略。 next（）会自动跳过可忽略的空白字符; 这个事件类型永远不会从next（）返回。

常量值：7（0x00000007）

NO_NAMESPACE

String NO_NAMESPACE

此常量表示默认名称空间（空字符串“”）

常数值：“”

PROCESSING_INSTRUCTION

int PROCESSING_INSTRUCTION

刚刚阅读了XML处理指令声明。 此事件类型仅通过nextToken()提供 。 getText（）将返回处理指令中的文本。 调用next（）会自动跳过处理指令。

常量值：8（0x00000008）

START_DOCUMENT

int START_DOCUMENT

指出分析器处于文档的开头，并且还没有读取任何内容。 此事件类型只能在第一次调用next（），nextToken或nextTag（））之前通过调用getEvent（）来观察。

常量值：0（0x00000000）

START_TAG

int START_TAG

从getEventType（）返回next() ， nextToken()当读取一个开始标记。 开始标记的名称可从getName（）获得，如果是namespaces are enabled ，则其名称空间和前缀可从getNamespace（）和getPrefix（）中获得 。 请参阅getAttribute *方法来检索元素属性。 请参阅getNamespace *方法来检索新声明的名称空间。

常量值：2（0x00000002）

TEXT

int TEXT

字符数据被读取并且通过调用getText（）可用。

请注意： next()会将多个事件累加到一个TEXT事件中，跳过IGNORABLE_WHITESPACE，PROCESSING_INSTRUCTION和COMMENT事件。相反，当观察到任何其他事件时， nextToken()将停止阅读文本。 另外，当通过调用next（）来达到状态时，文本值将被标准化，而getText（）将在nextToken（）的情况下返回非标准化内容。 这允许在检查低级别事件时不改变行结束而进行精确往返，而对于高级应用程序，文本适当地被标准化。

常量值：4（0x00000004）

TYPES

String[] TYPES

该数组可用于将事件类型的整型常量（如START_TAG或TEXT）转换为字符串。 例如，TYPES [START_TAG]的值是字符串“START_TAG”。 该阵列仅用于诊断输出。 依赖于数组的内容可能是危险的，因为恶意应用程序可能会改变数组，尽管它是最终的，因为Java语言的限制。

defineEntityReplacementText

void defineEntityReplacementText (String entityName, 
                String replacementText)

为XML 1.0 Section 4.5 Construction of Internal Entity Replacement Text中定义的实体替换文本设置新值。 如果设置了FEATURE_PROCESS_DOCDECL或FEATURE_VALIDATION，则调用此函数将导致异常 - 启用DOCDECL处理时，不需要手动更换实体替换文本。

这个功能的动机是允许在J2ME环境中工作的非常小的XMLPULL实现。 尽管这些实现可能无法处理文档类型声明，但它们仍然可以使用此函数与已知的DTD一起使用。

请注意：给定值实际上用作替换文本，它对应于在DTD中声明所有特殊字符都已转义的实体：左角括号替换为＆，＆与＆amp; 等等。

注意：给定值是字面替换文本，不得包含任何其他实体引用（如果它包含任何实体引用，则不会有进一步替换）。

注意：预定义实体名称的列表将总是包含诸如amp（＆amp;），lt（＆lt;），gt（＆gt;），quot（＆quot;）和apos（＆）的标准XML实体。 这些不能用这种方法重新定义！

getAttributeCount

int getAttributeCount ()

返回当前开始标记的属性数量，如果当前事件类型不是START_TAG，则返回-1

getAttributeName

String getAttributeName (int index)

如果命名空间已启用，则返回指定属性的本地名称;如果命名空间已禁用，则返回属性名称。 如果索引超出范围或当前事件类型不是START_TAG，则抛出IndexOutOfBoundsException。

getAttributeNamespace

String getAttributeNamespace (int index)

返回具有给定索引的属性的名称空间URI（从0开始）。 如果命名空间未启用或者该属性没有命名空间，则返回空字符串（“”）。 如果索引超出范围或当前事件类型不是START_TAG，则抛出IndexOutOfBoundsException。

注意：如果设置了FEATURE_REPORT_NAMESPACE_ATTRIBUTES，则名称空间属性（xmlns：ns ='...'）必须使用名称空间http://www.w3.org/2000/xmlns/ （请访问此URL以获取描述！）报告。 默认名称空间属性（xmlns =“...”）将以空名称空间报告。

注： xml前缀按照 Namespaces in XML规范中的定义绑定到“http://www.w3.org/XML/1998/namespace”。

getAttributePrefix

String getAttributePrefix (int index)

返回指定属性的前缀如果元素没有前缀，则返回null。 如果命名空间被禁用，它将始终返回null。 如果索引超出范围或当前事件类型不是START_TAG，则抛出IndexOutOfBoundsException。

getAttributeType

String getAttributeType (int index)

返回指定属性的类型如果解析器不验证，它必须返回CDATA。

getAttributeValue

String getAttributeValue (String namespace, 
                String name)

返回由名称空间URI和名称空间localName标识的属性值。 如果命名空间被禁用，则命名空间必须为空。 如果当前事件类型不是START_TAG，则会抛出IndexOutOfBoundsException。

注：属性值必须标准化（如果PROCESS_DOCDECL为false，则包括实体替换文本），如 XML 1.0 section 3.3.3 Attribute-Value Normalization

getAttributeValue

String getAttributeValue (int index)

返回给定的属性值。 如果索引超出范围或当前事件类型不是START_TAG，则抛出IndexOutOfBoundsException。

注：属性值必须标准化（如果PROCESS_DOCDECL为false，则包括实体替换文本），如 XML 1.0 section 3.3.3 Attribute-Value Normalization

getColumnNumber

int getColumnNumber ()

返回当前列号，从0开始。当解析器不知道当前列号或无法确定它时，返回-1（例如，用于WBXML）。

getDepth

int getDepth ()

返回元素的当前深度。 在根元素之外，深度为0.当达到开始标记时，深度加1。 在观察到结束标记事件后，深度递减。

 <!-- outside -->     0
 <root>                  1
   sometext                 1
     <foobar>         2
     </foobar>        2
 </root>              1
 <!-- outside -->     0
 

getEventType

int getEventType ()

返回当前事件的类型（START_TAG，END_TAG，TEXT等）

getFeature

boolean getFeature (String name)

返回给定特征的当前值。

请注意：未知功能 始终返回为false。

getInputEncoding

String getInputEncoding ()

返回输入编码（如果已知），否则返回null。 如果调用setInput（InputStream，inputEncoding）时，inputEncoding值不是null，则必须从此方法返回此值。 否则，如果inputEncoding为null并且解析器支持编码检测功能（http://xmlpull.org/v1/doc/features.html#detect-encoding），则它必须返回检测到的编码。 如果调用setInput（Reader），则返回null。 在第一次调用next时，如果存在XML声明，则此方法将返回声明的编码。

getLineNumber

int getLineNumber ()

返回当前行号，从1开始。当解析器不知道当前行号或无法确定它时，返回-1（例如，用于WBXML）。

getName

String getName ()

对于START_TAG或END_TAG事件，当启用名称空间时，返回当前元素的（本地）名称。 当命名空间处理被禁用时，返回原始名称。 对于ENTITY_REF事件，返回实体名称。 如果当前事件不是START_TAG，END_TAG或ENTITY_REF，则返回null。

请注意：当启用名称空间并且前缀不为空时，要重建原始元素名称，您需要将前缀和冒号添加到localName ..

getNamespace

String getNamespace ()

返回当前元素的名称空间URI。 默认名称空间表示为空字符串。 如果命名空间未启用，则总是返回空字符串（“”）。 目前的活动必须是START_TAG或END_TAG; 否则，返回null。

getNamespace

String getNamespace (String prefix)

根据解析器的当前状态，返回与给定前缀对应的URI。

如果前缀未在当前作用域中声明，则返回null。 默认名称空间包含在名称空间表中，可通过getNamespace（null）使用。

这种方法是一种方便的方法

  for (int i = getNamespaceCount(getDepth ())-1; i >= 0; i--) {
   if (getNamespacePrefix(i).equals( prefix )) {
     return getNamespaceUri(i);
   }
  }
  return null;
 

请注意：解析器实现可以提供更高效的查找，例如使用Hashtable。 “xml”前缀绑定到“http://www.w3.org/XML/1998/namespace”，如Namespaces in XML规范中所定义。 类似地，'xmlns'前缀已解析为http://www.w3.org/2000/xmlns/

getNamespaceCount

int getNamespaceCount (int depth)

返回给定深度的命名空间堆栈中元素的数量。 如果命名空间未启用，则返回0。

注意：当解析器位于END_TAG上时，允许使用getDepth（）+ 1参数调用此函数以检索在相应START_TAG上声明的名称空间前缀和URI的位置。

注：要检索在当前元素中声明的名称空间列表：

       XmlPullParser pp = ...
       int nsStart = pp.getNamespaceCount(pp.getDepth()-1);
       int nsEnd = pp.getNamespaceCount(pp.getDepth());
       for (int i = nsStart; i < nsEnd; i++) {
          String prefix = pp.getNamespacePrefix(i);
          String ns = pp.getNamespaceUri(i);
           // ...
      }
 

getNamespacePrefix

String getNamespacePrefix (int pos)

返回名称空间堆栈中给定位置的名称空间前缀。 默认名称空间声明（xmlns ='...'）将以空格作为前缀。 如果给定索引超出范围，则抛出异常。

请注意：当解析器位于END_TAG中时，在相应的START_TAG中声明的名称空间前缀仍然可以访问，尽管它们不在范围之内。

getNamespaceUri

String getNamespaceUri (int pos)

返回名称空间堆栈中给定位置的名称空间URI如果位置超出范围，则会引发异常。

注意：当解析器位于END_TAG上时，在相应的START_TAG中声明的名称空间前缀仍然可访问，即使它们不在作用域中

getPositionDescription

String getPositionDescription ()

返回描述当前解析器状态的短文本，包括位置，当前事件的描述和数据源（如果已知）。 此方法对提供有意义的错误消息和用于调试目的特别有用。

getPrefix

String getPrefix ()

返回当前元素的前缀。 如果该元素处于默认名称空间（没有前缀），则返回null。 如果名称空间未启用，或者当前事件不是START_TAG或END_TAG，则返回null。

getProperty

Object getProperty (String name)

查找一个属性的值。 属性名称是任何完全限定的URI。

注：未知属性 始终返回为空。

getText

String getText ()

以String形式返回当前事件的文本内容。 返回的值取决于当前的事件类型，例如对于TEXT事件，它是元素内容（这是使用next（）时的典型情况）。 有关不同类型事件的可能返回值的详细说明，请参阅nextToken（）的描述。

注意：如果是ENTITY_REF，则此方法返回实体替换文本（如果不可用，则返回null）。 这是getText（）和getTextCharacters（）返回不同值的唯一情况。

getTextCharacters

char[] getTextCharacters (int[] holderForStartAndLength)

返回包含当前事件文本的缓冲区，以及与当前事件相关的起始偏移量和长度。 有关可能的返回值的描述，请参阅getText（），next（）和nextToken（）。

请注意：在调用next（）或nextToken（）之后，不得修改此缓冲区，并且其内容可能会更改。 此方法将始终返回与getText（）相同的值，但ENTITY_REF除外。 对于ENTITY ref，getText（）返回替换文本，此方法返回包含实体名称的实际输入缓冲区。 如果getText（）返回null，则此方法也返回null，并且持有者数组中返回的值务必为-1（起始和长度）。

isAttributeDefault

boolean isAttributeDefault (int index)

如果指定的属性不在输入中，则返回在XML中声明的返回值。 如果解析器不验证，它必须总是返回false。 这些信息是XML信息集的一部分：

isEmptyElementTag

boolean isEmptyElementTag ()

如果当前事件是START_TAG且标签退化（例如<foobar />），则返回true。

注意：如果解析器不在START_TAG上，将抛出异常。

isWhitespace

boolean isWhitespace ()

检查当前的TEXT事件是否仅包含空白字符。 对于IGNORABLE_WHITESPACE，这总是如此。 对于TEXT和CDSECT，当当前事件文本至少包含一个非空白字符时，将返回false。 对于任何其他事件类型，都会引发异常。

请注意：非验证解析器不能区分空白和可忽略的空白，除了根元素之外的空白。 可忽略的空白报告为单独的事件，仅通过nextToken公开。

next

int next ()

获取下一个解析事件 - 元素内容将被合并，并且整个元素内容只能返回一个TEXT事件（注释和处理指令将被忽略，实体引用必须被扩展或者如果实体引用不能被扩展，则必须抛出异常）。 如果元素内容为空（内容为“”），则不会报告任何TEXT事件。

注意：空元素（例如<tag />）将用两个单独的事件报告：START_TAG，END_TAG - 必须这样才能将空元素的解析等同性保留为<tag> </ tag>。 （请参阅isEmptyElementTag（））

nextTag

int nextTag ()

如果它是START_TAG或END_TAG，则调用next（）并返回事件，否则引发异常。 如果有的话，它会在实际标签之前跳过空格TEXT。

基本上它是这样做的

   int eventType = next();
   if(eventType == TEXT &&  isWhitespace()) {   // skip whitespace
      eventType = next();
   }
   if (eventType != START_TAG &&  eventType != END_TAG) {
      throw new XmlPullParserException("expected start or end tag", this, null);
   }
   return eventType;
 

nextText

String nextText ()

如果当前事件是START_TAG，那么如果下一个元素是TEXT，则返回元素内容，或者如果下一个事件是END_TAG，则返回空字符串，否则引发异常。 在成功调用此函数后，解析器将位于END_TAG上。

这个函数的动机是允许一致地解析空元素和非空内容的元素，例如输入：

1. <tag>foo</tag>
2. <tag></tag> (which is equivalent to <tag/> both input can be parsed with the same code:

      p.nextTag()
      p.requireEvent(p.START_TAG, "", "tag");
      String content = p.nextText();
      p.requireEvent(p.END_TAG, "", "tag");
    

   This function together with nextTag make it very easy to parse XML that has no mixed content.

   本质上它是这样做的

     if(getEventType() != START_TAG) {
        throw new XmlPullParserException(
          "parser must be on START_TAG to read next text", this, null);
     }
     int eventType = next();
     if(eventType == TEXT) {
        String result = getText();
        eventType = next();
        if(eventType != END_TAG) {
          throw new XmlPullParserException(
             "event TEXT it must be immediately followed by END_TAG", this, null);
         }
         return result;
     } else if(eventType == END_TAG) {
        return "";
     } else {
        throw new XmlPullParserException(
          "parser must be on START_TAG or TEXT to read text", this, null);
     }
    

   警告：在API级别14之前，调用此方法时，由android.util.Xml返回的pull解析器并不总是前进到END_TAG事件。 在调用nextText（）之后使用手动前进来解决问题：

     String text = xpp.nextText();
     if (xpp.getEventType() != XmlPullParser.END_TAG) {
         xpp.next();
     }
    

   Returns
   String

   Throws
   XmlPullParserException
   IOException

nextToken

int nextToken ()

此方法与next（）类似，但会在输入中提供其他事件类型（COMMENT，CDSECT，DOCDECL，ENTITY_REF，PROCESSING_INSTRUCTION或IGNORABLE_WHITESPACE）。

如果启用了特殊功能FEATURE_XML_ROUNDTRIP （由URI标识：http: //xmlpull.org/v1/doc/features.html#xml-roundtrip ），则可以执行XML文档往返行程，即。 使用getText（）方法重现输出XML输入：返回的内容始终是非标准化的（与输入中一样）。 否则返回的内容是按照XML 1.0 End-of-Line Handling和XML 1.0 End-of-Line Handling所描述的结束标准化。 此外，启用此功能时，还可以使用START_TAG，END_TAG，DOCDECL和PROCESSING_INSTRUCTION的精确内容。

以下是可以从nextToken（）返回的令牌列表，以及getText（）和getTextCharacters（）返回的内容：

START_DOCUMENT

null

END_DOCUMENT

null

START_TAG

null unless FEATURE_XML_ROUNDTRIP enabled and then returns XML tag, ex: <tag attr='val'>

END_TAG

null unless FEATURE_XML_ROUNDTRIP id enabled and then returns XML tag, ex: </tag>

TEXT

return element content.
Note: that element content may be delivered in multiple consecutive TEXT events.

IGNORABLE_WHITESPACE

return characters that are determined to be ignorable white space. If the FEATURE_XML_ROUNDTRIP is enabled all whitespace content outside root element will always reported as IGNORABLE_WHITESPACE otherwise reporting is optional.
Note: that element content may be delivered in multiple consecutive IGNORABLE_WHITESPACE events.

CDSECT

return text inside CDATA (ex. 'fo<o' from <!CDATA[fo<o]]>)

PROCESSING_INSTRUCTION

if FEATURE_XML_ROUNDTRIP is true return exact PI content ex: 'pi foo' from <?pi foo?> otherwise it may be exact PI content or concatenation of PI target, space and data so for example for <?target data?> string "target data" may be returned if FEATURE_XML_ROUNDTRIP is false.

COMMENT

return comment content ex. 'foo bar' from <!--foo bar-->

ENTITY_REF

getText() MUST return entity replacement text if PROCESS_DOCDECL is false otherwise getText() MAY return null, additionally getTextCharacters() MUST return entity name (for example 'entity_name' for &entity_name;).
NOTE: this is the only place where value returned from getText() and getTextCharacters() are different
NOTE: it is user responsibility to resolve entity reference if PROCESS_DOCDECL is false and there is no entity replacement text set in defineEntityReplacementText() method (getText() will be null)
NOTE: character entities (ex. &#32;) and standard entities such as &amp; &lt; &gt; &quot; &apos; are reported as well and are not reported as TEXT tokens but as ENTITY_REF tokens! This requirement is added to allow to do roundtrip of XML documents!

DOCDECL

if FEATURE_XML_ROUNDTRIP is true or PROCESS_DOCDECL is false then return what is inside of DOCDECL for example it returns:

 " titlepage SYSTEM "http://www.foo.bar/dtds/typo.dtd"
 [<!ENTITY % active.links "INCLUDE">]"

输入文件包含：

 <!DOCTYPE titlepage SYSTEM "http://www.foo.bar/dtds/typo.dtd"
 [<!ENTITY % active.links "INCLUDE">]>

otherwise if FEATURE_XML_ROUNDTRIP is false and PROCESS_DOCDECL is true then what is returned is undefined (it may be even null)

注意：不能保证nextToken（）只会有一个TEXT或IGNORABLE_WHITESPACE事件，因为解析器可能会选择将元素内容传送到多个标记（将元素内容分割为块）

注意：令牌的返回文本是否是行尾标准化取决于FEATURE_XML_ROUNDTRIP。

注意：不报告XMLDecl（<？xml ...？>），但其内容可通过可选属性获得（请参阅上面的类描述）。

require

void require (int type, 
                String namespace, 
                String name)

测试当前事件是否为给定类型，以及名称空间和名称是否匹配。 null将匹配任何名称空间和任何名称。 如果测试未通过，则会引发异常。 异常文本指示解析器位置，预期事件和当前不符合要求的事件。

本质上它是这样做的

  if (type != getEventType()
  || (namespace != null &&  !namespace.equals( getNamespace () ) )
  || (name != null &&  !name.equals( getName() ) ) )
     throw new XmlPullParserException( "expected "+ TYPES[ type ]+getPositionDescription());
 

setFeature

void setFeature (String name, 
                boolean state)

使用此调用来更改解析器的常规行为，如名称空间处理或文档类型声明处理。 必须在第一次调用next或nextToken之前调用此方法。 否则，会引发异常。

示例：调用setFeature（FEATURE_PROCESS_NAMESPACES，true）以开启命名空间处理。 初始设置对应于XML Pull Parser工厂请求的属性。 如果没有人请求，则默认情况下所有功能均被禁用。

setInput

void setInput (Reader in)

将解析器的输入源设置为给定的阅读器并重置解析器。 事件类型设置为初始值START_DOCUMENT。 将阅读器设置为空将停止解析并重置解析器状态，从而允许解析器释放内部资源，如解析缓冲区。

setInput

void setInput (InputStream inputStream, 
                String inputEncoding)

设置解析器将要处理的输入流。 此调用重置解析器状态并将事件类型设置为初始值START_DOCUMENT。

注意：如果输入的编码字符串被传递，它必须被使用。 否则，如果inputEncoding为空，解析器应该尝试确定遵循XML 1.0规范的输入编码（见下文）。 如果支持编码检测，则功能http://xmlpull.org/v1/doc/features.html#detect-encoding务必为真，否则它必须为假

setProperty

void setProperty (String name, 
                Object value)

设置属性的值。 属性名称是任何完全限定的URI。