snmp.java

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

  public void trap(PDUv1 pdu, Target target) throws IOException {
    if (target.getVersion() != SnmpConstants.version1) {
      throw new IllegalArgumentException(
          "SNMPv1 trap PDU must be used with SNMPv1");
    }
    pdu.setType(PDU.V1TRAP);
    send(pdu, target);
  }

  /**
   * Sends a SNMPv2c or SNMPv3 notification to a target. This method sets the
   * PDU's type to {@link PDU#NOTIFICATION} and then sends it to the supplied
   * target. This method is a convenience wrapper for the
   * {@link #send(PDU pdu, Target target)} method.
   * @param pdu
   *    a <code>PDUv1</code> instance.
   * @param target
   *    the Target instance representing the target SNMP engine where to send
   *    the <code>pdu</code>. The selected SNMP protocol version for the
   *    target must be {@link SnmpConstants#version2c} or
   *    {@link SnmpConstants#version2c}.
   * @throws IOException
   *    if the notification cannot be sent.
   * @since 1.1
   */
  public void notify(PDU pdu, Target target) throws IOException {
    if (target.getVersion() == SnmpConstants.version1) {
      throw new IllegalArgumentException(
          "Notifications PDUs cannot be used with SNMPv1");
    }
    pdu.setType(PDU.NOTIFICATION);
    send(pdu, target);
  }


  /**
   * Sends a SET request to a target. This method sets the PDU's type to
   * {@link PDU#SET} and then sends a synchronous request to the supplied
   * target.
   * @param pdu
   *    a <code>PDU</code> instance. For SNMPv3 messages, the supplied PDU
   *    instance has to be a <code>ScopedPDU</code> instance.
   * @param target
   *    the Target instance representing the target SNMP engine where to send
   *    the <code>pdu</code>.
   * @return
   *    the received response encapsulated in a <code>ResponseEvent</code>
   *    instance. To obtain the received response <code>PDU</code> call
   *    {@link ResponseEvent#getResponse()}. If the request timed out,
   *    that method will return <code>null</code>.
   * @since 1.1
   */
  public ResponseEvent set(PDU pdu, Target target) {
    pdu.setType(PDU.SET);
    try {
      return send(pdu, target);
    }
    catch (IOException ex) {
      return new ResponseEvent(this, null, pdu, null, target, ex);
    }
  }

  /**
   * Asynchronously sends a SET request <code>PDU</code> to the given target.
   * The response is then returned by calling the supplied
   * <code>ResponseListener</code> instance.
   *
   * @param pdu
   *    the PDU instance to send.
   * @param target
   *    the Target instance representing the target SNMP engine where to send
   *    the <code>pdu</code>.
   * @param userHandle
   *    an user defined handle that is returned when the request is returned
   *    via the <code>listener</code> object.
   * @param listener
   *    a <code>ResponseListener</code> instance that is called when
   *    <code>pdu</code> is a confirmed PDU and the request is either answered
   *    or timed out.
   * @throws IOException
   *    if the PDU cannot be sent to the target.
   * @since 1.1
   */
  public void set(PDU pdu, Target target, Object userHandle,
                  ResponseListener listener) throws IOException {
    pdu.setType(PDU.SET);
    send(pdu, target, userHandle, listener);
  }

  public ResponseEvent send(PDU pdu, Target target) throws IOException {
    return send(pdu, target, null);
  }

  /**
   * Sends a <code>PDU</code> to the given target and if the <code>PDU</code>
   * is a confirmed request, then the received response is returned
   * synchronously.
   * @param pdu
   *    a <code>PDU</code> instance. When sending a SNMPv1 trap PDU, the
   *    supplied PDU instance must be a <code>PDUv1</code>. For all types of
   *    SNMPv3 messages, the supplied PDU instance has to be a
   *    <code>ScopedPDU</code> instance.
   * @param target
   *    the Target instance representing the target SNMP engine where to send
   *    the <code>pdu</code>.
   * @param transport
   *    specifies the <code>TransportMapping</code> to be used when sending
   *    the PDU. If <code>transport</code> is <code>null</code>, the associated
   *    message dispatcher will try to determine the transport mapping by the
   *    <code>target</code>'s address.
   * @return
   *    the received response encapsulated in a <code>ResponseEvent</code>
   *    instance. To obtain the received response <code>PDU</code> call
   *    {@link ResponseEvent#getResponse()}. If the request timed out,
   *    that method will return <code>null</code>. If the sent <code>pdu</code>
   *    is an unconfirmed PDU (notification, response, or report), then
   *    <code>null</code> will be returned.
   * @throws IOException
   *    if the message could not be sent.
   * @see PDU
   * @see ScopedPDU
   * @see PDUv1
   */
  public ResponseEvent send(PDU pdu, Target target,
                            TransportMapping transport) throws IOException {
    if (!pdu.isConfirmedPdu()) {
      sendMessage(pdu, target, transport, null);
      return null;
    }
    SyncResponseListener syncResponse = new SyncResponseListener();
    PendingRequest retryRequest = null;
    synchronized (syncResponse) {
      PduHandle handle = null;
      PendingRequest request =
          new PendingRequest(syncResponse, target, pdu, target, transport);
      handle = sendMessage(pdu, target, transport, request);
      try {
        syncResponse.wait();
        retryRequest = (PendingRequest) pendingRequests.remove(handle);
        if (logger.isDebugEnabled()) {
          logger.debug("Removed pending request with handle: "+handle);
        }
        request.setFinished();
        request.cancel();
      }
      catch (InterruptedException iex) {
        logger.warn(iex);
        // ignore
      }
    }
    if (retryRequest != null) {
      synchronized (retryRequest) {
        retryRequest.setFinished();
        retryRequest.cancel();
      }
    }
    return syncResponse.response;
  }

  public void send(PDU pdu, Target target,
                   Object userHandle,
                   ResponseListener listener) throws IOException {
    send(pdu, target, null, userHandle, listener);
  }

  public void send(PDU pdu, Target target,
                   TransportMapping transport,
                   Object userHandle,
                   ResponseListener listener) throws IOException {
    if (!pdu.isConfirmedPdu()) {
      sendMessage(pdu, target, transport, null);
      return;
    }
    PendingRequest request =
        new AsyncPendingRequest(listener, userHandle, pdu, target, transport);
    sendMessage(pdu, target, transport, request);
  }

  /**
   * Sends a <code>PDU</code> to the given target and returns the received
   * response <code>PDU</code>.
   * @param pdu
   *    a <code>PDU</code> instance. When sending a SNMPv1 trap PDU, the
   *    supplied PDU instance must be a <code>PDUv1</code>. For all types of
   *    SNMPv3 messages, the supplied PDU instance has to be a
   *    <code>ScopedPDU</code> instance.
   * @param target
   *    the Target instance representing the target SNMP engine where to send
   *    the <code>pdu</code>.
   * @return
   *    the received response <code>PDU</code> or <code>null</code>
   *    if the request timed out and if the PDU type of <code>pdu</code>
   *    is an unconfirmed PDU (i.e., trap or notification).
   * @throws IOException
   *    if the message could not be sent.
   * @see PDU
   * @see ScopedPDU
   * @see PDUv1
   * @deprecated This method has been deprecated because it does not return
   * the transport address of the entity (target) that sent the response.
   * Please use {@link #send(PDU pdu, Target target)} instead. It returns
   * a {@link ResponseEvent} object holding the response PDU and transport
   * address of a successfully received response. This method will be supported
   * until v2.0.
   */
  public PDU sendPDU(PDU pdu, Target target) throws IOException {
    ResponseEvent e = send(pdu, target);
    if (e != null) {
      return e.getResponse();
    }
    // pdu sent is unconfirmed one
    return null;
  }

  /**
   * Asynchronously sends a <code>PDU</code> to the given target. The response
   * is then returned by calling the supplied <code>ResponseListener</code>
   * instance.
   *
   * @param pdu
   *    the PDU instance to send.
   * @param target
   *    the Target instance representing the target SNMP engine where to send
   *    the <code>pdu</code>.
   * @param userHandle
   *    an user defined handle that is returned when the request is returned
   *    via the <code>listener</code> object.
   * @param listener
   *    a <code>ResponseListener</code> instance that is called when
   *    <code>pdu</code> is a confirmed PDU and the request is either answered
   *    or timed out.
   * @deprecated Please use {@link #send(PDU pdu, Target target, Object
   *    userHandle, ResponseListener listener)} instead. It has exactly
   *    the same function but follows the new naming scheme. This method
   *    will be supported until v2.0.
   * @throws IOException
   *    if the PDU could not be sent to the specified target.
   */
  public void sendPDU(PDU pdu,
                      Target target,
                      Object userHandle,
                      ResponseListener listener) throws IOException {
    send(pdu, target, userHandle, listener);
  }

  /**
   * Actually sends a PDU to a target and returns a handle for the sent PDU.
   * @param pdu
   *    the <code>PDU</code> instance to be sent.
   * @param target
   *    a <code>Target</code> instance denoting the target SNMP entity.
   * @param transport
   *    the (optional) transport mapping to be used to send the request.
   *    If <code>transport</code> is <code>null</code> a suitable transport
   *    mapping is determined from the <code>target</code> address.
   * @param pduHandleCallback
   *    callback for newly created PDU handles before the request is sent out.
   * @throws IOException
   *    if the transport fails to send the PDU or the if the message cannot
   *    be BER encoded.
   * @return PduHandle
   *    that uniquely identifies the sent PDU for further reference.
   */
  protected PduHandle sendMessage(PDU pdu, Target target,
                                  TransportMapping transport,
                                  PduHandleCallback pduHandleCallback)
      throws IOException
  {
    PduHandle handle = null;
    if (target instanceof SecureTarget) {
      SecureTarget secureTarget = (SecureTarget) target;
      handle = messageDispatcher.sendPdu(transport,
                                         secureTarget.getAddress(),
                                         secureTarget.getVersion(),
                                         secureTarget.getSecurityModel(),
                                         secureTarget.getSecurityName().
                                         getValue(),
                                         secureTarget.getSecurityLevel(),
                                         pdu, true, pduHandleCallback);
    }
    else if (target instanceof CommunityTarget) {
      CommunityTarget communityTarget = (CommunityTarget) target;
      int securityModel = SecurityModel.SECURITY_MODEL_SNMPv2c;
      if (communityTarget.getVersion() == SnmpConstants.version1) {
        securityModel = SecurityModel.SECURITY_MODEL_SNMPv1;
      }
      handle = messageDispatcher.sendPdu(transport,
                                         communityTarget.getAddress(),
                                         communityTarget.getVersion(),
                                         securityModel,
                                         communityTarget.getCommunity().
                                         getValue(),
                                         SecurityLevel.NOAUTH_NOPRIV,
                                         pdu, true, pduHandleCallback);

    }
    return handle;
  }

  public void cancel(PDU request, ResponseListener listener) {
    AsyncRequestKey key = new AsyncRequestKey(request, listener);
    PduHandle pending = (PduHandle) asyncRequests.remove(key);
    if (logger.isDebugEnabled()) {
      logger.debug("Cancelling pending request with handle " + pending);
    }
    if (pending != null) {
      PendingRequest pendingRequest =
          (PendingRequest) pendingRequests.remove(pending);
      if (pendingRequest != null) {
        synchronized (pendingRequest) {
          pendingRequest.setFinished();
          pendingRequest.cancel();
        }
      }
    }
  }

  /**
   * Sets the local engine ID for the SNMP entity represented by this
   * <code>Snmp</code> instance. This is a convenience method that sets
   * the local engine ID in the associated <code>MPv3</code> and
   * <code>USM</code>.
   * @param engineID
   *    a byte array containing the local engine ID. The length and content
   *    has to comply with the constraints defined in the SNMP-FRAMEWORK-MIB.
   * @param engineBoots
   *    the number of boots of this SNMP engine (zero based).
   * @param engineTime
   *    the number of seconds since the value of engineBoots last changed.
   * @see MPv3
   * @see USM