ca.gorman.io
Class WriterStack

java.lang.Object
  java.io.Writer
      ca.gorman.io.WriterStack

All Implemented Interfaces:

Closeable, Flushable, Appendable

Direct Known Subclasses:

ResequencingWriterStack

public class WriterStack
extends Writer

A Writer with additional methods to support nested temporary redirection of the output destination.

WriterStack supports multilevel temporary redirection of output. A stack of Writer objects is itself a Writer and all of its output methods are delegated to the Writer at the top of the stack. That Writer is the current destination. A reference to the stack is always a reference to the current destination, even as the current destination is changed by pushing and popping Writers.

Pushing a Writer on WriterStack makes the new Writer the destination of all output to WriterStack. Popping the Writer from WriterStack restores the previous Writer as the output destination.

All of the Writers below top of stack are maintained in a flushed state to ensure that the sequence of output from the Writers will be identical to the sequence of input to the WriterStack. This invariant is maintained by causing each push and pop to flush the top of stack before adding or removing a Writer. However, the invariant is violated when a ResequencingWriter is on the WriterStack, because the ResequencingWriter flush violates the contract of Writer.flush.

WriterStack always has a destination because the default Writer becomes the current destination when the stack is empty.

Field Summary

Fields inherited from class java.io.Writer

lock

Constructor Summary

WriterStack(Writer writer)
Create new WriterStack with a default Writer.

Method Summary

void	close() Close all Writers on the WriterStack.
void	flush() Flush the WriterStack.
boolean	isEmpty() Test if stack is empty.
protected Writer	peek() Return the Writer (and current destination) at the top of WriterStack.
Writer	pop() Pop and return the Writer at the top of WriterStack.
void	push(Writer writer) Push a Writer on the WriterStack.
int	size() Get the number of Writers currently pushed on the WriterStack.
void	write(char[] ch) Write an array of characters to the current destination.
void	write(char[] ch, int offset, int length) Write a subarray of characters to the current destination.
void	write(int ch) Write one character to the current destination.
void	write(String str) Write a string to the current destination.
void	write(String str, int offset, int length) Write a substring to the current destination.

Methods inherited from class java.io.Writer

append, append, append

Methods inherited from class java.lang.Object

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

Constructor Detail

WriterStack

public WriterStack(Writer writer)

Create new WriterStack with a default Writer. The default destination is the current destination when the WriterStack is empty.

Throws:

NullPointerException - when writer is null;

Method Detail

push

public void push(Writer writer)
          throws IOException

Push a Writer on the WriterStack. The Writer currently at top of stack will be flushed before the new Writer is pushed.

The new Writer becomes the output destination, until the previous destination is restored by popping the new Writer.

Throws:

NullPointerException - when writer is null;

IOException - if the Writer previously at top of stack throws the exception when flushed.

pop

public Writer pop()
           throws EmptyStackException,
                  IOException

Pop and return the Writer at the top of WriterStack. The Writer will be flushed before it is popped.

The Writer under the popped Writer will become the destination.

Throws:

EmptyStackException - when there is the only remaining destination is the Default Writer (which cannot be popped).

IOException - if the Writer currently at top of stack throws the exception when flushed.

UnsupportedOperationException - when writer is a Resequencer and Resequencer.isFlushThrowsException() returns true;

peek

protected Writer peek()

Return the Writer (and current destination) at the top of WriterStack.

isEmpty

public boolean isEmpty()

Test if stack is empty. The Writer used to construct WriterStack cannot be popped, so this method will return true when the only Writer is the default Writer.

size

public int size()

Get the number of Writers currently pushed on the WriterStack. The Default Writer is not included in the count.

close

public void close()
           throws IOException

Close all Writers on the WriterStack. All the Writers will remain on the WriterStack until they are popped.

Specified by:

close in interface Closeable

Specified by:

close in class Writer

Throws:

IOException

flush

public void flush()
           throws IOException

Flush the WriterStack.

Writers below the top of stack are already flushed by the push operation, so only the top Writer will be flushed.

Specified by:

flush in interface Flushable

Specified by:

flush in class Writer

Throws:

IOException

write

public void write(int ch)
           throws IOException

Write one character to the current destination.

Overrides:

write in class Writer

Throws:

IOException

write

public void write(char[] ch)
           throws IOException

Write an array of characters to the current destination.

Overrides:

write in class Writer

Throws:

IOException

write

public void write(char[] ch,
                  int offset,
                  int length)
           throws IOException

Write a subarray of characters to the current destination.

Specified by:

write in class Writer

Throws:

IOException

write

public void write(String str)
           throws IOException

Write a string to the current destination.

Overrides:

write in class Writer

Throws:

IOException

write

public void write(String str,
                  int offset,
                  int length)
           throws IOException

Write a substring to the current destination.

Overrides:

write in class Writer

Throws:

IOException