java.lang.Object
org.snmp4j.fluent.SnmpBuilder
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
- Author:
- Frank Fock
-
Field Summary
Modifier and TypeFieldDescriptionprotected CounterSupport
protected EngineBootsProvider
protected EngineIdProvider
protected byte[]
protected ThreadPool
protected String
protected final SecurityModels
protected final SecurityProtocols
protected final Snmp
-
Constructor Summary
ModifierConstructorDescriptionCreates anSnmpBuilder
with a default constructedSnmp
instance.protected
SnmpBuilder
(Snmp snmp) Creates anSnmpBuilder
with an preconfiguredSnmp
instance, which must provide a nonnull
Snmp.getMessageDispatcher()
. -
Method Summary
Modifier and TypeMethodDescriptionbuild()
Build theSnmp
instance with all the previously called configurations from this fluent builder.counterSupport
(CounterSupport counterSupport) Sets theCounterSupport
withSnmp.setCounterSupport(CounterSupport)
when building theSnmp
instance usingbuild()
.dtls()
dtls
(TlsTmSecurityCallback<X509Certificate> securityCallback, String[] dtlsProtocolVersions, DtlsAddress... listenAddresses) dtls
(TlsTmSecurityCallback<X509Certificate> securityCallback, DtlsAddress... listenAddresses) securityProtocols
(SecurityProtocols.SecurityProtocolSet securityProtocolSet) Specifies which predefined set ofSecurityProtocols
should be available forSnmp
session to be built.<A extends Address>
TargetBuilder<A> target
(A address) Creates aTargetBuilder
for the specified targetAddress
.tcp()
Add aDefaultTcpTransportMapping
in client mode with an arbitrary local address amd port.tcp
(TcpAddress... listenAddresses) Add theDefaultTcpTransportMapping
server mode TCP transport mappings for the specified listen addresses to theSnmp
instance to be built.threads
(int numThreads) Configures theMultiThreadedMessageDispatcher
as message dispatcher and thereby defines the number of threads in itsThreadPool
.tls()
tls
(TlsTmSecurityCallback<X509Certificate> securityCallback, String[] tlsProtocolVersions, TlsAddress... listenAddresses) tls
(TlsTmSecurityCallback<X509Certificate> securityCallback, TlsAddress... listenAddresses) tsm
(EngineIdProvider engineIdProvider, OctetString defaultLocalEngineID, boolean usePrefix) Creates a Transport Security Model as defined by RFC 5591 and adds it to the builtSnmp
instance.tsm
(OctetString localEngineID, boolean usePrefix) Creates a Transport Security Model as defined by RFC 5591 and adds it to the builtSnmp
instance.udp()
Adds a UDP transport mapping (DefaultUdpTransportMapping
) with an operating system chosen local port on all local IP addresses.udp
(UdpAddress... listenAddresses) Adds a set of UDP transport mappings (DefaultUdpTransportMapping
) with the specified local listen addressesusm()
Creates a USM for the specified engine ID and engine boots counter derived from the SNMP engine ID provider given byv3(EngineIdProvider, OctetString)
.usm
(SnmpEngineIdProvider snmpEngineIdProvider, OctetString defaultLocalEngineID) Creates a USM using the specifiedSnmpEngineIdProvider
.usm
(OctetString localEngineID, int engineBoots) Creates a USM for the specified engine ID and engine boots counter.v1()
Adds theMPv1
security model toSnmp.getMessageDispatcher()
.v2c()
Adds aMPv2c
security model toSnmp.getMessageDispatcher()
.v3()
Adds aMPv3
with a randomly created local engine IDSnmp.getMessageDispatcher()
ifusm(SnmpEngineIdProvider, OctetString)
ortsm(EngineIdProvider, OctetString, boolean)
have not been called yet to set anEngineIdProvider
.v3
(byte[] localEngineID) Sets the local engine ID for thisSnmpBuilder
and creates the message processing model 3 (MPv3
) by assigning theSecurityModels
andSecurityProtocols
configured by calls tousm(SnmpEngineIdProvider, OctetString)
andtsm(EngineIdProvider, OctetString, boolean)
for example as well assecurityProtocols(SecurityProtocols.SecurityProtocolSet)
.v3
(EngineIdProvider engineIdProvider, OctetString id) Adds aMPv3
message processing model with a random engine ID based on the supplied ID string.v3
(OctetString id) Adds aMPv3
message processing model with a random engine ID based on the supplied ID string.
-
Field Details
-
snmp
-
securityProtocols
-
securityModels
-
counterSupport
-
multiThreadedDispatcherPool
-
responderPoolName
-
engineIdProvider
-
engineBootsProvider
-
localEngineID
protected byte[] localEngineID
-
-
Constructor Details
-
SnmpBuilder
public SnmpBuilder()Creates anSnmpBuilder
with a default constructedSnmp
instance. -
SnmpBuilder
Creates anSnmpBuilder
with an preconfiguredSnmp
instance, which must provide a nonnull
Snmp.getMessageDispatcher()
.CounterSupport
is set toCounterSupport.getInstance()
,SecurityProtocols
are initialized withSecurityProtocols.SecurityProtocolSet.defaultSecurity
, andSecurityModels
is initialized with its default construct (i.e. no security models).- Parameters:
snmp
- a non-nullSnmp
instance.
-
-
Method Details
-
target
Creates aTargetBuilder
for the specified targetAddress
.- Type Parameters:
A
- the transport address type.- Parameters:
address
- aTransportIpAddress
.- Returns:
- a
TargetBuilder
instance.
-
counterSupport
Sets theCounterSupport
withSnmp.setCounterSupport(CounterSupport)
when building theSnmp
instance usingbuild()
.- Parameters:
counterSupport
- theCounterSupport
, defaults toCounterSupport.getInstance()
.- Returns:
- this builder.
-
v1
Adds theMPv1
security model toSnmp.getMessageDispatcher()
.- Returns:
- this builder.
-
v2c
Adds aMPv2c
security model toSnmp.getMessageDispatcher()
.- Returns:
- this builder.
-
v3
Adds aMPv3
with a randomly created local engine IDSnmp.getMessageDispatcher()
ifusm(SnmpEngineIdProvider, OctetString)
ortsm(EngineIdProvider, OctetString, boolean)
have not been called yet to set anEngineIdProvider
.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)
orv3(byte[])
.Make sure to set the
SNMP4JSettings.setEnterpriseID(int)
to the company's registered IANA ID before calling this method.- Returns:
- this builder.
-
v3
Adds aMPv3
message processing model with a random engine ID based on the supplied ID string. Make sure to set theSNMP4JSettings.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
Adds aMPv3
message processing model with a random engine ID based on the supplied ID string. Make sure to set theSNMP4JSettings.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
Sets the local engine ID for thisSnmpBuilder
and creates the message processing model 3 (MPv3
) by assigning theSecurityModels
andSecurityProtocols
configured by calls tousm(SnmpEngineIdProvider, OctetString)
andtsm(EngineIdProvider, OctetString, boolean)
for example as well assecurityProtocols(SecurityProtocols.SecurityProtocolSet)
.- Parameters:
localEngineID
- the local engine ID of the SNMP entity represented by theSnmp
instance to be built.- Returns:
- this builder.
-
threads
Configures theMultiThreadedMessageDispatcher
as message dispatcher and thereby defines the number of threads in itsThreadPool
.- Parameters:
numThreads
- the number of threads in theMultiThreadedMessageDispatcher
'sThreadPool
which must be greater than 1.- Returns:
- this builder.
-
usm
Creates a USM for the specified engine ID and engine boots counter derived from the SNMP engine ID provider given byv3(EngineIdProvider, OctetString)
. This method requires that eitherv3(byte[])
orv3(EngineIdProvider, OctetString)
have been already called before, otherwise aNullPointerException
will be thrown.- Returns:
- this builder.
-
usm
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
Creates a USM using the specifiedSnmpEngineIdProvider
.- 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 givenSnmpEngineIdProvider
has not stored one yet.- Returns:
- this builder.
-
tsm
Creates a Transport Security Model as defined by RFC 5591 and adds it to the builtSnmp
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 builtSnmp
instance.- Parameters:
engineIdProvider
- the engine ID of the SNMP entity using this transport security model. The local engine ID must be globally unique and theEngineIdProvider
is responsible to save the engine ID persistently.defaultLocalEngineID
- the engine ID to be used and stored persistently if the providedengineIdProvider
cannot provide an engine ID.usePrefix
- the snmpTsmConfigurationUsePrefix flag as defined in RFC 5591.- Returns:
- this builder.
-
udp
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
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
Add aDefaultTcpTransportMapping
in client mode with an arbitrary local address amd port.- Returns:
- this builder.
- Throws:
IOException
- if the local port cannot be bound.
-
tcp
Add theDefaultTcpTransportMapping
server mode TCP transport mappings for the specified listen addresses to theSnmp
instance to be built.- Parameters:
listenAddresses
- the local IPs and ports to listen for incoming TCP messages.- Returns:
- this builder.
- Throws:
IOException
- if theDefaultTcpTransportMapping
cannot bind all local ports.
-
dtls
- Returns:
- this builder.
- Throws:
IOException
- if theDTLSTM
cannot bind the local port.
-
dtls
public SnmpBuilder dtls(TlsTmSecurityCallback<X509Certificate> securityCallback, DtlsAddress... listenAddresses) throws IOException Add theDTLSTM
server mode DTLS transport mappings for the specified listen addresses to theSnmp
instance to be built. The DTLS protocol versions to be supported are defined byDTLSTM.DEFAULT_DTLSTM_PROTOCOLS
.- Parameters:
securityCallback
- the callback function to validate X509 certificates of communication peers, seeTlsTmSecurityCallback
.listenAddresses
- the local IPs and ports to listen for incoming DTLS messages.- Returns:
- this builder.
- Throws:
IOException
- if theDTLSTM
cannot bind all local ports.
-
dtls
public SnmpBuilder dtls(TlsTmSecurityCallback<X509Certificate> securityCallback, String[] dtlsProtocolVersions, DtlsAddress... listenAddresses) throws IOException Add theDTLSTM
server mode DTLS transport mappings for the specified listen addresses to theSnmp
instance to be built.- Parameters:
securityCallback
- the callback function to validate X509 certificates of communication peers, seeTlsTmSecurityCallback
.dtlsProtocolVersions
- the DTLS protocol versions to be supported, default isDTLSTM.DEFAULT_DTLSTM_PROTOCOLS
. That is used whennull
is provided.listenAddresses
- the local IPs and ports to listen for incoming DTLS messages.- Returns:
- this builder.
- Throws:
IOException
- if theDTLSTM
cannot bind all local ports.
-
tls
- Returns:
- this builder.
- Throws:
IOException
- if theTLSTM
cannot bind the local port.
-
tls
public SnmpBuilder tls(TlsTmSecurityCallback<X509Certificate> securityCallback, TlsAddress... listenAddresses) throws IOException Add theTLSTM
server mode TLS transport mappings for the specified listen addresses to theSnmp
instance to be built. The TLS protocol versions to be supported are defined byTLSTM.DEFAULT_TLSTM_PROTOCOLS
.- Parameters:
securityCallback
- the callback function to validate X509 certificates of communication peers, seeTlsTmSecurityCallback
.listenAddresses
- the local IPs and ports to listen for incoming TLS messages.- Returns:
- this builder.
- Throws:
IOException
- if theTLSTM
cannot bind all local ports.
-
tls
public SnmpBuilder tls(TlsTmSecurityCallback<X509Certificate> securityCallback, String[] tlsProtocolVersions, TlsAddress... listenAddresses) throws IOException Add theTLSTM
server mode TLS transport mappings for the specified listen addresses to theSnmp
instance to be built.- Parameters:
securityCallback
- the callback function to validate X509 certificates of communication peers, seeTlsTmSecurityCallback
.tlsProtocolVersions
- the TLS protocol versions to be supported, default isTLSTM.DEFAULT_TLSTM_PROTOCOLS
. That is used whennull
is provided.listenAddresses
- the local IPs and ports to listen for incoming TLS messages.- Returns:
- this builder.
- Throws:
IOException
- if theTLSTM
cannot bind all local ports.
-
securityProtocols
Specifies which predefined set ofSecurityProtocols
should be available forSnmp
session to be built.- Parameters:
securityProtocolSet
- a predefined set ofSecurityProtocol
, default isSecurityProtocols.SecurityProtocolSet.defaultSecurity
- Returns:
- this builder.
-
build
Build theSnmp
instance with all the previously called configurations from this fluent builder.- Returns:
- a new
Snmp
instance, that now starts toSnmp.listen()
for incoming requests/responses. - Throws:
IOException
- if theSnmp
instance fails to listen.
-