aktbus.core
Class AktBusReceiver

java.lang.Object
  |
  +--aktbus.core.AktBusReceiver
Direct Known Subclasses:
KqmlMessageReceiver

public class AktBusReceiver
extends java.lang.Object

The AktBusReceiver class receives an AktMessage through a socket. It can also be subclassed to receive messages which are subclasses of AktMessage. To do so, you should create a subclass of AktBusReceiver and define the message_creator method which construct your customised message from a String. The original AktBusReceiver receives a single message and disconnects from the client by the receive or receive_with_path method. In expanding it to accommodate piggy-packed reply, receive_with_extra is added, which does not disconnect after receiving an incoming message. This allows a customised reply to be sent through the same connection. If you use the piggy-packed feature, make sure that you call the close_connection method on the AktMessageWithExtra object when you finish.


Constructor Summary
AktBusReceiver()
          Creates an AktBusReceiver object that listens to a free port.
AktBusReceiver(int port)
          Creates an AktBusReceiver object that listens to a certain port.
 
Method Summary
 void close()
          Shutdown the receiver and release the port in use.
 int get_port()
          Returns the local port number that the AktBusReceiver is listening to.
 AktMessage receive_message()
          Receive and return an AktMessage.
 AktMessage receive_message(int timeout, java.lang.Class reply_class)
          Receive and return an AktMessage with timeout and expect a reply of a certain class.
 AktMessageWithExtra receive_with_extra()
          Waits and receive an AktMessageWithExtra.
 AktMessageWithExtra receive_with_extra(int timeout, java.lang.Class result_class)
          Waits and receive an AktMessageWithExtra with timeout.
 AktMessageWithExtra receive_with_extra(int timeout, java.lang.String class_string)
          Waits and receive an AktMessageWithExtra with timeout.
 AktMessageWithPath receive()
          Waits and receive an AktMessageWithPath.
 AktMessageWithPath receive(int timeout, java.lang.Class result_class)
          Waits and receive an AktMessageWithPath with timeout.
 AktMessageWithPath receive(int timeout, java.lang.String class_string)
          Waits and receive an AktMessageWithPath with timeout.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AktBusReceiver

public AktBusReceiver()
               throws java.io.IOException
Creates an AktBusReceiver object that listens to a free port. To find out the port being chosen, use the get_port() method.
Throws:
java.io.IOException - When any I/O error occurs.

AktBusReceiver

public AktBusReceiver(int port)
               throws java.io.IOException
Creates an AktBusReceiver object that listens to a certain port.
Parameters:
port - The port number to listen. If port is 0, then a free port will be used.
Throws:
java.io.IOException - When any I/O error occurs.
Method Detail

get_port

public int get_port()
Returns the local port number that the AktBusReceiver is listening to.
Returns:
The local port number in use.

close

public void close()
           throws java.io.IOException
Shutdown the receiver and release the port in use.
Throws:
java.io.IOException - When an I/O error occurs during closing.

receive_message

public AktMessage receive_message()
                           throws org.xml.sax.SAXException,
                                  java.io.IOException,
                                  java.lang.Exception
Receive and return an AktMessage. This method blocks until a reply is received. To receive with timeout, use receive_message(int) instead To reply an instance of a subclass of AktMessage, use receive_message(int,java.lang.String) or receive_message(int,java.lang.Class).
Returns:
An instance of the AktMessage class or one of its sub-classes.
Throws:
org.xml.sax.SAXException - When the received content cannot be parsed into XML.
java.io.IOException - If anything goes wrong witht the I/O.
java.lang.Exception - When other general error occurs.

receive_message

public AktMessage receive_message(int timeout,
                                  java.lang.Class reply_class)
                           throws org.xml.sax.SAXException,
                                  java.io.IOException,
                                  java.lang.Exception
Receive and return an AktMessage with timeout and expect a reply of a certain class.
Parameters:
timeout - The timeout value in second.
reply_class - The expect class of the replying message in a java.lang.Class object.
Returns:
An instance of the AktMessage class or one of its sub-classes.
Throws:
org.xml.sax.SAXException - When the received content cannot be parsed into XML.
java.io.IOException - If anything goes wrong witht the I/O.
java.lang.Exception - When other general error occurs.

receive

public AktMessageWithPath receive()
                           throws java.io.IOException,
                                  org.xml.sax.SAXException,
                                  java.lang.Exception
Waits and receive an AktMessageWithPath.
Returns:
Returns an AktMessageWithPath object.
Throws:
org.xml.sax.SAXException - When the received content cannot be parsed into XML.
java.io.IOException - If anything goes wrong witht the I/O.
java.lang.Exception - When other general error occurs.

receive

public AktMessageWithPath receive(int timeout,
                                  java.lang.String class_string)
                           throws java.io.IOException,
                                  org.xml.sax.SAXException,
                                  java.lang.Exception
Waits and receive an AktMessageWithPath with timeout.
Parameters:
timeout - The timeout value in second.
class_string - The expected class of the reply as a String.
Returns:
Returns an AktMessageWithPath.

receive

public AktMessageWithPath receive(int timeout,
                                  java.lang.Class result_class)
                           throws java.io.IOException,
                                  org.xml.sax.SAXException,
                                  java.lang.Exception
Waits and receive an AktMessageWithPath with timeout.
Parameters:
timeout - The timeout value in second.
result_class - The expected class of the reply as an java.lang.Class object.
Returns:
Returns an AktMessageWithPath.

receive_with_extra

public AktMessageWithExtra receive_with_extra()
                                       throws org.xml.sax.SAXException,
                                              java.io.IOException,
                                              java.lang.Exception
Waits and receive an AktMessageWithExtra. This is usually used when a piggy-packed reply is needed.
Returns:
An AktMessageWithExtra object containing the received AktMessage and other extra information.

receive_with_extra

public AktMessageWithExtra receive_with_extra(int timeout,
                                              java.lang.String class_string)
                                       throws java.io.IOException,
                                              org.xml.sax.SAXException,
                                              java.lang.Exception
Waits and receive an AktMessageWithExtra with timeout. This is usually used when a piggy-packed reply is needed.
Parameters:
timeout - The timeout value in second.
class_string - The expected class of the reply message as a String.
Returns:
An AktMessageWithExtra object containing the received AktMessage and other extra information.

receive_with_extra

public AktMessageWithExtra receive_with_extra(int timeout,
                                              java.lang.Class result_class)
                                       throws java.io.IOException,
                                              org.xml.sax.SAXException,
                                              java.lang.Exception
Waits and receive an AktMessageWithExtra with timeout. This is usually used when a piggy-packed reply is needed.
Parameters:
timeout - The timeout value in second.
result_class - The expected class of the reply message as a java.lang.Class object.
Returns:
An AktMessageWithExtra object containing the received AktMessage and other extra information.