snmpinformrequest.java

Mobile 应用程序使用 Java Micro Edition (Java ME) 平台

/*
 * @(#)file      SnmpInformRequest.java
 * @(#)author    Sun Microsystems, Inc.
 * @(#)version   1.18
 * @(#)date      08/09/12
 *
 * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 */

package com.sun.jmx.snmp.daemon ;


// JAVA imports
//
import java.io.Serializable;
import java.net.InetAddress;
import java.util.Vector;
import java.util.Date;

// JMX imports
//
import com.sun.jmx.snmp.SnmpMessage;
import com.sun.jmx.snmp.SnmpVarBind;
import com.sun.jmx.snmp.SnmpPduFactory;
import com.sun.jmx.snmp.SnmpPduPacket;
import com.sun.jmx.snmp.SnmpPduRequest;
import com.sun.jmx.snmp.SnmpPduBulk;
import com.sun.jmx.snmp.SnmpDefinitions;
import com.sun.jmx.snmp.SnmpStatusException;
import com.sun.jmx.snmp.SnmpTooBigException;
import com.sun.jmx.snmp.SnmpVarBindList;
import com.sun.jmx.snmp.SnmpPdu;
import com.sun.jmx.snmp.SnmpPduRequestType;

// SNMP Runtime imports
//
import com.sun.jmx.trace.Trace;


/**
 * This class is used by the {@link com.sun.jmx.snmp.daemon.SnmpAdaptorServer SNMP adaptor server} to send inform requests
 * to an SNMP manager and receive inform responses.
 * <P>
 * This class provides basic functions that enable you to fire inform requests,
 * handle retries, timeouts, and process responses from the manager.
 * <BR>
 * The SNMP adaptor server specifies the destination of the inform request and controls
 * the size of a single inform request/response to fit into its <CODE>bufferSize</CODE>.
 * It specifies the maximum number of tries and the timeout to be used for the inform requests.
 * It also provides resources such as the authentication mechanism (using its PDU factory), 
 * controlling all inform requests created by it, and finally the inform response to the user.
 * <P>
 * Each inform request, when ready to be sent, is assigned a unique identifier which helps
 * in identifying the inform request with matching inform responses to the protocol engine 
 * lying transparently underneath. The engine does the job of retrying the inform requests
 * when the timer expires and calls the SNMP adaptor server when a timeout occurs after exhausting 
 * the maximum number of tries.
 * <P>
 * The inform request object provides the method, {@link #waitForCompletion waitForCompletion(long time)},
 * which enables a user to operate in a synchronous mode with an inform request.
 * This is done by blocking the user thread for the desired time interval.
 * The user thread gets notified whenever a request reaches completion, independently of the status of the response. 
 * <P>
 * If an {@link com.sun.jmx.snmp.daemon.SnmpInformHandler inform callback} is provided when sending the inform request,
 * the user operates in an asynchronous mode with the inform request. The user thread is not blocked
 * and the specific inform callback implementation provided by the user is invoked when the inform response is received.
 *
 * <P>
 * <B>Note:</B>
 * <BR>From RFC 1905, the SNMP inform request is defined as a request generated and transmitted
 * by an SNMPv2 entity acting in a manager role to another SNMPv2 entity also acting in a manager role.
 * The mechanisms to implement this behaviour are defined in the SNMP manager API.
 * <BR>
 * Nevertheless, this feature has derived and in some documentations, the inform request appears
 * like an SNMPv2 trap that gets responded.
 * <BR>The <CODE>SnmpInformRequest</CODE> class is used to fullfill this latter case.
 * <p><b>This API is a Sun Microsystems internal API  and is subject 
 * to change without notice.</b></p>
 */

public class SnmpInformRequest implements SnmpDefinitions {
    
    // VARIABLES
    //----------
      
    /**
     * This object maintains a global counter for the inform request ID.
     */
    private static SnmpRequestCounter requestCounter = new SnmpRequestCounter();
    
    /**
     * This contains a list of <CODE>SnmpVarBind</CODE> objects for making the SNMP inform requests.
     */
    private SnmpVarBindList varBindList = null;
    
    /**
     * The error status associated with the inform response packet.
     */
    int errorStatus = 0;	
    
