net.sf.freecol.common.networking
Class Connection

java.lang.Object
  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)

Field Summary

private int	currentQuestionID
private java.io.InputStream	in
private static java.util.logging.Logger	logger
private MessageHandler	messageHandler
private java.io.OutputStream	out
private java.net.Socket	socket
private ReceivingThread	thread
private java.lang.String	threadName
private static int	TIMEOUT
private javax.xml.stream.XMLStreamWriter	xmlOut
private javax.xml.transform.Transformer	xmlTransformer
private javax.xml.stream.XMLOutputFactory	xof

Constructor Summary

protected	Connection() Dead constructor, for DummyConnection purposes.
	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, String).

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.
private static java.net.Socket	createSocket(java.lang.String host, int port)
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.
private void	releaseQuestionId() Release a previously obtained question id.
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.
private void	waitForAndSetNewQuestionId() Wait until the previous question has been released, then install a new question id.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

logger

private static final java.util.logging.Logger logger

TIMEOUT

private static final int TIMEOUT

See Also:

Constant Field Values

out

private final java.io.OutputStream out

in

private final java.io.InputStream in

socket

private final java.net.Socket socket

xmlTransformer

private final javax.xml.transform.Transformer xmlTransformer

thread

private final ReceivingThread thread

xof

private final javax.xml.stream.XMLOutputFactory xof

messageHandler

private MessageHandler messageHandler

xmlOut

private javax.xml.stream.XMLStreamWriter xmlOut

currentQuestionID

private int currentQuestionID

threadName

private java.lang.String threadName

Constructor Detail

Connection

protected Connection()

Dead constructor, for DummyConnection purposes.

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, String).

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

createSocket

private static java.net.Socket createSocket(java.lang.String host,
                                            int port)
                                     throws java.io.IOException

Throws:

java.io.IOException

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)

releaseQuestionId

private void releaseQuestionId()

Release a previously obtained question id. This is absolutely necessary as other questions will be blocked as long as the old id is in place.

See Also:

waitForAndSetNewQuestionId()

waitForAndSetNewQuestionId

private void waitForAndSetNewQuestionId()

Wait until the previous question has been released, then install a new question id. The caller is then free to send.

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.