Author: Aleksander Slominski

# XmlPull v1 API Features

The feature defines a discoverable and possibly changeable characteristic of XmlPull parser.

Please note: the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

## Standard features

The semantics of of all standard features MUST be followed by every XmlPull v1 API implementation.

All standard feature values MUST NOT change unless setFeature() is called (even when setInput() is called!)

### Standard feature: PROCESS NAMESPACES

The feature is identified by http://xmlpull.org/v1/doc/features.html#process-namespaces

Processing of namespaces in XMLPULL V1 parser MUST be by default set to false.

This feature MUST be recognized and allowed to be set both to true and false by every XMLPULL V1 API compliant parser implementation.

If set to false XML namespaces MUST not be processed and instead namespace attributes (starting with xmlns) will be treated as normal attributes.

If set to true than XML namespaces MUST be processed according to Namespaces in XML specification.

The feature MUST be allowed to be changed only when parser is in START_DOCUMENT state i.e. this feature can not be changed during parsing.

### Standard feature: PROCESS DOCDECL

Identified by http://xmlpull.org/v1/doc/features.html#process-docdecl

The default value of the feature is undefined.

If the VALIDATION feature is true then this feature MUST not be modified and MUST be reported as true

If the feature is set to false and if XML document type declaration (in short DOCDECL) is encountered it MUST be reported by nextToken() and MUST be ignored by next().

As the DOCDECL was ignored, references to entities cannot be expanded (they will produce a fatal error if you call next(), but will be reported as ENTITY_REF if you call nextToken() instead).

If the feature is true and VALIDATION feature is false then parser MUST be non validating as defined in XML 1.0 specification (DOCDECL MUST be parsed and processed by parser).

If the feature is true and VALIDATION feature is true then parser MUST be validating as defined in XML 1.0 specification.

The feature MUST be allowed to be changed only when parser is in START_DOCUMENT state i.e. this feature can not be changed during parsing.

### Standard feature: VALIDATION

Identified by http://xmlpull.org/v1/doc/features.html#validation

The feature MUST be false by default.

See description of PROCESS DOCDECL feature for required behavior.

If the feature is set to true then PROCESS DOCDECL MUST be automatically set to true as well.

The feature MUST be allowed to be changed only when parser is in START_DOCUMENT state i.e. this feature can not be changed during parsing.

## Optional features

They MAY be supported but are not part of XmlPull API

### Optional feature: REPORT NAMESPACE ATTRIBUTES

The feature is identified by http://xmlpull.org/v1/doc/features.html#report-namespace-prefixes

The feature MUST be false by default and only meaningful when PROCESS NAMESPACES feature is on.

This feature MAY be recognized and allowed to be set to true (by default as other optional features it is false)

When set to true then XMLPULL parser MUST report namespace attributes also - they can be distinguished looking for prefix == "xmlns" or prefix == "" and name == "xmlns

The feature MUST be allowed to be changed only when parser is in START_DOCUMENT state i.e. this feature can not be changed during parsing.

### Optional feature: NAMES INTERNED

This feature is identified by http://xmlpull.org/v1/doc/features.html#names-interned

If set to true then XMLPULL parser MUST intern all returned names using java.lang.String.intern that includes following functions: getName(), getPrefix(), getNamespace(), getNamespace(prefix), getNamespacePrefix(int), getNamespaceUri(int pos) , getAttributeName(), getAttributeNamespace(), getAttributePrefix(), getAttributeType(). However this feature provides no assurance about String values (like getText()) or attribute values (getAttributeValue()).

NOTE: when enabled this feature allows for fast testing of equality against string constants (no need to use String.equals()).

###

### Optional feature: EXPAND ENTITY REF

This feature is identified by http://xmlpull.org/v1/doc/features.html#expand-entity-ref

This optional feature changes behavior of nextToken() and when enabled parser MUST report expanded entity reference content as tokens and MUST report end of expanded entity ref as ENTITY_REF with name that is null (getText() returns null).

For example if entity foo was defined to have replacement text bar then parser will report following tokens: ENTITY_REF with 'foo' as entity name, TEXT with value 'bar' and ENTITY_REF with no name to signal end of expansion) . If PROCESS_DOCDECL is true then reported tokens may include START_TAG/END_TAG if entity has embedded markup and ENTITY_REF for recursively expanded entity references (following calls to nextToken() will report entity content as possibly multiple TEXT, START_TAG, END_TAG, ENTITY_REF etc.).