    /**
     * The index in <CODE>SnmpVarBindList</CODE> that caused the exception.
     */
    int errorIndex = 0;	
    
    //private SnmpVarBind internalVarBind[] = null;
    SnmpVarBind internalVarBind[] = null;

    //private String reason = null;
    String reason = null;
        
    /**
     * The SNMP adaptor associated with this inform request.
     */
    private transient SnmpAdaptorServer adaptor;
        
    /**
     * The session object associated with this inform request.
     */
    private transient SnmpSession informSession;
        
    /**
     * The user implementation of the callback interface for this request.
     */
    private SnmpInformHandler callback = null;
        
    /**
     * The inform request PDU.
     */
    //private SnmpPduPacket requestPdu;
    SnmpPdu requestPdu;

    /**
     * The inform response PDU.
     */
    //private SnmpPduRequest responsePdu;
    SnmpPduRequestType responsePdu;
    
    /**
     * Base status of an inform request.
     */
    final static private int stBase             = 1;
    
    /**
     * Status of an inform request: in progress.
     */
    final static public int stInProgress 		= stBase;
  
    /**
     * Status of an inform request: waiting to be sent.
     */
    final static public int stWaitingToSend 	= (stBase << 1) | stInProgress;
  
    /**
     * Status of an inform request: waiting for reply.
     */
    final static public int stWaitingForReply 	= (stBase << 2) | stInProgress;
  
    /**
     * Status of an inform request: reply received.
     */
    final static public int stReceivedReply 	= (stBase << 3) | stInProgress;
  
    /**
     * Status of an inform request: request aborted.
     */
    final static public int stAborted 			= (stBase << 4);
  
    /**
     * Status of an inform request: timeout.
     */
    final static public int stTimeout 			= (stBase << 5);
  
    /**
     * Status of an inform request: internal error occured.
     */
    final static public int stInternalError 	= (stBase << 6);
  
    /**
     * Status of an inform request: result available for the request.
     */
    final static public int stResultsAvailable 	= (stBase << 7);
  
    /**
     * Status of an inform request: request never used.
     */
    final static public int stNeverUsed 		= (stBase << 8);
        
    /**
     * Number of tries performed for the current polling operation.
     */
    private int numTries = 0;

    /**
     * Timeout.
     * The default amount of time is 3000 millisec.
     */
    private int timeout = 3 * 1000; // 3 seconds.

    /**
     */
    private int reqState = stNeverUsed;

    // Polling control parameters.
    private long  prevPollTime = 0;	// value of 0 means poll never happened.
    private long  nextPollTime = 0;
    private long  waitTimeForResponse;
    private Date debugDate = new Date();

    /**
     * The request ID for an active inform request.
     */
    private int requestId = 0;	
    
    private int port = 0;

    private InetAddress address = null;
    private String communityString = null;
    
    String dbgTag = "SnmpInformRequest";
    
    // CONSTRUCTORS
    //-------------

    /**
     * For SNMP Runtime internal use only.
     * Constructor for creating new inform request. This object can be created only by an SNMP adaptor object. 
     * @param session <CODE>SnmpSession</CODE> object for this inform request.
     * @param adp <CODE>SnmpAdaptorServer</CODE> object for this inform request.
     * @param addr The <CODE>InetAddress</CODE> destination for this inform request.
     * @param cs The community string to be used for the inform request.
     * @param requestCB Callback interface for the inform request.
     * @exception SnmpStatusException SNMP adaptor is not ONLINE or session is dead.
     */
    SnmpInformRequest(SnmpSession session, 
		      SnmpAdaptorServer adp, 
		      InetAddress addr, 
		      String cs, 
		      int p,
		      SnmpInformHandler requestCB) 
        throws SnmpStatusException {
        
        informSession = session;
        adaptor = adp;
        address = addr;
        communityString = cs;
	port = p;
        callback = requestCB;
        informSession.addInformRequest(this);  // add to adaptor queue.
        setTimeout(adaptor.getTimeout()) ;
    }

    // PUBLIC METHODS
    //---------------

    /**
     * Gets the request id (invoke identifier) of the current inform request.
     * @return The request id.
     */
    final public synchronized int getRequestId () {
        return requestId;
    }

