tableutils.java

snmp4j

/*_############################################################################
  _##
  _##  SNMP4J - TableUtils.java
  _##
  _##  Copyright 2003-2005  Frank Fock and Jochen Katz (SNMP4J.org)
  _##
  _##  Licensed under the Apache License, Version 2.0 (the "License");
  _##  you may not use this file except in compliance with the License.
  _##  You may obtain a copy of the License at
  _##
  _##      http://www.apache.org/licenses/LICENSE-2.0
  _##
  _##  Unless required by applicable law or agreed to in writing, software
  _##  distributed under the License is distributed on an "AS IS" BASIS,
  _##  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  _##  See the License for the specific language governing permissions and
  _##  limitations under the License.
  _##
  _##########################################################################*/

package org.snmp4j.util;

import java.util.*;

import org.snmp4j.log.*;
import org.snmp4j.*;
import org.snmp4j.event.*;
import org.snmp4j.mp.SnmpConstants;
import org.snmp4j.smi.*;

/**
 * The <code>TableUtils</code> class provides utility functions to retrieve
 * SNMP tabular data.
 *
 * @author Frank Fock
 * @version 1.1
 * @since 1.0.2
 */
public class TableUtils {

  private static final LogAdapter logger =
      LogFactory.getLogger(TableUtils.class);

  private Session session;
  private PDUFactory pduFactory;
  private int maxNumOfRowsPerPDU = 10;
  private int maxNumColumnsPerPDU = 10;

  /**
   * Creates a <code>TableUtils</code> instance. The created instance is thread
   * safe as long as the supplied <code>Session</code> and <code>PDUFactory</code>
   * are thread safe.
   *
   * @param snmpSession
   *    a SNMP <code>Session</code> instance.
   * @param pduFactory
   *    a <code>PDUFactory</code> instance that creates the PDU that are used
   *    by this instance to retrieve table data using GETBULK/GETNEXT
   *    operations.
   */
  public TableUtils(Session snmpSession, PDUFactory pduFactory) {
    this.session = snmpSession;
    this.pduFactory = pduFactory;
  }

  /**
   * Gets synchronously SNMP tabular data from one or more tables.
   * The data is returned row-by-row as a list of {@link 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.
   *
   * @param target
   *    a <code>Target</code> instance.
   * @param 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!
   * @param lowerBoundIndex
   *    an optional parameter that specifies the lower bound index.
   *    If not <code>null</code>, all returned rows have an index greater than
   *    <code>lowerBoundIndex</code>.
   * @param upperBoundIndex
   *    an optional parameter that specifies the upper bound index.
   *    If not <code>null</code>, all returned rows have an index less or equal
   *    than <code>lowerBoundIndex</code>.
   * @return
   *    a <code>List</code> of {@link TableEvent} instances. Each instance
   *    represents successfully retrieved row or an error condition. Error
   *    conditions (any status other than {@link TableEvent#STATUS_OK})
   *    may only appear at the last element of the list.
   */
  public List getTable(Target target,
                       OID[] columnOIDs,
                       OID lowerBoundIndex,
                       OID upperBoundIndex) {

    if ((columnOIDs == null) || (columnOIDs.length == 0)) {
      throw new IllegalArgumentException("No column OIDs specified");
    }
    InternalTableListener listener = new InternalTableListener();
    TableRequest req = new TableRequest(target, columnOIDs, listener,
                                        null,
                                        lowerBoundIndex,
                                        upperBoundIndex);
    synchronized (listener) {
      if (req.sendNextChunk()) {
        try {
          listener.wait();
        }
        catch (InterruptedException ex) {
          logger.warn(ex);
        }
      }
    }
    return listener.getRows();
  }


  /**
   * 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.
   *
   * @param target
   *    a <code>Target</code> instance.
   * @param 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!
   * @param listener
   *    a <code>TableListener</code> that is called with {@link TableEvent}
   *    objects when an error occured, new rows have been retrieved, or when
   *    the table has been retrieved completely.
   * @param userObject
   *    an user object that is transparently supplied to the above call back.
   * @param lowerBoundIndex
   *    an optional parameter that specifies the lower bound index.
   *    If not <code>null</code>, all returned rows have an index greater than
   *    <code>lowerBoundIndex</code>.
   * @param upperBoundIndex
   *    an optional parameter that specifies the upper bound index.
   *    If not <code>null</code>, all returned rows have an index less or equal
   *    than <code>lowerBoundIndex</code>.
   */
  public void getTable(Target target,
                       OID[] columnOIDs,
                       TableListener listener,
                       Object userObject,
                       OID lowerBoundIndex,
                       OID upperBoundIndex) {
    if ((columnOIDs == null) || (columnOIDs.length == 0)) {
      throw new IllegalArgumentException("No column OIDs specified");
    }
    TableRequest req = new TableRequest(target, columnOIDs, listener,
                                        userObject,
                                        lowerBoundIndex,
                                        upperBoundIndex);
    req.sendNextChunk();
  }

