PIRL.Utilities
Class Styled_Multiwriter

java.lang.Object
  java.io.Writer
      PIRL.Utilities.Styled_Multiwriter

All Implemented Interfaces:

Closeable, Flushable, Appendable, Styled_Writer

public class Styled_Multiwriter
extends Writer
implements Styled_Writer

A Styled_Multiwriter is a one-to-many Writer, any of which may be a Styled_Writer.

Writers are wrapped in a Suspendable_Styled_Writer before being added to the list of Writers unless they are already a Suspendable_Styled_Writer.

Each write method is repeated on each Writer in the Writers list. Each Writer is used even if a writer throws an exception. Any exceptions thrown are accumulated in a Multiwriter_IOException which associates the exception thrown with the original Writer source of the exception. A Writer that throws an exception is suspended, except in the case of the close method.

N.B.: If the Writers list is empty each write method will do nothing.

Version:

1.12

Author:

Bradford Castalia - UA/PIRL

See Also:

Writer, Styled_Writer, Suspendable_Styled_Writer

Field Summary

boolean	Add_Enabled Determines whether a Writer is enabled or disabled when it is added to the Writers list.
static String	ID Class identification name with source code version and date.

Fields inherited from class java.io.Writer

lock

Constructor Summary

Styled_Multiwriter()
Construct a Styled_Multiwriter.

Method Summary

boolean	Add(Writer writer) Add a Writer to the list of Writers.
void	close() Close the writers.
boolean	Contains(Writer writer) Test if the list of Writers contains a specified Writer.
Suspendable_Styled_Writer	Entry_for(Writer writer) Get the Writers entry for a Writer that was Added.
Writer	Entry_from(Suspendable_Styled_Writer writer) Get the Writer that was Added from a Writers list entry.
void	flush() Flush the writers.
boolean	Is_Empty() Test if the Writers list is empty.
void	Remove_All() Remove all Writers list entries.
boolean	Remove(Writer writer) Remove a Writer from the list of Writers.
boolean	Suspend(Writer writer, boolean suspend) Turn output suspension on or off for a Writer.
boolean	Suspended(Writer writer) Test if output for a Writer is suspended.
void	write(char[] characters) Write an array of characters.
void	write(char[] characters, int offset, int amount) Write a portion of an array of characters.
void	write(int character) Write a character.
void	write(String string) Write a String.
Styled_Writer	Write(String text) Write plain text.
Styled_Writer	Write(String text, AttributeSet style) Write styled text.
void	write(String string, int offset, int amount) Write a portion of a String.
Vector	Writers() Get a reference to the list of Writers.

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

Field Detail

ID

public static final String ID

Class identification name with source code version and date.

See Also:

Constant Field Values

Add_Enabled

public volatile boolean Add_Enabled

Determines whether a Writer is enabled or disabled when it is added to the Writers list.

Constructor Detail

Styled_Multiwriter

public Styled_Multiwriter()

Construct a Styled_Multiwriter.

Writers have yet to be added.

Method Detail

Add

public boolean Add(Writer writer)

Add a Writer to the list of Writers.

If the Writer is already in the list it is not added. A Writer that is added to the list is wrapped in a Suspendable_Styled_Writer unless it is already an instance of a Suspendable_Styled_Writer.

The addition of the Writer to the Writers list is synchronized on the Writers list.

Parameters:

writer - The Writer to add.

Returns:

true if the Writer was added to the list; false if it was already in the list or is null.

See Also:

Suspendable_Styled_Writer, Remove(Writer)

Remove

public boolean Remove(Writer writer)

Remove a Writer from the list of Writers.

The removal of the Writer from the Writers list is synchronized on the Writers list.

Parameters:

writer - The Writer to remove. This is expected to be a Writer that was Added.

Returns:

true if the Writer was removed to the list; false if it was not in the list or is null.

See Also:

Add(Writer), Entry_for(Writer)

Remove_All

public void Remove_All()

Remove all Writers list entries.

The removal of the Writer from the Writers list is synchronized on the Writers list.

N.B.: The Writers entries are not closed.

See Also:

Add(Writer)

Suspend

public boolean Suspend(Writer writer,
                       boolean suspend)

Turn output suspension on or off for a Writer.

Searching the Writers list for the Writer is synchronized on the Writers list,

Parameters:

writer - The Writer to be affected. This is expected to be a Writer that was Added.

suspend - true if the Writer output is to be suspended; false if output is to be allowed.

