XmlPull v1 API Changes
Author: Aleksander Slominski [http://www.extreme.indiana.edu/~aslom]

# Changes to XmlPull v1 API

### IN PROGRESS:

### 2006-10-23 (XMLPULL_1_1_3_4c)

- 2006-10-22 (XMLPULL_1_1_3_4c): fixed XmlPull SAX2 driver not sending correct qname (rawName) in startElement() callback
- 2006-10-22: fixed Bug 246: DOM2XmlPullBuilder not handling default namespaces
- 2006-10-22: moved addons test (wrapper test) to one shared directory added test for DOM2XmlPullBuilder
- 2005-02-28: replaced xpp.START_TAG with XmlPullParser.START_TAG (and similiar) everywhere (removes static access through instance warnings, except for mess it is TYPES ...), minor typos fixed, incremented minor version (1.1.3.4b)
- 2004-02-13: added sample that demonstrates how to use XmlPullParser that implements Cloneable to allow exploring efficient "What-If" parsing, for more details see mailing list archies.
- 2004-02-01: fixed style issue raised by Max Gilead related to unnecessary use of public modifier in interfaces (bug 174)
- 2004-01-20: stronger serializer tests for case when char values < 32" (TestSerialize.java)
- added `target="1.1"` to make sure that compiled code can work with JDK 1.1 (as described in ANT Javac Task documentation: (...) Generate class files for specific VM version (e.g., 1.1 or 1.2). Note that the default value depends on the JVM that is running Ant. In particular, if you use JDK 1.4 the generated classes will not be usable for a 1.1 Java VM unless you explicitly set this attribute to the value 1.1 (which is the default value for JDK 1.1 to 1.3).
- added test to check that workaround from issue "unable to select prefix to use when writing startTag, endTag, and attribute" " (bug 169) is tested
- updated unit test to check for disallowed "]]>" in character content, more tests for CDSECT
- changed DOM2 builder addon to be completely stateless factory and made factory constructor empty
- improved DOM2 builder addon to allow building DOM tree from only part of XML pull even stream and still have all namespaces declared
- IN PROGRESS (currently code is commented out): added methods to wrapper to encapsulate need to read some of XSD simple types (partially based on JiBX)

### 2003-05-19 (XMLPULL_1_1_3_1)

- added set of addons that add new functionality or extend existing interfaces in XmlPull API
- updated tests to look for boundary cases with PI/comments and next() (thanks to Henry Minsky)
- marked all supported optional features and properties as such in unit tests summary
- changed XmlPullParserFactory.newInstance() to use XmlPullParserFactory class as default class context and not String.class because when using String we will never find /META-INF/services/org.xmlpull.v1.XmlPullParserFactory resource ...

### 2003-02-26 (XMLPULL_1_1_2_1)

- minor release to make available the latest tests and documentation changes
- added quick introduction to using XmlSerializer
- added test to check that generating namespace prefix for attributes is allowed (method getPrefix(uri, true) called after startTag() should add new prefix to current start tag elements and not next start tag)
- added tests to check optional support for formatting XML output from XML serializer
- SAX2 driver moved to addons, removed AttributesCachingDriver but left documented how to achieve this functionality
- added to addons XML RPC implementation

### 2002-10-16 (XMLPULL_1_1_2)

- NOTE: potentially backward incompatible change to nextToken(): XMLDecl (<?xml ... ?>) will no longer be reported as PROCESSING_INSTRUCTION but instead content of XMLDecl is made available as set of properties XMLDECL VERSION XMLDECL STANDALONE and XMLDECL CONTENT.
- J2ME compatibility issue fixed: changed to use `instanceof` instead of .class in XmlPullParserFactory
- added to XmlSerializer three new utility methods: getDepth(), getName(), and getNamespace() to allows intelligent closing of serialized output for example when writing error/fault information into serialized XML stream from inside exception handler
- changed tests to reflect changed handling of XMLDecl and added tests to check for optional XMLDecl properties
- XmlSerializer is now required to throw exception when user tries to write startTag() in default namespace ("") and default namespace is bound to non-empty string, added test to check for it
- added patch by Holger Krug to SAX2 Driver to allow modification in sub classes of how Attributes in startElement() are kept. Added also AttributesCachingDriver that extends SAX2 Driver to create a new copy of Attributes for each startElement() so Attributes provided in startTag() will not change during parsing and can be kept indefinitely (not that Attributes object is created for each startTag() and this is expensive both performance and memory wise and is not required by SAX2.
- more tests to check for CDATA end-of-line normalization
- changed tests to require support for ROUNDTRIP==false and additional checks for EOL normalization of tokens

###

### 2002-08-27 (XMLPULL_1_1_1)

- NEW! XmlSerializer API that is now required part of XMLPULL API on J2SE (on J2ME typically factory is not used and only implementation of serializer or parser may be available).
- NOTE: potentially backward incompatible change to nextToken(): content returned by getText()/getTextCharacters() is end-of-line normalized and also IGNORABLE_WHITESPACE for content outside element root and end-of-line unnormalized content for elements MAY not reported by nextToken() (unless optional XML ROUNDTRIP feature is false). However if XML ROUNDTRIP feature is true parser behavior is exactly the same as in previous XmlPull API version . This change is made to improve compatibility with XML by requiring normalized content as described in XML 1.0 End-of-Line Handling and with XML infoset Document Information Item properties which only contain comments and processing instructions but not white space content (so now reporting IGNORABLE_WHITESPACE event outside is optional).
- added optional features EXPAND ENTITY REF and SERIALIZER ATTVALUE USE APOSTROPHE
- added optional properties related to indenting serializer output (pretty printing): SERIALIZER INDENTATION, SERIALIZER LINE SEPARATOR
- added clarification to nextToken() that there is no requirement for reported token events to be coalesced (for example nextToken() may report multiple consecutive TEXT or IGNORABLE_WHITESPACE events). This is different from next() that always report exactly one TEXT event
- conformance tests can be now described in XML allowing to keep tests in format independent from Java (and potentially to use the same XML tests with other XmlPull API bindings such as C++ or PHP) XML files with tests are read from CLASSPATH
- added newSerializer() method to XmlPullParserFactory
- added new FAQ entries:
  - Why is there only one "large" interface, wouldn't it be cleaner to use event objects and polymorphism?
  - What is the difference between `nextToken()`, `next()`, `nextTag()`, and `nextText()`?
  - Why are there different `next()` methods, wouldn't it be cleaner to have a set method, allowing me to specify the type of events I am interested in in general?
- list of class names with factory, serializer and/or parser must be now separated by colon in XMLPULL tests property (`org.xmlpull.v1.tests`), for example: `-Dorg.xmlpull.v1.tests=DEFAULT:org.xmlpull.mxp1.MXParser,org.xmlpull.mxp1_serializer.MXSerializer`
- changed XmlPullParser constants to be all consistently `int` (few were declared as `byte` ...)

### 2002-04-24 (XMLPULL_1_0_8)

- two API changes are not backward compatible with 1.0.7:
  - readText() function was removed, please use nextText() instead
  - require() is changed - no longer will skip white space content
- added new functions:
  - getAttributeType(index)
  - isAttributeDefault(index)
  - setInput(InputStream is, String inputEncoding)
  - getInputEncoding()
  - nextText()
  - nextTag()
- modified tests to allow -1 for column or line number and updated Javadoc to reflect it
- updated all tests to check new functions
- modified test driver PackageTest to accept list of XMLPULL factories or parsers to check from system property org.xmlpull.v1.test, DEFAULT can be used to indicate using of default parser factory (taken from system property or resource from CLASSPATH), for example:
  -Dorg.xmlpull.v1.tests=DEFAULT,org.xmlpull.mxp1.MXParser
- modified XmlPullParserFactory to use resource from CLASSPATH when not only classNames is null but also if classNames is empty String or if it is equal to "DEFAULT"
- improved error messages in XmlPullParserFactory to better diagnose why new pull parser can not be created
- added test to check that when on END_TAG namespaces that were declared in corresponding START_TAG are still accessible even though they are not in scope
- added tests to check that setInput() does not read any bytes from input stream or characters from reader until first call to next()

### 2002-04-20 (XMLPULL_1_0_7_1)

- fixed Quick Introduction to use correct API for getTextCharacters and getEventType (instead of getType)
- added requirement to getNamespace(prefix) to have 'xml' and 'xmlns' pre-declared
- removed from getNamespace(prefiix) exception XmlPullParserException as this function simply returns null when namespace is not declared ...
- updated tests:
  - updated header with license pointer to http://www.xmlpull.org
  - added printing test summary (parser used, supported features)
  - added one test to check that tokens are equivalent to events (next() <-> nextToken())

### 2002-04-08 (XMLPULL_1_0_7)

- changed default namespace semantics: the prefix must be reported as null and not empty string from getNamespacePrefix(depth) and getNamespace(null) must return default namespace if declared in XML
- modified getText() method behavior for ENTITY_REF: in this case getText() must return entity replacement text and getTextCharacters() returns actual input buffer with entity name the same as getName()
- for ENTITY_REF token getName() must return entity name
- added specific requirement that attribute values MUST be normalized

### 2002-04-06 (XMLPULL_1_0_6)

- changed hard coded parser factory in XmlPullParserFactory name for KXML2 to org.kxml2.io.KXmlParserFactory
- clarified required semantics in features description
- refactored XmlPullParserFactory:
  - reduced in size as much as possible,
  - String classNames in newInstance() can now specify both factories and parsers
  - removed method newInstance(String classNames) the same can be done with newInstance(classNames, null)
  - modified tests use newInstance(*,null) instead of one argument version
- removed constructor with line numbers and Throwable from XmlPullParserException
- changed API to add default namespace declaration to be counted in getNamespaceCount() and available from getNamespace...(...) methods
- refactored tests for common problem: check if no XMLPULL implementation available and print just one error message (instead of dozen...)

### 2002-04-03 (XMLPULL_1_0_5)

- changed features URI to point to actual documentation on http://www.xmlpull.org
- automatic JUnit tests now covers whole API
- clarified isWhitespace() can only be checked on TEXT, IGNORABLE_WHITESPACES, CDSECT
- clarified what is attribute namespace for xmlns:ns='...' when FEATURE_REPORT_NAMESPACE_ATTRIBUTES is set
- changed defineCharacterEntity() to defineEntityReplacementText() and described semantics of this function and its motivation in J2ME environments
- clarified how nextToken() works: return un-normalized (no end-of-line normalization) parts of XML input
- if additional feature i set then XML text of START_TAG and END_TAG token is available allowing to do full XML document roundtrip: reproduce on output exactly what was in input. However this works on level of UNICODE characters (UTF16 char in Java) and output will need to be converted into required encoding (like UTF8 or UTF16).
- getNamespacesCount changed to getNamespaceCount for consistency
- getAttributesCount changed to getAttributeCount for consistency

### 2002-03-30 (XMLPULL_1_0_4)

- added FEATURE_ prefix to all feature constants
- changed function name getType() to getEventType()
- clarified that getNamespacesCount() does not include default namespaces declarations (xmlns='...')
- specified that attributes if has no namespace declared will have "" namespace (empty string)
- clarified that when getTextCharacters returns null then holder MUST contain start and length will be set to -1]
- added more comprehensive JUnit tests for API conformance

### 2002-03-29 (XMLPULL_1_0_3)

- changed getTextCharacters to use pass by reference two int parameters (char[] getTextCharacters (int [] holderForStartAndLength)
- nextToken() is required to return actual input data with getText() (no end-of-line normalization) - this will allow to reconstruct input XML

### 2002-03-28 (XMLPULL_1_0_2a)

- fixed typos in getAttribute(s)* and getNamespace(s)* functions
- numerous improvements to interface documentation
- clarified PROCESS_DOCDECL and removed REPORT_DOCDECL
- initial release of JUnit tests (very limited for now ...)

### 2002-03-25 (XMLPULL_1_0_1)

- first interim release of API and supporting files (incomplete)