org.snmp4j.util
Class TableUtils

java.lang.Object
  extended by org.snmp4j.util.AbstractSnmpUtility
      extended by org.snmp4j.util.TableUtils

public class TableUtils
extends AbstractSnmpUtility

The TableUtils class provides utility functions to retrieve SNMP tabular data.

Since:
1.0.2
Version:
1.6e
Author:
Frank Fock

Nested Class Summary
 class TableUtils.TableRequest
           
 
Field Summary
static int ROWSTATUS_ACTIVE
           
static int ROWSTATUS_CREATEANDGO
           
static int ROWSTATUS_CREATEANDWAIT
           
static int ROWSTATUS_DESTROY
           
static int ROWSTATUS_NOTINSERVICE
           
static int ROWSTATUS_NOTREADY
           
 
Fields inherited from class org.snmp4j.util.AbstractSnmpUtility
pduFactory, session
 
Constructor Summary
TableUtils(Session snmpSession, PDUFactory pduFactory)
          Creates a TableUtils instance.
 
Method Summary
 ResponseEvent createRow(Target target, OID rowStatusColumnOID, OID rowIndex, VariableBinding[] values)
          Creates a SNMP table row for a table that supports the RowStatus mechanism for row creation.
protected  TableUtils.TableRequest createTableRequest(Target target, OID[] columnOIDs, TableListener listener, java.lang.Object userObject, OID lowerBoundIndex, OID upperBoundIndex)
           
 ResponseEvent destroyRow(Target target, OID rowStatusColumnOID, OID rowIndex)
          Destroys a SNMP table row from a table that support the RowStatus mechanism for row creation/deletion.
 void getDenseTable(Target target, OID[] columnOIDs, TableListener listener, java.lang.Object userObject, OID lowerBoundIndex, OID upperBoundIndex)
          Gets SNMP tabular data from one or more tables.
 int getMaxNumColumnsPerPDU()
          Gets the maximum number of columns that will be retrieved per SNMP GETNEXT or GETBULK request.
 int getMaxNumRowsPerPDU()
          Gets the maximum number of rows that will be retrieved per SNMP GETBULK request.
 java.util.List getTable(Target target, OID[] columnOIDs, OID lowerBoundIndex, OID upperBoundIndex)
          Gets synchronously SNMP tabular data from one or more tables.
 void getTable(Target target, OID[] columnOIDs, TableListener listener, java.lang.Object userObject, OID lowerBoundIndex, OID upperBoundIndex)
          Gets SNMP tabular data from one or more tables.
 void setMaxNumColumnsPerPDU(int numberOfColumnsPerChunk)
          Sets the maximum number of columns that will be retrieved per SNMP GETNEXT or GETBULK request.
 void setMaxNumRowsPerPDU(int numberOfRowsPerChunk)
          Sets the maximum number of rows that will be retrieved per SNMP GETBULK request.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ROWSTATUS_ACTIVE

public static final int ROWSTATUS_ACTIVE
See Also:
Constant Field Values

ROWSTATUS_NOTINSERVICE

public static final int ROWSTATUS_NOTINSERVICE
See Also:
Constant Field Values

ROWSTATUS_NOTREADY

public static final int ROWSTATUS_NOTREADY
See Also:
Constant Field Values

ROWSTATUS_CREATEANDGO

public static final int ROWSTATUS_CREATEANDGO
See Also:
Constant Field Values

ROWSTATUS_CREATEANDWAIT

public static final int ROWSTATUS_CREATEANDWAIT
See Also:
Constant Field Values

ROWSTATUS_DESTROY

public static final int ROWSTATUS_DESTROY
See Also:
Constant Field Values
Constructor Detail

TableUtils

public TableUtils(Session snmpSession,
                  PDUFactory pduFactory)
Creates a TableUtils instance. The created instance is thread safe as long as the supplied Session and PDUFactory are thread safe.

Parameters:
snmpSession - a SNMP Session instance.
pduFactory - a PDUFactory instance that creates the PDU that are used by this instance to retrieve table data using GETBULK/GETNEXT operations.
Method Detail