Returns:

true If the Writer was found in the Writers list; false otherwise.

See Also:

Suspended(Writer), Entry_for(Writer)

Suspended

public boolean Suspended(Writer writer)

Test if output for a Writer is suspended.

Searching the Writers list for the Writer is synchronized on the Writers list,

Parameters:

writer - The Writer to test. This is expected to be a Writer that was Added.

Returns:

true if the Writer output is suspended or could not be be found in the Writers list; false if the Writer is not suspended. N.B.: Because a Writer that is not in the Writers list will be deemed suspended - it will not produce any output via this object - test if the Writer is contained in the list if the distinction is important.

See Also:

Suspend(Writer, boolean)

Contains

public boolean Contains(Writer writer)

Test if the list of Writers contains a specified Writer.

Searching the Writers list for the Writer is synchronized on the Writers list,

Parameters:

writer - The Writer to test for. This is expected to be a Writer that was Added.

Returns:

true If the Writer is in the Writers list; false otherwise.

See Also:

Entry_for(Writer)

Entry_for

public Suspendable_Styled_Writer Entry_for(Writer writer)

Get the Writers entry for a Writer that was Added.

When a Writer is Added it is wrapped in a Suspendable_Styled_Writer if it is not already an instance of this class. This method searches for the Suspendable_Styled_Writer in the Writers list that is associated with a specified Writer which may or may not have been wrapped by a Suspendable_Styled_Writer before being entered into the list.

Searching the Writers list for the Writer is synchronized on the Writers list,

Parameters:

writer - A Writer. This is expected to be one of the Writer objects that was Added.

Returns:

A Suspendable_Styled_Writer from the Writers list. This will be null if the writer was not found.

Entry_from

public Writer Entry_from(Suspendable_Styled_Writer writer)

Get the Writer that was Added from a Writers list entry.

When a Writer is Added it is wrapped in a Suspendable_Styled_Writer if it is not already an instance of this class. This method searches for the Suspendable_Styled_Writer in the Writers list that is associated with a specified Writer which may or may not have been wrapped by a Suspendable_Styled_Writer before being entered into the list. It then checks this against the list of Suspendable_Styled_Writer objects that were added without being wrapped. If this check succeeds then the Writer that was specified is returned; otherwise the Writer from this specified Suspendable_Styled_Writer is returned.

Searching the Writers list is synchronized on the Writers list,

Parameters:

writer - A Suspendable_Styled_Writer from which to determine the original Writer that was Added.

Returns:

The Writer that was Added, or null if the writer is not in the Writers list.

Is_Empty

public boolean Is_Empty()

Test if the Writers list is empty.

Returns:

true if the Writers list is empty; false otherwise.

Writers

public Vector Writers()

Get a reference to the list of Writers.

The Writers in the list are Suspendable_Styled_Writer objects. When a Writer is Added it is wrapped in a Suspendable_Styled_Writer if it is not already an instance of this class. A Suspendable_Styled_Writer always contains a Writer to which I/O is deferred.

Returns:

A Vector of Suspendable_Styled_Writer objects. N.B.: The returned list is a reference, not a copy. DO NOT MODIFY THE CONTENTS OF THIS LIST!

See Also:

Add(Writer), Remove(Writer)

write

public void write(char[] characters,
                  int offset,
                  int amount)
           throws Multiwriter_IOException

Write a portion of an array of characters.

Iterating over the Writers list is synchronized on the Writers list, and the write to the Writer is synchronized on the Writer.

All Writers are written even if one or more Writers throws an exception.

Specified by:

write in class Writer

Parameters:

characters - The char array containing the characters to be written. If null or empty nothing is done.

offset - Array offset from which to start writing characters.

amount - The number of characters to write. If zero nothing is done.

Throws:

IndexOutOfBoundsException - If the offset or amount are negative or the offset plus the amount is greater than the length of the array.

Multiwriter_IOException - If any Writer throws an exception. A Writer that throws an exception is suspended. The Writers in the exception's Multiwriter_IOException.Sources list are the original Writers that were Added.

See Also:

Suspended(Writer)

write

public void write(char[] characters)
           throws Multiwriter_IOException

Write an array of characters.

Using this method is the same as using write (characters, 0, characters.length).

All Writers are written even if one or more Writers throws an exception.

Overrides:

write in class Writer

Parameters:

characters - The char array containing the characters to be written. If null or empty nothing is done.

Throws:

