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.

Version:

1.50

Author:

Bradford Castalia - UA/PIRL

See Also:

Parameter, Messenger, Serialized Form

Field Summary

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

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

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.