Module org.snmp4j

Package org.snmp4j.fluent

Class SnmpBuilder

java.lang.Object

org.snmp4j.fluent.SnmpBuilder

public class SnmpBuilder
extends Object

Builds a Snmp instance through step-by-step configuration using a fluent interface design pattern. This SnmpBuilder is the starting context. It creates the non-fluent Snmp instance that is needed to as first parameter for SnmpCompletableFuture.send(Snmp, Target, PDU, Object...) which actually sends the SNMP message to a Target. Use TargetBuilder and PduBuilder to create the other two mandatory parameters. To get a TargetBuilder call target(Address). The PduBuilder can be then retrieved from that TargetBuilder by calling TargetBuilder.pdu(). For a complete code sample see https://snmp4j.org.

  //Brief flow description of using the new SNMP4J fluent interface:
  SnmpBuilder.udp()...build() => Snmp
  SnmpBuilder.target(..) => TargetBuilder
      TargetBuilder.user(..)...done()...build() => Target
      TargetBuilder.pdu()...build() => PDUrequest
  SnmpCompletableFuture.send(Snmp, Target, PDUrequest) => SnmpCompletableFuture
  SnmpCompletableFuture.get() => PDUresponse
 

Since:

3.5.0

Version:

3.9.0

Author:

Frank Fock

Field Summary

Fields

Modifier and Type	Field	Description
protected CounterSupport	counterSupport
protected EngineBootsProvider	engineBootsProvider
protected EngineIdProvider	engineIdProvider
protected byte[]	localEngineID
protected ThreadPool	multiThreadedDispatcherPool
protected String	responderPoolName
protected final SecurityModels	securityModels
protected final SecurityProtocols	securityProtocols
protected final Snmp	snmp

Constructor Summary

Constructors

Modifier	Constructor	Description
	SnmpBuilder()	Creates an SnmpBuilder with a default constructed Snmp instance.
protected	SnmpBuilder(Snmp snmp)	Creates an SnmpBuilder with an preconfigured Snmp instance, which must provide a non null Snmp.getMessageDispatcher().

Method Summary

