Package com.beanit.dnp3bean

Class Master.TcpBuilder

java.lang.Object

com.beanit.dnp3bean.Master.TcpBuilder

Enclosing class:

Master

public static final class Master.TcpBuilder
extends java.lang.Object

A builder to create TCP based master associations.

Master associations built using the same builder share resources (e.g. thread pools) and can listen identical ports for TCP connections.

Method Summary

Modifier and Type	Method	Description
Master	build()	Create a master association.
Master.TcpBuilder	endPointType(TcpEndPointType type)	Sets the master's end point type.
Master.TcpBuilder	eventListener(Master.EventListener eventListener)	Sets the lister that is notified of incoming DNP3 event data.
Master.TcpBuilder	linkStatusRequestTimeout(java.time.Duration duration)	Sets the maximum idle duration after which a link status message is requested.
Master.TcpBuilder	linkStatusResponseTimeout(java.time.Duration duration)	Sets the time to wait for a link status after having sent a link status request.
Master.TcpBuilder	listeningPort(int port)	Sets the port to listen for an incoming connection by the outstation.
Master.TcpBuilder	localAddress(java.net.InetAddress localAddress)	Sets the local IP address.
Master.TcpBuilder	masterDlAddress(int address)	Sets the master data link address.
Master.TcpBuilder	maxReceiveMessageFragmentSize(int size)	Sets the maximum message fragment size that can be received.
Master.TcpBuilder	maxSendMessageFragmentSize(int size)	Sets the maximum message fragment size for sending.
Master.TcpBuilder	outstationDlAddress(int address)	Sets the outstation data link address.
Master.TcpBuilder	outstationHost(java.lang.String host)	Sets the host name or IP address of the outstation.
Master.TcpBuilder	outstationPort(int port)	Sets the port of the outstation to connect to.
Master.TcpBuilder	reconnectInterval(java.time.Duration duration)	Sets the reconnect interval.
Master.TcpBuilder	reset()	Resets all parameters of this builder to their default value.
Master.TcpBuilder	responseFragmentTimeout(java.time.Duration duration)	Sets the response fragment timeout.
Master.TcpBuilder	tcpConnectionListener(TcpConnectionListener listener)	Sets the lister that is notified of TCP connection events.

Methods inherited from class java.lang.Object

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

Method Detail

reset

public Master.TcpBuilder reset()

Resets all parameters of this builder to their default value. This method may be useful if the builder shall be reused to create new associations from scratch but keep the ability to share resources between created associations.

Returns:

this builder

outstationHost

public Master.TcpBuilder outstationHost(java.lang.String host)

Sets the host name or IP address of the outstation. The default is "localhost".

Parameters:

host - the host name or IP address of the outstation

Returns:

this builder

outstationPort

public Master.TcpBuilder outstationPort(int port)

Sets the port of the outstation to connect to. This port is only used when the master is in initiating or dual end point mode. Allowed range: 1-65535. The default port is 20_000 (DNP3's standard port).

Parameters:

port - the port to connect to

Returns:

this builder

listeningPort

public Master.TcpBuilder listeningPort(int port)

Sets the port to listen for an incoming connection by the outstation. This port is only used when the master is in listening or dual end point mode. Allowed range: 1-65535. The default port is 20_001.

Parameters:

port - the port to listen for an incoming connection by the outstation

Returns:

this builder

localAddress

public Master.TcpBuilder localAddress(java.net.InetAddress localAddress)

Sets the local IP address. The local IP is used 1) as the local bind address when initiating TCP connections and 2) as the interface to listen for connections when in listening or dual-endpoint mode. Default is the wildcard/anylocal InetAddress. Specifying null is equivalent to passing the wildcard address. The wildcard address will cause 1) the system to choose the a valid IP for initiating connections and 2) to listen on all available interfaces when listening for connections.

Parameters:

localAddress - the local IP address, or null for the wildcard address

