com.h3c.util.snmp

## Class DefaultSnmpClient

- java.lang.Object
- - com.h3c.util.snmp.DefaultSnmpClient

- All Implemented Interfaces:
    DatagramEngine.Listener, SnmpClient

      public class DefaultSnmpClient
      extends Object
      implements SnmpClient, DatagramEngine.Listener

  The SNMP client is designed to be thread safe. The follow describes each of the 3 types of threads that will use call into an instance of this class:

  The Caller's thread (SNMP client) makes a call to `sendRequest(SnmpRequest)`. A caller can only send a request once. If the request is invalid or there is a problem with the engine an exception will be thrown. If the request is valid, the caller will receive a asynchronous notification on the request's listener. Internally, a call will be made to the `sendEngine(SnmpRequest)` method that is synchronized with respect to this instance.

  The Response Worker Thread will call `ClientResponseHandler.responseRecieved(SnmpResponse, byte[], InetSocketAddress)` when a response is received. A call is then made to `checkOut(int)` (which is synchronized) to unregister the associated request. If no request ID is found in the map, this response will be dropped because we have no knowledge of the original request. If a matching request is found, the response will be attached to the request and the response will be processed further. Note that the request has already been removed from the request map so there is no possibility for a retry to occur.

  The Timeout Worker Thread will periodically check the request map and perform resends or call back request that have exhausted all retry attempts. A call is made to `checkAndHandleTimeouts()` which will call `removeTimedOutRequests(long)` according to the timeout check frequency. The handler (which is synchronized) will iterate and remove all requests that have timed out. Any pending requests that arrive in the meantime will be dropped. (The response thread will have to wait for the iteration to complete before attempting to check out the request from the map). The synchronized block is exited and we are left with a list of requests that we now will retry or all the error listener.

  In summary, the `sendEngine(SnmpRequest)`, `checkOut(int)` and `removeTimedOutRequests(long)` methods are synchronized with respect to one another so that we can treat the request map and request ID allocation safely. This enforces that a request can only be worked on by a single thread at a time.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `DefaultSnmpClient(DatagramEngine datagramEngine)` Constructor.
    `DefaultSnmpClient(DatagramEngine datagramEngine, long timeoutCheckFrequencyMillis)` Constructor.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `onReceive(byte[] payload, InetSocketAddress remoteAddress)` Called back when a new datagram arrives.
    `void` | `sendRequest(SnmpRequest request)` Main entry point for sending requests to a SNMP server.
    `void` | `sendTrap(SnmpTrapRequest trap)` Main entry point for sending traps to a SNMP receiver.
    `void` | `stop()` Shutdown the client and underlying engine.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### DefaultSnmpClient

          public DefaultSnmpClient(DatagramEngine datagramEngine)

      Constructor.
      Parameters:
        `datagramEngine` - datagram engine implementation

    - #### DefaultSnmpClient

          public DefaultSnmpClient(DatagramEngine datagramEngine,
                           long timeoutCheckFrequencyMillis)

      Constructor.
      Parameters:
        `datagramEngine` - datagram engine implementation
        `timeoutCheckFrequencyMillis` - frequency in milliseconds between request timeout checks.

  - ### Method Detail

    - #### stop

          public void stop()

      Shutdown the client and underlying engine.
      Specified by:
        `stop` in interface `SnmpClient`

    - #### sendTrap

          public void sendTrap(SnmpTrapRequest trap)

      Main entry point for sending traps to a SNMP receiver. The caller creates a trap and hands it off to this this method. Once a trap enters this method the caller should not keep a reference to it.
      Specified by:
        `sendTrap` in interface `SnmpClient`
      Parameters:
        `trap` - SNMP trap
      Throws:
        `IllegalArgumentException` - if there is a problem with this request

    - #### sendRequest

          public void sendRequest(SnmpRequest request)

      Main entry point for sending requests to a SNMP server. The caller creates a request and hands it off to this method. Once a request enters this method the caller should not keep a reference to it.
      Specified by:
        `sendRequest` in interface `SnmpClient`
      Parameters:
        `request` - SNMP request (all required fields must be setup properly)
      Throws:
        `IllegalArgumentException` - if there is a problem with this request

    - #### onReceive

          public void onReceive(byte[] payload,
                       InetSocketAddress remoteAddress)

      Description copied from interface: `DatagramEngine.Listener`
      Called back when a new datagram arrives.
      Specified by:
        `onReceive` in interface `DatagramEngine.Listener`
      Parameters:
        `payload` - received datagram payload
        `remoteAddress` - remote socket address for received payload

Copyright © 2014. All Rights Reserved.