PIRL.Messenger

## Class Messenger_Styled_Writer

- java.lang.Object
- - java.io.Writer
  - - PIRL.Messenger.Messenger_Styled_Writer

All Implemented Interfaces:
  Closeable, Flushable, Appendable, AutoCloseable, Styled_Writer

    public class Messenger_Styled_Writer
    extends Writer
    implements Styled_Writer

A Messenger_Styled_Writer is a Writer that encapsulates what is written, along with Styled_Writer information, into a Message that is sent via a Messenger.

Each write operation produces a Message that is sent to the Messenger to which a Messenger_Styled_Writer is bound. The Message contains a "Write" Action parameter and a "Written" parameter with a string value that is what was written. Styled_Writer information, if present, is contained in a "Style" Aggregate parameter in which each member describes style properties.

Messages are routed by the Messenger according to the route-to address list that may be provided. If no route-to list is provided Messages that are sent will be delivered to the receiving Messenger's Employer.

No buffering is done; each write operation causes a message to be immediately sent.

Message sending may be suspended. While a Messenger_Styled_Writer is suspended all write operations have no effect. Argument parameters will still be checked for validity, where applicable.

See Also:
  `Writer`, `Messenger`, `Message`

### Field Summary

Fields
`static String` `ALIGNMENT_NAME` Recognized `STYLE_PARAMETER_GROUP` parameter names.
`static String` `BACKGROUND_NAME` Recognized `STYLE_PARAMETER_GROUP` parameter names.
`static String` `BIDI_LEVEL_NAME` Recognized `STYLE_PARAMETER_GROUP` parameter names.
`static String` `BOLD_NAME` Recognized `STYLE_PARAMETER_GROUP` parameter names.
`static String` `FIRST_LINE_INDENT_NAME` Recognized `STYLE_PARAMETER_GROUP` parameter names.
`static String` `FONT_FAMILY_NAME` Recognized `STYLE_PARAMETER_GROUP` parameter names.
`static String` `FONT_SIZE_NAME` Recognized `STYLE_PARAMETER_GROUP` parameter names.
`static String` `FOREGROUND_NAME` Recognized `STYLE_PARAMETER_GROUP` parameter names.
`static String` `ID` Class identification name with source code version and date.
`static String` `ITALIC_NAME` Recognized `STYLE_PARAMETER_GROUP` parameter names.
`static String` `LEFT_INDENT_NAME` Recognized `STYLE_PARAMETER_GROUP` parameter names.
`static String` `LINE_SPACING_NAME` Recognized `STYLE_PARAMETER_GROUP` parameter names.
`static String` `RIGHT_INDENT_NAME` Recognized `STYLE_PARAMETER_GROUP` parameter names.
`static String` `SPACE_ABOVE_NAME` Recognized `STYLE_PARAMETER_GROUP` parameter names.
`static String` `SPACE_BELOW_NAME` Recognized `STYLE_PARAMETER_GROUP` parameter names.
`static String` `STRIKETHROUGH_NAME` Recognized `STYLE_PARAMETER_GROUP` parameter names.
`static String` `STYLE_PARAMETER_GROUP` The name of the Parameter Group that contains the style parameters.
`static String` `SUBSCRIPT_NAME` Recognized `STYLE_PARAMETER_GROUP` parameter names.
`static String` `SUPERSCRIPT_NAME` Recognized `STYLE_PARAMETER_GROUP` parameter names.
`boolean` `Suspended` The suspension state of the Writer.
`static String` `TAB_SET_NAME` Recognized `STYLE_PARAMETER_GROUP` parameter names.
`static String` `UNDERLINE_NAME` Recognized `STYLE_PARAMETER_GROUP` parameter names.
`static String` `WRITE_ACTION` The `Message.ACTION_PARAMETER_NAME` value that identifies the Message sent to the Messenger as coming from a Messenger_Styled_Writer.
`static String` `WRITTEN_PARAMETER_NAME` The name of the Message parameter whose value is what was written.

### Fields inherited from class java.io.Writer

`lock`

### Constructor Summary

Constructors
Constructor and Description
`Messenger_Styled_Writer(Messenger messenger)` Construct a Messenger_Styled_Writer on a Messenger.
`Messenger_Styled_Writer(Messenger messenger, Value route)` Construct a Messenger_Styled_Writer on a Messenger with a Message route address list.

### Method Summary