getTable

public java.util.List getTable(Target target,
                               OID[] columnOIDs,
                               OID lowerBoundIndex,
                               OID upperBoundIndex)
Gets synchronously SNMP tabular data from one or more tables. The data is returned row-by-row as a list of TableEvent instances. Each instance represents a row (or an error condition). Besides the target agent, the OIDs of the columnar objects have to be specified for which instances should be retrieved. With a lower bound index and an upper bound index, the result set can be narrowed to improve performance. This method can be executed concurrently by multiple threads.

Parameters:
target - a Target instance.
columnOIDs - an array of OIDs of the columnar objects whose instances should be retrieved. The columnar objects may belong to different tables. Typically they belong to tables that share a common index or sub-index prefix. Note: The result of this method is not defined if instance OIDs are supplied in this array!
lowerBoundIndex - an optional parameter that specifies the lower bound index. If not null, all returned rows have an index greater than lowerBoundIndex.
upperBoundIndex - an optional parameter that specifies the upper bound index. If not null, all returned rows have an index less or equal than upperBoundIndex.
Returns:
a List of TableEvent instances. Each instance represents successfully retrieved row or an error condition. Error conditions (any status other than RetrievalEvent.STATUS_OK) may only appear at the last element of the list.

createTableRequest

protected TableUtils.TableRequest createTableRequest(Target target,
                                                     OID[] columnOIDs,
                                                     TableListener listener,
                                                     java.lang.Object userObject,
                                                     OID lowerBoundIndex,
                                                     OID upperBoundIndex)

getTable

public void getTable(Target target,
                     OID[] columnOIDs,
                     TableListener listener,
                     java.lang.Object userObject,
                     OID lowerBoundIndex,
                     OID upperBoundIndex)
Gets SNMP tabular data from one or more tables. The data is returned asynchronously row-by-row through a supplied callback. Besides the target agent, the OIDs of the columnar objects have to be specified for which instances should be retrieved. With a lower bound index and an upper bound index, the result set can be narrowed to improve performance.

This method may call the TableListener.finished(org.snmp4j.util.TableEvent) method before it returns. If you want to synchronize the main thread with the finishing of the table retrieval, follow this pattern:

      synchronized (this) {
         TableListener myListener = ... {
            private boolean finished;

            public boolean isFinished() {
              return finished;
            }

            public void finished(TableEvent event) {
               ..
               finished = true;
               synchronized (event.getUserObject()) {
                  event.getUserObject().notify();
               }
            }
         };
         tableUtil.getTable(..,..,myListener,this,..,..);
         while (!myListener.isFinished()) {
           wait();
         }
      }
 

Parameters:
target - a Target instance.
columnOIDs - an array of OIDs of the columnar objects whose instances should be retrieved. The columnar objects may belong to different tables. Typically they belong to tables that share a common index or sub-index prefix. Note: The result of this method is not defined if instance OIDs are supplied in this array!
listener - a TableListener that is called with TableEvent objects when an error occured, new rows have been retrieved, or when the table has been retrieved completely.
userObject - an user object that is transparently supplied to the above call back.
lowerBoundIndex - an optional parameter that specifies the lower bound index. If not null, all returned rows have an index greater than lowerBoundIndex.
upperBoundIndex - an optional parameter that specifies the upper bound index. If not null, all returned rows have an index less or equal than upperBoundIndex.

getDenseTable

public void getDenseTable(Target target,
                          OID[] columnOIDs,
                          TableListener listener,
                          java.lang.Object userObject,
                          OID lowerBoundIndex,
                          OID upperBoundIndex)
Gets SNMP tabular data from one or more tables. The data is returned asynchronously row-by-row through a supplied callback. Besides the target agent, the OIDs of the columnar objects have to be specified for which instances should be retrieved. With a lower bound index and an upper bound index, the result set can be narrowed to improve performance.

This implementation must not be used with sparese tables, because it is optimized for dense tables and will not return correct results for sparse tables.

