- java.lang.Object
-
- org.snmp4j.fluent.SnmpBuilder
-
public class SnmpBuilder extends java.lang.Object
Builds aSnmp
instance through step-by-step configuration using a fluent interface design pattern. ThisSnmpBuilder
is the starting context. It creates the non-fluentSnmp
instance that is needed to as first parameter forSnmpCompletableFuture.send(Snmp, Target, PDU, Object...)
which actually sends the SNMP message to aTarget
. UseTargetBuilder
andPduBuilder
to create the other two mandatory parameters. To get aTargetBuilder
calltarget(Address)
. ThePduBuilder
can be then retrieved from thatTargetBuilder
by callingTargetBuilder.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
Fields Modifier and Type Field Description protected CounterSupport
counterSupport
protected EngineBootsProvider
engineBootsProvider
protected EngineIdProvider
engineIdProvider
protected byte[]
localEngineID
protected ThreadPool
multiThreadedDispatcherPool
protected java.lang.String
responderPoolName
protected SecurityModels
securityModels
protected SecurityProtocols
securityProtocols
protected Snmp
snmp
-
Constructor Summary
Constructors Modifier Constructor Description SnmpBuilder()
Creates 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
All Methods Instance Methods Concrete Methods Modifier and Type Method Description Snmp
build()
Build theSnmp
instance with all the previously called configurations from this fluent builder.SnmpBuilder
counterSupport(CounterSupport counterSupport)
Sets theCounterSupport
withSnmp.setCounterSupport(CounterSupport)
when building theSnmp
instance usingbuild()
.SnmpBuilder
dtls()
SnmpBuilder
dtls(TlsTmSecurityCallback<java.security.cert.X509Certificate> securityCallback, java.lang.String[] dtlsProtocolVersions, DtlsAddress... listenAddresses)
SnmpBuilder
dtls(TlsTmSecurityCallback<java.security.cert.X509Certificate> securityCallback, DtlsAddress... listenAddresses)
SnmpBuilder
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
.SnmpBuilder
tcp()
Add aDefaultTcpTransportMapping
in client mode with an arbitrary local address amd port.SnmpBuilder
tcp(TcpAddress... listenAddresses)
Add theDefaultTcpTransportMapping
server mode TCP transport mappings for the specified listen addresses to theSnmp
instance to be built.SnmpBuilder
threads(int numThreads)
Configures theMultiThreadedMessageDispatcher
as message dispatcher and thereby defines the number of threads in itsThreadPool
.SnmpBuilder
tls()
SnmpBuilder
tls(TlsTmSecurityCallback<java.security.cert.X509Certificate> securityCallback, java.lang.String[] tlsProtocolVersions, TlsAddress... listenAddresses)
SnmpBuilder
tls(TlsTmSecurityCallback<java.security.cert.X509Certificate> securityCallback, TlsAddress... listenAddresses)
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.SnmpBuilder
tsm(OctetString localEngineID, boolean usePrefix)
Creates a Transport Security Model as defined by RFC 5591 and adds it to the builtSnmp
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 addressesSnmpBuilder
usm()
Creates a USM for the specified engine ID and engine boots counter derived from the SNMP engine ID provider given byv3(EngineIdProvider, OctetString)
.SnmpBuilder
usm(SnmpEngineIdProvider snmpEngineIdProvider, OctetString defaultLocalEngineID)
Creates a USM using the specifiedSnmpEngineIdProvider
.SnmpBuilder
usm(OctetString localEngineID, int engineBoots)
Creates a USM for the specified engine ID and engine boots counter.SnmpBuilder
v1()
Adds theMPv1
security model toSnmp.getMessageDispatcher()
.SnmpBuilder
v2c()
Adds aMPv2c
security model toSnmp.getMessageDispatcher()
.SnmpBuilder
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
.SnmpBuilder
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)
.SnmpBuilder
v3(EngineIdProvider engineIdProvider, OctetString id)
Adds aMPv3
message processing model with a random engine ID based on the supplied ID string.SnmpBuilder
v3(OctetString id)
Adds aMPv3
message processing model with a random engine ID based on the supplied ID string.
-
-
-
Field Detail
-
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 java.lang.String responderPoolName
-
engineIdProvider
protected EngineIdProvider engineIdProvider
-
engineBootsProvider
protected EngineBootsProvider engineBootsProvider
-
localEngineID
protected byte[] localEngineID
-
-
Constructor Detail
-
SnmpBuilder
public SnmpBuilder()
Creates anSnmpBuilder
with a default constructedSnmp
instance.
-
SnmpBuilder
protected SnmpBuilder(Snmp snmp)
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 Detail
-
target
public <A extends Address> TargetBuilder<A> target(A address)
Creates aTargetBuilder
for the specified targetAddress
.- Type Parameters:
A
- the transport address type.- Parameters:
address
- aTransportIpAddress
.- Returns:
- a
TargetBuilder
instance.
-
counterSupport
public SnmpBuilder counterSupport(CounterSupport counterSupport)
Sets theCounterSupport
withSnmp.setCounterSupport(CounterSupport)
when building theSnmp
instance usingbuild()
.- Parameters:
counterSupport
- theCounterSupport
, defaults toCounterSupport.getInstance()
.- Returns:
- this builder.
-
v1
public SnmpBuilder v1()
Adds theMPv1
security model toSnmp.getMessageDispatcher()
.- Returns:
- this builder.
-
v2c
public SnmpBuilder v2c()
Adds aMPv2c
security model toSnmp.getMessageDispatcher()
.- Returns:
- this builder.
-
v3
public SnmpBuilder 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
public SnmpBuilder v3(OctetString id)
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
public SnmpBuilder v3(EngineIdProvider engineIdProvider, OctetString id)
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
public SnmpBuilder 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)
.- Parameters:
localEngineID
- the local engine ID of the SNMP entity represented by theSnmp
instance to be built.- Returns:
- this builder.
-
threads
public SnmpBuilder threads(int numThreads)
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
public SnmpBuilder 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
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 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
public SnmpBuilder tsm(OctetString localEngineID, boolean usePrefix)
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
public SnmpBuilder udp() throws java.io.IOException
Adds a UDP transport mapping (DefaultUdpTransportMapping
) with an operating system chosen local port on all local IP addresses.- Returns:
- this builder.
- Throws:
java.io.IOException
- if the socket could not be bound.
-
udp
public SnmpBuilder udp(UdpAddress... listenAddresses) throws java.io.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:
java.io.IOException
- if one of the sockets could not be bound.
-
tcp
public SnmpBuilder tcp() throws java.io.IOException
Add aDefaultTcpTransportMapping
in client mode with an arbitrary local address amd port.- Returns:
- this builder.
- Throws:
java.io.IOException
- if the local port cannot be bound.
-
tcp
public SnmpBuilder tcp(TcpAddress... listenAddresses) throws java.io.IOException
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:
java.io.IOException
- if theDefaultTcpTransportMapping
cannot bind all local ports.
-
dtls
public SnmpBuilder dtls() throws java.io.IOException
- Returns:
- this builder.
- Throws:
java.io.IOException
- if theDTLSTM
cannot bind the local port.
-
dtls
public SnmpBuilder dtls(TlsTmSecurityCallback<java.security.cert.X509Certificate> securityCallback, DtlsAddress... listenAddresses) throws java.io.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:
java.io.IOException
- if theDTLSTM
cannot bind all local ports.
-
dtls
public SnmpBuilder dtls(TlsTmSecurityCallback<java.security.cert.X509Certificate> securityCallback, java.lang.String[] dtlsProtocolVersions, DtlsAddress... listenAddresses) throws java.io.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:
java.io.IOException
- if theDTLSTM
cannot bind all local ports.
-
tls
public SnmpBuilder tls() throws java.io.IOException
- Returns:
- this builder.
- Throws:
java.io.IOException
- if theTLSTM
cannot bind the local port.
-
tls
public SnmpBuilder tls(TlsTmSecurityCallback<java.security.cert.X509Certificate> securityCallback, TlsAddress... listenAddresses) throws java.io.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:
java.io.IOException
- if theTLSTM
cannot bind all local ports.
-
tls
public SnmpBuilder tls(TlsTmSecurityCallback<java.security.cert.X509Certificate> securityCallback, java.lang.String[] tlsProtocolVersions, TlsAddress... listenAddresses) throws java.io.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:
java.io.IOException
- if theTLSTM
cannot bind all local ports.
-
securityProtocols
public SnmpBuilder securityProtocols(SecurityProtocols.SecurityProtocolSet securityProtocolSet)
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
public Snmp build() throws java.io.IOException
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:
java.io.IOException
- if theSnmp
instance fails to listen.
-
-