Connections Manual

Connections

Procedural Considerations
The basic idea of JennyNet is to make life of applications using this network-layer as convenient as possible. Therefore the layer is fundamentally multi-threaded. By this design we achieve the following benefits

• sending and receiving are parallel running tasks, and as much as the operating system supports this, can operate parallel on the network socket
• delivery of send-orders to the layer (e.g. send objects) returns immediately independent of ongoing network load while serialisations and actual transmission of data are performed in separate threads

This design relieves the application of a chunk of time related considerations and capitalises on the presence of multiple processors on the computer. One of the points to be observed, however, is that deliveries from the layer to the application (objects and events) occur in a separate thread. Where such a design cannot be handled, it can be easily transformed for single-threaded polling. JennyNet offers the class ConnectionPollService which implements ConnectionListener and queues for received objects and events.

File-transfers, including local writing of data, are always performed in a separate thread for each file. The events concerning file-transfers can also be made available via the poll service.

Object Delivery and Send Priority
Object delivery at the receiver basically occurs in the same order as objects were pushed for sending. However, this is only valid for the same Send Priority class assigned to an object at its send event. By principle objects are delivered to the user when they are completely received from the network, indiscriminate of their priority setting. However, transmission of data parcels of higher priority are preferred, thus resulting that the reception order of objects of different Priority settings is unpredictable. There are 7 Priority levels available, comfortably given in an enum.

If a ConnectionListener is used for event reporting, the layer ensures that only one event is reported at any time. No assertion is possible about the identity of the delivery thread other than it is not a user's thread.

Sending Data

Sending Objects -- to be done --
Transmitting Files -- to be done --

Disconnection
A Connection is valid for communication until it is disconnected. Once a connection is disconnected it becomes invalid and cannot be re-established; the instance has to be dropped and a new Client set up on the client side if communication has to be continued. On the server side, a Connection can only be accepted but not created.

Disconnection can occur for various reasons ranging from technical issues of the net to decisive action of any one of the two communication sides. Disconnection is indicated to the user over the ConnectionListener.disconnected method. The parameters of this method supply information about the type of cause involved and, if lucky, a text message. When objects are tried to be sent over a disconnected Connection, a ClosedConnectionException is thrown.

/** Called when the remote end is no longer connected. 
* 
* @param connection <code>Connection</code>  source connection
* @param cause int code for cause of disconnection if available
* @param message String message about cause of disconnection if available
*/
public void disconnected (Connection connection, int cause, String message);

---

Closing Connections
Connections can be actively closed by any communication side by the Connection.close() method. This relays a "Disconnected" event to connection listeners and the closing of this connection on the remote station. The contract on closed connections is that

• ongoing file transmissions are immediately and completely broken
• ongoing signal and object receive transmissions are broken and never reported
• ongoing signal and object send transmissions are completed before the Connection is closed on the remote side and the socket locally
• registered local ConnectionListener receive a Disconnected event immediately