aktbus.core
Class AktMessage

aktbus.core.AktMessage

Direct Known Subclasses:

KqmlMessage

public class AktMessage

The AKTMessage class represents an AKT message according to the AKT-Bus white paper. It provides methods to compose and manipulate AKT messages, including sending an AKT message to a specific URL.

Field Summary

protected java.util.HashMap

name_space

Constructor Summary

AktMessage()
Creates an empty AktMessage.

AktMessage(org.xml.sax.InputSource source)
Constructs an AktMessage by reading from an org.xml.sax.InputSource.

AktMessage(java.lang.String message_to_parse)
Constructs an AktMessage by parsing an XML string.

AktMessage(java.lang.String sender, java.lang.String receiver, java.lang.String simple_content)
Creates an AktMessage with <aktbus:SimpleContent>, using String for URLs.

AktMessage(java.net.URL sender, java.net.URL receiver, boolean parse_content, java.lang.String content)
A general constructor that creates an AktMessage.

AktMessage(java.net.URL sender, java.net.URL receiver, org.w3c.dom.Node content)
Creates an AktMessage using the sender and reciever URIs and appends the content node as the content of the message.

AktMessage(java.net.URL sender, java.net.URL receiver, java.lang.String simple_content)
Creates an AktMessage from a String.

Method Summary

org.w3c.dom.Node	createDOM(com.sun.xml.tree.XmlDocument parent, java.net.URL sender, java.net.URL receiver, org.w3c.dom.Node content) Creates an AktMessage as an XmlDocument, with proper header information and Node content as the message content.
com.sun.xml.tree.ElementNode	find_element_node(com.sun.xml.tree.ElementNode root, java.lang.String tagname) Search for an ElementNode with a given tag-name under a subtree by depth-first-search.
com.sun.xml.tree.ElementNode	find_element_node(java.lang.String tagname) Given the tag, find an ElementNode in an AktMessage object by depth-first-search.
java.lang.String	get_element_node_text(com.sun.xml.tree.ElementNode parent, java.lang.String tag_name) Get the value of the 1st TextNode after a certain ElementNode.
java.lang.String	get_element_node_text(java.lang.String tag_name) Get the value of the 1st TextNode under a certain ElementNode, start search from the root.
org.w3c.dom.Node	get_first_child_node(com.sun.xml.tree.ElementNode parent, int type_wanted) Get the first child node of a specific type under the current ElementNode.
org.w3c.dom.Node	get_first_child_node(com.sun.xml.tree.ElementNode parent, java.lang.String node_name, int type_wanted) Get the first child node matching an optional node_name & type.
org.w3c.dom.Node	get_next_sibling_node(com.sun.xml.tree.ElementNode current_node, int type_wanted) Find the next sibling of an ElementNode with a specific type.
org.w3c.dom.Node	get_next_sibling_node(com.sun.xml.tree.ElementNode current_node, java.lang.String node_name, int type_wanted) Find the next sibling of an com.sun.xml.tree.ElementNode with a specific type, matching an optional node_name.
java.lang.String	get_receiver() Find the receiver URI in an AktMessage and return it as a String.
java.lang.String	get_sender() Find the sender URI in an AktMessage and return it as a String.
java.lang.String	get_simple_message() Find the content of the <aktbus:hasSimpleMessage> element.
java.lang.String	get_subtree_text(org.w3c.dom.Node n) Return the subtree under the given node as a String.
java.lang.String	get_subtree_text(org.w3c.dom.Node n, boolean translate) Return the subtree under the given node as a String with optional entity references translation.
protected void	initialise_namespace() Initialise the field name_space to contain the HashMap of default XML name space definition.
static void	print_node_type(org.w3c.dom.Node node) Print out the type of a node according to the org.w3c.dom.Node class.
void	print_tree_type(aktbus.core.Node n) Print out all nodes' type in the XML tree.
AktMessage	send_and_receive() Send to receiver and waits for reply from the same connection.
AktMessage	send_and_receive(java.net.URL receiver_uri, int timeout, java.lang.Class result_class) Send to receiver and waits for reply from the same connection.
void	send() Send an AktMessage with blocking, using specified receiver URI in the AktMessage object.
void	send(int timeout) Send to the receiver as specified in the AktMessage, with timeout.
void	send(java.net.URL receiver_uri, int timeout) Sends an AktMessage to a certain recipient.
void	ugly_write() Ugly-printing an AktMessage to stdout without any translation of escape char (entity reference).
void	ugly_write(boolean translate) Ugly-printing an AktMessage to stdout.
void	ugly_write(java.io.OutputStream out) Ugly-printing an AktMessage to an OutputStream.
void	ugly_write(java.io.OutputStream out, boolean translate) Ugly-printing an AktMessage to a OutputStream.
void	ugly_write(java.io.Writer out) Ugly-printing an AktMessage to a Writer.
void	ugly_write(java.io.Writer out, boolean translate) Ugly-printing an AktMessage to a Writer.
void	ugly_write(java.io.Writer out, java.lang.String encoding) Ugly-printing an AktMessage to a Writer, using a certain encoding.
void	ugly_write(java.io.Writer out, java.lang.String encoding, boolean translate) Ugly-printing an AktMessage to a Writer, using a certain encoding.

