snmp.java

snmp4j 1.8.2版 The org.snmp4j classes are capable of creating, sending, and receiving SNMPv1/v2c/v3

   */
  public void setLocalEngine(byte[] engineID,
                             int engineBoots,
                             int engineTime) {
    MPv3 mpv3 = getMPv3();
    mpv3.setLocalEngineID(engineID);
    USM usm = (USM) mpv3.getSecurityModel(SecurityModel.SECURITY_MODEL_USM);
    usm.setLocalEngine(new OctetString(engineID), engineBoots, engineTime);
  }

  /**
   * Gets the local engine ID if the MPv3 is available, otherwise a runtime
   * exception is thrown.
   * @return byte[]
   *    the local engine ID.
   */
  public byte[] getLocalEngineID() {
    return getMPv3().getLocalEngineID();
  }

  private MPv3 getMPv3() {
    MPv3 mpv3 = (MPv3) getMessageProcessingModel(MessageProcessingModel.MPv3);
    if (mpv3 == null) {
      throw new NoSuchElementException("MPv3 not available");
    }
    return mpv3;
  }

  /**
   * Discovers the engine ID of the SNMPv3 entity denoted by the supplied
   * address. This method does not need to be called for normal operation,
   * because SNMP4J automatically discovers authoritative engine IDs and
   * also automatically synchronize engine time values.
   * <p>
   * <em>For this method to operate succesfully, the discover engine IDs
   * flag in {@link USM} must be <code>true</code> (which is the default).
   * </em>
   * @param address
   *    an Address instance representing the transport address of the SNMPv3
   *    entity for which its authoritative engine ID should be discovered.
   * @param timeout
   *    the maximum time in milliseconds to wait for a response.
   * @return
   *    a byte array containing the authoritative engine ID or <code>null</code>
   *    if it could not be discovered.
   * @see USM#setEngineDiscoveryEnabled(boolean enableEngineDiscovery)
   */
  public byte[] discoverAuthoritativeEngineID(Address address, long timeout) {
    MPv3 mpv3 = getMPv3();
    // We need to remove the engine ID explicitly to be sure that it is updated
    OctetString engineID = mpv3.removeEngineID(address);
    // Now try to remove the engine as well
    if (engineID != null) {
      USM usm = getUSM();
      if (usm != null) {
        usm.removeEngineTime(engineID);
      }
    }
    ScopedPDU scopedPDU = new ScopedPDU();
    scopedPDU.setType(PDU.GET);
    SecureTarget target = new UserTarget();
    target.setTimeout(timeout);
    target.setAddress(address);
    try {
      send(scopedPDU, target);
      OctetString authoritativeEngineID = mpv3.getEngineID(address);
      if (authoritativeEngineID == null) {
        return null;
      }
      // we copy the byte array here, so we are sure nobody can modify the
      // internal cache.
      return new OctetString(authoritativeEngineID.getValue()).getValue();
    }
    catch (IOException ex) {
      logger.error(
          "IO error while trying to discover authoritative engine ID: " +
          ex);
      return null;
    }
  }

  /**
   * Gets the User Based Security Model (USM). This is a convenience method
   * that uses the <code>SecurityModels</code> singleton to get the USM.
   * @return
   *    an <code>USM</code> instance if available in the current SNMP4J
   *    configuration, <code>null</code> otherwise.
   */
  public USM getUSM() {
    return (USM) SecurityModels.getInstance().getSecurityModel(
        new Integer32(SecurityModel.SECURITY_MODEL_USM));
  }

  /**
   * Gets the message processing model for the supplied ID.
   * @param messageProcessingModel
   *    a mesage processing model ID as defined in {@link MessageProcessingModel}.
   * @return MessageProcessingModel
   *    a <code>MessageProcessingModel</code> if
   *    <code>messageProcessingModel</code> has been registered with the
   *    message dispatcher associated with this SNMP session.
   */
  public MessageProcessingModel getMessageProcessingModel(int
      messageProcessingModel) {
    return messageDispatcher.getMessageProcessingModel(messageProcessingModel);
  }

  /**
   * Process an incoming request or notification PDU.
   *
   * @param event
   *   a <code>CommandResponderEvent</code> with the decoded incoming PDU as
   *   dispatched to this method call by the associated message dispatcher.
   */
  public void processPdu(CommandResponderEvent event) {
    PduHandle handle = event.getPduHandle();
    PDU pdu = event.getPDU();
    if (pdu.getType() == PDU.RESPONSE) {
      event.setProcessed(true);
      PendingRequest request;
      if (logger.isDebugEnabled()) {
        logger.debug("Looking up pending request with handle " + handle);
      }
      request = (PendingRequest) pendingRequests.get(handle);
      if (request == null) {
        if (logger.isWarnEnabled()) {
          logger.warn("Received response that cannot be matched to any " +
                      "outstanding request, address=" +
                      event.getPeerAddress() +
                      ", requestID=" + pdu.getRequestID());
        }
      }
      if (request == null) {
        logger.warn("Received response that cannot be matched to any " +
                    "outstanding request, address=" +
                    event.getPeerAddress() +
                    ", requestID=" + pdu.getRequestID());
      }
      else {
        request.listener.onResponse(new ResponseEvent(this,
            event.getPeerAddress(),
            request.pdu,
            pdu,
            request.userObject));
      }
    }
    else if (pdu.getType() == PDU.REPORT) {
      event.setProcessed(true);
      reportHandler.processReport(handle, event);
    }
    else {
      if (logger.isDebugEnabled()) {
        logger.debug("Fire process PDU event: " + event.toString());
      }
      fireProcessPdu(event);
    }
  }

  class ReportProcessor implements ReportHandler {

    public void processReport(PduHandle handle, CommandResponderEvent e) {
      PDU pdu = e.getPDU();
      logger.debug("Searching pending request with handle" + handle);
      PendingRequest request = (PendingRequest) pendingRequests.get(handle);
      if (request == null) {
        logger.warn("Unmatched report PDU received from " + e.getPeerAddress());
        return;
      }
      if (pdu.size() == 0) {
        logger.error("Illegal report PDU received from " + e.getPeerAddress() +
                     " missing report variable binding");
        return;
      }
      VariableBinding vb = pdu.get(0);
      if (vb == null) {
        logger.error("Received illegal REPORT PDU from " + e.getPeerAddress());
        return;
      }
      OID firstOID = vb.getOid();
      boolean resend = false;
      if (request.requestStatus < request.maxRequestStatus) {
        switch (request.requestStatus) {
          case 0:
            if (SnmpConstants.usmStatsUnknownEngineIDs.equals(firstOID)) {
              resend = true;
            }
            else if (SnmpConstants.usmStatsNotInTimeWindows.equals(firstOID)) {
              request.requestStatus++;
              resend = true;
            }
            break;
          case 1:
            if (SnmpConstants.usmStatsNotInTimeWindows.equals(firstOID)) {
              resend = true;
            }
            break;
        }
      }
      // if legal report PDU received, then resend request
      if (resend) {
        logger.debug("Send new request after report.");
        request.requestStatus++;
        try {
          // We need no callback here because we already have an equivalent
          // handle registered.
          PduHandle resentHandle =
              sendMessage(request.pdu, request.target, e.getTransportMapping(),
                          null);
          // make sure reference to handle is hold until request is finished,
          // because otherwise cache information may get lost (WeakHashMap)
          request.key = resentHandle;
        }
        catch (IOException iox) {
          logger.error("Failed to send message to " + request.target + ": " +
                       iox.getMessage());
          return;
        }
      }
      else {
        boolean intime;
        synchronized (request) {
          intime = request.cancel();
        }
        // remove pending request
        // (sync is not needed as request is already canceled)
        pendingRequests.remove(handle);
        if (intime) {
          // return report
          request.listener.onResponse(new ResponseEvent(this,
              e.getPeerAddress(),
              request.pdu,
              pdu,
              request.userObject));
        }
        else {
          // silently drop late report
          if (logger.isInfoEnabled()) {
            logger.info("Received late report from " +
                        e.getPeerAddress() +
                        " with request ID " + pdu.getRequestID());
          }
        }
      }
    }
  }


  /**
   * Removes a <code>CommandResponder</code> from this SNMP session.
   * @param listener
   *    a previously added <code>CommandResponder</code> instance.
   */
  public synchronized void removeCommandResponder(CommandResponder listener) {
    if (commandResponderListeners != null &&
        commandResponderListeners.contains(listener)) {
      Vector v = (Vector) commandResponderListeners.clone();
      v.removeElement(listener);
      commandResponderListeners = v;
    }
  }

  /**
   * Adds a <code>CommandResponder</code> to this SNMP session.
   * The command responder will then be informed about incoming SNMP PDUs of
   * any kind that are not related to any outstanding requests of this SNMP
   * session.
   *
   * @param listener
   *    the <code>CommandResponder</code> instance to be added.
   */
  public synchronized void addCommandResponder(CommandResponder listener) {
    Vector v = (commandResponderListeners == null) ?
        new Vector(2) : (Vector) commandResponderListeners.clone();
    if (!v.contains(listener)) {
      v.addElement(listener);
      commandResponderListeners = v;
    }
  }

  /**
   * Fires a <code>CommandResponderEvent</code> event to inform listeners about
   * a received PDU. If a listener has marked the event as processed further
   * listeners will not be informed about the event.
   * @param event
   *    a <code>CommandResponderEvent</code>.
   */
  protected void fireProcessPdu(CommandResponderEvent event) {
    if (commandResponderListeners != null) {
      Vector listeners = commandResponderListeners;
      int count = listeners.size();
      for (int i = 0; i < count; i++) {
        ((CommandResponder) listeners.elementAt(i)).processPdu(event);
        // if event is marked as processed the event is not forwarded to
        // remaining listeners
        if (event.isProcessed()) {
          return;
        }
      }
    }
  }

  /**
   * Gets the timeout model associated with this SNMP session.
   * @return
   *    a TimeoutModel instance (never <code>null</code>).
   * @see #setTimeoutModel(TimeoutModel timeoutModel)
   */
  public TimeoutModel getTimeoutModel() {
    return timeoutModel;
  }

  /**
   * Returns the report handler which is used internally to process reports
   * received from command responders.
   * @return
   *    the <code>ReportHandler</code> instance.
   * @since 1.6
   */
  public ReportHandler getReportHandler() {
    return reportHandler;
  }

  /**
   * Sets the timeout model for this SNMP session. The default timeout model
   * sends retries whenever the time specified by the <code>timeout</code>
   * parameter of the target has elapsed without a response beeing received for
   * the request. By specifying a different timeout model this behaviour can
   * be changed.
   * @param timeoutModel
   *    a <code>TimeoutModel</code> instance (must not be <code>null</code>).
   */