PIRL.Utilities

## Class Styled_Multiwriter

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

All Implemented Interfaces:
  Closeable, Flushable, Appendable, AutoCloseable, 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.

See Also:
  `Writer`, `Styled_Writer`, `Suspendable_Styled_Writer`

### Field Summary

Fields
`boolean` `Add_Enabled` Determines whether a Writer is enabled or disabled when it is `add`ed 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

Constructors
Constructor and Description
`Styled_Multiwriter()` Construct a Styled_Multiwriter.

### Method Summary

Methods
`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 `Add`ed.
`Writer` `Entry_from(Suspendable_Styled_Writer writer)` Get the Writer that was `Add`ed 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 `add`ed to the Writers list.

### Constructor Detail

#### Styled_Multiwriter

    public Styled_Multiwriter()

Construct a Styled_Multiwriter.

Writers have yet to be `add`ed.

### 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 `Add`ed.
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 `Add`ed.
  `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 `Add`ed.
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 `Add`ed.
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 `Add`ed.

When a Writer is `Add`ed 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 `Add`ed.
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 `Add`ed from a `Writers` list entry.

When a Writer is `Add`ed 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 `Add`ed.
Returns:
  The Writer that was `Add`ed, 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 `Add`ed 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 `suspend`ed. The Writers in the exception's `Multiwriter_IOException.Sources` list are the original Writers that were `Add`ed.
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 `suspend`ed. The Writers in the exception's `Multiwriter_IOException.Sources` list are the original Writers that were `Add`ed.

#### 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 `suspend`ed. The Writers in the exception's `Multiwriter_IOException.Sources` list are the original Writers that were `Add`ed.

#### 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 `suspend`ed. The Writers in the exception's `Multiwriter_IOException.Sources` list are the original Writers that were `Add`ed.
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 `suspend`ed. The Writers in the exception's `Multiwriter_IOException.Sources` list are the original Writers that were `Add`ed.
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 `suspend`ed. The Writers in the exception's `Multiwriter_IOException.Sources` list are the original Writers that were `Add`ed.

#### 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 interface `AutoCloseable`
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 `Add`ed. 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 `suspend`ed. The Writers in the exception's `Multiwriter_IOException.Sources` list are the original Writers that were `Add`ed.
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 `suspend`ed. The Writers in the exception's `Multiwriter_IOException.Sources` list are the original Writers that were `Add`ed.