PIRL.Messenger

## Class Message

- java.lang.Object
- - javax.swing.tree.DefaultMutableTreeNode
  - - PIRL.PVL.Parameter
    - - PIRL.Messenger.Message

All Implemented Interfaces:
  Serializable, Cloneable, MutableTreeNode, TreeNode

Direct Known Subclasses:
  Conductor_Definition

    public class Message
    extends Parameter

A Message contains a message and its routing information.

A Message is a Parameter Aggregate and the message routing information. A Message is typically managed by a Messenger.

See Also:
  `Parameter`, `Messenger`, Serialized Form

### Field Summary

Fields
`static String` `ACK_ACTION` Acknowledgment Message `ACTION_PARAMETER_NAME` value.
`static String` `ACTION_PARAMETER_NAME` A Message parameter specifying the action associated with the message.
`static String` `CLASS_ID_PARAMETER_NAME` Class ID parameter name.
`static String` `CONTENT_AMOUNT_PARAMETER_NAME` A label parameter of a transmitted message with a value that is the number of message label characters to follow.
`static String` `DONE_ACTION` End of messaging - no further messages can be expected - Message `ACTION_PARAMETER_NAME` value.
`static char` `ERROR_MESSAGE_MARKER` Marks the first character of a Message `String representation` when there was a problem rendering the Message content into valid PVL syntax.
`static String` `ID` Class identification name with source code version and date.
`static String` `IDENTIFY_ACTION` Identify request Message `ACTION_PARAMETER_NAME` value.
`static String` `IDENTITY_ACTION` Identity Message `ACTION_PARAMETER_NAME` value.
`static String` `NACK_ACTION` Negative acknowledgment Message `ACTION_PARAMETER_NAME` value.
`static String` `NAME_PARAMETER_NAME` Sender name in an `IDENTIFY_ACTION` or `IDENTITY_ACTION` action Message.
`static String` `ROUTE_FROM_PARAMETER_NAME` A label parameter of a transmitted message with a value that is the Message `route-from list`.
`static String` `ROUTE_TO_PARAMETER_NAME` A label parameter of a transmitted message with a value that is the Message `route-to list`.
`static String` `START_MARKER` Synchronization sequence at the beginning of a trasmitted message.
`static char` `START_MARKER_DELIMITER` Separates the label `START_MARKER` from its label size value in a transmitted message.
`static char` `START_MARKER_END` Marks the end of the message label size value and the required message transmission start sequence.

### Fields inherited from class PIRL.PVL.Parameter

`AGGREGATE, ASSIGNMENT, BEGIN_GROUP, BEGIN_OBJECT, END, END_AGGREGATE, END_GROUP, END_OBJECT, END_PVL, GROUP, HIGHEST_BIT, LOWEST_BIT, MASK, OBJECT, TOKEN, UNKNOWN`

### Fields inherited from class javax.swing.tree.DefaultMutableTreeNode

`allowsChildren, children, EMPTY_ENUMERATION, parent, userObject`

### Constructor Summary

Constructors
Constructor and Description
`Message()` Construct an empty Message.
`Message(ByteBuffer content)` Construct a Message from the contents of a ByteBuffer.
`Message(Message message)` Construct a copy of another Message.
`Message(Parameter parameter)` Construct a Message as a copy of a Parameter.
`Message(String token)` Construct a Message from a token name.

### Method Summary

