Package javanet.staxutils

Class XMLEventPipe

java.lang.Object
javanet.staxutils.XMLEventPipe
public class XMLEventPipe extends Object
Provides the ability to pipe the XMLEvents written to one XMLEventWriter to be read from a XMLEventReader. The implementation is based on a bounded-buffer with a specifiable maximum capacity. When that capacity is reached, the write end of the pipe will block until events are read from the read end. Similarly, when an attempt is made to read from an empty queue, the operation will block until more events are written to the buffer. The write end of the pipe will repair namespaces and buffer attribute/namespace events as defined in the specification of the XMLEventWriter interface.

Both the read and write ends of this pipe are fully synchronized to allow multiple threads to read or write events to the pipe. However, care must be taken that the order of events is consistent, and that the stream is properly closed when writing is complete. If the write end is never closed the read end may block indefinitely, waiting for further events. To help prevent this, the write end will automatically close when an END_DOCUMENT event is written.

To properly obey the expected behaviour of XMLEventReader and XMLStreamWriter, methods such as XMLEventReader.peek() and XMLEventReader.hasNext() may block. This is necessary to prevent XMLEventReader.hasNext() from returning true just before the write end is closed, or false just before additional events are added. If the read end is closed before the writer, then the write end will silently discard all elements written to it until it is closed.
Version:
$Revision: 1.2 $
Author:
Christian Niles

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    QUEUE_CAPACITY
    Default maximum number of events that may be stored by this pipe until the write end blocks.

  • Constructor Summary

    Constructors
    Constructor
    Description
    XMLEventPipe()
    Constructs a new XMLEventPipe with the default capacity.
    XMLEventPipe(int capacity)
    Constructs a new XMLEventPipe with the specified capacity.

  • Method Summary

    Modifier and Type
    Method
    Description
    XMLEventReader
    getReadEnd()
    Returns the read end of the pipe, from which events written to the write end of the pipe will be available.
    XMLEventWriter
    getWriteEnd()
    Returns the write end of the pipe, whose events will be available from the read end of this pipe.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • QUEUE_CAPACITY

      public static final int QUEUE_CAPACITY
      Default maximum number of events that may be stored by this pipe until the write end blocks.
      See Also:

  • Constructor Details

    • XMLEventPipe

      public XMLEventPipe()
      Constructs a new XMLEventPipe with the default capacity.

    • XMLEventPipe

      public XMLEventPipe(int capacity)
      Constructs a new XMLEventPipe with the specified capacity.
      Parameters:
      capacity - The number of events to buffer until the pipe will block. A number less than or equal to 0 means the pipe will buffer an unbounded number of events.

  • Method Details

    • getReadEnd

      public XMLEventReader getReadEnd()
      Returns the read end of the pipe, from which events written to the write end of the pipe will be available.
      Returns:
      The read end of the pipe.

    • getWriteEnd

      public XMLEventWriter getWriteEnd()
      Returns the write end of the pipe, whose events will be available from the read end of this pipe.
      Returns:
      The write end of the pipe.