OpenNMS API 1.2.3

org.opennms.netmgt.collectd
Class SnmpIfCollector

java.lang.Object
  extended byorg.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.3

Generated by eevans on May 29 2005 2015.