PIRL.Messenger
Class Messenger_Styled_Writer

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

All Implemented Interfaces:

Closeable, Flushable, Appendable, 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.

Version:

1.13

Author:

Bradford Castalia - UA/PIRL

See Also:

Writer, Messenger, Message

Field Summary

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

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

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.

: 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 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)