Modifier and Type	Method	Description
SnmpBuilder	addSecurityProtocol(SecurityProtocol securityProtocol)	Make an additional SecurityProtocol available for the Snmp session to be built.
Snmp	build()	Build the Snmp instance with all the previously called configurations from this fluent builder.
SnmpBuilder	counterSupport(CounterSupport counterSupport)	Sets the CounterSupport with Snmp.setCounterSupport(CounterSupport) when building the Snmp instance using build().
SnmpBuilder	dtls()	Add a DTLSTM client mode DTLS transport mapping to the Snmp instance to be built.
SnmpBuilder	dtls(TlsTmSecurityCallback<X509Certificate> securityCallback, String[] dtlsProtocolVersions, DtlsAddress... listenAddresses)	Add the DTLSTM server mode DTLS transport mappings for the specified listen addresses to the Snmp instance to be built.
SnmpBuilder	dtls(TlsTmSecurityCallback<X509Certificate> securityCallback, DtlsAddress... listenAddresses)	Add the DTLSTM server mode DTLS transport mappings for the specified listen addresses to the Snmp instance to be built.
SnmpBuilder	securityProtocols(SecurityProtocols.SecurityProtocolSet securityProtocolSet)	Specifies which predefined set of SecurityProtocols should be available for the Snmp session to be built.
<A extends Address> TargetBuilder<A>	target(A address)	Creates a TargetBuilder for the specified target Address.
SnmpBuilder	tcp()	Add a DefaultTcpTransportMapping in client mode with an arbitrary local address amd port.
SnmpBuilder	tcp(TcpAddress... listenAddresses)	Add the DefaultTcpTransportMapping server mode TCP transport mappings for the specified listen addresses to the Snmp instance to be built.
SnmpBuilder	threads(int numThreads)	Configures the MultiThreadedMessageDispatcher as message dispatcher and thereby defines the number of threads in its ThreadPool.
SnmpBuilder	tls()	Add a TLSTM client mode TLS transport mapping to the Snmp instance to be built.
SnmpBuilder	tls(TlsTmSecurityCallback<X509Certificate> securityCallback, String[] tlsProtocolVersions, TlsAddress... listenAddresses)	Add the TLSTM server mode TLS transport mappings for the specified listen addresses to the Snmp instance to be built.
SnmpBuilder	tls(TlsTmSecurityCallback<X509Certificate> securityCallback, TlsAddress... listenAddresses)	Add the TLSTM server mode TLS transport mappings for the specified listen addresses to the Snmp instance to be built.
SnmpBuilder	tm(TransportMapping<?>... transportMappings)	Configures the SNMP builder with the specified transport mappings.
SnmpBuilder	tsm(EngineIdProvider engineIdProvider, OctetString defaultLocalEngineID, boolean usePrefix)	Creates a Transport Security Model as defined by RFC 5591 and adds it to the built Snmp instance.
SnmpBuilder	tsm(OctetString localEngineID, boolean usePrefix)	Creates a Transport Security Model as defined by RFC 5591 and adds it to the built Snmp instance.
SnmpBuilder	udp()	Adds a UDP transport mapping (DefaultUdpTransportMapping) with an operating system chosen local port on all local IP addresses.
SnmpBuilder	udp(UdpAddress... listenAddresses)	Adds a set of UDP transport mappings (DefaultUdpTransportMapping) with the specified local listen addresses
SnmpBuilder	usm()	Creates a USM for the specified engine ID and engine boots counter derived from the SNMP engine ID provider given by v3(EngineIdProvider, OctetString).
SnmpBuilder	usm(SnmpEngineIdProvider snmpEngineIdProvider, OctetString defaultLocalEngineID)	Creates a USM using the specified SnmpEngineIdProvider.
SnmpBuilder	usm(OctetString localEngineID, int engineBoots)	Creates a USM for the specified engine ID and engine boots counter.
SnmpBuilder	v1()	Adds the MPv1 security model to Snmp.getMessageDispatcher().
SnmpBuilder	v2c()	Adds a MPv2c security model to Snmp.getMessageDispatcher().
SnmpBuilder	v3()	Adds a MPv3 with a randomly created local engine ID Snmp.getMessageDispatcher() if usm(SnmpEngineIdProvider, OctetString) or tsm(EngineIdProvider, OctetString, boolean) have not been called yet to set an EngineIdProvider.
SnmpBuilder	v3(byte[] localEngineID)	Sets the local engine ID for this SnmpBuilder and creates the message processing model 3 (MPv3) by assigning the SecurityModels and SecurityProtocols configured by calls to usm(SnmpEngineIdProvider, OctetString) and tsm(EngineIdProvider, OctetString, boolean) for example as well as securityProtocols(SecurityProtocols.SecurityProtocolSet).
SnmpBuilder	v3(EngineIdProvider engineIdProvider, OctetString id)	Adds a MPv3 message processing model with a random engine ID based on the supplied ID string.
SnmpBuilder	v3(OctetString id)	Adds a MPv3 message processing model with a random engine ID based on the supplied ID string.

Methods inherited from class java.lang.Object

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

Field Details

snmp

protected final Snmp snmp

securityProtocols

protected final SecurityProtocols securityProtocols

securityModels

protected final SecurityModels securityModels

counterSupport

protected CounterSupport counterSupport

multiThreadedDispatcherPool

protected ThreadPool multiThreadedDispatcherPool

responderPoolName

protected String responderPoolName

engineIdProvider

protected EngineIdProvider engineIdProvider

engineBootsProvider

protected EngineBootsProvider engineBootsProvider

localEngineID

protected byte[] localEngineID

Constructor Details

SnmpBuilder

public SnmpBuilder()

Creates an SnmpBuilder with a default constructed Snmp instance.

SnmpBuilder

protected SnmpBuilder(Snmp snmp)

