Module org.snmp4j

Class SnmpBuilder


  • public class SnmpBuilder
    extends java.lang.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
    • Field Detail

      • snmp

        protected final Snmp snmp
      • multiThreadedDispatcherPool

        protected ThreadPool multiThreadedDispatcherPool
      • responderPoolName

        protected java.lang.String responderPoolName
      • localEngineID

        protected byte[] localEngineID
    • Method Detail

      • 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
      • 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 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 a DefaultTcpTransportMapping 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 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:
        java.io.IOException - if the DefaultTcpTransportMapping cannot bind all local ports.
      • dtls

        public SnmpBuilder dtls()
                         throws java.io.IOException
        Add a DTLSTM client mode DTLS transport mapping to the Snmp instance to be built.
        Returns:
        this builder.
        Throws:
        java.io.IOException - if the DTLSTM cannot bind the local port.
      • dtls

        public SnmpBuilder dtls​(TlsTmSecurityCallback<java.security.cert.X509Certificate> securityCallback,
                                DtlsAddress... listenAddresses)
                         throws java.io.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:
        java.io.IOException - if the DTLSTM 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 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:
        java.io.IOException - if the DTLSTM cannot bind all local ports.
      • tls

        public SnmpBuilder tls()
                        throws java.io.IOException
        Add a TLSTM client mode TLS transport mapping to the Snmp instance to be built.
        Returns:
        this builder.
        Throws:
        java.io.IOException - if the TLSTM cannot bind the local port.
      • tls

        public SnmpBuilder tls​(TlsTmSecurityCallback<java.security.cert.X509Certificate> securityCallback,
                               TlsAddress... listenAddresses)
                        throws java.io.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:
        java.io.IOException - if the TLSTM 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 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:
        java.io.IOException - if the TLSTM cannot bind all local ports.
      • build

        public Snmp build()
                   throws java.io.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:
        java.io.IOException - if the Snmp instance fails to listen.