Add peeknext() to XMLEventReader

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.