Methods
`void` `close()` Close the writer.
`boolean` `Closed()` Test if this Messenger_Styled_Writer is capable of sending write messages.
`void` `flush()` Flush the writers.
`static Parameter` `Parameter_Style(AttributeSet style)` Generate a Parameter that specifies a set of text styles.
`Value` `Route()` Get the message route address list.
`Messenger_Styled_Writer` `Route(Value route)` Set the message route address list.
`static SimpleAttributeSet` `Style_Parameter(Parameter group)` Generate a SimpleAttributeSet from a Parameter Aggregate that specifies a set of text style attributes.
`Messenger_Styled_Writer` `Suspend(boolean suspend)` Turn output suspension on or off.
`boolean` `Suspended()` Test if output has been 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.
`Messenger_Styled_Writer` `Write(String string)` Write a plain String.
`Messenger_Styled_Writer` `Write(String string, AttributeSet style)` Write a styled String.
`void` `write(String string, int offset, int amount)` Write a portion of a String.
`Messenger` `Writer_Messenger()` Get the Messenger used to send what is written.

### 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

#### WRITE_ACTION

    public static final String WRITE_ACTION

The `Message.ACTION_PARAMETER_NAME` value that identifies the Message sent to the Messenger as coming from a Messenger_Styled_Writer.

See Also:
  Constant Field Values

#### WRITTEN_PARAMETER_NAME

    public static final String WRITTEN_PARAMETER_NAME

The name of the Message parameter whose value is what was written.

See Also:
  Constant Field Values

#### STYLE_PARAMETER_GROUP

    public static final String STYLE_PARAMETER_GROUP

The name of the Parameter Group that contains the style parameters.

See Also:
  Constant Field Values

#### Suspended

    public volatile boolean Suspended

The suspension state of the Writer.

#### ALIGNMENT_NAME

    public static final String ALIGNMENT_NAME

Recognized `STYLE_PARAMETER_GROUP` parameter names.

#### BACKGROUND_NAME

    public static final String BACKGROUND_NAME

Recognized `STYLE_PARAMETER_GROUP` parameter names.

#### BIDI_LEVEL_NAME

    public static final String BIDI_LEVEL_NAME

Recognized `STYLE_PARAMETER_GROUP` parameter names.

#### BOLD_NAME

    public static final String BOLD_NAME

Recognized `STYLE_PARAMETER_GROUP` parameter names.

#### FIRST_LINE_INDENT_NAME

    public static final String FIRST_LINE_INDENT_NAME

Recognized `STYLE_PARAMETER_GROUP` parameter names.

#### FONT_FAMILY_NAME

    public static final String FONT_FAMILY_NAME

Recognized `STYLE_PARAMETER_GROUP` parameter names.

#### FONT_SIZE_NAME

    public static final String FONT_SIZE_NAME

Recognized `STYLE_PARAMETER_GROUP` parameter names.

#### FOREGROUND_NAME

    public static final String FOREGROUND_NAME

Recognized `STYLE_PARAMETER_GROUP` parameter names.

#### ITALIC_NAME

    public static final String ITALIC_NAME

Recognized `STYLE_PARAMETER_GROUP` parameter names.

#### LEFT_INDENT_NAME

    public static final String LEFT_INDENT_NAME

Recognized `STYLE_PARAMETER_GROUP` parameter names.

#### LINE_SPACING_NAME

    public static final String LINE_SPACING_NAME

Recognized `STYLE_PARAMETER_GROUP` parameter names.

#### RIGHT_INDENT_NAME

    public static final String RIGHT_INDENT_NAME

Recognized `STYLE_PARAMETER_GROUP` parameter names.

#### SPACE_ABOVE_NAME

    public static final String SPACE_ABOVE_NAME

Recognized `STYLE_PARAMETER_GROUP` parameter names.

#### SPACE_BELOW_NAME

    public static final String SPACE_BELOW_NAME

Recognized `STYLE_PARAMETER_GROUP` parameter names.

#### STRIKETHROUGH_NAME

    public static final String STRIKETHROUGH_NAME

Recognized `STYLE_PARAMETER_GROUP` parameter names.

#### SUBSCRIPT_NAME

    public static final String SUBSCRIPT_NAME

Recognized `STYLE_PARAMETER_GROUP` parameter names.

#### SUPERSCRIPT_NAME

    public static final String SUPERSCRIPT_NAME

Recognized `STYLE_PARAMETER_GROUP` parameter names.

#### TAB_SET_NAME

    public static final String TAB_SET_NAME

