org.eclipse.californium.scandium.dtls

Class Connection

java.lang.Object

org.eclipse.californium.scandium.dtls.Connection

public final class Connection
extends Object

Information about the DTLS connection to a peer. Contains status information regarding

• a potentially ongoing handshake with the peer
• an already established session with the peer

Constructor Summary

Constructors

Constructor and Description
Connection(InetSocketAddress peerAddress, org.eclipse.californium.elements.util.SerialExecutor serialExecutor) Creates a new connection to a given peer.
Connection(SessionTicket sessionTicket, SessionId sessionId, InetSocketAddress peerAddress) Creates a new connection from a session ticket containing current state from another connection that should be resumed.

Method Summary

Methods

Modifier and Type	Method and Description
void	close(Record record) Close connection with record.
boolean	equalsPeerAddress(InetSocketAddress peerAddress) Check, if the provided address is the peers address.
boolean	expectCid() Check, if this connection expects connection ID for incoming records.
ConnectionId	getConnectionId() Gets the connection id.
DTLSSession	getEstablishedSession() Gets the already established DTLS session that exists with this connection's peer.
org.eclipse.californium.elements.util.SerialExecutor	getExecutor() Gets the serial executor assigned to this connection.
long	getLastPeerAddressNanos() Get real time nanoseconds of last updatePeerAddress(InetSocketAddress).
Handshaker	getOngoingHandshake() Gets the handshaker managing the currently ongoing handshake with the peer.
InetSocketAddress	getPeerAddress() Gets the address of this connection's peer.
AlertMessage	getRootCauseAlert() Gets the root cause alert.
InetSocketAddress	getRouter() Gets the address of this connection's router.
DTLSSession	getSession() Gets the session containing the connection's current state.
DTLSSession	getSession(int readEpoch) Gets the session containing the connection's current state for the provided epoch.
SessionId	getSessionIdentity() Gets the session identity this connection can be resumed from.
SessionListener	getSessionListener() Get session listener of connection.
SessionTicket	getSessionTicket() Gets the session ticket this connection can be resumed from.
boolean	hasEstablishedSession() Checks whether a session has already been established with the peer.
boolean	hasOngoingHandshake() Checks whether there is a handshake going on with the peer.
boolean	isActive() Checks whether this connection is either in use on this node or can be resumed by peers interacting with this node.
boolean	isAutoResumptionRequired(Long autoResumptionTimeoutMillis) Check, if the automatic session resumption should be triggered or is already required.
boolean	isClosed() Check, if connection was closed.
boolean	isExecuting() Checks, if the connection has a executing serial executor.
boolean	isResumptionRequired() Check, if resumption is required.
boolean	isStartedByClientHello(ClientHello clientHello) Checks whether this connection is started for the provided CLIENT_HELLO.
void	refreshAutoResumptionTime() Refresh auto resumption timeout.
void	resetSession() Reset session.
void	setConnectionId(ConnectionId cid) Sets the connection id.
void	setExecutionListener(ConnectionExecutionListener listener)
void	setExecutor(org.eclipse.californium.elements.util.SerialExecutor serialExecutor) Set new executor to restart execution for stopped connection.
void	setResumptionRequired(boolean resumptionRequired) Use to force an abbreviated handshake next time a data will be sent on this connection.
void	setRootCause(AlertMessage rootCause) Sets root cause alert.
void	setRouter(InetSocketAddress router) Sets the address of this connection's router.
void	startByClientHello(ClientHello clientHello) Set starting CLIENT_HELLO.
String	toString()
void	updateConnectionState()
void	updatePeerAddress(InetSocketAddress peerAddress) Update the address of this connection's peer.

Methods inherited from class java.lang.Object

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

Constructor Detail

Connection

public Connection(InetSocketAddress peerAddress,
          org.eclipse.californium.elements.util.SerialExecutor serialExecutor)

Creates a new connection to a given peer.

Parameters:

peerAddress - the IP address and port of the peer the connection exists with

serialExecutor - serial executor.

Throws:

NullPointerException - if the peer address or the serial executor is null

Connection