Parameters:
target - a Target instance.
columnOIDs - an array of OIDs of the columnar objects whose instances should be retrieved. The columnar objects may belong to different tables. Typically they belong to tables that share a common index or sub-index prefix. Note: The result of this method is not defined if instance OIDs are supplied in this array!
listener - a TableListener that is called with TableEvent objects when an error occured, new rows have been retrieved, or when the table has been retrieved completely.
userObject - an user object that is transparently supplied to the above call back.
lowerBoundIndex - an optional parameter that specifies the lower bound index. If not null, all returned rows have an index greater than lowerBoundIndex.
upperBoundIndex - an optional parameter that specifies the upper bound index. If not null, all returned rows have an index less or equal than lowerBoundIndex.
Since:
1.5

getMaxNumRowsPerPDU

public int getMaxNumRowsPerPDU()
Gets the maximum number of rows that will be retrieved per SNMP GETBULK request.

Returns:
an integer greater than zero that specifies the maximum number of rows to retrieve per SNMP GETBULK operation.

setMaxNumRowsPerPDU

public void setMaxNumRowsPerPDU(int numberOfRowsPerChunk)
Sets the maximum number of rows that will be retrieved per SNMP GETBULK request. The default is 10.

Parameters:
numberOfRowsPerChunk - an integer greater than zero that specifies the maximum number of rows to retrieve per SNMP GETBULK operation.

getMaxNumColumnsPerPDU

public int getMaxNumColumnsPerPDU()
Gets the maximum number of columns that will be retrieved per SNMP GETNEXT or GETBULK request.

Returns:
an integer greater than zero that specifies the maximum columns of rows to retrieve per SNMP GETNEXT or GETBULK operation.

setMaxNumColumnsPerPDU

public void setMaxNumColumnsPerPDU(int numberOfColumnsPerChunk)
Sets the maximum number of columns that will be retrieved per SNMP GETNEXT or GETBULK request. The default is 10.

Parameters:
numberOfColumnsPerChunk - an integer greater than zero that specifies the maximum columns of rows to retrieve per SNMP GETNEXT or GETBULK operation.

createRow

public ResponseEvent createRow(Target target,
                               OID rowStatusColumnOID,
                               OID rowIndex,
                               VariableBinding[] values)
Creates a SNMP table row for a table that supports the RowStatus mechanism for row creation.

Parameters:
target - the Target SNMP entity for the operation.
rowStatusColumnOID - the column OID of the RowStatus column (without any instance identifier).
rowIndex - the OID denoting the index of the table row to create.
values - the values of columns to set in the row. If values is null the row is created via the tripple mode row creation mechanism (RowStatus is set to createAndWait). Otherwise, each variable binding has to contain the OID of the columnar object ID (without any instance identifier) and its value. On return, the variable bindings will be modified so that the variable binding OIDs will contain the instance OIDs of the respective columns (thus column OID + rowIndex).
Returns:
ResponseEvent the ResponseEvent instance returned by the SNMP session on response of the internally sent SET request. If null, an IO exception has occurred. Otherwise, if the response PDU is null a timeout has occured, Otherwise, check the error status for SnmpConstants.SNMP_ERROR_SUCCESS to verify that the row creation was successful.
Since:
1.6

destroyRow

public ResponseEvent destroyRow(Target target,
                                OID rowStatusColumnOID,
                                OID rowIndex)
Destroys a SNMP table row from a table that support the RowStatus mechanism for row creation/deletion.

Parameters:
target - the Target SNMP entity for the operation.
rowStatusColumnOID - the column OID of the RowStatus column (without any instance identifier).
rowIndex - the OID denoting the index of the table row to destroy.
Returns:
ResponseEvent the ResponseEvent instance returned by the SNMP session on response of the internally sent SET request. If null, an IO exception has occurred. Otherwise, if the response PDU is null a timeout has occured, Otherwise, check the error status for SnmpConstants.SNMP_ERROR_SUCCESS to verify that the row creation was successful.
Since:
1.7.6

Copyright 2005-2010 Frank Fock (SNMP4J.org)

Copyright © 2011 SNMP4J.org. All Rights Reserved.