Recognized `STYLE_PARAMETER_GROUP` parameter names.

#### UNDERLINE_NAME

    public static final String UNDERLINE_NAME

Recognized `STYLE_PARAMETER_GROUP` parameter names.

### Constructor Detail

#### Messenger_Styled_Writer

    public Messenger_Styled_Writer(Messenger messenger,
                           Value route)

Construct a Messenger_Styled_Writer on a Messenger with a Message route address list.

N.B.: Unless the messenger `is connected` to its communication channel this Messenger_Styled_Writer will be initially `closed` and thus useless.

Parameters:
  `messenger` - The Messenger to which Writer Messages will be sent.
  `route` - An Array Value containing the route-to address list to be used when sending Messages. If null no message routing will be used.
Throws:
  `IllegalArgumentException` - If the messenger is null or the route is not an Array of address Strings.

#### Messenger_Styled_Writer

    public Messenger_Styled_Writer(Messenger messenger)

Construct a Messenger_Styled_Writer on a Messenger.

Unless the Messenger `is connected` to its communication channel this Messenger_Styled_Writer will be initially `closed` and thus useless.

<b.N.B.: No Message routing will be used; Messages sent will be delivered to the receiving Messenger's Employer rather than being forwarded to another Messenger.

Parameters:
  `messenger` - The Messenger to which Writer Messages will be sent.
Throws:
  `IllegalArgumentException` - If the messenger is null.

### Method Detail

#### Writer_Messenger

    public Messenger Writer_Messenger()

Get the Messenger used to send what is written.

Returns:
  A Messenger.

#### Route

    public Value Route()

Get the message route address list.

Returns:
  A Value that contains a copy of the message route address list.

#### Route

    public Messenger_Styled_Writer Route(Value route)
                                  throws PVL_Exception

Set the message route address list.

Parameters:
  `route` - An Array Value containing the route-to address list to be used when sending Messages. If null no message routing will be used. The Value is copied.
Returns:
  This Messenger_Styled_Writer.
Throws:
  `PVL_Exception` - If the route is not an Array of STRING type Values.

#### Suspended

    public boolean Suspended()

Test if output has been suspended.

Returns:
  true if output has been suspended; false otherwise.

#### Suspend

    public Messenger_Styled_Writer Suspend(boolean suspend)

Turn output suspension on or off.

Parameters:
  `suspend` - If true subsequent output will be suspended; if false output will occur.
Returns:
  This Messenger_Styled_Writer.

#### Closed

    public boolean Closed()

Test if this Messenger_Styled_Writer is capable of sending write messages.

Returns:
  true if the `Messenger` bound to this Messenger_Styled_Writer is no longer `connected` to it communication channel; false if this Messenger_Styled_Writer is currently able to write to its Messenger.

#### write

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

Write a portion of an array of characters.

If the characters array is null or zero length, or the amount to write is zero, nothing is done.

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.
  `IOException` - If the write message could not be sent. This will be an EOFException if this Messenger_Styled_Writer is `closed`.

#### write

    public void write(char[] characters)
               throws IOException

Write an array of characters.

If the characters array is null or zero length nothing is done.

Overrides:
  `write` in class `Writer`
Parameters:
  `characters` - The char array containing the characters to be written. If null or empty nothing is done.
Throws:
  `IOException` - If the write message could not be sent. This will be an EOFException if this Messenger_Styled_Writer is `closed`.

#### write

    public void write(int character)
               throws IOException

Write a character.

N.B.: Characters are not buffered so writing characters one at a time, rather than `as an array` or `string`, is very inefficient.

Overrides:
  `write` in class `Writer`
Parameters:
  `character` - The character to be written in the 16 low-order bits.
Throws:
  `IOException` - If the write message could not be sent. This will be an EOFException if this Messenger_Styled_Writer is `closed`.

#### write

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

Write a portion of a String.

If the string is null or zero length, or the amount to write is zero, nothing is done.

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.
  `IOException` - If the write message could not be sent. This will be an EOFException if this Messenger_Styled_Writer is `closed`.

#### write

    public void write(String string)
               throws IOException

Write a String.

Overrides:
  `write` in class `Writer`
Parameters:
  `string` - The String containing the characters to be written. If null or empty nothing is done.
Throws:
  `IOException` - If the write message could not be sent. This will be an EOFException if this Messenger_Styled_Writer is `closed`.

#### flush

    public void flush()

Flush the writers.

Because no buffering is done flush has no effect.

Specified by:
  `flush` in interface `Flushable`