Creates an SnmpBuilder with an preconfigured Snmp instance, which must provide a non null Snmp.getMessageDispatcher(). CounterSupport is set to CounterSupport.getInstance(), SecurityProtocols are initialized with SecurityProtocols.SecurityProtocolSet.defaultSecurity, and SecurityModels is initialized with its default construct (i.e. no security models).

Parameters:

snmp - a non-null Snmp instance.

Method Details

target

public <A extends Address> TargetBuilder<A> target(A address)

Creates a TargetBuilder for the specified target Address.

Type Parameters:

A - the transport address type.

Parameters:

address - a TransportIpAddress.

Returns:

a TargetBuilder instance.

counterSupport

public SnmpBuilder counterSupport(CounterSupport counterSupport)

Sets the CounterSupport with Snmp.setCounterSupport(CounterSupport) when building the Snmp instance using build().

Parameters:

counterSupport - the CounterSupport, defaults to CounterSupport.getInstance().

Returns:

this builder.

v1

public SnmpBuilder v1()

Adds the MPv1 security model to Snmp.getMessageDispatcher().

Returns:

this builder.

v2c

public SnmpBuilder v2c()

Adds a MPv2c security model to Snmp.getMessageDispatcher().

Returns:

this builder.

v3

public SnmpBuilder v3()

Adds a MPv3 with a randomly created local engine ID Snmp.getMessageDispatcher() if usm(SnmpEngineIdProvider, OctetString) or tsm(EngineIdProvider, OctetString, boolean) have not been called yet to set an EngineIdProvider.

CAUTION: Randomly generated engine IDs work fairly well for command generator applications, but SHOULD NOT be used for command responder (i.e. agents). Instead use preferably v3(OctetString) or v3(byte[]).

Make sure to set the SNMP4JSettings.setEnterpriseID(int) to the company's registered IANA ID before calling this method.

Returns:

this builder.

v3

public SnmpBuilder v3(OctetString id)

Adds a MPv3 message processing model with a random engine ID based on the supplied ID string. Make sure to set the SNMP4JSettings.setEnterpriseID(int) to the company's registered IANA ID before calling this method.

Parameters:

id - an ID string (see RFC 3414) suitable to build an unique local engine ID.

Returns:

this builder

v3

public SnmpBuilder v3(EngineIdProvider engineIdProvider,
 OctetString id)

Adds a MPv3 message processing model with a random engine ID based on the supplied ID string. Make sure to set the SNMP4JSettings.setEnterpriseID(int) to the company's registered IANA ID before calling this method.

Parameters:

engineIdProvider - a class that provides the persistently stored engine ID from the previous application execution and that provides and saves the current boot counter as well as a first time initialized engine ID.

id - an ID string suitable to build a local engine ID.

Returns:

this builder

v3

public SnmpBuilder v3(byte[] localEngineID)

Sets the local engine ID for this SnmpBuilder and creates the message processing model 3 (MPv3) by assigning the SecurityModels and SecurityProtocols configured by calls to usm(SnmpEngineIdProvider, OctetString) and tsm(EngineIdProvider, OctetString, boolean) for example as well as securityProtocols(SecurityProtocols.SecurityProtocolSet).

Parameters:

localEngineID - the local engine ID of the SNMP entity represented by the Snmp instance to be built.

Returns:

this builder.

threads

public SnmpBuilder threads(int numThreads)

Configures the MultiThreadedMessageDispatcher as message dispatcher and thereby defines the number of threads in its ThreadPool.

Parameters:

numThreads - the number of threads in the MultiThreadedMessageDispatcher's ThreadPool which must be greater than 1.

Returns:

this builder.

usm

public SnmpBuilder usm()

Creates a USM for the specified engine ID and engine boots counter derived from the SNMP engine ID provider given by v3(EngineIdProvider, OctetString). This method requires that either v3(byte[]) or v3(EngineIdProvider, OctetString) have been already called before, otherwise a NullPointerException will be thrown.

Returns:

this builder.

usm

public SnmpBuilder usm(OctetString localEngineID,
 int engineBoots)