public Connection(SessionTicket sessionTicket,
          SessionId sessionId,
          InetSocketAddress peerAddress)

Creates a new connection from a session ticket containing current state from another connection that should be resumed. The connection is not isExecuting().

Parameters:

sessionTicket - The other connection's current state.

sessionId - The other connection's session id.

peerAddress - optional peer address for ClientSessionCache. May be null.

Throws:

NullPointerException - if the session ticket or id is null

Method Detail

setExecutionListener

public void setExecutionListener(ConnectionExecutionListener listener)

updateConnectionState

public void updateConnectionState()

setExecutor

public void setExecutor(org.eclipse.californium.elements.util.SerialExecutor serialExecutor)

Set new executor to restart execution for stopped connection.

Parameters:

serialExecutor - new serial executor

Throws:

NullPointerException - if the serial executor is null

IllegalStateException - if the connection is already executing

getExecutor

public org.eclipse.californium.elements.util.SerialExecutor getExecutor()

Gets the serial executor assigned to this connection.

Returns:

serial executor. May be null, if the connection was created with Connection(SessionTicket, SessionId, InetSocketAddress).

isExecuting

public boolean isExecuting()

Checks, if the connection has a executing serial executor.

Returns:

true, if the connection has an executing serial executor. false, if no serial executor is available, or the executor is shutdown.

getSessionListener

public final SessionListener getSessionListener()

Get session listener of connection.

Returns:

session listener.

isActive

public boolean isActive()

Checks whether this connection is either in use on this node or can be resumed by peers interacting with this node.

A connection that is not active is currently being negotiated by means of the ongoingHandshake.

Returns:

true if this connection either already has an established session or contains a session ticket that it can be resumed from.

getSessionIdentity

public SessionId getSessionIdentity()

Gets the session identity this connection can be resumed from.

Returns:

The session identity or null if this connection has not been created from a session ticket.

getSessionTicket

public SessionTicket getSessionTicket()

Gets the session ticket this connection can be resumed from.

Returns:

The ticket or null if this connection has not been created from a session ticket.

expectCid

public boolean expectCid()

Check, if this connection expects connection ID for incoming records.

Returns:

true, if connection ID is expected, false, otherwise

getConnectionId

public ConnectionId getConnectionId()

Gets the connection id.

Returns:

the cid

setConnectionId

public void setConnectionId(ConnectionId cid)

Sets the connection id.

Parameters:

cid - the connection id

getLastPeerAddressNanos

public long getLastPeerAddressNanos()

Get real time nanoseconds of last updatePeerAddress(InetSocketAddress).

Returns:

real time nanoseconds

See Also:

ClockUtil.nanoRealtime()

getPeerAddress

public InetSocketAddress getPeerAddress()

Gets the address of this connection's peer.

Returns:

the address

updatePeerAddress

public void updatePeerAddress(InetSocketAddress peerAddress)

Update the address of this connection's peer. If the new address is null, an ongoing handshake is failed. A non-null address could only be applied, if the session is established. Note: to keep track of the associated address in the connection store, this method must not be called directly. It must be called by calling ResumptionSupportingConnectionStore.update(Connection, InetSocketAddress) or ResumptionSupportingConnectionStore.remove(Connection, boolean).

Parameters:

peerAddress - the address of the peer

Throws:

IllegalArgumentException - if the address should be updated with a non-null value without an established session.

equalsPeerAddress

public boolean equalsPeerAddress(InetSocketAddress peerAddress)

Check, if the provided address is the peers address.

Parameters:

peerAddress - provided peer address

Returns:

true, if the addresses are equal

getRouter

public InetSocketAddress getRouter()

Gets the address of this connection's router.

Returns:

the address of the router

Since:

2.5

setRouter

public void setRouter(InetSocketAddress router)

Sets the address of this connection's router.

Parameters:

router - the address of the router

Since:

2.5

getEstablishedSession

public DTLSSession getEstablishedSession()

Gets the already established DTLS session that exists with this connection's peer.

Returns:

the session or null if no session has been established (yet)

hasEstablishedSession

public boolean hasEstablishedSession()