Specified by:
  `flush` in class `Writer`

#### close

    public void close()

Close the writer.

This method has no effect. Because writing is done by sending Messages via the `Messenger` bound to this Messenger_Styled_Writer, and the Messenger may be in use by other objects, its communication channel should not be disconnected by the Messenger_Styled_Writer. To disconnect the Messenger tell it that it is `done`.

Specified by:
  `close` in interface `Closeable`
Specified by:
  `close` in interface `AutoCloseable`
Specified by:
  `close` in class `Writer`
See Also:
  `Closed()`

#### Write

    public Messenger_Styled_Writer Write(String string,
                                AttributeSet style)
                                  throws IOException

Write a styled String.

The AttributeSet used to specify the display style may be generated using the StyleConstants functions. For example:

>     SimpleAttributeSet style;
>     StyleConstants.setBold (style, true);
>     StyleConstants.setForeground (style, Color.RED);

The following styles, indicated by their StyleConstants functions, are recognized by a Messenger_Styled_Writer:

- setAlignment
- setBackground
- setBidiLevel
- setBold
- setFirstLineIndent
- setFontFamily
- setFontSize
- setForeground
- setItalic
- setLeftIndent
- setLineSpacing
- setRightIndent
- setSpaceAbove
- setSpaceBelow
- setStrikeThrough
- setSubscript
- setSuperscript
- setTabSet
- setUnderline

Specified by:
  `Write` in interface `Styled_Writer`
Parameters:
  `string` - The String containing the characters to be written. If null or empty nothing is done.
  `style` - An AttributeSet describing the style to be used when displaying the text. If null, no style will be applied.
Returns:
  This Styled_Writer
Throws:
  `IOException` - If the Write message could not be sent. This will be an EOFException if this Messenger_Styled_Writer is `closed`.
See Also:
  `StyleConstants`, `SimpleAttributeSet`

#### Write

    public Messenger_Styled_Writer Write(String string)
                                  throws IOException

Write a plain String.

Using this method is the same a using `Write(String, AttributeSet)` with a null style, or using (@link #write(String)}.

Specified by:
  `Write` in interface `Styled_Writer`
Parameters:
  `string` - The String containing the characters to be written. If null or empty nothing is done.
Returns:
  This Styled_Writer
Throws:
  `IOException` - If the write message could not be sent. This will be an EOFException if this Messenger_Styled_Writer is `closed`.

#### Parameter_Style

    public static Parameter Parameter_Style(AttributeSet style)

Generate a Parameter that specifies a set of text styles.

The set of style attributes is represented by a `STYLE_PARAMETER_GROUP` Parameter Aggregate in which each style attribute is reprented by Pararmeter tht the name of the attribute and its Assignment Value has the value of the attribute.

Parameters:
  `style` - An AttributeSet containing a set of text style attributes. If null, null is returned.
Returns:
  A Parameter Aggregate specifying each style attribute.
See Also:
  `Style_Parameter(Parameter)`

#### Style_Parameter

    public static SimpleAttributeSet Style_Parameter(Parameter group)

Generate a SimpleAttributeSet from a Parameter Aggregate that specifies a set of text style attributes.

The name of each Parameter in the Aggregate is mapped to a StyleConstants function that is used to set an attribute in a SimpleAttributeSet using the Value of the Parameter. The following attribute names are recognized as text style specification Parameter names:

- `ALIGNMENT_NAME`
- `BACKGROUND_NAME`
- `BIDI_LEVEL_NAME`
- `BOLD_NAME`
- `FIRST_LINE_INDENT_NAME`
- `FONT_FAMILY_NAME`
- `FONT_SIZE_NAME`
- `FOREGROUND_NAME`
- `ITALIC_NAME`
- `LEFT_INDENT_NAME`
- `LINE_SPACING_NAME`
- `RIGHT_INDENT_NAME`
- `SPACE_ABOVE_NAME`
- `SPACE_BELOW_NAME`
- `STRIKETHROUGH_NAME`
- `SUBSCRIPT_NAME`
- `SUPERSCRIPT_NAME`
- `TAB_SET_NAME`
- `UNDERLINE_NAME`

  Parameters that have unrecognized names or that are not an Assignment of the appropriate Value are ignored.

Parameters:
  `group` - A Parameter Aggregate containing a list of text style specification Parameters.
Returns:
  A SimpleAttributeSet contained a set of text styles.
See Also:
  `Parameter_Style(AttributeSet)`