ca.gorman.io
Interface Resequencer<K>

All Known Implementing Classes:

ResequencingWriter, ResequencingWriterStack

public interface Resequencer<K>

Interface for Writers that support pseudo-random access to the output stream.

A Writer with the Resequencer interface accepts characters in the same way as any Writer, and will also accept a Mark to mark a place for data that will be supplied at a different time. This makes a Writer almost as flexible as a random-access file, because an application can set the location of data in the output stream at one time, but write the data at a different time.

The entire stream of characters and Marks is held within Writer until the Writer is closed. Then the marks are replaced by the data that they represent and all data is written to the final destination. The data for any Mark can be changed at any time before the Writer is closed, because replacement and final output only occurs when the Writer is closed.

A Resequencer violates the flush contract because no output goes to the final destination until the Resequencer is closed.

Nested Class Summary

static class	Resequencer.Buffer<K> Buffer to hold Marks with keys of type K and character data until all character data have been written, and all Marks have been associated with data values.
static class	Resequencer.Mark<K> Associates data with a key of type K and contains other internal data to support efficient operation.
static class	Resequencer.MarkGroup<K> Manager (access and temporary storage) for Marks with keys of type K .
static class	Resequencer.SpillBuffer Overflow buffer for Buffer, when the amount of data exceeds the capacity of the fast buffer used by Buffer.

Method Summary

Resequencer.Mark<K>	getMark(K key) Get an existing Mark.
Resequencer.MarkGroup<K>	getMarkGroup() Get the MarkGroup used by this Resequencer.
boolean	isFlushThrowsException() Indicate whether flush will throw UnsupportedOperationException or fail silently (the default).
Resequencer.Mark<K>	mark() Create a Mark without a key.
Resequencer.Mark<K>	mark(K key) Get the Mark for a specific key, creating a new Mark if one does not already exist.
void	setFlushThrowsException(boolean b) Choose whether flush will throw UnsupportedOperationException or fail silently (the default).
void	write(Resequencer.Mark<K> mark) Write a Mark representing data that will be supplied at some other time.
void	writeMark(K key) Write a Mark representing data that will be supplied at some other time, creating a new Mark if one does not already exist.

Method Detail

getMarkGroup

Resequencer.MarkGroup<K> getMarkGroup()

Get the MarkGroup used by this Resequencer.

getMark

Resequencer.Mark<K> getMark(K key)

Get an existing Mark.

This method should be delegated to the Buffer that supports the Resequencer.

Throws:

NullPointerException - if key is null

NoSuchElementException - if a Mark does not exist for the key.

mark

Resequencer.Mark<K> mark()

Create a Mark without a key. This method returns a new Mark each time it is invoked. The only way to obtain the same Mark again is to assign it to a variable for later use.

This method should be delegated to the Buffer that supports the Resequencer.

mark

Resequencer.Mark<K> mark(K key)

Get the Mark for a specific key, creating a new Mark if one does not already exist. This method returns the same Mark each time it is invoked with the same key.

This method should be delegated to the Buffer that supports the Resequencer.

Parameters:

key - Identifies the mark to be retrieved or created

Throws:

NullPointerException - if key is null

writeMark

void writeMark(K key)
               throws IOException

Write a Mark representing data that will be supplied at some other time, creating a new Mark if one does not already exist. The Mark will be replaced by data when this Resequencer is closed.

This method should be delegated to the Buffer that supports the Resequencer.

Parameters:

key - the key that identifies the place mark within the MarkGroup used by this Resequencer

Throws:

NullPointerException - if key is null

IOException

write

void write(Resequencer.Mark<K> mark)
           throws IOException

Write a Mark representing data that will be supplied at some other time. The Mark will be replaced by data when this Resequencer is closed.

This method should be delegated to the Buffer that supports the Resequencer.

Parameters:

mark - The Mark to be written,

Throws:

NullPointerException - if mark is null

IOException

isFlushThrowsException

boolean isFlushThrowsException()

Indicate whether flush will throw UnsupportedOperationException or fail silently (the default). A Resequencer cannot be flushed because it retains all data until the supporting Writer is closed.

Returns:

true if flush will throw UnsupportedOperationException, false if flush will be ignored.

See Also:

setFlushThrowsException(boolean)

setFlushThrowsException

void setFlushThrowsException(boolean b)

Choose whether flush will throw UnsupportedOperationException or fail silently (the default). A Resequencer cannot be flushed because it retains all data until the supporting Writer is closed.

Parameters:

b - true to throw UnsupportedOperationException, false (default) to simply ignore flush.

See Also:

isFlushThrowsException()