Multiwriter_IOException - If any Writer throws an exception. A Writer that throws an exception is suspended. The Writers in the exception's Multiwriter_IOException.Sources list are the original Writers that were Added.

write

public void write(int character)
           throws Multiwriter_IOException

Write a character.

Iterating over the Writers list is synchronized on the Writers list, and the write to the Writer is synchronized on the Writer.

All Writers are written even if one or more Writers throws an exception.

Overrides:

write in class Writer

Parameters:

character - The character to be written in the 16 low-order bits..

Throws:

Multiwriter_IOException - If any Writer throws an exception. A Writer that throws an exception is suspended. The Writers in the exception's Multiwriter_IOException.Sources list are the original Writers that were Added.

write

public void write(String string,
                  int offset,
                  int amount)
           throws Multiwriter_IOException

Write a portion of a String.

Using this method is the same as using write (string.toCharArray (), offset, amount).

All Writers are written even if one or more Writers throws an exception.

Overrides:

write in class Writer

Parameters:

string - The String containing the characters to be written. If null or empty nothing is done.

offset - String offset from which to start writing characters.

amount - The number of characters to write. If zero nothing is done.

Throws:

IndexOutOfBoundsException - If the offset or amount are negative or the offset plus the amount is greater than the length of the string.

Multiwriter_IOException - If any Writer throws an exception. A Writer that throws an exception is suspended. The Writers in the exception's Multiwriter_IOException.Sources list are the original Writers that were Added.

See Also:

write(char[], int, int)

write

public void write(String string)
           throws Multiwriter_IOException

Write a String.

Using this method is the same as using write (string, 0, string.length ()).

All Writers are written even if one or more Writers throws an exception.

Overrides:

write in class Writer

Parameters:

string - The String containing the characters to be written. If null or empty nothing is done.

Throws:

Multiwriter_IOException - If any Writer throws an exception. A Writer that throws an exception is suspended. The Writers in the exception's Multiwriter_IOException.Sources list are the original Writers that were Added.

See Also:

write(String, int, int)

flush

public void flush()
           throws Multiwriter_IOException

Flush the writers.

Iterating over the Writers list is synchronized on the Writers list, and the flush to the Writer is synchronized on the Writer.

All Writers are flushed even if one or more Writers throws an exception.

Specified by:

flush in interface Flushable

Specified by:

flush in class Writer

Throws:

Multiwriter_IOException - If any Writer throws an exception. A Writer that throws an exception is suspended. The Writers in the exception's Multiwriter_IOException.Sources list are the original Writers that were Added.

close

public void close()
           throws Multiwriter_IOException

Close the writers.

Iterating over the Writers list is synchronized on the Writers list, and the close of the Writer is synchronized on the Writer.

Specified by:

close in interface Closeable

Specified by:

close in class Writer

Throws:

Multiwriter_IOException - If any Writer throws an exception. All Writers are closed even if one or more Writers throws an exception. The Writers in the exception's Multiwriter_IOException.Sources list are the original Writers that were Added. N.B.: A Writer that throws an exception is not suspended.

Write

public Styled_Writer Write(String text,
                           AttributeSet style)
                    throws Multiwriter_IOException

Write styled text.

Iterating over the Writers list is synchronized on the Writers list, and the Write to the Writer is synchronized on the Writer.

All Writers are written even if one or more Writers throws an exception.

Specified by:

Write in interface Styled_Writer

Parameters:

text - The text String to be written. If null or empty nothing is done.

style - The AttributeSet to be applied to the text. This may be null if plain text is to be displayed.

Returns:

This Styled_Multiwriter

Throws:

Multiwriter_IOException - If any Writer throws an exception. A Writer that throws an exception is suspended. The Writers in the exception's Multiwriter_IOException.Sources list are the original Writers that were Added.

See Also:

Suspendable_Styled_Writer.Write(String, AttributeSet), Styled_Writer.Write(String, AttributeSet)

Write

public Styled_Writer Write(String text)
                    throws Multiwriter_IOException

Write plain text.

This is the same as writing text with a null style.

All Writers are written even if one or more Writers throws an exception.

Specified by:

Write in interface Styled_Writer

Parameters:

text - The text String to be written.

Returns:

This Styled_Multiwriter

Throws:

Multiwriter_IOException - If any Writer throws an exception. A Writer that throws an exception is suspended. The Writers in the exception's Multiwriter_IOException.Sources list are the original Writers that were Added.