Creates a USM for the specified engine ID and engine boots counter.

Parameters:

localEngineID - the local engine ID.

engineBoots - the number of engine boots.

Returns:

this builder.

usm

public SnmpBuilder usm(SnmpEngineIdProvider snmpEngineIdProvider,
 OctetString defaultLocalEngineID)

Creates a USM using the specified SnmpEngineIdProvider.

Parameters:

snmpEngineIdProvider - the engine ID and boots counter provider, that stores and restores both values according to RFC 3414, i.e. by increasing engine boots on each application initialization.

defaultLocalEngineID - the local engine ID if the given SnmpEngineIdProvider has not stored one yet.

Returns:

this builder.

tsm

public SnmpBuilder tsm(OctetString localEngineID,
 boolean usePrefix)

Creates a Transport Security Model as defined by RFC 5591 and adds it to the built Snmp instance.

Parameters:

localEngineID - the engine ID of the SNMP entity using this transport security model. The local engine ID must be globally unique.

usePrefix - the snmpTsmConfigurationUsePrefix flag as defined in RFC 5591.

Returns:

this builder.

tsm

public SnmpBuilder tsm(EngineIdProvider engineIdProvider,
 OctetString defaultLocalEngineID,
 boolean usePrefix)

Creates a Transport Security Model as defined by RFC 5591 and adds it to the built Snmp instance.

Parameters:

engineIdProvider - the engine ID of the SNMP entity using this transport security model. The local engine ID must be globally unique and the EngineIdProvider is responsible to save the engine ID persistently.

defaultLocalEngineID - the engine ID to be used and stored persistently if the provided engineIdProvider cannot provide an engine ID.

usePrefix - the snmpTsmConfigurationUsePrefix flag as defined in RFC 5591.

Returns:

this builder.

udp

public SnmpBuilder udp()
                throws IOException

Adds a UDP transport mapping (DefaultUdpTransportMapping) with an operating system chosen local port on all local IP addresses.

Returns:

this builder.

Throws:

IOException - if the socket could not be bound.

udp

public SnmpBuilder udp(UdpAddress... listenAddresses)
                throws IOException

Adds a set of UDP transport mappings (DefaultUdpTransportMapping) with the specified local listen addresses

Parameters:

listenAddresses - the local IPs and ports to listen for incoming UDP messages.

Returns:

this builder.

Throws:

IOException - if one of the sockets could not be bound.

tcp

public SnmpBuilder tcp()
                throws IOException

Add a DefaultTcpTransportMapping in client mode with an arbitrary local address amd port.

Returns:

this builder.

Throws:

IOException - if the local port cannot be bound.

tcp

public SnmpBuilder tcp(TcpAddress... listenAddresses)
                throws IOException

Add the DefaultTcpTransportMapping server mode TCP transport mappings for the specified listen addresses to the Snmp instance to be built.

Parameters:

listenAddresses - the local IPs and ports to listen for incoming TCP messages.

Returns:

this builder.

Throws:

IOException - if the DefaultTcpTransportMapping cannot bind all local ports.

dtls

public SnmpBuilder dtls()
                 throws IOException

Add a DTLSTM client mode DTLS transport mapping to the Snmp instance to be built.

Returns:

this builder.

Throws:

IOException - if the DTLSTM cannot bind the local port.

dtls

public SnmpBuilder dtls(TlsTmSecurityCallback<X509Certificate> securityCallback,
 DtlsAddress... listenAddresses)
                 throws IOException

Add the DTLSTM server mode DTLS transport mappings for the specified listen addresses to the Snmp instance to be built. The DTLS protocol versions to be supported are defined by DTLSTM.DEFAULT_DTLSTM_PROTOCOLS.

Parameters:

securityCallback - the callback function to validate X509 certificates of communication peers, see TlsTmSecurityCallback.

listenAddresses - the local IPs and ports to listen for incoming DTLS messages.

Returns:

this builder.

Throws:

IOException - if the DTLSTM cannot bind all local ports.