NOTE: it can only be supported when PROCESS_DOCDECL is true as defineEntityReplacementText() will always escape markup or entity references.

NOTE: next() will always expand entity ref and report combined TEXT event and this feature does not affect next() behavior.

### Optional feature: XML ROUNDTRIP

This feature is identified by http://xmlpull.org/v1/doc/features.html#xml-roundtrip

If ROUNDTRIP is on it is affecting getText/getTextCharacters() when nextToken() is used to make possible an exact roundtrip of XML 1.0 input - here are constraints on values returned by getText()/getTextCharacters:

- for all tokens exactly what was in input MUST be returned - in particular returned content MUST NOT be end-of-line normalized (the algorithm described in XML 1.0 End-of-Line Handling is not applied)
- for START_TAG and END_TAG event original XML value MUST be returned for events for start/end tag (for example "tag" for <tag>)
- for PROCESSING INSTRUCTION event exact content of PI MUST be returned: in <?target data?> white spaces between target and data must be preserved
- content of XMLDecl must be reported as not null by XMLDECL CONTENT property
- DOCDECL MUST be reported exactly as in input

- additionally for nextToken(): ignorable whites spaces outside root element MUST be reported as IGNORABLE_WHITESPACE

By default this feature is off and it implies unchanged behavior of XmlPullParser:

- for all tokens call to getText()/getTextCharacters returns end-of-line normalized content
  (that includes beside TEXT, IGNORABLE_WHITESPACE also COMMENT, PROCESSING_INSTRUCTION, ENTITY_REF etc.)
- getText() for START_TAG and END_TAG event MUST return null
- PROCESSING_INSTRUCTION MUST be reported as target + ' ' + data or exactly as it was in input
- DOCDECL MUST be reported exactly if PROCESS DOCDECL is true otherwise MAY be reported (but does not have to and may be even null)
- ignorable whites spaces (event IGNORABLE_WHITESPACE) outside root element MAY be reported by nextToken()

Note that content outside of root element is typically not reported by parsers to make it consistent with XML infoset Document Information Item properties in which white spaces in prolog and part root element are ignored. If reported IGNORABLE_WHITESPACE event may be used to preserved formatting of XML input when serializing it.

However as IGNORABLE_WHITESPACE event MAY be reported make sure that application will be prepared to ignore IGNORABLE_WHITESPACE evens from nextToken() when processing content outside of root element (getDepth() == 0).

### Optional feature: DETECT ENCODING

This feature is identified by http://xmlpull.org/v1/doc/features.html#detect-encoding

If this feature is true it means that XmlPull parser MUST detect encoding from input stream when inputEncoding is null in call setInput(InputStream inputStream, String inputEncoding).

Parameter inputStream from setInput(InputStream inputStream, String inputEncoding) contains raw byte input stream of possibly unknown encoding (when inputEncoding is null) and in such case the parser must derive encoding from <?xml declaration or assume UTF8 or UTF16 as described in XML 1.0 Appendix F.1 Detection Without External Encoding Information otherwise if inputEncoding is present then it must be used (this is consistent with XML 1.0 Appendix F.2 Priorities in the Presence of External Encoding Information that allows for exception only for files and in such cases inputEncoding should be null to trigger auto detecting.

### Optional feature: SERIALIZER ATTVALUE USE APOSTROPHE

This feature is identified by http://xmlpull.org/v1/doc/features.html#serializer-attvalue-use-apostrophe

If this feature is supported that means that XmlSerializer output for attribute value quotation can be controlled (when serializing XML 1.0 it allows to chose one of alternative representations for AttValue).

If the feature is set to true it means than XmlSerializer parser MUST use apostrophe (') to quote attribute value.

If the feature is set to false it means than XmlSerializer parser MUST use quotation mark (") to quote attribute value.

### Optional feature: RELAXED

This feature is identified by http://xmlpull.org/v1/doc/features.html#relaxed

If this feature is supported that means that XmlPull parser will be lenient when checking XML well formedness.

NOTE: use it only if XML input is not well-formed and in general usage if this feature is discouraged

NOTE: as there is no definition of what is relaxed XML parsing therefore what parser will do completely depends on implementation used