Methods
`String` `Action()` Get the action associated with this Message.
`static Message` `Action(String action)` Get a Message intitialized with an `ACTION_PARAMETER_NAME`.
`Message` `Add(Parameter parameter)` Add a Parameter to the Message.
`Message` `Add(String name, Parameter parameter)` Add a parameter to the Message.
`Message` `Clear_Route_From()` Clear the Message route-from list.
`Message` `Clear_Route_To()` Clear the Message route-to list.
`protected int` `Content_Amount()` Get the value of the `CONTENT_AMOUNT_PARAMETER_NAME` from the Message.
`static String` `Content_String(ByteBuffer content)` Get the String representation of Message content bytes.
`Message` `Content(ByteBuffer content)` Set the Message content.
`String` `Destination_Address()` Get the address from the front of the `route-to` list.
`static Message` `Done()` Get a Message intitialized with a `DONE_ACTION` `ACTION_PARAMETER_NAME`.
`String` `From()` Get the next address from the end of the `route-from` list.
`Message` `From(String from)` Add an address to the `route-from` list.
`String` `Get(String name)` Get a named parameter value as a String.
`static Message` `Identify()` Get a Message intitialized with an `IDENTIFY_ACTION` `ACTION_PARAMETER_NAME`.
`static Message` `Identity()` Get a Message intitialized with an `IDENTITY_ACTION` `ACTION_PARAMETER_NAME`.
`static Message` `Identity(String name)` Get a Message intitialized with an `IDENTITY_ACTION` `ACTION_PARAMETER_NAME` and a `NAME_PARAMETER_NAME` with a specified name value.
`String` `Matching(String pattern)` Get the String value of a parameter with a name matching a pattern.
`static Message` `NACK()` Get a Message intitialized with a `NACK_ACTION` `ACTION_PARAMETER_NAME`.
`protected String` `Packet_Label(int content_amount)` Get the message transmission packet label for a Message
`ByteBuffer` `Packet()` Get the Message content as a transmittable packet.
`String` `Pop_From()` Get the next address off of the end of the `route-from` list.
`String` `Pop_To()` Get the next address off of the end of the `route-to` list.
`static Lister` `PVL_Lister()` Get a PVL Lister configured for Message content representation.
`static Parser` `PVL_Parser()` Get a PVL Parser configured for parsing an input stream into Message content.
`String` `PVL()` Get the Message content as a PVL String representation.
`boolean` `Remove_All(String pathname)` Remove all occurances of a named parameter from the Message.
`Parameter` `Remove(String pathname)` Remove a named parameter from the Message.
`Message` `Reply_To(Message message)` Set a Message to be routed back to the sender of another Message.
`int` `Route_From_Count()` Get the count of `route-from` adresses.
`Value` `Route_From()` Get the Message route-from list.
`Message` `Route_From(Value from)` Set the Message route-from list.
`int` `Route_To_Count()` Get the count of `route-to` adresses.
`Value` `Route_To()` Get the Message route-to list.
`Message` `Route_To(Message message)` Apply the `route-to list` from another Message to this Message.
`Message` `Route_To(Value to)` Set the Message route-to list.
`String` `Routing()` Get the routing description.
`Message` `Set_Token(String name)` Set a named parameter token.
`Message` `Set_Token(String name, int index)` Set a named parameter token.
`Message` `Set(String name, double value)` Set a named parameter value.
`Message` `Set(String name, double value, int index)` Set a named parameter value.
`Message` `Set(String name, long value)` Set a named parameter value.
`Message` `Set(String name, long value, int index)` Set a named parameter value.
`Message` `Set(String name, Object value)` Set a named parameter value.
`Message` `Set(String name, Object value, int index)` Set a named parameter value at a list index.
`Message` `Set(String name, String value)` Set a named parameter value.
`Message` `Set(String name, String value, int index)` Set a named parameter value.
`String` `Source_Address()` Get the address from the front of the `route-from` list.
`String` `To()` Get the next address from the end of the `route-to` list.
`Message` `To(String to)` Add an address to the `route-to` list.
`String` `toString()` Get the Message content as a printable PVL String representation.
`static String` `Unescape(String string)` Replace escape sequences in a String with their unescaped equivalents.
`static Value` `Valid_Route(Value value)` Check that a Value is a valid routing address list.
`Value` `Value_of_Matching(String pattern)` Get the Value of a parameter with a name matching a pattern.
`Value` `Value_of(String name)` Get a named parameter value as a Value.

### Methods inherited from class PIRL.PVL.Parameter

`Absolute_Pathname, Absolute_Pathname, Add, add, Add, adopt, Basename, Classification_Name, Classification_Name, Classification, Classification, Classification, clone, Comments, Comments, Data, Data, Data, Description, Description, equals, equalsIgnoreCase, Find, Find, Find, Find, Find, Find, Find, Find, Find, Find, Find, Find, First_Warning, First_Warning, graft, Has_List, Has_Value, Insert, insert, Insert, Is_Absolute_Pathname, Is_Aggregate, Is_Aggregate, Is_Assignment, Is_Assignment, Is_Begin_Aggregate, Is_Begin_Aggregate, Is_Begin_Group, Is_Begin_Group, Is_Begin_Object, Is_Begin_Object, Is_Empty, Is_End_Aggregate, Is_End_Aggregate, Is_End_Group, Is_End_Group, Is_End_Object, Is_End_Object, Is_End_PVL, Is_End_PVL, Is_End, Is_End, Is_Group, Is_Group, Is_Object, Is_Object, Is_Parameter_List, Is_Parameter_Value, Is_Parameter, Is_Token, Is_Token, Is_Unknown, Is_Unknown, iterator, iterator, Last_Warning, Last_Warning, List_Size, List, List, listIterator, listIterator, Match_Depth, Match, Name, Name, orphan, Parent_Pathname, Parent, Path_Delimiter, Path_Delimiter, Path_from, Path_Name, Path_to_Name, Remove_All, remove, Remove, remove, Remove, Reset_Warning, set_classification, set_data, setAllowsChildren, setUserObject, Value, Value, Value, Value, Value, Value, Value, Value, Value, Warning, Write, Write, Write, Write, Write, Write, Write, Write`