Checks whether a session has already been established with the peer.

Returns:

true if a session has been established

getOngoingHandshake

public Handshaker getOngoingHandshake()

Gets the handshaker managing the currently ongoing handshake with the peer.

Returns:

the handshaker or null if no handshake is going on

hasOngoingHandshake

public boolean hasOngoingHandshake()

Checks whether there is a handshake going on with the peer.

Returns:

true if a handshake is going on

isStartedByClientHello

public boolean isStartedByClientHello(ClientHello clientHello)

Checks whether this connection is started for the provided CLIENT_HELLO. Use the random and message sequence number contained in the CLIENT_HELLO. Note: called outside of serial-execution and so requires external synchronization!

Parameters:

clientHello - the message to check.

Returns:

true if the given client hello has initially started this connection.

Throws:

NullPointerException - if client hello is null.

See Also:

startByClientHello(ClientHello)

startByClientHello

public void startByClientHello(ClientHello clientHello)

Set starting CLIENT_HELLO. Use the random and handshake message sequence number contained in the CLIENT_HELLO. Removed, if when the handshake fails or with configurable timeout after handshake completion. Note: called outside of serial-execution and so requires external synchronization!

Parameters:

clientHello - message which starts the connection.

See Also:

isStartedByClientHello(ClientHello)

getSession

public DTLSSession getSession(int readEpoch)

Gets the session containing the connection's current state for the provided epoch. This is the establishedSession, if not null and the read epoch is matching. Or the session negotiated in the ongoingHandshake, if not null and the read epoch is matching. If both are null, or the read epoch doesn't match, null is returned.

Parameters:

readEpoch - the read epoch to match.

Returns:

the current session or null, if neither an established session nor an ongoing handshake exists with an matching read epoch

getSession

public DTLSSession getSession()

Gets the session containing the connection's current state. This is the establishedSession if not null or the session negotiated in the ongoingHandshake.

Returns:

the current session or null if neither an established session nor an ongoing handshake exists

resetSession

public void resetSession()

Reset session. Prepare connection for new handshake. Reset established session or session ticket and remove resumption mark.

Throws:

IllegalStateException - if neither a established session nor a ticket is available

isClosed

public boolean isClosed()

Check, if connection was closed.

Returns:

true, if connection was closed, false, otherwise.

Since:

2.3

close

public void close(Record record)

Close connection with record. Mark session as closed. Received records with sequence numbers before will still be processed, others are dropped. No message will be send after this.

Parameters:

record - received close notify record.

Since:

2.3

getRootCauseAlert

public AlertMessage getRootCauseAlert()

Gets the root cause alert. For some case, the root cause may be hidden and replaced by a general cause when sending an alert message. This keeps the root cause for internal analysis.

Returns:

root cause alert.

Since:

2.5

setRootCause

public void setRootCause(AlertMessage rootCause)

Sets root cause alert. For some case, the root cause may be hidden and replaced by a general cause when sending an alert message. This keeps the root cause for internal analysis.

Parameters:

rootCause - root cause alert

Since:

2.5

isResumptionRequired

public boolean isResumptionRequired()

Check, if resumption is required.

Returns:

true, if an abbreviated handshake should be done next time a data will be sent on this connection.

isAutoResumptionRequired

public boolean isAutoResumptionRequired(Long autoResumptionTimeoutMillis)

Check, if the automatic session resumption should be triggered or is already required.

Parameters:

autoResumptionTimeoutMillis - auto resumption timeout in milliseconds. null, if auto resumption is not used.

Returns:

true, if the provided autoResumptionTimeoutMillis has expired without exchanging messages.

refreshAutoResumptionTime

public void refreshAutoResumptionTime()

Refresh auto resumption timeout. Uses ClockUtil.nanoRealtime().

See Also:

lastMessageNanos

setResumptionRequired

public void setResumptionRequired(boolean resumptionRequired)

Use to force an abbreviated handshake next time a data will be sent on this connection.

Parameters:

resumptionRequired - true to force abbreviated handshake.

toString

public String toString()

Overrides:

toString in class Object