dtls

public SnmpBuilder dtls(TlsTmSecurityCallback<X509Certificate> securityCallback,
 String[] dtlsProtocolVersions,
 DtlsAddress... listenAddresses)
                 throws IOException

Add the DTLSTM server mode DTLS transport mappings for the specified listen addresses to the Snmp instance to be built.

Parameters:

securityCallback - the callback function to validate X509 certificates of communication peers, see TlsTmSecurityCallback.

dtlsProtocolVersions - the DTLS protocol versions to be supported, default is DTLSTM.DEFAULT_DTLSTM_PROTOCOLS. That is used when null is provided.

listenAddresses - the local IPs and ports to listen for incoming DTLS messages.

Returns:

this builder.

Throws:

IOException - if the DTLSTM cannot bind all local ports.

tls

public SnmpBuilder tls()
                throws IOException

Add a TLSTM client mode TLS transport mapping to the Snmp instance to be built.

Returns:

this builder.

Throws:

IOException - if the TLSTM cannot bind the local port.

tls

public SnmpBuilder tls(TlsTmSecurityCallback<X509Certificate> securityCallback,
 TlsAddress... listenAddresses)
                throws IOException

Add the TLSTM server mode TLS transport mappings for the specified listen addresses to the Snmp instance to be built. The TLS protocol versions to be supported are defined by TLSTM.DEFAULT_TLSTM_PROTOCOLS.

Parameters:

securityCallback - the callback function to validate X509 certificates of communication peers, see TlsTmSecurityCallback.

listenAddresses - the local IPs and ports to listen for incoming TLS messages.

Returns:

this builder.

Throws:

IOException - if the TLSTM cannot bind all local ports.

tls

public SnmpBuilder tls(TlsTmSecurityCallback<X509Certificate> securityCallback,
 String[] tlsProtocolVersions,
 TlsAddress... listenAddresses)
                throws IOException

Add the TLSTM server mode TLS transport mappings for the specified listen addresses to the Snmp instance to be built.

Parameters:

securityCallback - the callback function to validate X509 certificates of communication peers, see TlsTmSecurityCallback.

tlsProtocolVersions - the TLS protocol versions to be supported, default is TLSTM.DEFAULT_TLSTM_PROTOCOLS. That is used when null is provided.

listenAddresses - the local IPs and ports to listen for incoming TLS messages.

Returns:

this builder.

Throws:

IOException - if the TLSTM cannot bind all local ports.

tm

public SnmpBuilder tm(TransportMapping<?>... transportMappings)

Configures the SNMP builder with the specified transport mappings. This method adds the transport mappings to the message dispatcher and sets the dispatcher as a listener for the provided mappings.

Parameters:

transportMappings - one or more TransportMapping objects to be added to the SNMP message dispatcher.

Returns:

the current instance of SnmpBuilder for method chaining.

Since:

3.9.3

securityProtocols

public SnmpBuilder securityProtocols(SecurityProtocols.SecurityProtocolSet securityProtocolSet)

Specifies which predefined set of SecurityProtocols should be available for the Snmp session to be built. Already added or set security protocols will be removed before the specified set is added.

Parameters:

securityProtocolSet - a predefined set of SecurityProtocol, default is SecurityProtocols.SecurityProtocolSet.defaultSecurity

Returns:

this builder.

addSecurityProtocol

public SnmpBuilder addSecurityProtocol(SecurityProtocol securityProtocol)

Make an additional SecurityProtocol available for the Snmp session to be built.

Parameters:

securityProtocol - a AuthenticationProtocol or PrivacyProtocol to add. Please note that privacy protocols require certain authentication protocol key length and you cannot use privacy without authentication protocol.

Returns:

this builder

Since:

3.9.0

build

public Snmp build()
           throws IOException

Build the Snmp instance with all the previously called configurations from this fluent builder.

Returns:

a new Snmp instance, that now starts to Snmp.listen() for incoming requests/responses.

Throws:

IOException - if the Snmp instance fails to listen.