java.lang.Object
org.snmp4j.util.AbstractSnmpUtility
org.snmp4j.util.TableUtils
The
TableUtils
class provides utility functions to retrieve
SNMP tabular data.- Since:
- 1.0.2
- Version:
- 2.5.11
- Author:
- Frank Fock
-
Nested Class Summary
Modifier and TypeClassDescriptionprotected class
protected class
TheDenseTableRequest
extends TableRequest to implement a faster table retrieval than the original.protected class
protected class
protected class
protected class
static enum
class
-
Field Summary
Modifier and TypeFieldDescriptionstatic final int
static final int
static final int
static final int
static final int
static final int
Fields inherited from class org.snmp4j.util.AbstractSnmpUtility
pduFactory, session
-
Constructor Summary
ConstructorDescriptionTableUtils
(Session snmpSession, PDUFactory pduFactory) Creates aTableUtils
instance. -
Method Summary
Modifier and TypeMethodDescription<A extends Address>
ResponseEvent<A> createRow
(Target<A> target, OID rowStatusColumnOID, OID rowIndex, VariableBinding[] values) Creates an SNMP table row for a table that supports the RowStatus mechanism for row creation.protected TableUtils.TableRequest
createTableRequest
(Target<?> target, OID[] columnOIDs, TableListener listener, Object userObject, OID lowerBoundIndex, OID upperBoundIndex, TableUtils.SparseTableMode sparseTableMode) <A extends Address>
ResponseEvent<A> destroyRow
(Target<A> target, OID rowStatusColumnOID, OID rowIndex) Destroys an SNMP table row from a table that support the RowStatus mechanism for row creation/deletion.void
getDenseTable
(Target<?> target, OID[] columnOIDs, TableListener listener, Object userObject, OID lowerBoundIndex, OID upperBoundIndex) Gets SNMP tabular data from one or more tables.int
Gets the maximum number of rows with wrong lexicographic ordering whicb will be return on a table retrieval withisCheckLexicographicOrdering()
set totrue
.int
Gets the maximum number of columns that will be retrieved per SNMP GETNEXT or GETBULK request.int
Gets the maximum number of rows that will be retrieved per SNMP GETBULK request.int
Gets the current row limit.Gets synchronously SNMP tabular data from one or more tables.getTable
(Target<?> target, OID[] columnOIDs, OID lowerBoundIndex, OID upperBoundIndex, long timeoutSeconds) Gets synchronously SNMP tabular data from one or more tables.void
getTable
(Target<?> target, OID[] columnOIDs, TableListener listener, Object userObject, OID lowerBoundIndex, OID upperBoundIndex) Gets SNMP tabular data from one or more tables.void
getTable
(Target<?> target, OID[] columnOIDs, TableListener listener, Object userObject, OID lowerBoundIndex, OID upperBoundIndex, TableUtils.SparseTableMode sparseTableMode) Gets SNMP tabular data from one or more tables.boolean
Indicates whether a single request on behalf ofgetTable(Target, OID[], OID, OID)
orgetTable(Target, OID[], TableListener, Object, OID, OID)
is sent to the agent or not.boolean
void
setCheckLexicographicOrdering
(boolean checkLexicographicOrdering) Enables or disables lexicographic ordering checks.void
setIgnoreMaxLexicographicRowOrderingErrors
(int ignoreMaxLexicographicRowOrderingErrors) Sets the maximum number of rows that will be returned with statusRetrievalEvent.STATUS_WRONG_ORDER
before the table retrieval will be stopped.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.void
setRowLimit
(int rowLimit) Sets the maximum number of rows returned from the target whengetTable(Target, OID[], OID, OID)
or any other overloaded variants of it are called.void
setSendColumnPDUsMultiThreaded
(boolean sendColumnPDUsMultiThreaded) Enable multi-threaded column PDU sending.
-
Field Details
-
ROWSTATUS_ACTIVE
public static final int ROWSTATUS_ACTIVE- See Also:
-
ROWSTATUS_NOTINSERVICE
public static final int ROWSTATUS_NOTINSERVICE- See Also:
-
ROWSTATUS_NOTREADY
public static final int ROWSTATUS_NOTREADY- See Also:
-
ROWSTATUS_CREATEANDGO
public static final int ROWSTATUS_CREATEANDGO- See Also:
-
ROWSTATUS_CREATEANDWAIT
public static final int ROWSTATUS_CREATEANDWAIT- See Also:
-
ROWSTATUS_DESTROY
public static final int ROWSTATUS_DESTROY- See Also:
-
-
Constructor Details
-
TableUtils
Creates aTableUtils
instance. The created instance is thread safe as long as the suppliedSession
andPDUFactory
are thread safe.- Parameters:
snmpSession
- a SNMPSession
instance.pduFactory
- aPDUFactory
instance that creates the PDU that are used by this instance to retrieve table data using GETBULK/GETNEXT operations.
-
-
Method Details
-
getTable
public List<TableEvent> 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 ofTableEvent
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
- aTarget
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 notnull
, all returned rows have an index greater thanlowerBoundIndex
.upperBoundIndex
- an optional parameter that specifies the upper bound index. If notnull
, all returned rows have an index less or equal thanupperBoundIndex
.- Returns:
- a
List
ofTableEvent
instances. Each instance represents successfully retrieved row or an error condition. Error conditions (any status other thanRetrievalEvent.STATUS_OK
) may only appear at the last element of the list.
-
getTable
public List<TableEvent> getTable(Target<?> target, OID[] columnOIDs, OID lowerBoundIndex, OID upperBoundIndex, long timeoutSeconds) Gets synchronously SNMP tabular data from one or more tables. The data is returned row-by-row as a list ofTableEvent
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
- aTarget
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 notnull
, all returned rows have an index greater thanlowerBoundIndex
.upperBoundIndex
- an optional parameter that specifies the upper bound index. If notnull
, all returned rows have an index less or equal thanupperBoundIndex
.timeoutSeconds
- the maximum number of seconds to wait for the whole table to be retrieved. Set it to 0, to wait forever.- Returns:
- a
List
ofTableEvent
instances. Each instance represents successfully retrieved row or an error condition. Error conditions (any status other thanRetrievalEvent.STATUS_OK
) may only appear at the last element of the list. - Since:
- 3.4.5
-
createTableRequest
protected TableUtils.TableRequest createTableRequest(Target<?> target, OID[] columnOIDs, TableListener listener, Object userObject, OID lowerBoundIndex, OID upperBoundIndex, TableUtils.SparseTableMode sparseTableMode) -
getTable
public void getTable(Target<?> target, OID[] columnOIDs, TableListener listener, Object userObject, OID lowerBoundIndex, OID upperBoundIndex, TableUtils.SparseTableMode sparseTableMode) 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().notifyAll(); } } }; tableUtil.getTable(..,..,myListener,this,..,..); while (!myListener.isFinished()) { wait(); } }
- Parameters:
target
- aTarget
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
- aTableListener
that is called withTableEvent
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 notnull
, all returned rows have an index greater thanlowerBoundIndex
.upperBoundIndex
- an optional parameter that specifies the upper bound index. If notnull
, all returned rows have an index less or equal thanupperBoundIndex
.sparseTableMode
- defines how rows with non-existing column values should be handled. Such rows can occur when new rows are being created or rows are removed from an agent while it is being
-
getTable
public void getTable(Target<?> target, OID[] columnOIDs, TableListener listener, 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().notifyAll(); } } }; tableUtil.getTable(..,..,myListener,this,..,..); while (!myListener.isFinished()) { wait(); } }
- Parameters:
target
- aTarget
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
- aTableListener
that is called withTableEvent
objects when an error occurred, 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 notnull
, all returned rows have an index greater thanlowerBoundIndex
.upperBoundIndex
- an optional parameter that specifies the upper bound index. If notnull
, all returned rows have an index less or equal thanupperBoundIndex
.- Since:
- 1.5
-
getDenseTable
public void getDenseTable(Target<?> target, OID[] columnOIDs, TableListener listener, 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 sparse tables, because it is optimized for dense tables and will not return correct results for sparse tables.
Rows that appear or disappear while being retrieved, are dropped and will be not returned partially (seeTableUtils.SparseTableMode.denseTableDropIncompleteRows
).- Parameters:
target
- aTarget
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
- aTableListener
that is called withTableEvent
objects when an error occurred, 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 notnull
, all returned rows have an index greater thanlowerBoundIndex
.upperBoundIndex
- an optional parameter that specifies the upper bound index. If notnull
, all returned rows have an index less or equal thanlowerBoundIndex
.- Since:
- 3.0
-
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.
-
isSendColumnPDUsMultiThreaded
public boolean isSendColumnPDUsMultiThreaded() -
setSendColumnPDUsMultiThreaded
public void setSendColumnPDUsMultiThreaded(boolean sendColumnPDUsMultiThreaded) Enable multi-threaded column PDU sending. If set totrue
and if themaxNumColumnsPerPDU
value is less than the number of columns to be retrieved in aTableUtils
request, then the requests for the columns will be splitted in two or more columns and the requests will be send to the agent concurrently without waiting for the response of the first/previous PDU. By default, this is disabled.- Parameters:
sendColumnPDUsMultiThreaded
- iftrue
, multi-threaded processing of column PDUs is enabled, otherwise only a single request will be sent to the agent on behalf agetTable(Target, OID[], OID, OID)
orgetTable(Target, OID[], TableListener, Object, OID, OID)
.
-
isCheckLexicographicOrdering
public boolean isCheckLexicographicOrdering()Indicates whether a single request on behalf ofgetTable(Target, OID[], OID, OID)
orgetTable(Target, OID[], TableListener, Object, OID, OID)
is sent to the agent or not.- Returns:
false
if single requests are sent,true
if more than a single request may be sent at a time.
-
getIgnoreMaxLexicographicRowOrderingErrors
public int getIgnoreMaxLexicographicRowOrderingErrors()Gets the maximum number of rows with wrong lexicographic ordering whicb will be return on a table retrieval withisCheckLexicographicOrdering()
set totrue
.- Returns:
- the number of ignored row ordering errors.
- Since:
- 2.5.11
-
setIgnoreMaxLexicographicRowOrderingErrors
public void setIgnoreMaxLexicographicRowOrderingErrors(int ignoreMaxLexicographicRowOrderingErrors) Sets the maximum number of rows that will be returned with statusRetrievalEvent.STATUS_WRONG_ORDER
before the table retrieval will be stopped. If this value is set to zero and lexicographic ordering check is enabled bysetCheckLexicographicOrdering(boolean)
, then table retrieval finishes immediately when the error is detected. Otherwise, retrieval continues until the maximum errors are detected and then the row cache will be returned too, although it may contain already incomplete rows based on correctly or incorrectly (!) ordered rows. The default value is three. That means, even if the ordering error occurs at the end of the table and- Parameters:
ignoreMaxLexicographicRowOrderingErrors
- the maximum numbers of rows with lexicographic ordering error to be returned before finishing table retrieve automatically. Setting this value has no effect ifisCheckLexicographicOrdering()
isfalse
.- Since:
- 2.5.11
-
setCheckLexicographicOrdering
public void setCheckLexicographicOrdering(boolean checkLexicographicOrdering) Enables or disables lexicographic ordering checks. By default, those checks are enabled, because otherwise with agents, that do not implement correct lexicographic ordering, endless looping could occur.- Parameters:
checkLexicographicOrdering
-false
to disable checks which could increase performance.- Since:
- 2.5.10
-
createRow
public <A extends Address> ResponseEvent<A> createRow(Target<A> target, OID rowStatusColumnOID, OID rowIndex, VariableBinding[] values) Creates an SNMP table row for a table that supports the RowStatus mechanism for row creation.- Type Parameters:
A
- type of the targetAddress
- 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. Ifvalues
isnull
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 isnull
a timeout has occurred. Otherwise, check the error status forSnmpConstants.SNMP_ERROR_SUCCESS
to verify that the row creation was successful. - Since:
- 1.6
-
destroyRow
public <A extends Address> ResponseEvent<A> destroyRow(Target<A> target, OID rowStatusColumnOID, OID rowIndex) Destroys an SNMP table row from a table that support the RowStatus mechanism for row creation/deletion.- Type Parameters:
A
- address type of the target.- 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 isnull
a timeout has occurred, Otherwise, check the error status forSnmpConstants.SNMP_ERROR_SUCCESS
to verify that the row creation was successful. - Since:
- 1.7.6
-
getRowLimit
public int getRowLimit()Gets the current row limit. A value greater than zero limits the total number of row events (TableEvent
to the given number. SeesetRowLimit(int)
for details.- Returns:
- the row limit.
- Since:
- 3.7.4
-
setRowLimit
public void setRowLimit(int rowLimit) Sets the maximum number of rows returned from the target whengetTable(Target, OID[], OID, OID)
or any other overloaded variants of it are called. Please note, that the last rows returned up togetMaxNumRowsPerPDU()
might not be complete (i.e., not all columns with data in the agent might have correspondingVariableBinding
s in the returnedTableEvent
. This can happen only for sparse tables, where not all columns of a row have values.- Parameters:
rowLimit
- a value greater than zero limits the total number of rows returned. If the limit is reached and probably more rows would have been available theRetrievalEvent.STATUS_ROW_LIMIT_REACHED
is returned.- Since:
- 3.7.4
-