    /**
     * Gets the destination address of the current inform request.
     * @return The destination address.
     */
    synchronized InetAddress getAddress() {
        return address;
    }

    /**
     * Gets the current status of the inform request.
     * @return The current status of the inform request.
     */
    final public synchronized int getRequestStatus() {
        return reqState ;
    }
    
    /**
     * Indicates whether or not the inform request was aborted.
     * @return <CODE>true</CODE> if the inform request was aborted, <CODE>false</CODE> otherwise.
     */
    final public synchronized boolean isAborted() {
        return ((reqState & stAborted) == stAborted);
    }

    /**
     * Indicates whether or not the inform request is in progress.
     * @return <CODE>true</CODE> if the inform request is in progress, <CODE>false</CODE> otherwise.
     */
    final public synchronized boolean inProgress() {
        return ((reqState & stInProgress) == stInProgress);
    }

    /**
     * Indicates whether or not the inform request result is available.
     * @return <CODE>true</CODE> if the inform request result is available, <CODE>false</CODE> otherwise.
     */
    final public synchronized boolean isResultAvailable() {
        return (reqState == stResultsAvailable);
    }
    
    /**
     * Gets the status associated with the <CODE>SnmpVarBindList</CODE>.
     * @return The error status.
     */
    final public synchronized int getErrorStatus() {
        return errorStatus;
    }

    /**
     * Gets the index.
     * <P>NOTE: this value is equal to the <CODE>errorIndex</CODE> field minus 1. 
     * @return The error index.
     */
    final public synchronized int getErrorIndex() {
        return errorIndex;
    }

    /**
     * Gets the maximum number of tries before declaring that the manager is not responding.
     * @return The maximum number of times an inform request should be tried.
     */
    final public int getMaxTries() {
        return adaptor.getMaxTries();
    }
    
    /**
     * Gets the number of tries performed for the current inform request.
     * @return The number of tries performed.
     */
    final public synchronized int getNumTries() {
        return numTries ;
    }
    
    /**
     * For SNMP Runtime internal use only.
     */
    final synchronized void setTimeout(int value) {
        timeout = value ;
    }
    
    /**
     * Gets absolute time in milliseconds (based on epoch time) when the next
     * polling activity will begin.
     * @return The absolute time when polling will begin.
     */
    final public synchronized long getAbsNextPollTime () {
        return nextPollTime ;
    }
    
    /**
     * Gets absolute time in milliseconds (based on epoch time) before which an inform
     * response is expected from a manager.
     * @return The absolute time within which an inform response is expected.
     */
    final public synchronized long getAbsMaxTimeToWait() {
        if (prevPollTime == 0) {
            return System.currentTimeMillis() ;  // should never happen.
        } else {
            return waitTimeForResponse ;
        }
    }
    
    /**
     * Gets the <CODE>SnmpVarBindList</CODE> of the inform response.
     * It returns a null value if the inform request is in progress. 
     * This ensures accidental manipulation does not occur when a request is in progress. 
     * In case of an error, <CODE>SnmpVarBindList</CODE> is the copy 
     * of the original <CODE>SnmpVarBindList</CODE> at the time of making the inform request.
     * @return The list of <CODE>SnmpVarBind</CODE> objects returned by the manager or the null value if the request
     * is in progress.
     */
    public final synchronized SnmpVarBindList getResponseVarBindList() {
        if (inProgress())
            return null;
        return varBindList;
    }
            
    /**
     * Used in synchronous mode only.
     * Provides a hook that enables a synchronous operation on a previously sent inform request.
     * Only one inform request can be in synchronous mode on a given thread.
     * The blocked thread is notified when the inform request state reaches completion. 
     * If the inform request is not active, the method returns immediately.
     * The user must get the error status of the inform request to determine the
     * exact status of the request.
     * 
     * @param time The amount of time to wait. Zero means block until complete.
     * @return <CODE>true</CODE> if the inform request has completed, <CODE>false</CODE> if it is still active.
     */
    final public boolean waitForCompletion(long time) {
        
        if (! inProgress())     // check if request is in progress.
            return true;

        if (informSession.thisSessionContext()) {
            // We can manipulate callback safely as we are in session thread.
            //