CVS Update: xmlpull-api-v1/src/java/api/org/xmlpull/v1

aslom       02/08/01 10:13:11

  Modified:    src/java/api/org/xmlpull/v1 XmlPullParser.java
  Log:
  changed possibly nextToken() behavior as it depends now
  on UNNORMLIZED XML feature - if this feature is enabled
  then nextToken() is 100% compatible with previosu version
  but if feature is disabled nextToken() is exact like SAX
  in devlivering multiple TEXT (characters()) or
  IGNORABLE_WHITESPACE (ignorableWhitespace()) events
  with end-of-line normalized XML content
  
  Revision  Changes    Path
  1.63      +116 -101  xmlpull-api-v1/src/java/api/org/xmlpull/v1/XmlPullParser.java
  
  Index: XmlPullParser.java
  ===================================================================
  RCS file: /l/extreme/cvspub/xmlpull-api-v1/src/java/api/org/xmlpull/v1/XmlPullParser.java,v
  retrieving revision 1.62
  retrieving revision 1.63
  diff -u -b -t -w -r1.62 -r1.63
  --- XmlPullParser.java	2002/07/19 23:24:06	1.62
  +++ XmlPullParser.java	2002/08/01 15:13:11	1.63
  @@ -892,21 +892,32 @@
        * additional event types (COMMENT, CDSECT, DOCDECL, ENTITY_REF, PROCESSING_INSTRUCTION, or
        * IGNORABLE_WHITESPACE) if they are available in input.
        *
  -     * <p>If special feature FEATURE_XML_ROUNDTRIP
  +     * <p>If special feature
  +     * <a href="http://xmlpull.org/v1/doc/features.html#unnormalized-xml">FEATURE_UNNORMALIZED_XML</a>
  +     * (identified by URI: http://xmlpull.org/v1/doc/features.html#unnormalized-xml)
  +     * <p>If special feature
  +     * <a href="http://xmlpull.org/v1/doc/features.html#xml-roundtrip">FEATURE_XML_ROUNDTRIP</a>
        * (identified by URI: http://xmlpull.org/v1/doc/features.html#xml-roundtrip)
        * is true then it is possible to do XML document round trip ie. reproduce
  -     * exectly on output the XML input using getText().
  +     * exectly on output the XML input using getText(). When enabled this feature implies
  +     * enabling FEATURE_UNNORMALIZED_XML.
        *
        * <p>Here is the list of tokens that can be  returned from nextToken()
        * and what getText() and getTextCharacters() returns:<dl>
        * <dt>START_DOCUMENT<dd>null
        * <dt>END_DOCUMENT<dd>null
  -     * <dt>START_TAG<dd>null
  -     *   unless FEATURE_XML_ROUNDTRIP enabled and then returns XML tag, ex: &lt;tag attr='val'>
  -     * <dt>END_TAG<dd>null
  -     * unless FEATURE_XML_ROUNDTRIP enabled and then returns XML tag, ex: &lt;/tag>
  -     * <dt>TEXT<dd>return unnormalized element content
  +     * <dt>START_TAG<dd>null unless FEATURE_XML_ROUNDTRIP
  +     *   enabled and then returns XML tag, ex: &lt;tag attr='val'>
  +     * <dt>END_TAG<dd>null unless FEATURE_XML_ROUNDTRIP
  +     *  id enabled and then returns XML tag, ex: &lt;/tag>
  +     * <dt>TEXT<dd>return unnormalized (exact as in input) element content if
  +     * FEATURE_UNNORMALIZED_CONTENT is enabled
  +     * otherwise returned content is end-of-line normalized as described
  +     * <a href="http://www.w3.org/TR/REC-xml#sec-line-ends">XML 1.0 End-of-Line Handling</a>
        * <dt>IGNORABLE_WHITESPACE<dd>return unnormalized characters
  +     * if FEATURE_UNNORMALIZED_CONTENT is enabled otherwise
  +     * returned content is end-of-line normalized as described
  +     * <a href="http://www.w3.org/TR/REC-xml#sec-line-ends">XML 1.0 End-of-Line Handling</a>
        * <dt>CDSECT<dd>return unnormalized text <em>inside</em> CDATA
        *  ex. 'fo&lt;o' from &lt;!CDATA[fo&lt;o]]>
        * <dt>PROCESSING_INSTRUCTION<dd>return unnormalized PI content ex: 'pi foo' from &lt;?pi foo?>
  @@ -926,7 +937,11 @@
        * </dd>
        * </dl>
        *
  -     * <p><strong>NOTE:</strong> returned text of token is not end-of-line normalized.
  +     * <p><strong>NOTE:</strong> there is no gurantee that there will only one TEXT
  +     * event from nextToken() as parser may chose to deliver element content in
  +     * multiple TEXT events (dividing element content into chunks)
  +     * <p><strong>NOTE:</strong> returned text of token MAY NOT be end-of-line normalized
  +     *  (depending on FEATURE_UNNORMIZED_XML).
        *
        * @see #next
        * @see #START_TAG