Field Detail

name_space

protected java.util.HashMap name_space

Constructor Detail

AktMessage

public AktMessage()

Creates an empty AktMessage.

AktMessage

public AktMessage(java.lang.String message_to_parse)
           throws org.xml.sax.SAXException,
                  java.lang.Exception

Constructs an AktMessage by parsing an XML string. The string should contain the message header and body.

Parameters:

message_to_parse - The string to be parsed.

Throws:

org.xml.sax.SAXException - When a parse error is encounted.

java.lang.Exception - When a general exception is found.

AktMessage

public AktMessage(org.xml.sax.InputSource source)
           throws org.xml.sax.SAXException,
                  java.lang.Exception

Constructs an AktMessage by reading from an org.xml.sax.InputSource.

Parameters:

source - InputSource to read from.

Throws:

org.xml.sax.SAXException - When a parsing error occurs.

java.lang.Exception - When other general erros occur.

AktMessage

public AktMessage(java.net.URL sender,
                  java.net.URL receiver,
                  boolean parse_content,
                  java.lang.String content)
           throws org.xml.sax.SAXException,
                  java.lang.Exception

A general constructor that creates an AktMessage. When parse_content is false, content is treated as plain text without any XML parsing. In this case it is put inside the default XML element . When parse_content is true, the string content is parsed to form an XML subtree which will be inserted as the content of the message.

Parameters:

sender - The URL of the sender.

receiver - The URL of the receiver.

parse_content - A boolean flag indicating if the content is to be parsed as XML.

content - The content of the message.

Throws:

org.xml.sax.SAXException - When a parsing error occurs.

java.lang.Exception - When other general error occur.

AktMessage

public AktMessage(java.net.URL sender,
                  java.net.URL receiver,
                  org.w3c.dom.Node content)
           throws java.net.MalformedURLException,
                  java.lang.Exception

Creates an AktMessage using the sender and reciever URIs and appends the content node as the content of the message.

Parameters:

sender - The URI of the sender of the message.

receiver - The URI of the receiver of the message.

content - The Node (subtree) to be the content of the message.

Throws:

java.net.MalformedURLException - When either URI is invalid.

java.lang.Exception - On other general errors.

AktMessage

public AktMessage(java.net.URL sender,
                  java.net.URL receiver,
                  java.lang.String simple_content)
           throws org.xml.sax.SAXException,
                  java.lang.Exception

Creates an AktMessage from a String.

Parameters:

sender - The sender of the AktMessage.

receiver - The receiver of the AktMessage.

simple_content - A String forming the simple content of the AktMessage.

AktMessage

public AktMessage(java.lang.String sender,
                  java.lang.String receiver,
                  java.lang.String simple_content)
           throws java.net.MalformedURLException,
                  org.xml.sax.SAXException,
                  java.lang.Exception

Creates an AktMessage with <aktbus:SimpleContent>, using String for URLs.

Parameters:

sender - The sender URL in a String.

receiver - The receiver URL in a String.

simple_content - The message content in a String.

Throws:

java.net.MalformedURLExcpetion - When either sender/reciver URI is not valid.

org.xml.sax.SAXException - When simple_content cannot be parsed as XML.

java.lang.Exception - On other general errors.

Method Detail

createDOM