Returns:

this builder

endPointType

public Master.TcpBuilder endPointType(TcpEndPointType type)

Sets the master's end point type. The default is INITIATING.

Parameters:

type - the end point type

Returns:

this builder

reconnectInterval

public Master.TcpBuilder reconnectInterval(java.time.Duration duration)

Sets the reconnect interval. The interval specifies the time to wait after a failed connection attempt or a closed connection util a new connection attempt shall be started. This interval is only relevant for initiating and dual end points.

A duration equal to Duration.ZERO disables reconnection. The default is 5 seconds.

Parameters:

duration - the reconnect interval

Returns:

this builder

tcpConnectionListener

public Master.TcpBuilder tcpConnectionListener(TcpConnectionListener listener)

Sets the lister that is notified of TCP connection events. Passing null disables notification.

Parameters:

listener - the listener that is notified of TCP connection events

Returns:

this builder

masterDlAddress

public Master.TcpBuilder masterDlAddress(int address)

Sets the master data link address. The default is 0. The allowed address range is 0-65519.

Parameters:

address - the master data link address

Returns:

this builder

outstationDlAddress

public Master.TcpBuilder outstationDlAddress(int address)

Sets the outstation data link address. The default is 1. The allowed address range is 0-65519.

Parameters:

address - the outstation data link address

Returns:

this builder

linkStatusRequestTimeout

public Master.TcpBuilder linkStatusRequestTimeout(java.time.Duration duration)

Sets the maximum idle duration after which a link status message is requested.

Link status messages are also called keep-alive or heartbeat messages. DNP3's link layer will send link status requests after the connection was idle (no messages have been exchanged) for the given duration. Any data link message received will reset the timer for sending link status requests.

Set to Duration.ZERO to disable link status requests. Default is 60s.

Parameters:

duration - idle duration after which a link status message is requested

Returns:

this builder

linkStatusResponseTimeout

public Master.TcpBuilder linkStatusResponseTimeout(java.time.Duration duration)

Sets the time to wait for a link status after having sent a link status request.

A duration equal to Duration.ZERO disables waiting for link status response messages. In this case is does not matter if a link status reply is received. The default timeout is 10s.

If no link status message is received on time, the TCP connection is closed before attempting to reconnect again (through initiation and/or listening).

Parameters:

duration - the time to wait for a link status response

Returns:

this builder

maxSendMessageFragmentSize

public Master.TcpBuilder maxSendMessageFragmentSize(int size)

Sets the maximum message fragment size for sending. Messages that exceed this size are fragmented. Allowed range: 249-65535. The default is 2048. This setting does not limit the size of received message fragments.

Parameters:

size - the maximum message fragment size for sending

Returns:

this builder

maxReceiveMessageFragmentSize

public Master.TcpBuilder maxReceiveMessageFragmentSize(int size)

Sets the maximum message fragment size that can be received. Messages that exceed this size are discarded. Allowed range: 249-65535. The default is 4096.

Parameters:

size - the maximum message fragment size that can be received

Returns:

this builder

responseFragmentTimeout

public Master.TcpBuilder responseFragmentTimeout(java.time.Duration duration)

Sets the response fragment timeout. The timeout is reset after each fragment received. If no fragment is received in time a Dnp3TimeoutException is thrown by the request method.

A duration equal to Duration.ZERO disables the timeout. The default is 5 seconds.

Parameters:

duration - the response fragment timeout

Returns:

this builder

eventListener

public Master.TcpBuilder eventListener(Master.EventListener eventListener)

Sets the lister that is notified of incoming DNP3 event data. Passing null disables notification.

Parameters:

eventListener - the listener

Returns:

this builder

build

public Master build()
             throws ListeningEndPointException

Create a master association.

Returns:

the new association

Throws:

ListeningEndPointException - If the listening end point cannot be started, e.g. because the port is occupied. Cannot be thrown if no listening end point was configured.