com.github.mucaho.jnetrobust
Class Protocol<T>

java.lang.Object
  extended by com.github.mucaho.jnetrobust.Protocol<T>
Type Parameters:
T - the user data type
All Implemented Interfaces:
java.util.Comparator<java.lang.Short>
public class Protocol<T>
extends java.lang.Object
implements java.util.Comparator<java.lang.Short>

The central API class that represents the virtual protocol. It maintains the state of a virtual protocol instance and offers methods to alter that state by wrapping user data with protocol specific metadata.

Various constructors are offered to instantiate a new protocol instance.

Typically you call the protocol's send(Object) and receive(Packet) methods in order to attach/detach protocol-specific information to your user data. This protocol-specific information and the protocol's internal state is then used to enable reliable & ordered communication even over an unreliable medium.

Note that both send(Object) and receive(Packet) methods may trigger zero or more listener events before they return.

How serialization is done and over which medium the packaged user-data is sent is up to the user (analogue for receiving and deserialization).

Note that always the same two protocol instances must communicate with each other, as they share a distributed state together.

In order for the protocol to work the user must immediately acknowledge received data, either by sending an empty transmission or sending new user-data if it is available. The user may delay doing this, if he is sending new data at a fixed interval < 50ms.

The send(Object, java.io.ObjectOutput) & receive(java.io.ObjectInput) are utility methods which automatically write the packaged user-data to a ObjectOutput or read the packaged user-data from a ObjectInput respectively. Other than that, they behave exactly like the send(Object) and receive(Packet) methods.

This class also offer utility methods to query the round-trip time, as well as the round-trip time variation.

This class also offers the ability to compare dataIds against each other. The user must not compare these ids with built-in comparison operators. These ids wrap around to their min value once they are incremented beyond their max value, hence this compare method must be used.

Constructor Summary
Protocol(ProtocolConfig<T> config)
          Construct a new protocol instance using the supplied protocol configuration.
Protocol(ProtocolConfig<T> config, Logger logger)
          Construct a new protocol instance using the supplied protocol configuration.
Protocol(ProtocolListener<T> protocolListener)
          Construct a new protocol instance using the default protocol configuration.
Protocol(ProtocolListener<T> protocolListener, Logger logger)
          Construct a new protocol instance using the default protocol configuration.
 
Method Summary
 int compare(java.lang.Short dataId1, java.lang.Short dataId2)
          Compare dataIds against each other.
 long getRTTVariation()
          Get the round-trip time variance.
 long getSmoothedRTT()
          Get the round-trip time.
 java.util.NavigableMap<java.lang.Short,T> receive(java.io.ObjectInput objectInput)
          Convenience method which reads the input of an ObjectInput with the help of internally called receive(package).
 java.util.NavigableMap<java.lang.Short,T> receive(com.github.mucaho.jnetrobust.controller.Packet<T> packet)
          Unpackage the packaged user-data, in order to retrieve the user-data that was received, acknowledge sent data and receive retransmitted data (if retransmission is enabled).
 java.util.Map.Entry<java.lang.Short,com.github.mucaho.jnetrobust.controller.Packet<T>> send()
          Convenience method does the same as send(null).
 java.util.Map.Entry<java.lang.Short,com.github.mucaho.jnetrobust.controller.Packet<T>> send(T data)
          Package the user-data, in order to transmit the user-data, acknowledge received data and retransmit data (if retransmission is enabled).
 java.util.Map.Entry<java.lang.Short,com.github.mucaho.jnetrobust.controller.Packet<T>> send(T data, java.io.ObjectOutput objectOutput)
          Convenience method which writes the output of internally called send(data) to a ObjectOutput.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface java.util.Comparator
equals
 

Constructor Detail

Protocol

public Protocol(ProtocolListener<T> protocolListener)
Construct a new protocol instance using the default protocol configuration.

Parameters:
protocolListener - the ProtocolListener which will be notified about protocol events

Protocol

public Protocol(ProtocolConfig<T> config)
Construct a new protocol instance using the supplied protocol configuration.

Parameters:
config - the protocol configuration which will be used to configure this protocol instance

Protocol