public org.w3c.dom.Node createDOM(com.sun.xml.tree.XmlDocument parent,
                                  java.net.URL sender,
                                  java.net.URL receiver,
                                  org.w3c.dom.Node content)
                           throws java.net.MalformedURLException,
                                  java.lang.Exception

Creates an AktMessage as an XmlDocument, with proper header information and Node content as the message content. When you create an AktMessage with a customised content, you can use this method to add an XML subtree into an AktMessage envelope.

Parameters:

parent - The parent XmlDocument object.

sender - The sender of this AktMessage.

receiver - The receiver of this AktMessage.

content - A Node containing the subtree as the AktMessage content.

Throws:

java.net.MalformedURLExcpetion - When either sender/reciver URI is not valid.

java.lang.Exception - On other general errors.

find_element_node

public com.sun.xml.tree.ElementNode find_element_node(java.lang.String tagname)

Given the tag, find an ElementNode in an AktMessage object by depth-first-search. To get the value of a certain element, first search for the ElementNode by specifying the tag name. Once the ElementNode is found, use get_first_child_node() to look for its child which is a text node. Then get the value of the text node by getNodeValue().

Parameters:

tagname - The name of the node to find.

Returns:

The node with the text if found, null otherwise.

find_element_node

public com.sun.xml.tree.ElementNode find_element_node(com.sun.xml.tree.ElementNode root,
                                                      java.lang.String tagname)

Search for an ElementNode with a given tag-name under a subtree by depth-first-search.

Parameters:

root - The root of the subtree to search

tagname - The name of the node to find.

Returns:

ElementNode The node with the text if found, null otherwise.

get_subtree_text

public java.lang.String get_subtree_text(org.w3c.dom.Node n)

Return the subtree under the given node as a String. This is useful for extracting the content as text for display. References to entities will not be translated. Notice that it does not include the tag name of the top node.

Parameters:

n - The node under which the text node of the subtree is to be extracted.

Returns:

A String which contains value of all text node in the subtree.

get_subtree_text

public java.lang.String get_subtree_text(org.w3c.dom.Node n,
                                         boolean translate)

Return the subtree under the given node as a String with optional entity references translation. Notice that it does not include the tag name of the top node.

Parameters:

n - The node under which the text node of the subtree is to be extracted.

translate - A boolean flag specifying if entity reference translation is needed.

Returns:

A String which contains value of all text node in the subtree.

get_first_child_node

public org.w3c.dom.Node get_first_child_node(com.sun.xml.tree.ElementNode parent,
                                             int type_wanted)
                                      throws java.lang.Exception

Get the first child node of a specific type under the current ElementNode.

Parameters:

parent - The parent node under which we search for its children.

type_wanted - The type of node we are looking for. It is defined in org.w3c.dom.Node. Some of the valid values are: ELEMENT_NODE, ATTRIBUTE_NODE, TEXT_NODE.

Throws:

java.lang.Exception - When an error occurs.

get_first_child_node

public org.w3c.dom.Node get_first_child_node(com.sun.xml.tree.ElementNode parent,
                                             java.lang.String node_name,
                                             int type_wanted)
                                      throws java.lang.Exception

Get the first child node matching an optional node_name & type.

Parameters:

parent - The Node under which we look for the child.

node_name - An optional node name to match. Specify null to ignore it.

type_wanted - The node type to match.

Returns:

The child node found. null if not found.

Throws:

java.lang.Exception - When an error occurs.

get_next_sibling_node

public org.w3c.dom.Node get_next_sibling_node(com.sun.xml.tree.ElementNode current_node,
                                              int type_wanted)
                                       throws java.lang.Exception

Find the next sibling of an ElementNode with a specific type.

Parameters:

parent - The parent node, which is an com.sun.xml.tree.ElementNode.

Throws:

java.lang.Exception - When an error occurs.

get_next_sibling_node

public org.w3c.dom.Node get_next_sibling_node(com.sun.xml.tree.ElementNode current_node,
                                              java.lang.String node_name,
                                              int type_wanted)
                                       throws java.lang.Exception

Find the next sibling of an com.sun.xml.tree.ElementNode with a specific type, matching an optional node_name.

Parameters:

parent - The parent node, which is an com.sun.xml.tree.ElementNode.

Throws:

java.lang.Exception - When an error occurs.