### Methods inherited from class javax.swing.tree.DefaultMutableTreeNode

`breadthFirstEnumeration, children, depthFirstEnumeration, getAllowsChildren, getChildAfter, getChildAt, getChildBefore, getChildCount, getDepth, getFirstChild, getFirstLeaf, getIndex, getLastChild, getLastLeaf, getLeafCount, getLevel, getNextLeaf, getNextNode, getNextSibling, getParent, getPath, getPathToRoot, getPreviousLeaf, getPreviousNode, getPreviousSibling, getRoot, getSharedAncestor, getSiblingCount, getUserObject, getUserObjectPath, isLeaf, isNodeAncestor, isNodeChild, isNodeDescendant, isNodeRelated, isNodeSibling, isRoot, pathFromAncestorEnumeration, postorderEnumeration, preorderEnumeration, removeAllChildren, removeFromParent, setParent`

### Methods inherited from class java.lang.Object

`finalize, getClass, hashCode, notify, notifyAll, 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

#### ACTION_PARAMETER_NAME

    public static final String ACTION_PARAMETER_NAME

A Message parameter specifying the action associated with the message.

See Also:
  Constant Field Values

#### IDENTIFY_ACTION

    public static final String IDENTIFY_ACTION

Identify request Message `ACTION_PARAMETER_NAME` value.

See Also:
  Constant Field Values

#### IDENTITY_ACTION

    public static final String IDENTITY_ACTION

Identity Message `ACTION_PARAMETER_NAME` value.

See Also:
  Constant Field Values

#### CLASS_ID_PARAMETER_NAME

    public static final String CLASS_ID_PARAMETER_NAME

Class ID parameter name.

See Also:
  Constant Field Values

#### NAME_PARAMETER_NAME

    public static final String NAME_PARAMETER_NAME

Sender name in an `IDENTIFY_ACTION` or `IDENTITY_ACTION` action Message.

See Also:
  Constant Field Values

#### ACK_ACTION

    public static final String ACK_ACTION

Acknowledgment Message `ACTION_PARAMETER_NAME` value.

See Also:
  Constant Field Values

#### NACK_ACTION

    public static final String NACK_ACTION

Negative acknowledgment Message `ACTION_PARAMETER_NAME` value.

See Also:
  Constant Field Values

#### DONE_ACTION

    public static final String DONE_ACTION

End of messaging - no further messages can be expected - Message `ACTION_PARAMETER_NAME` value.

See Also:
  Constant Field Values

#### START_MARKER

    public static final String START_MARKER

Synchronization sequence at the beginning of a trasmitted message.

See Also:
  `Packet_Label(int)`, Constant Field Values

#### START_MARKER_DELIMITER

    public static final char START_MARKER_DELIMITER

Separates the label `START_MARKER` from its label size value in a transmitted message.

See Also:
  `Packet_Label(int)`, Constant Field Values

#### START_MARKER_END

    public static final char START_MARKER_END

Marks the end of the message label size value and the required message transmission start sequence.

See Also:
  `Packet_Label(int)`, Constant Field Values

#### CONTENT_AMOUNT_PARAMETER_NAME

    public static final String CONTENT_AMOUNT_PARAMETER_NAME

A label parameter of a transmitted message with a value that is the number of message label characters to follow.

See Also:
  `Packet_Label(int)`, Constant Field Values

#### ROUTE_TO_PARAMETER_NAME

    public static final String ROUTE_TO_PARAMETER_NAME

A label parameter of a transmitted message with a value that is the Message `route-to list`.

See Also:
  `Packet_Label(int)`, Constant Field Values

#### ROUTE_FROM_PARAMETER_NAME

    public static final String ROUTE_FROM_PARAMETER_NAME

A label parameter of a transmitted message with a value that is the Message `route-from list`.

See Also:
  `Packet_Label(int)`, Constant Field Values

#### ERROR_MESSAGE_MARKER

    public static final char ERROR_MESSAGE_MARKER

Marks the first character of a Message `String representation` when there was a problem rendering the Message content into valid PVL syntax.

### Constructor Detail

#### Message

    public Message()

Construct an empty Message.

The Message will be an empty Group with emtpy `route-to` and `route-from` address lists. The Name of the Message will be the `Parser.CONTAINER_NAME`.

#### Message

    public Message(String token)

Construct a Message from a token name.

A single Token Parameter with a name the same as the token and no Value is added to the new empty Message.

Parameters:
  `token` - A Token Parameter name.
See Also:
  `Message()`

#### Message

    public Message(Message message)
            throws PVL_Exception

Construct a copy of another Message.

The Message Name, Parameter content and `route-to` and `route-from` address lists are copied into this Message.

Parameters:
  `message` - The Message to be copied.
Throws:
  `PVL_Exception` - If the message contains an invalid Parameter.

#### Message

    public Message(Parameter parameter)
            throws PVL_Exception

Construct a Message as a copy of a Parameter.

The contents of the parameter are copied into an empty Message. If the copied Parameter is an Assignment it becomes the sole Parameter in this Message. If it is an Aggregate its Parameter list becomes the list of Parameters in this Message and its `name` becomes the name of this Message.

Parameters:
  `parameter` - The Parameter to copy into the new Message.
Throws:
  `PVL_Exception` - If the Parameter is or contains an invalid Parameter.
See Also:
  `Message()`

#### Message

    public Message(ByteBuffer content)
            throws PVL_Exception

Construct a Message from the contents of a ByteBuffer.

Parameters:
  `content` - The ByteBuffer containing the Message content.
Throws:
  `PVL_Exception`
See Also:
  `Content(ByteBuffer)`, `Message()`

### Method Detail

#### Content

    public Message Content(ByteBuffer content)
                    throws PVL_Exception

Set the Message content.

The current Message content is removed and the new content is added by `parsing` the ByteBuffer data. N.B.: The ByteBuffer must be positioned at the beginning of the content data and its limit must be at or beyond the end of the content data. The position and limit will be unchanged when this method completes, whether normally or by throwing an exception.

The ByteBuffer content data must be PVL formatted parameters. All the parameters found in the content buffer are added to the Message. The Message itself will retain its name.

Parameters:
  `content` - The ByteBuffer containing the Message content. If null the current content of this Message is simply emptied.
Returns:
  This Message with the new content.
Throws:
  `PVL_Exception` - If the content can not be parsed by the `Message PVL parser`.

#### Content_String

    public static String Content_String(ByteBuffer content)

Get the String representation of Message content bytes.

If the content buffer has an accessible backing array its contents, from the array offset to the first byte of the buffer plus the buffer position up to the buffer remaining amount, are converted. Otherwise the buffer content, from the buffer position up to the buffer remaining amount, are copied into a temporary array for conversion.

The byte buffer content array is converted to a new String using the PVL `Parser.CHARACTER_ENCODING`.

Parameters:
  `content` - A ByteBuffer containing the remaining bytes starting at its current position to be converted to a String.
Returns:
  A String representation of the buffer content. This will be null if the content is null or the content could not be converted.

#### Packet

    public ByteBuffer Packet()
                      throws PVL_Exception

Get the Message content as a transmittable packet.

A Message packet is a ByteBuffer that contains Message routing information and Message content in a form that can be transmitted over a stream.

The packet begins with a set of `label` parameters. The packet label is followed by the Message content as `PVL formatted text`.

All content is US_ASCII encoded that ensurces that 7-bit characters, one character per byte, will be used for the PVL text.

Returns:
  A ByteBuffer containing the Message label and content data.
Throws:
  `PVL_Exception` - If a valid PVL representation can not be produced for the Message content.
See Also:
  `Packet_Label(int)`

#### Packet_Label

    protected String Packet_Label(int content_amount)

Get the message transmission packet label for a Message

A Message label section contains PVL with the following parts:

`START_MARKER`
  Used as a message synchronization marker to locate the beginning of a message in a byte stream.
`START_MARKER_DELIMITER`
  Separates the `START_MARKER` from the label size value that immediately follows. There are no spaces around the `START_MARKER_DELIMITER` character ('=') that separates the parameter name from its value.
Label size
  The number of Message label characters that follow. N.B. the label size does not include the `START_MARKER`, `START_MARKER_DELIMITER`, the label size representation characters nor the `START_MARKER_END` that immediately follows.
`START_MARKER_END`
  Marks the end of the label size value representation characters. There is no end-of-line sequence following this marker.
`CONTENT_AMOUNT_PARAMETER_NAME`
  A parameter with the `CONTENT_AMOUNT_PARAMETER_NAME` name and the content amount as its assigned value. An `end-of-line sequence` ends the parameter.
`ROUTE_TO_PARAMETER_NAME`
  A parameter with the `ROUTE_TO_PARAMETER_NAME` name and the `route-to list` of addresses as its assigned value array. An `end-of-line sequence` ends the parameter. If this Message has an empty route-to list this parameter is not included in the label.
`ROUTE_FROM_PARAMETER_NAME`
  A parameter with the `ROUTE_FROM_PARAMETER_NAME` name and the `route-from list` of addresses as its assigned value array. An `end-of-line sequence` ends the parameter. If this Message has an empty route-from list this parameter is not included in the label.

N.B.: The message start synchronization sequence is composed of the START_MARKER through START_MARKER_END characters. This sequence is critical for identifying the start of a message in an unreliable transmitted byte stream.

Parameters:
  `content_amount` - The value to be assigned to the `CONTENT_AMOUNT_PARAMETER_NAME`.
Returns:
  A String containing the Message label section of a message transmission packet.
See Also:
  `Packet()`

#### Content_Amount

    protected int Content_Amount()
                          throws PVL_Exception

Get the value of the `CONTENT_AMOUNT_PARAMETER_NAME` from the Message.

This convenience method is used to obtain from a Message label the amount of content data that follows the label section.

Returns:
  The value of the `CONTENT_AMOUNT_PARAMETER_NAME`.
Throws:
  `PVL_Exception` - If the content amount parameter was not found or its Value could not produce an integer.
See Also:
  `Packet_Label(int)`

#### PVL

    public String PVL()

Get the Message content as a PVL String representation.

The Message's PVL `description` String is generated using a suitably configured `PVL Lister`. If the Name of the Message is not the `Parser.CONTAINER_NAME` it is temporarily changed to this special name so a PVL "END" statement will always be provided.

N.B.: If the first character of the resultant String is the `ERROR_MESSAGE_MARKER` character then a problem was encountered while attempting to generate the PVL syntax from the Message content. In this case the returned String is an error report.

Returns:
  A PVL String representation of the Message content.
See Also:
  `toString()`

#### toString

    public String toString()

Get the Message content as a printable PVL String representation.

The Message's PVL `description` String is generated in standard format. Any escape sequences are `converted` to their original character values. As a result, parameter string values containing new-line sequences, for example, will be printed as multiple lines. If the Message `name` is not the `Parser.CONTAINER_NAME` a top-level group with this name will be included in the PVL represenation and no PVL "END" statement will be provided; otherwise the top-level container group will not be included but the "END" statement will be.

N.B.: If the first character of the resultant String is the `ERROR_MESSAGE_MARKER` character then a problem was encountered while attempting to generate the PVL syntax from the Message content. In this case the returned String is an error report.

Overrides:
  `toString` in class `Parameter`
Returns:
  A String representation of the Message content.
See Also:
  `PVL()`

#### Get

    public String Get(String name)

Get a named parameter value as a String.

The named Parameter must be an Assignment of a single non-Array Value.

Parameters:
  `name` - The String naming the parameter to be found. If null, null will be returned.
Returns:
  A String representing the value of the parameter. This will be null if the named parameter could not be found, it is not an Assignment or its Value is an Array. N.B. The actual Parameter Value may not be a String in which case its String representation is returned.
See Also:
  `Value_of(String)`

#### Matching

    public String Matching(String pattern)

Get the String value of a parameter with a name matching a pattern.

The matching Parameter must be an Assignment of a single non-Array Value.

Parameters:
  `pattern` - A regular expression pattern String. If null, null is returned.
Returns:
  A String representing the value of the parameter with the name that matches the pattern. This will be null if no matching parameter could be found, it is not an Assignment or its Value is an Array. N.B. The actual Parameter Value may not be a String in which case its String representation is returned.
See Also:
  `Value_of_Matching(String)`

#### Value_of

    public Value Value_of(String name)

Get a named parameter value as a Value.

Only an Assignment parameter will be found. The first Assignment parameter with the matching name is returned.

Parameters:
  `name` - The String naming the parameter to be found. If null, null is returned.
Returns:
  The Value of the Parameter. This will be null if the parameter could not be found.
See Also:
  `Get(String)`

#### Value_of_Matching

    public Value Value_of_Matching(String pattern)

Get the Value of a parameter with a name matching a pattern.

Only an Assignment parameter will be found.

Parameters:
  `pattern` - A regular expression pattern String. If null, null is returned.
Returns:
  The Value of the Parameter with the name that matches the pattern. This will be null if a matching parameter could not be found.

#### Set

    public Message Set(String name,
              Object value,
              int index)
                throws PVL_Exception

Set a named parameter value at a list index.

If a Parameter with the specified name is found its Value is set to the specified value; any existing Value is replaced. If no Parameter is found a new one with the specified Value is added to the parameter list at the specified index.

The specified value may be any object suitable for providing the `data of a Value`. If the specified value is null and an existing Parameter is found, the Parameter is removed. If, however, no Parameter is found a null value does nothing.

Parameters:
  `name` - The name of the Parameter to be assigned the value. If null nothing is done.
  `value` - A Object that contains the value to be applied, or null if an existing parameter is to be removed.
  `index` - The index in the parameter list at which to insert a new Parameter. If less than zero a new parameter will be added to the beginning of the list (index zero); if greater than or equal to the size of the parameter list a new parameter will be added to the end of the list (index equal to the list size).
Returns:
  This Message.
Throws:
  `PVL_Exception` - If the value is not a suitable Object for a Value.

#### Set

    public Message Set(String name,
              Object value)
                throws PVL_Exception

Set a named parameter value.

If a Parameter with the specified name is found its Value is set to the specified value; any existing Value is replaced. If no Parameter with the specified name is found a new one with the specified value is added to the end of the parameter list.

The specified value may be any object suitable for providing the `data of a Value`. If the specified value is null and an existing Parameter is found, the Parameter is removed. If, however, no Parameter is found a null value does nothing.

Parameters:
  `name` - The name of the Parameter to be assigned the value. If null nothing is done.
  `value` - A Object that contains the value to be assigned, or null if an existing parameter is to be removed.
Returns:
  This Message.
Throws:
  `PVL_Exception` - If the value is not a suitable Object for a Value.
See Also:
  `Set(String, Object, int)`

#### Set

    public Message Set(String name,
              String value)

Set a named parameter value.

This is a convenience method to set a String value with no possibility of an exception being thrown.

Parameters:
  `name` - The name of the Parameter to be assigned the value. If null nothing is done.
  `value` - A String value to be assigned, or null if an existing parameter is to be removed.
Returns:
  This Message.
See Also:
  `Set(String, Object)`

#### Set

    public Message Set(String name,
              String value,
              int index)

Set a named parameter value.

This is a convenience method to set a String value with no possibility of an exception being thrown.

Parameters:
  `name` - The name of the Parameter to be assigned the value. If null nothing is done.
  `value` - A String value to be assigned, or null if an existing parameter is to be removed.
  `index` - The index in the parameter list at which to insert a new Parameter. If less than zero a new parameter will be added to the beginning of the list (index zero); if greater than or equal to the size of the parameter list a new parameter will be added to the end of the list (index equal to the list size).
Returns:
  This Message.
See Also:
  `Set(String, Object, int)`

#### Set

    public Message Set(String name,
              long value)

Set a named parameter value.

This is a convenience method to set an integer value with no possibility of an exception being thrown.

Parameters:
  `name` - The name of the Parameter to be assigned the value. If null nothing is done.
  `value` - A long integer value to be assigned.
Returns:
  This Message.
See Also:
  `Set(String, Object)`

#### Set

    public Message Set(String name,
              long value,
              int index)

Set a named parameter value.

This is a convenience method to set an integer value with no possibility of an exception being thrown.

Parameters:
  `name` - The name of the Parameter to be assigned the value. If null nothing is done.
  `value` - A long integer value to be assigned.
  `index` - The index in the parameter list at which to insert a new Parameter. If less than zero a new parameter will be added to the beginning of the list (index zero); if greater than or equal to the size of the parameter list a new parameter will be added to the end of the list (index equal to the list size).
Returns:
  This Message.
See Also:
  `Set(String, Object, int)`

#### Set

    public Message Set(String name,
              double value)

Set a named parameter value.

This is a convenience method to set a real number value with no possibility of an exception being thrown.

Parameters:
  `name` - The name of the Parameter to be assigned the value. If null nothing is done.
  `value` - A double value to be assigned.
Returns:
  This Message.
See Also:
  `Set(String, Object)`

#### Set

    public Message Set(String name,
              double value,
              int index)

Set a named parameter value.

This is a convenience method to set a real number value with no possibility of an exception being thrown.

Parameters:
  `name` - The name of the Parameter to be assigned the value. If null nothing is done.
  `value` - A double value to be assigned.
  `index` - The index in the parameter list at which to insert a new Parameter. If less than zero a new parameter will be added to the beginning of the list (index zero); if greater than or equal to the size of the parameter list a new parameter will be added to the end of the list (index equal to the list size).
Returns:
  This Message.
See Also:
  `Set(String, Object, int)`

#### Set_Token

    public Message Set_Token(String name,
                    int index)

Set a named parameter token.

A parameter token has no value. N.B.: If an existing Parameter with the specified name is found it's Value is dropped. If no Parameter with the specified name is found a new one is added to the end of the parameter list.

Parameters:
  `name` - The name of the token Parameter. If null nothing is done.
  `index` - The index in the parameter list at which to insert a new Parameter. If less than zero a new parameter will be added to the beginning of the list (index zero); if greater than or equal to the size of the parameter list a new parameter will be added to the end of the list (index equal to the list size).
Returns:
  This Message.

#### Set_Token

    public Message Set_Token(String name)

Set a named parameter token.

The token will be added to the end of the parameter list.

Parameters:
  `name` - The name of the token Parameter. If null nothing is done.
Returns:
  This Message.
See Also:
  `Set_Token(String, int)`

#### Add

    public Message Add(String name,
              Parameter parameter)

Add a parameter to the Message.

The parameter is copied. The name of the copy is set to the specified name if the specified name is non-null. Then the copy is added to the end of the Message parameter list.

Parameters:
  `name` - A String that will be the name of the new parameter. If null, the existing name will be unchanged.
  `parameter` - A Parameter a copy of which will be added to the end of this Message list. If null, nothing is done.
Returns:
  This Message.

#### Add

    public Message Add(Parameter parameter)

Add a Parameter to the Message.

The Parameter is added to the end of the Message Parameter list. N.B.: The Parameter is not copied.

This is a convenience method to add a Parameter with no possibility of an exception being thrown.

Overrides:
  `Add` in class `Parameter`
Parameters:
  `parameter` - The Parameter to be added to the end of this Message list. If null, nothing is done.
Returns:
  This Message.
See Also:
  `Add(String, Parameter)`

#### Remove

    public Parameter Remove(String pathname)

Remove a named parameter from the Message.

Any parameter at the specified pathname - relative or absolute - is removed from the Message regardless of its Classification (Token, Assignment or Aggregate). Only the first parameter found at the pathname is removed.

Parameters:
  `pathname` - The pathnname String for the parameter to be removed. If null nothing is done.
Returns:
  The removed Parameter, or null if nothing was removed.
See Also:
  `Parameter.Remove(Parameter)`

#### Remove_All

    public boolean Remove_All(String pathname)

Remove all occurances of a named parameter from the Message.

All parameters at the specified pathname - relative or absolute - are removed from the Message regardless of their Classification (Token, Assignment or Aggregate).

Parameters:
  `pathname` - The pathnname String for the parameters to be removed. If null nothing is done.
Returns:
  true if at least one parameter was removed; false otherwise.
See Also:
  `Parameter.Remove(Parameter)`

#### Action

    public String Action()

Get the action associated with this Message.

If an `ACTION_PARAMETER_NAME` is found its value is returned. Otherwise, if the Message contains at least one parameter and the first parameter is a token (a parameter without a value), then the token name is returned.

Returns:
  A String naming the action associated with this Message. This will be null if no action could be identified.

#### To

    public Message To(String to)

Add an address to the `route-to` list.

Parameters:
  `to` - A `Messenger address`.
Returns:
  This Message.

#### To

    public String To()

Get the next address from the end of the `route-to` list.

The address is not removed from the list.

Returns:
  The address on the end of the route-to list, or null if the list is empty.

#### Destination_Address

    public String Destination_Address()

Get the address from the front of the `route-to` list.

The address is not removed from the list.

Returns:
  The address at the front of the route-to list, or null if the list is empty. This should be the address of the destination Messenger where the Message is to be delivered.

#### Pop_To

    public String Pop_To()

Get the next address off of the end of the `route-to` list.

The address is removed from the list.

Returns:
  The address on the end of the route-to list, or null if the list is empty.

#### Route_To

    public Value Route_To()

Get the Message route-to list.

The addresses in the list are LIFO ordered: The last entry is the address of the first Messenger to which the Message should be sent (not the Messenger that sends the Message); the first entry is the intended recipient Messenger where the Message is to be delivered. A Message with an empty route-to list will be delivered by the Messenger that receives it.

Returns:
  An Array Value containing zero or more `Messenger addresses`. This is a copy of the list owned by the Message.
See Also:
  `Route_To(Value)`

#### Route_To

    public Message Route_To(Value to)
                     throws PVL_Exception

Set the Message route-to list.

Parameters:
  `to` - An Array Value containing zero or more `Messenger addresses`. The Value will be copied into this Message replacing the previous route-to list. If the Value is null the current list is emptied.
Returns:
  This Message.
Throws:
  `PVL_Exception` - If the Value is not an Array of STRING type Values.

#### Clear_Route_To

    public Message Clear_Route_To()

Clear the Message route-to list.

Returns:
  This Message.

#### Route_To

    public Message Route_To(Message message)

Apply the `route-to list` from another Message to this Message.

Parameters:
  `message` - The Message from which to obtain the route-to list. If the message is the same as this Message, nothing is done.
Returns:
  This Message.

#### Route_To_Count

    public int Route_To_Count()

Get the count of `route-to` adresses.

Returns:
  The number of addresses on the route-to list.

#### From

    public Message From(String from)

Add an address to the `route-from` list.

Parameters:
  `from` - A `Messenger address`.
Returns:
  This Message.

#### From

    public String From()

Get the next address from the end of the `route-from` list.

The address is not removed from the list.

Returns:
  The address on the end of the route-from list, or null if the list is empty. This will be the address of the last Messenger to have sent the Message.

#### Source_Address

    public String Source_Address()

Get the address from the front of the `route-from` list.

The address is not removed from the list.

Returns:
  The address at the front of the route-from list, or null if the list is empty. This should be the address of the source Messenger where the Message originated.

#### Pop_From

    public String Pop_From()

Get the next address off of the end of the `route-from` list.

The address is removed from the list.

Returns:
  The address on the end of the route-from list, or null if the list is empty.

#### Route_From

    public Value Route_From()

Get the Message route-from list.

Each Messenger that sends a Message adds its adress to the end of the list.

Returns:
  An Array Value containing zero or more `Messenger addresses`. This is a copy of the list owned by the Message.
See Also:
  `Route_From(Value)`

#### Route_From

    public Message Route_From(Value from)
                       throws PVL_Exception

Set the Message route-from list.

Parameters:
  `from` - An Array Value containing zero or more `Messenger addresses`. The Value will be copied into this Message replacing the previous route-to list. If the Value is null the current list is emptied.
Returns:
  This Message.
Throws:
  `PVL_Exception` - If the Value is not an Array of STRING type Values.

#### Clear_Route_From

    public Message Clear_Route_From()

Clear the Message route-from list.

Returns:
  This Message.

#### Route_From_Count

    public int Route_From_Count()

Get the count of `route-from` adresses.

Returns:
  The number of addresses on the route-from list.

#### Routing

    public String Routing()

Get the routing description.

Returns:
  A String containing a Route To: address list followed by a Route From: address list.

#### Reply_To

    public Message Reply_To(Message message)

Set a Message to be routed back to the sender of another Message.

The `route-to` list is of this Message is set to the `route-from` list of the other Message. The route-from list of this Message is emptied.

Parameters:
  `message` - The Message to receive a reply.
Returns:
  This Message.

#### Valid_Route

    public static Value Valid_Route(Value value)
                             throws PVL_Exception

Check that a Value is a valid routing address list.

A valid routing address list is an Array of STRING Type Values.

Parameters:
  `value` - The Value to be checked. May not be null, but may be an empty Array.
Throws:
  `PVL_Exception` - If the Value is not an Array or one of its Value's is not a STRING Type.

#### PVL_Lister

    public static Lister PVL_Lister()

Get a PVL Lister configured for Message content representation.

The Lister is configured with `verbatim strings` enabled, `indenting` disabled and `array indenting` disabled. The Lister has no writer bound to it.

Returns:
  A PVL Lister.
See Also:
  `Lister`

#### PVL_Parser

    public static Parser PVL_Parser()

Get a PVL Parser configured for parsing an input stream into Message content.

The Parser has no source reader bound to it. It has default syntax modes set except: `verbatim strings` is enabled and `string continuation` and `input filtering` are disabled.

N.B.: The Reader that will be bound to the Parser is excpected to employ "US-ASCII" character encoding. Multi-byte characters may produce unexpected results.

N.B.: If the Parser is to be reused with more than one parsing sequence - such as with different input readers - it must be `reset` before each reuse.

Returns:
  A PVL Parser suitable for parsing an input stream into a Message.
See Also:
  `Parser`, `Parser.Set_Reader(Reader, long)`

#### Identify

    public static Message Identify()

Get a Message intitialized with an `IDENTIFY_ACTION` `ACTION_PARAMETER_NAME`.

Returns:
  A Message.

#### Identity

    public static Message Identity(String name)

Get a Message intitialized with an `IDENTITY_ACTION` `ACTION_PARAMETER_NAME` and a `NAME_PARAMETER_NAME` with a specified name value.

Parameters:
  `name` - The name String to be assigned as the value of the `NAME_PARAMETER_NAME`.
Returns:
  A Message.

#### Identity

    public static Message Identity()

Get a Message intitialized with an `IDENTITY_ACTION` `ACTION_PARAMETER_NAME`.

Returns:
  A Message.

#### NACK

    public static Message NACK()

Get a Message intitialized with a `NACK_ACTION` `ACTION_PARAMETER_NAME`.

Returns:
  A Message.

#### Done

    public static Message Done()

Get a Message intitialized with a `DONE_ACTION` `ACTION_PARAMETER_NAME`.

Returns:
  A Message.

#### Action

    public static Message Action(String action)

Get a Message intitialized with an `ACTION_PARAMETER_NAME`.

Parameters:
  `action` - The String specifying the `ACTION_PARAMETER_NAME` value.
Returns:
  A Message.

#### Unescape

    public static String Unescape(String string)

Replace escape sequences in a String with their unescaped equivalents.

When Message content contains parameters with multi-line report text, the end-of-line sequences are converted to escape sequences for transmision. This applies to other special characters such as horizontal tabs. Before printing such report text they should have any escape sequences converted back to their original character values.

Parameters:
  `string` - A String that may contain escape sequences.
Returns:
  A copy of the string argument with all escape sequences converted to their original character values.