public Protocol(ProtocolListener<T> protocolListener,
                Logger logger)
Construct a new protocol instance using the default protocol configuration. Internal state changes will be logged using the supplied logger.

Parameters:
protocolListener - the ProtocolListener which will be notified about protocol events
logger - the Logger which will be used to track internal state changes

Protocol

public Protocol(ProtocolConfig<T> config,
                Logger logger)
Construct a new protocol instance using the supplied protocol configuration. Internal state changes will be logged using the supplied logger.

Parameters:
config - the protocol configuration which will be used to configure this protocol instance
logger - the Logger which will be used to track internal state changes
Method Detail

send

public java.util.Map.Entry<java.lang.Short,com.github.mucaho.jnetrobust.controller.Packet<T>> send()
Convenience method does the same as send(null).

See Also:
send(null)

send

public java.util.Map.Entry<java.lang.Short,com.github.mucaho.jnetrobust.controller.Packet<T>> send(T data)
Package the user-data, in order to transmit the user-data, acknowledge received data and retransmit data (if retransmission is enabled).
Zero or more unackedData events may be fired before this method returns.

Parameters:
data - the user-data to package, if it's null no user-data will be contained in the package
Returns:
a Map.Entry containing the packaged user-data and the dataId that was assigned to the user-data; the returned mapEntry should not be saved by the user, as its contents are invalidated next time one of the send methods is called

send

public java.util.Map.Entry<java.lang.Short,com.github.mucaho.jnetrobust.controller.Packet<T>> send(T data,
                                                                                                   java.io.ObjectOutput objectOutput)
                                                                                            throws java.io.IOException
Convenience method which writes the output of internally called send(data) to a ObjectOutput.

Parameters:
objectOutput - the object output to write the packaged user-data to
Throws:
java.io.IOException - if there was an error writing to the ObjectOutput
See Also:
send(data)

receive

public java.util.NavigableMap<java.lang.Short,T> receive(com.github.mucaho.jnetrobust.controller.Packet<T> packet)
Unpackage the packaged user-data, in order to retrieve the user-data that was received, acknowledge sent data and receive retransmitted data (if retransmission is enabled).
Zero or more orderedData, unorderedData or ackedData events may be fired before this method returns.

Parameters:
packet - the packaged-user data to unpackage
Returns:
a NavigableMap containing all received (directly received or received by retransmission) user-datas and their assigned dataIds; the returned object should not be saved by the user, as its contents are invalidated next time one of the receive methods is called

receive

public java.util.NavigableMap<java.lang.Short,T> receive(java.io.ObjectInput objectInput)
                                                  throws java.io.IOException,
                                                         java.lang.ClassNotFoundException
Convenience method which reads the input of an ObjectInput with the help of internally called receive(package).

Parameters:
objectInput - the object input to read the packaged user-data from
Throws:
java.io.IOException - if there was an error reading from the ObjectInput
java.lang.ClassNotFoundException - if the object being read from the ObjectInput is not of the correct type
See Also:
receive(package)

compare

public int compare(java.lang.Short dataId1,
                   java.lang.Short dataId2)
Compare dataIds against each other. The user must not compare these ids with built-in comparison operators. These ids wrap around to their min value once they are incremented beyond their max value, hence this compare method must be used.

Specified by:
compare in interface java.util.Comparator<java.lang.Short>
Parameters:
dataId1 - the first id to compare
dataId2 - the second id to compare
Returns:

getSmoothedRTT

public long getSmoothedRTT()
Get the round-trip time.

Updated on receiving acknowledgement of data receipt, using the formula RTT_SMOOTHED_AVG = 7/8 * RTT_SMOOTHED_AVG + 1/8 * RTT_NEW

Returns:
the exponentially smoothed round-trip time

getRTTVariation

public long getRTTVariation()
Get the round-trip time variance.

Updated on receiving acknowledgement of data receipt, using the formula RTT_SMOOTHED_VAR = 3/4 * RTT_SMOOTHED_VAR + 1/4 * |RTT_SMOOTHED_AVG - RTT_NEW|

Returns:
the exponentially smoothed round-trip time variance