get_element_node_text

public java.lang.String get_element_node_text(java.lang.String tag_name)

Get the value of the 1st TextNode under a certain ElementNode, start search from the root. This is a short-hand method that saves you from fetching the ElementNode, find the TextNode and get its value. It gets the first TextNode child of the ElementNode and return it's node value. If you have multiple TextNode under the target ElementNode, better use the get_first_child_node and get_next_sibling_node methods().

Parameters:

tag_name - The tagname of the ElementNode to search.

Returns:

The value of the element as a String. Or null if cannot find it.

get_element_node_text

public java.lang.String get_element_node_text(com.sun.xml.tree.ElementNode parent,
                                              java.lang.String tag_name)
                                       throws java.lang.Exception

Get the value of the 1st TextNode after a certain ElementNode. This is a short-hand method that saves you from fetching the ElementNode, find the TextNode and get its value. It gets the first TextNode child of the ElementNode and return it's node value. If you have multiple TextNode under the target ElementNode, better use the get_first_child_node() and get_next_sibling_node methods().

Parameters:

parent - The ElementNode to start searching.

tag_name - The tagname of the ElementNode to search.

Returns:

The value of the element as a String. Or null if cannot find it.

get_sender

public java.lang.String get_sender()
                            throws java.net.MalformedURLException,
                                   java.lang.Exception

Find the sender URI in an AktMessage and return it as a String.

Returns:

The sender URI as a String.

Throws:

java.net.MalformedURLException - When the returned String is not a valid URL.

java.lang.Exception - When other errors occur.

get_receiver

public java.lang.String get_receiver()
                              throws java.net.MalformedURLException,
                                     java.lang.Exception

Find the receiver URI in an AktMessage and return it as a String.

Returns:

The receiver URI as a String.

Throws:

java.net.MalformedURLException - When the returned String is not a valid URL.

java.lang.Exception - When other errors occur.

get_simple_message

public java.lang.String get_simple_message()
                                    throws java.lang.Exception

Find the content of the <aktbus:hasSimpleMessage> element.

Returns:

The value of the element <aktbus:hasSimpleMessage> in a string.

Throws:

java.lang.Exception - When an error occurs.

send

public void send()
          throws java.lang.Exception,
                 java.io.IOException,
                 java.io.InterruptedIOException

Send an AktMessage with blocking, using specified receiver URI in the AktMessage object.

Throws:

java.lang.Exception - When a general error occurs.

java.io.IOException - When I/O-related error occurs.

java.io.InterruptedIOException - When a timeout occurs.

send

public void send(int timeout)
          throws java.lang.Exception,
                 java.io.IOException,
                 java.io.InterruptedIOException

Send to the receiver as specified in the AktMessage, with timeout. A receiver must be specified in the AktMessage.

Parameters:

timeout - The timeout (in second) on the connection to the receiver.

Throws:

java.lang.Exception - When a general error occurs.

java.io.IOException - When I/O-related error occurs.

java.io.InterruptedIOException - When a timeout occurs.

send

public void send(java.net.URL receiver_uri,
                 int timeout)
          throws java.lang.Exception,
                 java.io.IOException,
                 java.io.InterruptedIOException

Sends an AktMessage to a certain recipient. A receiver URI must be specified in the AktMessage, although the two do not have to be the same.

Parameters:

sender_uri - The URL of the sender. A null means piggy-packed reply.

receiver_uri - The URL of the receiver.

timeout - The timeout value waiting for a response from the other side, in second.

Throws:

java.lang.Exception - When sending fails. i.e. reply is not OK.

java.io.IOException - When I/O-related error occurs.

java.io.InterruptedIOException - When a timeout occurs.

send_and_receive

public AktMessage send_and_receive()
                            throws java.io.IOException,
                                   java.io.InterruptedIOException,
                                   java.net.MalformedURLException,
                                   java.lang.Exception

Send to receiver and waits for reply from the same connection. There must be no sender URI specified in the AktMessage or an Exception will be raised.

Throws:

java.net.MalformedURLException - When the receiver URI is not valid.

java.io.IOException - When I/O-related error occurs.

java.io.InterruptedIOException - When a timeout occurs.

java.lang.Exception - When sending fails. i.e. reply is not OK.

send_and_receive

