org.eclipse.californium.scandium.dtls

Class DTLSFlight

java.lang.Object

org.eclipse.californium.scandium.dtls.DTLSFlight

public class DTLSFlight
extends Object

A container for a set of DTLS records that are to be (re-)transmitted as a whole on a DTLS connection. DTLS messages are grouped into a series of message flights. One flight consists of at least one message and needs to be re-transmitted until the peer's next flight has arrived in its total. A flight needs not only consist of HandshakeMessages but may also contain AlertMessages and ChangeCipherSpecMessages. See RFC 6347 for details. Scandium offers also the possibility to stop the retransmission with receiving the first response message instead of the complete flight. That is currently configurable using DtlsConnectorConfig.isEarlyStopRetransmission(). Only for the flight before the very last flight of a handshake, it must be ensured, that the retransmission is only stopped, after that very last flight is received completely. Though the very last flight in DTLS 1.2 is always a flight with CCS and FINISH, the implementation just use message of type handshake to stop the retransmissions. Even with stopped retransmission, a flight may timeout a handshake, if the handshake response could not received completely. That timeout with stopped retransmission is implemented using the timeout of the current try/retry and the timeout used for the retry, when the maximum number of retries is reached. To support both variants, the flight provides the responseStarted and responseCompleted flags and a general handle to a timeout task.

See Also:

"e-mail discussion IETF TLS mailarchive, 2017, May 31. - June 1., Simone Bernard and Raja Ashok"

Constructor Summary

Constructors

Constructor and Description
DTLSFlight(DTLSSession session, int flightNumber) Creates an empty flight to be sent within a session with a peer.

Method Summary

Methods

Modifier and Type	Method and Description
void	addDtlsMessage(int epoch, DTLSMessage messageToAdd) Adds a dtls message to this flight.
boolean	contains(DTLSMessage message) Check, if the provided message is contained in this flight.
List<DatagramPacket>	getDatagrams(int maxDatagramSize, int maxFragmentSize, Boolean useMultiHandshakeMessageRecords, Boolean useMultiRecordMessages, boolean backOff) List of datagrams to be sent for this flight.
int	getFlightNumber() Get the flight number.
int	getNumberOfMessages() Get number of dtls messages of this flight.
List<Record>	getRecords(int maxDatagramSize, int maxFragmentSize, boolean useMultiHandshakeMessageRecords) Get wrapped records for flight.
int	getTimeout() Get timeout.
int	getTries() Get number of (re-)tries.
void	incrementTimeout() Called, when the flight needs to be retransmitted.
static int	incrementTimeout(int timeoutMillis) Increment the timeout, here we double it.
void	incrementTries() Increment number of (re-)tries.
boolean	isResponseCompleted() Check, if retransmission was cancelled.
boolean	isResponseStarted() Indicates, that first handshake message of the response is received.
boolean	isRetransmissionNeeded() Indicate, if flight needs retransmission.
void	scheduleRetransmission(ScheduledExecutorService timer, Runnable task) Schedule timeout or retransmission task.
void	setResponseCompleted() Cancels retransmission of this flight.
void	setResponseStarted() Signal, that the first handshake message of the response is received.
void	setRetransmissionNeeded(boolean needsRetransmission) Set retransmission needs.
void	setTimeout(int timeout) Set timeout
protected void	wrapMessage(org.eclipse.californium.scandium.dtls.DTLSFlight.EpochMessage epochMessage) Wraps a DTLS message into (potentially multiple) DTLS records and add them to the flight.

Methods inherited from class java.lang.Object

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

Constructor Detail

DTLSFlight

public DTLSFlight(DTLSSession session,
          int flightNumber)

Creates an empty flight to be sent within a session with a peer. Flights created using this constructor are by default eligible for re-transmission.

Parameters:

session - the session to get record sequence numbers from when sending out the flight

flightNumber - number of the flight. Used for logging and MessageCallback.onDtlsRetransmission(int).

Throws:

NullPointerException - if session or peer address of session is null

Method Detail

addDtlsMessage

public void addDtlsMessage(int epoch,
                  DTLSMessage messageToAdd)

Adds a dtls message to this flight.

Parameters:

epoch - the epoch of the dtls message.

messageToAdd - the dtls message to add.

Since:

2.4

getNumberOfMessages

public int getNumberOfMessages()

Get number of dtls messages of this flight.

Returns:

number of dtls messages

Since:

2.4

contains

public boolean contains(DTLSMessage message)

Check, if the provided message is contained in this flight.

Parameters:

message - message to check

Returns:

true, if message is contained, false, if not.

Since:

2.5

wrapMessage

protected final void wrapMessage(org.eclipse.californium.scandium.dtls.DTLSFlight.EpochMessage epochMessage)
                          throws HandshakeException

Wraps a DTLS message into (potentially multiple) DTLS records and add them to the flight. Sets the record's epoch, sequence number and handles fragmentation for handshake messages.

Parameters:

epochMessage - dtls message and epoch

Throws:

HandshakeException - if the message could not be encrypted using the session's current security parameters

Since:

2.4

getRecords

public List<Record> getRecords(int maxDatagramSize,
                      int maxFragmentSize,
                      boolean useMultiHandshakeMessageRecords)
                        throws HandshakeException

Get wrapped records for flight.

Parameters:

maxDatagramSize - maximum datagram size

maxFragmentSize - maximum fragment size

useMultiHandshakeMessageRecords - enable to use dtls records with multiple handshake messages.

Returns:

list of records

Throws:

HandshakeException - if the message could not be encrypted using the session's current security parameters

Since:

2.4

getDatagrams

public List<DatagramPacket> getDatagrams(int maxDatagramSize,
                                int maxFragmentSize,
                                Boolean useMultiHandshakeMessageRecords,
                                Boolean useMultiRecordMessages,
                                boolean backOff)
                                  throws HandshakeException

List of datagrams to be sent for this flight.

Parameters:

maxDatagramSize - maximum datagram size

maxFragmentSize - maximum fragment size

useMultiHandshakeMessageRecords - enable to use dtls records with multiple handshake messages.

useMultiRecordMessages - use datagrams with multiple dtls records

backOff - send flight in back off mode.

Returns:

list of datagrams

Throws:

HandshakeException - if the message could not be encrypted using the session's current security parameters

Since:

2.4

getFlightNumber

public int getFlightNumber()

Get the flight number.

Returns:

flight number

getTries

public int getTries()

Get number of (re-)tries.

Returns:

number of (re-)tries

incrementTries

public void incrementTries()

Increment number of (re-)tries.

getTimeout

public int getTimeout()

Get timeout.

Returns:

timeout in milliseconds.

setTimeout

public void setTimeout(int timeout)

Set timeout

Parameters:

timeout - timeout in milliseconds.

incrementTimeout

public void incrementTimeout()

Called, when the flight needs to be retransmitted. Increment the timeout, here we double it. Limit the timeout to MAX_TIMEOUT_MILLIS.

See Also:

incrementTimeout(int)

isRetransmissionNeeded

public boolean isRetransmissionNeeded()

Indicate, if flight needs retransmission.

Returns:

true, if flight needs retransmission, false, otherwise.

setRetransmissionNeeded

public void setRetransmissionNeeded(boolean needsRetransmission)

Set retransmission needs.

Parameters:

needsRetransmission - true, if flight needs retransmission, false, otherwise.

isResponseStarted

public boolean isResponseStarted()

Indicates, that first handshake message of the response is received.

Returns:

true, if the first handshake message of the response is received, false, otherwise.

setResponseStarted

public void setResponseStarted()

Signal, that the first handshake message of the response is received. If DtlsConnectorConfig.isEarlyStopRetransmission() is configured, this stops sending retransmissions but keep a scheduled timeout task.

setResponseCompleted

public void setResponseCompleted()

Cancels retransmission of this flight. Response flight is received completely. Note: a already cancelled flight could not be restarted using scheduleRetransmission(ScheduledExecutorService, Runnable).

isResponseCompleted

public boolean isResponseCompleted()

Check, if retransmission was cancelled.

Returns:

true, if retransmission was cancelled, false, otherwise.

scheduleRetransmission

public void scheduleRetransmission(ScheduledExecutorService timer,
                          Runnable task)

Schedule timeout or retransmission task.

Parameters:

timer - timer to schedule task.

task - task to be scheduled executed

Since:

2.4

incrementTimeout

public static int incrementTimeout(int timeoutMillis)

Increment the timeout, here we double it. Limit the timeout to MAX_TIMEOUT_MILLIS.

Parameters:

timeoutMillis - timeout in milliseconds

Returns:

doubled and limited timeout in milliseconds

Since:

2.1

See Also:

incrementTimeout()