OpenNMS API 1.2.9

## org.opennms.netmgt.collectd
Class SnmpIfCollector

    java.lang.Object
      org.opennms.netmgt.collectd.SnmpIfCollector

All Implemented Interfaces:
  SnmpHandler

public class SnmpIfCollector
extends java.lang.Object
implements SnmpHandler

The SnmpIfCollector class is responsible for performing the actual SNMP data collection for a node over a specified network interface. The SnmpIfCollector implements the SnmpHandler class in order to receive notifications when an SNMP reply is received or error occurs. The SnmpIfCollector is provided a list of MIB objects to collect and an interface over which to collect the data. Data collection can be via SNMPv1 GetNext requests or SNMPv2 GetBulk requests depending upon the parms used to construct the collector.

Version:
  1.1.1.1
Author:
  Mike , Jon Whetzel , OpenNMS

Field Summary
`private SNMPCollectorEntry` `m_collectorEntry` For SNMPv1, used to store the collected MIB data.
`private java.util.List` `m_entries` Used to store all the generated maps of the MIB data for each interface.
`private boolean` `m_error` Flag indicating the success or failure of the informational query.
`private int` `m_errorIndex` If the SNMP collection failed due to a problem with one or more varbinds (for example if a particular object oid is requested which is not implemented in the target's SNMP agent) then this value will be set equal to the *first* failing varbind in the request.
`private int` `m_errorStatus` Reason that the SNMP request failed.
`private static java.lang.String[]` `m_errorText` Array of SNMPv1 error strings.
`private java.util.Map` `m_ifMap` Map of IfInfo objects representing each of the nodes interfaces.
`private java.lang.String[]` `m_indexArray` Used for keeping track of all the possible indexes.
`private int` `m_maxVarsPerPdu` Max number of variables permitted in a single outgoing SNMP PDU request..
`private int` `m_numInterfaces` The number of interfaces associated with the remote host.
`private java.util.List` `m_objList` List of MibObject objects to be collected.
`private java.util.List` `m_objList_v2` Copy of m_objList list that will used solely by version 2.
`private int` `m_oidListIndex` For SNMPv1, keeps track of current oid list index.
`private java.lang.String` `m_primaryIf` Holds the IP Address of the primary SNMP iterface.
`private java.lang.String` `m_primaryIfIndex` Holds the ifIndex of the primary SNMP interface.
`private int` `m_responses` For SNMPv1, used for keeping track of the SNMP response PDUs received.
`private java.util.List` `m_responseVbList` Used as temporary storage for variables coming from Snmp v2 PDU reponses.
`private Signaler` `m_signal` Used to synchronize the class to ensure that the session has finished collecting data before the value of success or failure is set, and control is returned to the caller.
`private boolean` `m_timeout` Flag indicating if the SNMP collection failed due to the SNMP request timing out.
`private int` `m_version` Used for classifying the SNMP version of the session.

Constructor Summary
`private` `SnmpIfCollector()` The default constructor is marked private and will always throw an exception.
`` `SnmpIfCollector(SnmpSession session, Signaler signaler, java.lang.String primaryIfIndex, java.util.Map ifMap, int ifCount, int maxVarsPerPdu)` The class constructor is used to initialize the collector and send out the initial SNMP packet requesting data.

Method Summary
`private static java.util.List` `buildV2CombinedOidList(java.util.Map ifMap)` This method is responsible for building a new object list consisting of all unique oids to be collected for all interfaces represented within the interface map.
`boolean` `failed()` Returns the success or failure code for collection of the data.
`java.util.List` `getEntries()` Returns the list of all entry maps that can be used to access all the information from the service polling.
`private SnmpPduPacket` `getNextSnmpV1Pdu(java.lang.String ifAddress)` This method constructs the next SnmpPduPacket (pdu) for sending to the remote node.
`private SnmpPduPacket` `getNextSnmpV2Pdu(java.lang.String ifAddress)` This method constructs the next SnmpPduPacket (pdu) for sending to the remote node.
`void` `snmpInternalError(SnmpSession session, int error, SnmpSyntax pdu)` This method is part of the SnmpHandler interface and called when an internal error happens in a session.
`void` `snmpReceivedPdu(SnmpSession session, int command, SnmpPduPacket pdu)` This method is used to process received SNMP PDU packets from the remote agent.
`void` `snmpTimeoutError(SnmpSession session, SnmpSyntax pdu)` This method is part of the SnmpHandler interface and is invoked when the SnmpSession does not receive a reply after exhausting the retransmission attempts.
`static SnmpObjectId` `stop_oid(java.lang.String oid)` This method will take an OID, and generate the succeeding OID.
`boolean` `timedout()` Returns true if SNMP collection failed due to timeout.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### m_error

    private boolean m_error

  Flag indicating the success or failure of the informational query. If the flag is set to false then either part of all of the information was unable to be retreived. If it is set to true then all of the data was received from the remote host.

### m_errorStatus

    private int m_errorStatus

  Reason that the SNMP request failed. Please see org.opennms.protocols.snmp.SnmpPduPacket class for a list of possible SNMP error codes. This variable only has meaning of m_error flag is true.

### m_errorText

    private static java.lang.String[] m_errorText

  Array of SNMPv1 error strings. Please see org.opennms.protocols.snmp.SnmpPduPacket class for list of SNMP error codes which serve as indices into this string array.

### m_errorIndex

    private int m_errorIndex

  If the SNMP collection failed due to a problem with one or more varbinds (for example if a particular object oid is requested which is not implemented in the target's SNMP agent) then this value will be set equal to the *first* failing varbind in the request. This variable only has meaning if m_error flag is true. Will be set to -1 if the SNMP collection failed for an unrelated reason.

### m_timeout

    private boolean m_timeout

  Flag indicating if the SNMP collection failed due to the SNMP request timing out. Its value only has meaning if m_error flag is true.

### m_signal

    private Signaler m_signal

  Used to synchronize the class to ensure that the session has finished collecting data before the value of success or failure is set, and control is returned to the caller.

### m_objList

    private java.util.List m_objList

  List of MibObject objects to be collected.

### m_objList_v2

    private java.util.List m_objList_v2

  Copy of m_objList list that will used solely by version 2. As each object is collected from the remote node via subsequent SNMPv2 GetBulk commands the MibObject is removed and the collection for the next object started.

### m_entries

    private java.util.List m_entries

  Used to store all the generated maps of the MIB data for each interface.

### m_version

    private int m_version

  Used for classifying the SNMP version of the session.

### m_indexArray

    private java.lang.String[] m_indexArray

  Used for keeping track of all the possible indexes. Needed for generating packets for SNMP v1.

### m_responseVbList

    private java.util.List m_responseVbList

  Used as temporary storage for variables coming from Snmp v2 PDU reponses. Once all the data is gathered, we can generate maps of the data, one map per interface.

### m_responses

    private int m_responses

  For SNMPv1, used for keeping track of the SNMP response PDUs received. For SNMPv2, this used for keeping track of the total number of variable bindings returned during each subsequent MIB object collection. This variable is reset back to 0 after the MIB object has been collected for all interfaces.

### m_collectorEntry

    private SNMPCollectorEntry m_collectorEntry

  For SNMPv1, used to store the collected MIB data.

### m_oidListIndex

    private int m_oidListIndex

  For SNMPv1, keeps track of current oid list index.

### m_primaryIfIndex

    private java.lang.String m_primaryIfIndex

  Holds the ifIndex of the primary SNMP interface.

### m_primaryIf

    private java.lang.String m_primaryIf

  Holds the IP Address of the primary SNMP iterface.

### m_numInterfaces

    private int m_numInterfaces

  The number of interfaces associated with the remote host.

### m_maxVarsPerPdu

    private int m_maxVarsPerPdu

  Max number of variables permitted in a single outgoing SNMP PDU request..

### m_ifMap

    private java.util.Map m_ifMap

  Map of IfInfo objects representing each of the nodes interfaces.

Constructor Detail

### SnmpIfCollector

    private SnmpIfCollector()
                     throws java.lang.UnsupportedOperationException

  The default constructor is marked private and will always throw an exception. This is done to disallow the default constructor. The reason is that this object requires several arguments to perform it's duties.

Throws:
  `java.lang.UnsupportedOperationException` - Always thrown from this method since it is not supported.

### SnmpIfCollector

    public SnmpIfCollector(SnmpSession session,
                           Signaler signaler,
                           java.lang.String primaryIfIndex,
                           java.util.Map ifMap,
                           int ifCount,
                           int maxVarsPerPdu)

  The class constructor is used to initialize the collector and send out the initial SNMP packet requesting data. The data is then received and store by the object. When all the data has been collected the passed signaler object is notified using the notifyAll() method.

Parameters:
  `session` - The SNMP session with the remote agent.
  `signaler` - The object signaled when data collection is done.
  `primaryIfIndex` - The ifIndex value linked to the primary IP.
  `ifMap` - Map of org.opennms.netmgt.poller.collectd.IfInfo objects.
  `ifCount` - Number of interfaces found in node's MIB-II ifTable
  `maxVarsPerPdu` - Max number of variables permitted in a single PDU.

Method Detail

### stop_oid

    public static SnmpObjectId stop_oid(java.lang.String oid)

  This method will take an OID, and generate the succeeding OID. This will be used for examining responses from SNMPv2 GETBULK packets when doing SNMPv2 collection, so that we can keep all the data for a particular object, and throw out the rest.

  Parameters:
    `oid` - Object identifier from which to generate the stop oid
  Returns:
    SnmpObjectId object which represents the oid on which to stop the bulk collection.

### getNextSnmpV1Pdu

    private SnmpPduPacket getNextSnmpV1Pdu(java.lang.String ifAddress)

  This method constructs the next SnmpPduPacket (pdu) for sending to the remote node. For SNMPv1, GET commands are built. Each constructed PDU contains varbinds for all the objects to be collected for a single interface. For objects whose instance id is determined by ifIndex (such as ifOctetsIn or ifOctetsOut in the ifTable) the interface index will be appended to the oid name within the varbind. Therefore, for an SNMPv1 based collection the number of PDUs generated will be equal to the number interfaces in the remote node's ifTable. As each GET response is received the response count is incremented and each subsequent call to getNextSnmpV1Pdu() will generate a PDU for collecting data pertaining to the next interface in the ifTable.

  Parameters:
    `ifAddress` - Interface address of the remote agent
  Returns:
    An SnmpPduPacket appropriate for the SNMP version supported.
  See Also:
    `SnmpNull`, `SnmpPduPacket`

### getNextSnmpV2Pdu

    private SnmpPduPacket getNextSnmpV2Pdu(java.lang.String ifAddress)

  This method constructs the next SnmpPduPacket (pdu) for sending to the remote node. For SNMPv2, GETBULK commands are built. Each constructed PDU contains a single varbind representing the next object to be retrieved. If that object pertains to all the remote node's interfaces (such as ifOctetsIn or ifOctetsOut) then maxRepetitions will be set to the number of interfaces in the ifTable and the object will be collected for every interface with a single GETBULK pdu. If the oid is a singular instance which doesn't pertain to all interfaces then a GETBULK pdu is built with nonRepeaters set to 1 and maxRepetitions set to 0 and only that individual value is collected. Therefore, for SNMPv2 based collection the number of PDUs generated will be equal to (numInterfaces * numInterfaceBasedObjects) + (numSingularObjects).

  Parameters:
    `ifAddress` - Interface address of the remote agent
  Returns:
    An SnmpPduPacket appropriate for the SNMP version supported.
  See Also:
    `SnmpNull`, `SnmpPduPacket`

### snmpReceivedPdu

    public void snmpReceivedPdu(SnmpSession session,
                                int command,
                                SnmpPduPacket pdu)

  This method is used to process received SNMP PDU packets from the remote agent. The method is part of the SnmpHandler interface and will be invoked when a PDU is successfully decoded. The method is passed the receiving session, the PDU command, and the actual PDU packet. For SNMPv2, all the data will be stored within a temporary array. Once all data has been acquired, it will be organized by interface. For any MIB OID whose index is zero, their data will be associated with the primary interface's index. For SNMPv1, a map will be created after each response. Once again, if the MIB OID has a zero at the end, it will be linked with the primary interface. When all the data has been received from the session the signaler object, initialized in the constructor, is signaled. In addition, the receiving instance will call notifyAll() on itself at the same time.

  Specified by:
    `snmpReceivedPdu` in interface `SnmpHandler`
  Parameters:
    `session` - The SNMP Session that received the PDU
    `command` - The command contained in the received pdu
    `pdu` - The actual received PDU.

### snmpInternalError

    public void snmpInternalError(SnmpSession session,
                                  int error,
                                  SnmpSyntax pdu)

  This method is part of the SnmpHandler interface and called when an internal error happens in a session. This is usually the result of an I/O error. This method will not be called if the session times out sending a packet, see snmpTimeoutError for timeout handling.

  Specified by:
    `snmpInternalError` in interface `SnmpHandler`
  Parameters:
    `session` - The session that had an unexpected error
    `error` - The error condition
    `pdu` - The PDU being sent when the error occured
  See Also:
    `snmpTimeoutError(org.opennms.protocols.snmp.SnmpSession, org.opennms.protocols.snmp.SnmpSyntax)`, `SnmpHandler`

### snmpTimeoutError

    public void snmpTimeoutError(SnmpSession session,
                                 SnmpSyntax pdu)

  This method is part of the SnmpHandler interface and is invoked when the SnmpSession does not receive a reply after exhausting the retransmission attempts.

  Specified by:
    `snmpTimeoutError` in interface `SnmpHandler`
  Parameters:
    `session` - The session invoking the error handler
    `pdu` - The PDU that the remote failed to respond to.
  See Also:
    `SnmpHandler`

### failed

    public boolean failed()

  Returns the success or failure code for collection of the data.

### timedout

    public boolean timedout()

  Returns true if SNMP collection failed due to timeout. Otherwise, returns false.

### getEntries

    public java.util.List getEntries()

  Returns the list of all entry maps that can be used to access all the information from the service polling.

### buildV2CombinedOidList

    private static java.util.List buildV2CombinedOidList(java.util.Map ifMap)

  This method is responsible for building a new object list consisting of all unique oids to be collected for all interfaces represented within the interface map. The new list can then be used for SNMPv2 collection.

  Parameters:
    `ifMap` - Map of IfInfo objects indexed by ifIndex
  Returns:
    unified MibObject list

OpenNMS API 1.2.9

Generated by ranger on May 19 2007 2335.