public AktMessage send_and_receive(java.net.URL receiver_uri,
                                   int timeout,
                                   java.lang.Class result_class)
                            throws java.io.IOException,
                                   java.io.InterruptedIOException,
                                   java.net.MalformedURLException,
                                   java.lang.Exception

Send to receiver and waits for reply from the same connection. There must be no sender URI specified in the AktMessage or an Exception will be raised.

Parameters:

receiver_uri - The URL of the receiver.

timeout - The timeout value waiting for a response from the other side, in second.

result_class - The class of the expected reply as a java.lang.Class object.

Throws:

java.net.MalformedURLException - When the receiver URI is not valid.

java.io.IOException - When I/O-related error occurs.

java.io.InterruptedIOException - When a timeout occurs.

java.lang.Exception - When sending fails. i.e. reply is not OK.

ugly_write

public void ugly_write()
                throws java.io.IOException

Ugly-printing an AktMessage to stdout without any translation of escape char (entity reference). This is useful when you want to print a message without any newline, e.g. into a String.

Throws:

java.io.IOException - When an I/O error occurs in writing.

ugly_write

public void ugly_write(boolean translate)
                throws java.io.IOException

Ugly-printing an AktMessage to stdout. User can choose to have entity references (like &, >, <) translated.

Parameters:

translate - A boolean flag. True if translation wanted, false otherwise.

Throws:

java.io.IOException - When an I/O error occurs in writing.

ugly_write

public void ugly_write(java.io.OutputStream out)
                throws java.io.IOException

Ugly-printing an AktMessage to an OutputStream.

Parameters:

out - The OutputStream where the message will be ugly-printed.

Throws:

java.io.IOException - When an I/O error occurs in writing.

ugly_write

public void ugly_write(java.io.OutputStream out,
                       boolean translate)
                throws java.io.IOException

Ugly-printing an AktMessage to a OutputStream.

Parameters:

out - The OutputStream where the message will be ugly-printed.

translate - true to have entity references translated into characters, false otherwise.

Throws:

java.io.IOException - When an I/O error occurs in writing.

ugly_write

public void ugly_write(java.io.Writer out)
                throws java.io.IOException

Ugly-printing an AktMessage to a Writer.

Parameters:

out - The Writer where the message will be ugly-printed.

Throws:

java.io.IOException - When an I/O error occurs in writing.

ugly_write

public void ugly_write(java.io.Writer out,
                       boolean translate)
                throws java.io.IOException

Ugly-printing an AktMessage to a Writer.

Parameters:

out - The Writer where the message will be ugly-printed.

translate - true to have entity references translated into characters, false otherwise.

Throws:

java.io.IOException - When an I/O error occurs in writing.

ugly_write

public void ugly_write(java.io.Writer out,
                       java.lang.String encoding)
                throws java.io.IOException

Ugly-printing an AktMessage to a Writer, using a certain encoding.

Parameters:

out - The Writer where the message will be ugly-printed.

encoding - The encoding to use.

Throws:

java.io.IOException - When an I/O error occurs in writing.

ugly_write

public void ugly_write(java.io.Writer out,
                       java.lang.String encoding,
                       boolean translate)
                throws java.io.IOException

Ugly-printing an AktMessage to a Writer, using a certain encoding.

Parameters:

out - The Writer where the message will be ugly-printed.

encoding - The encoding to use.

translate - true to have entity references translated into characters, false otherwise.

Throws:

java.io.IOException - When an I/O error occurs in writing.

print_tree_type

public void print_tree_type(aktbus.core.Node n)

Print out all nodes' type in the XML tree. Mainly for debugging purpose.

Parameters:

n - The org.w3c.dom.Node from which we start to print in a deep-first manner.

print_node_type

public static void print_node_type(org.w3c.dom.Node node)

Print out the type of a node according to the org.w3c.dom.Node class. Mainly for debugging purpose.

Parameters:

node - The node whose type is to be printed.

initialise_namespace

protected void initialise_namespace()

Initialise the field name_space to contain the HashMap of default XML name space definition. When you extend the AktMessage, you may want to add more XML name space definitions. You can do so by overriding this method and put more definition into the field name_space, which is a HashMap. Remember to call the superclass' initialise_namespace() before adding, if you want to include the default AktMessage XML name space definition.