Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8219511

Add peeknext() to XMLEventReader

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Withdrawn
    • Fix Version/s: 13
    • Component/s: xml
    • Labels:
      None
    • Subcomponent:
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      low
    • Compatibility Risk Description:
      Hide
      The compatibility risk is low overall.

      Corresponding to the proposed changes in the Solution section:

      1. Has no compatibility risk. The new peekNext() method does not change existing behavior.

      2. Has low compatibility risk. Fixing the implementation would result in the peek method to not change the current event. The current behavior that causes the reader to advance the cursor from the current event is unexpected, and should not have been dependent upon by an application.

      3. Has no compatibility risk. This change involves a clarification of the javadoc only.
      Show
      The compatibility risk is low overall. Corresponding to the proposed changes in the Solution section: 1. Has no compatibility risk. The new peekNext() method does not change existing behavior. 2. Has low compatibility risk. Fixing the implementation would result in the peek method to not change the current event. The current behavior that causes the reader to advance the cursor from the current event is unexpected, and should not have been dependent upon by an application. 3. Has no compatibility risk. This change involves a clarification of the javadoc only.
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      Summary

      Add peekNext() method to the javax.xml.stream.XMLEventReader interface.

      Problem

      There are three issues this CSR attempts to resolve.

      1. Limitation of the existing peek method

        StAX defines a Streaming API where XML infosets are transmitted and parsed serially. The XML stream is read from the beginning to end in one pass as requested, in other words, a StAX reader moves the cursor in one direction that can not be moved back. At any given time, the StAX reader's cursor points at the current event. For cases where the knowledge of the infosets down the stream is needed, StAX provides a peek method.

        The issue with the existing peek() method is that it checks only the first event immediately after the current event. This limitation led to an incorrect implementation of the peeking process when an EventFilter is employed. In such a case, the current implementation had to actually move the cursor down the stream, and that violates the contract of the peek() method.

      2. Violation to the peek specification

        The implementation of the peek method violates the specification when it needs to peek more events down the stream. Due to the limitation stated above, in order to peek into the stream for more than one event, it resolved to actually advance the cursor by calling the nextEvent() method. This is manifested by adding an EventFilter to the process, which expands the peek method's ability to being able to peek into the stream further until a desirable event is found.

      3. Incorrect statement in peek's javadoc

        The javadoc for the peek method contains incorrect information. While the behavior it defined is largely comprehensible, the statement that says it checks the next XMLEvent "without reading it from the stream" is literally incorrect.

      Solution

      1. Add a new peekNext method

        To maintain compatibility, the proposal is to keep the existing peek() method as is, but add a new method peekNext() that will be defined as having the ability to continue searching down the stream until a desirable event is found.

      2. Fix the implementation of the peek method

        The implementation of the peek method shall be fixed to not advance the event reader's cursor in all cases.

      3. Clarification of peek's javadoc

        The javadoc for the peek method will be clarified to explain that the event reader's cursor remains pointing at the current event after a call to the method.

      Specification

      The specdiff for the proposed change can be viewed at: http://cr.openjdk.java.net/~joehw/jdk13/8177872/specdiff_07/javax/xml/stream/XMLEventReader.html

      A zip file of the specdiff is attached.

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                joehw Joe Wang
                Reporter:
                webbuggrp Webbug Group
                Reviewed By:
                Daniel Fuchs, Lance Andersen
              • Votes:
                0 Vote for this issue
                Watchers:
                4 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: