net.sf.freecol.common.networking
Class Connection

java.lang.Object
  extended by net.sf.freecol.common.networking.Connection
Direct Known Subclasses:
DummyConnection

public class Connection
extends java.lang.Object

A network connection. Responsible for both sending and receiving network messages.

See Also:
send(Element), sendAndWait(Element), ask(Element)

Constructor Summary
Connection(java.net.Socket socket, MessageHandler messageHandler, java.lang.String threadName)
          Creates a new Connection with the specified Socket and MessageHandler.
Connection(java.lang.String host, int port, MessageHandler messageHandler, java.lang.String threadName)
          Sets up a new socket with specified host and port and uses #Connection(Socket, MessageHandler).
 
Method Summary
 javax.xml.stream.XMLStreamWriter ask()
          Starts a session for asking a question using streaming.
 org.w3c.dom.Element ask(org.w3c.dom.Element element)
          Sends a message to the other peer and returns the reply.
 void close()
          Sends a "disconnect"-message and closes this connection.
 void endTransmission(javax.xml.stream.XMLStreamReader in)
          Ends the transmission of a message or a ask/get-reply session.
 MessageHandler getMessageHandler()
          Gets the MessageHandler for this Connection.
 javax.xml.stream.XMLStreamReader getReply()
          Gets the reply being received after sending a question.
 java.net.Socket getSocket()
          Gets the socket.
 void handleAndSendReply(java.io.BufferedInputStream in)
          Handles a message using the registered MessageHandler.
 void reallyClose()
          Closes this connection.
 javax.xml.stream.XMLStreamWriter send()
          Starts a session for sending a message using streaming.
 void send(org.w3c.dom.Element element)
          Sends the given message over this Connection.
 void sendAndWait(org.w3c.dom.Element element)
          Sends the given message over this Connection and waits for confirmation of receiveval before returning.
 void setMessageHandler(MessageHandler mh)
          Sets the MessageHandler for this Connection.
 java.lang.String toString()
          Override the default and return socket details.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Connection

public Connection(java.lang.String host,
                  int port,
                  MessageHandler messageHandler,
                  java.lang.String threadName)
           throws java.io.IOException
Sets up a new socket with specified host and port and uses #Connection(Socket, MessageHandler).

Parameters:
host - The host to connect to.
port - The port to connect to.
messageHandler - The MessageHandler to call for each message received.
Throws:
java.io.IOException

Connection

public Connection(java.net.Socket socket,
                  MessageHandler messageHandler,
                  java.lang.String threadName)
           throws java.io.IOException
Creates a new Connection with the specified Socket and MessageHandler.

Parameters:
socket - The socket to the client.
messageHandler - The MessageHandler to call for each message received.
Throws:
java.io.IOException
Method Detail

close

public void close()
           throws java.io.IOException
Sends a "disconnect"-message and closes this connection.

Throws:
java.io.IOException

reallyClose

public void reallyClose()
                 throws java.io.IOException
Closes this connection.

Throws:
java.io.IOException

send

public void send(org.w3c.dom.Element element)
          throws java.io.IOException
Sends the given message over this Connection.

Parameters:
element - The element (root element in a DOM-parsed XML tree) that holds all the information
Throws:
java.io.IOException - If an error occur while sending the message.
See Also:
sendAndWait(Element), ask(Element)

ask

public org.w3c.dom.Element ask(org.w3c.dom.Element element)
                        throws java.io.IOException
Sends a message to the other peer and returns the reply.

Parameters:
element - The question for the other peer.
Returns:
The reply from the other peer.
Throws:
java.io.IOException - If an error occur while sending the message.
See Also:
send(Element), sendAndWait(Element)

ask

public javax.xml.stream.XMLStreamWriter ask()
                                     throws java.io.IOException
Starts a session for asking a question using streaming. There is also a simpler method for sending data using XML Elements that can be used when streaming is not required (that is: when the messages to be transmitted are small).

Example:
 
 try { XMLStreamWriter out = ask(); // Write XML here XMLStreamReader in =
 connection.getReply(); // Read XML here connection.endTransmission(in); }
 catch (IOException e) { logger.warning("Could not send XML."); }
 
 

Returns:
The XMLStreamWriter for sending the question. The method getReply() should be called when the message has been written and the reply is required.
Throws:
java.io.IOException - if thrown by the underlying network stream.
See Also:
getReply(), endTransmission(XMLStreamReader)

send

public javax.xml.stream.XMLStreamWriter send()
                                      throws java.io.IOException
Starts a session for sending a message using streaming. There is also a simpler method for sending data using XML Elements that can be used when streaming is not required (that is: when the messages to be transmitted are small).

Example:
 
 try { XMLStreamWriter out = send(); // Write XML here
 connection.endTransmission(in); } catch (IOException e) {
 logger.warning("Could not send XML."); }
 
 

Returns:
The XMLStreamWriter for sending the question. The method endTransmission(XMLStreamReader) should be called when the message has been written.
Throws:
java.io.IOException - if thrown by the underlying network stream.
See Also:
getReply(), endTransmission(XMLStreamReader)

getReply

public javax.xml.stream.XMLStreamReader getReply()
                                          throws java.io.IOException
Gets the reply being received after sending a question.

Returns:
An XMLStreamReader for reading the incoming data.
Throws:
java.io.IOException - if thrown by the underlying network stream.
See Also:
ask()

endTransmission

public void endTransmission(javax.xml.stream.XMLStreamReader in)
                     throws java.io.IOException
Ends the transmission of a message or a ask/get-reply session.

Throws:
java.io.IOException - if thrown by the underlying network stream.
See Also:
ask(), send()

sendAndWait

public void sendAndWait(org.w3c.dom.Element element)
                 throws java.io.IOException
Sends the given message over this Connection and waits for confirmation of receiveval before returning.

Parameters:
element - The element (root element in a DOM-parsed XML tree) that holds all the information
Throws:
java.io.IOException - If an error occur while sending the message.
See Also:
send(Element), ask(Element)

setMessageHandler

public void setMessageHandler(MessageHandler mh)
Sets the MessageHandler for this Connection.

Parameters:
mh - The new MessageHandler for this Connection.

getMessageHandler

public MessageHandler getMessageHandler()
Gets the MessageHandler for this Connection.

Returns:
The MessageHandler for this Connection.

handleAndSendReply

public void handleAndSendReply(java.io.BufferedInputStream in)
Handles a message using the registered MessageHandler.

Parameters:
in - The stream containing the message.

getSocket

public java.net.Socket getSocket()
Gets the socket.

Returns:
The Socket used while communicating with the other peer.

toString

public java.lang.String toString()
Override the default and return socket details.

Overrides:
toString in class java.lang.Object
Returns:
human-readable description of connection.