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 and Description
static int	QUEUE_CAPACITY Default maximum number of events that may be stored by this pipe until the write end blocks.

Constructor Summary

Constructors

Constructor and 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 and 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 Detail

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:

Constant Field Values

Constructor Detail

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 Detail

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.