tuwien.auto.calimero.mgmt
Interface TransportLayer

All Known Implementing Classes:

TransportLayerImpl

public interface TransportLayer

Transport layer providing OSI layer 4 (connection oriented) communication.

A transport layer (TL) communicates using a KNXNetworkLink. On creation of a new transport layer object, a network link is attached to the layer to be used for communication with the KNX network. This attached link is not owned by the TL and will never get closed by it. If the TL object is not needed anymore, this is indicated by detaching the link from the TL.

Method Summary

void	addTransportListener(TransportListener l) Adds the specified event listener l to receive events from this transport layer.
void	broadcast(boolean system, Priority p, byte[] tsdu) Broadcasts data in the KNX network.
void	connect(Destination d) Connects to the destination.
Destination	createDestination(IndividualAddress remote, boolean connectionOriented) Creates a new destination using the remote KNX address for doing transport layer communication.
Destination	createDestination(IndividualAddress remote, boolean connectionOriented, boolean keepAlive, boolean verifyMode) Creates a new destination using the remote KNX address and connection settings for doing transport layer communication.
void	destroyDestination(Destination d) Destroys the given destination and removes it from being maintained by this transport layer.
KNXNetworkLink	detach() Detaches the network link from this transport layer and terminates all layer 4 communication.
void	disconnect(Destination d) Disconnects from the destination.
java.lang.String	getName() Returns the name of this transport layer, a short textual representation to identify this layer.
void	removeTransportListener(TransportListener l) Removes the specified event listener l, so it does no longer receive events from this transport layer.
void	sendData(Destination d, Priority p, byte[] tsdu) Sends data to the given destination using connection oriented mode.
void	sendData(KNXAddress addr, Priority p, byte[] tsdu) Sends data to the given KNX address using connectionless mode.

Method Detail

addTransportListener

void addTransportListener(TransportListener l)

Adds the specified event listener l to receive events from this transport layer.

If l was already added as listener, no action is performed.

Parameters:

l - the listener to add

broadcast

void broadcast(boolean system,
               Priority p,
               byte[] tsdu)
               throws KNXTimeoutException,
                      KNXLinkClosedException

Broadcasts data in the KNX network.

The broadcast mode for KNX messages also depends on the used KNX medium, and might differ from the mode specified here.

Parameters:

system - true for system broadcast, false for default (domain) broadcast

p - KNX message priority

tsdu - transport layer service data unit to send

Throws:

KNXTimeoutException - on a timeout during send

KNXLinkClosedException - if sending on a closed KNX network link

connect

void connect(Destination d)
             throws KNXTimeoutException,
                    KNXLinkClosedException

Connects to the destination.

If the supplied destination is not configured in connection oriented mode or is not in disconnected state, no action is performed.
On return of this method, the destination is in connected state.

Parameters:

d - destination to connect

Throws:

KNXTimeoutException - on timeout during connect

KNXLinkClosedException - if sending on a closed KNX network link

createDestination

Destination createDestination(IndividualAddress remote,
                              boolean connectionOriented)

Creates a new destination using the remote KNX address for doing transport layer communication.

The destination is owned and maintained by this transport layer, it is also responsible for doing all layer 4 communication with that destination. The returned destination connection state for a new destination is disconnected.
If a destination with the remote address is already available, behavior is implementation dependent.

Parameters:

remote - destination KNX individual address

connectionOriented - true for connection oriented mode, false for connectionless mode

Returns:

destination representing the logical connection

See Also:

Destination

createDestination

Destination createDestination(IndividualAddress remote,
                              boolean connectionOriented,
                              boolean keepAlive,
                              boolean verifyMode)

Creates a new destination using the remote KNX address and connection settings for doing transport layer communication.

The destination is owned and maintained by this transport layer, it is also responsible for doing all layer 4 communication with that destination. The returned destination connection state for a new destination is disconnected.
If a destination with the remote address is already available, behavior is implementation dependent.

Parameters:

remote - destination KNX individual address

connectionOriented - true for connection oriented mode, false for connectionless mode

keepAlive - true to prevent a timing out of the logical connection in connection oriented mode, false to use default connection timeout

verifyMode - true to indicate the destination has verify mode enabled, false otherwise

Returns:

destination representing the logical connection

See Also:

Destination

destroyDestination

void destroyDestination(Destination d)

Destroys the given destination and removes it from being maintained by this transport layer.

All necessary steps (like disconnecting) are done according to the transport layer protocol before destroying the destination.
The transport layer does not own the destination any longer.
If the destination is not owned by this transport layer, no action is performed.

Parameters:

d - destination to destroy

detach

KNXNetworkLink detach()

Detaches the network link from this transport layer and terminates all layer 4 communication.

All owned destinations will get destroyed (equally to destroyDestination(Destination)), other transport layer resources are freed and all registered event listeners get notified with TransportListener.detached(tuwien.auto.calimero.DetachEvent).
If no network link is attached, no action is performed.

Note that a detach does not trigger a close of the used network link.

Returns:

the formerly attached KNX network link, or null if already detached

disconnect

void disconnect(Destination d)
                throws KNXLinkClosedException

Disconnects from the destination.

If the supplied destination is in connected state, it will be in disconnected state on return of this method.
If the destination is already in disconnected state or destroyed, no action is performed.

Parameters:

d - destination to disconnect from

Throws:

KNXLinkClosedException - if sending on a closed KNX network link

getName

java.lang.String getName()

Returns the name of this transport layer, a short textual representation to identify this layer.

The name should at least be unique for transport layers attached to different links.
The returned name is used by this layer as the name of its log service. Supply getName() for LogManager.getLogService(String) for example to get the associated log service.

By default, the name starts with "TL " + the name of the attached network link. After detach of the transport layer the name might get reset to some default name.

Returns:

transport layer name as string

removeTransportListener

void removeTransportListener(TransportListener l)

Removes the specified event listener l, so it does no longer receive events from this transport layer.

If l was not added in the first place, no action is performed.

Parameters:

l - the listener to remove

sendData

void sendData(Destination d,
              Priority p,
              byte[] tsdu)
              throws KNXDisconnectException,
                     KNXLinkClosedException

Sends data to the given destination using connection oriented mode.

A destination has to be set in connected state before sending. All necessary timeouts are observed and send repetition are done according to the transport layer protocol. The method blocks for the corresponding layer 4 acknowledge before returning. If no acknowledge is received, the destination is disconnected.

Parameters:

d - send destination in the KNX network

p - KNX message priority

tsdu - transport layer service data unit to send

Throws:

KNXDisconnectException - if destination state is disconnected or a disconnect occurs during send

KNXLinkClosedException - if sending on a closed KNX network link

sendData

void sendData(KNXAddress addr,
              Priority p,
              byte[] tsdu)
              throws KNXTimeoutException,
                     KNXLinkClosedException

Sends data to the given KNX address using connectionless mode.

Depending on the supplied type of KNX address, sending on the KNX network is unicast or multicast.

Parameters:

addr - send destination in the KNX network, address of type IndividualAddress for unicast, GroupAddress for multicast

p - KNX message priority

tsdu - transport layer service data unit to send

Throws:

KNXTimeoutException - on a timeout during send

KNXLinkClosedException - if sending on a closed KNX network link