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.
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!)
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.
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.
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.
They MAY be supported but are not part of XmlPull API
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.
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()).
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.
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:
By default this feature is off and it implies unchanged behavior of XmlPullParser:
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).
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.
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.
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