  /**
   * 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.
   * <p>
   * 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.
   * </p>
   *
   * @param target
   *    a <code>Target</code> instance.
   * @param 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!
   * @param listener
   *    a <code>TableListener</code> that is called with {@link TableEvent}
   *    objects when an error occured, new rows have been retrieved, or when
   *    the table has been retrieved completely.
   * @param userObject
   *    an user object that is transparently supplied to the above call back.
   * @param lowerBoundIndex
   *    an optional parameter that specifies the lower bound index.
   *    If not <code>null</code>, all returned rows have an index greater than
   *    <code>lowerBoundIndex</code>.
   * @param upperBoundIndex
   *    an optional parameter that specifies the upper bound index.
   *    If not <code>null</code>, all returned rows have an index less or equal
   *    than <code>lowerBoundIndex</code>.
   * @since 1.5
   */
  public void getDenseTable(Target target,
                            OID[] columnOIDs,
                            TableListener listener,
                            Object userObject,
                            OID lowerBoundIndex,
                            OID upperBoundIndex) {
    if ((columnOIDs == null) || (columnOIDs.length == 0)) {
      throw new IllegalArgumentException("No column OIDs specified");
    }
    TableRequest req = new TableRequest(target, columnOIDs, listener,
                                        userObject,
                                        lowerBoundIndex,
                                        upperBoundIndex);
    req.sendNextChunk();
  }


  /**
   * Gets the maximum number of rows that will be retrieved per SNMP GETBULK
   * request.
   *
   * @return
   *    an integer greater than zero that specifies the maximum number of rows
   *    to retrieve per SNMP GETBULK operation.
   */
  public int getMaxNumRowsPerPDU() {
    return maxNumOfRowsPerPDU;
  }

  /**
   * Sets the maximum number of rows that will be retrieved per SNMP GETBULK
   * request. The default is 10.
   *
   * @param numberOfRowsPerChunk
   *    an integer greater than zero that specifies the maximum number of rows
   *    to retrieve per SNMP GETBULK operation.
   */
  public void setMaxNumRowsPerPDU(int numberOfRowsPerChunk) {
    if (numberOfRowsPerChunk < 1) {
      throw new IllegalArgumentException("The number of rows per PDU must be > 0");
    }
    this.maxNumOfRowsPerPDU = numberOfRowsPerChunk;
  }

  /**
   * Gets the maximum number of columns that will be retrieved per SNMP GETNEXT
   * or GETBULK request.
   *
   * @return
   *    an integer greater than zero that specifies the maximum columns of rows
   *    to retrieve per SNMP GETNEXT or GETBULK operation.
   */
  public int getMaxNumColumnsPerPDU() {
    return maxNumColumnsPerPDU;
  }

  /**
   * Sets the maximum number of columns that will be retrieved per SNMP GETNEXT
   * or GETBULK request. The default is 10.
   *
   * @param numberOfColumnsPerChunk
   *    an integer greater than zero that specifies the maximum columns of rows
   *    to retrieve per SNMP GETNEXT or GETBULK operation.
   */
  public void setMaxNumColumnsPerPDU(int numberOfColumnsPerChunk) {
    if (numberOfColumnsPerChunk < 1) {
      throw new IllegalArgumentException("The number of columns per PDU must be > 0");
    }
    this.maxNumColumnsPerPDU = numberOfColumnsPerChunk;
  }

  class TableRequest implements ResponseListener {

    Target target;
    OID[] columnOIDs;
    TableListener listener;
    Object userObject;
    OID lowerBoundIndex;
    OID upperBoundIndex;

    private int sent = 0;
    private Vector lastSent = null;
    private LinkedList rowCache = new LinkedList();
    protected Vector lastReceived;

    volatile boolean finished = false;

    protected TableRequest(Target target,
                           OID[] columnOIDs,
                           TableListener listener,
                           Object userObject,
                           OID lowerBoundIndex,
                           OID upperBoundIndex) {
      this.target = target;
      this.columnOIDs = columnOIDs;
      this.listener = listener;
      this.userObject = userObject;
      this.lastReceived = new Vector(Arrays.asList(columnOIDs));
      this.upperBoundIndex = upperBoundIndex;
      this.lowerBoundIndex = lowerBoundIndex;
      if (lowerBoundIndex != null) {
        for (int i=0; i<lastReceived.size(); i++) {
          OID oid = new OID(((OID) lastReceived.get(i)));
          oid.append(lowerBoundIndex);
          lastReceived.set(i, oid);
        }
      }
    }

    public boolean sendNextChunk() {
      if (sent >= lastReceived.size()) {
        return false;
      }
      PDU pdu = pduFactory.createPDU(target);
      if (target.getVersion() == SnmpConstants.version1) {
        pdu.setType(PDU.GETNEXT);
      }
      else {
        pdu.setType(PDU.GETBULK);
      }
      int sz = Math.min(lastReceived.size() - sent, maxNumColumnsPerPDU);
      if (pdu.getType() == PDU.GETBULK) {
        if (maxNumOfRowsPerPDU > 0) {
          pdu.setMaxRepetitions(maxNumOfRowsPerPDU);
          pdu.setNonRepeaters(0);
        }
        else {
          pdu.setNonRepeaters(sz);
          pdu.setMaxRepetitions(0);