com.sun.jaw.snmp.manager
Class SnmpRequest

java.lang.Object
  |
  +--com.sun.jaw.snmp.manager.Request
        |
        +--com.sun.jaw.snmp.manager.SnmpRequest
Direct Known Subclasses:
SnmpPollRequest

public class SnmpRequest
extends Request
implements java.io.Serializable, SnmpDefinitions

This class creates a request that is used to perform one or more SNMP operations such as Get, GetNext, Set, and GetBulk on a specified SnmpVarbindList.

This class provides basic functions that enable you to fire requests, handle retrys, timeouts, and process responses from the agent. It then notifies the user upon completion of requests by invoking the callback interface implementation provided by the user.

The periodic polling functionality is implemented by SnmpPollRequest which inherits the functionalities of this class and fires the requests periodically.

An SnmpRequest can be created by the session object using one of the many convenience methods as stated in the SnmpManagerSrvIf interface class.

The peer object determines the destination of the request and controls what and how many SnmpVarbindLists to pack into a single request. For example, the protocol data units (PDU) packet size, the number of SnmpVarbindLists allowed in a packet, the peer address and port, the SnmpParameters and probably some flow control mechanism.

The session object provides resources such as which socket to use, the authentication mechanism, controlling all requests created by it, and finally the response to the user.

Each request can be configured with various options that influence how a request handles a correctable error situation. For example, SnmpTooBig error and snmpRspNoSuchName exception in SNMPv1 context.

Each request when ready to be sent, is assigned a unique identifier which help in identifying the request with matching responses to the protocol engine lying transparently underneath. The engine does the job of retrying the requests when the timer expires and calls the session when a timeout occurs after exhausting the retry counts.

When a user submits a request, it joins the pool of waiting requests waiting to be sent. When the request becomes ready to be sent, the underlying engine constructs a PDU packet and sends it out after starting the wait timer. The SnmpVarbindList, with a request can get multiplexed with a SnmpVarbindList of other requests (passing multiplexing rules). The responses will be de-multiplexed. The multiplex operation remains transparent to the user. A user can choose to disallow such multiplexing of certain specific requests by providing the options when the request is created. This may become necessary to optimize performance of certain requests.

An application can cancel one or more request at any time.

The request that are sent are automatically retried if a response does not arrive within a specified interval. If the agent responds with an error, the request object uses the options to determine what should be done.

The request object provides the method, waitForCompletion(long time), which enables a user to operate in a synchronous mode with a request. This is done by blocking the user thread for the desired time interval. The user thread gets notified whenever a request reaches completion independent of the status of response. If the user blocks on the session thread context an exception is thrown (you should not block the session thread).

A request becomes active when a user submits the request successfully. When any event happens that moves the request to the done state, the request becomes inactive. At any time, one or more requests active in a session can be cancelled.

See Also:
SnmpSession, SnmpVar, SnmpVarbindList, SnmpParameters, SnmpPeer, Serialized Form

Field Summary
protected  SnmpHandlerIf callback
          The user implementation of the callback interface for this session.
protected  int errorIndex
          The index in SnmpVarbindList that caused the exception.
protected  int errorStatus
          The error status associated with the response packet.
protected  int maxRepetitions
          The maxRepetitions field for the bulk operation.
protected  int nonRepeaters
          The nonRepeaters field for the bulk operation.
protected  SnmpSession session
          The session object associated with this request.
protected  SnmpPeer thePeer
          The peer object associated with this request.
protected  SnmpVarbindList varbindList
          This contains a list of SnmpVar objects for making the SNMP requests.
 
Fields inherited from class com.sun.jaw.snmp.manager.Request
retry, stAborted, stBase, stInProgress, stInternalError, stNeverUsed, stReceivedReply, stResultsAvailable, stTimeout, stWaitingForReply, stWaitingToSend, timeout
 
Method Summary
 boolean allowMultiplex()
          Checks to see if this request can be multiplexed with other requests.
 void cancelRequest()
          Cancels the active request and removes itself from polling list.
 void finalize()
          Sets all the references to the SnmpRequest object to null.
 boolean fixPduOnError()
          Returns true if the PDU should be fixed for recoverable error.
 boolean fixTooBigError()
          Returns true if request should be retried for SnmpTooBig error.
 int getCommand()
          Gets the SNMP command for this request.
 int getErrorIndex()
          Gets the index.
 int getErrorStatus()
          Gets the status associated with the SnmpVarbindList.
 int getMaxRetry()
          Gets the maximum number of retries before declaring that the peer is not responding.
 int getOptions()
          Gets the options set for this request.
 SnmpParameters getParam()
          Gets the session parameter object for this request.
 SnmpPeer getPeer()
          Gets the peer object for this request.
 SnmpVarbindList getRequestVbList()
          Gets the active SnmpVarbindList.
 SnmpVarbindList getResponseVbList()
          Gets the SnmpVarbindList that is the response obtained when an agent is queried.
 SnmpSession getSnmpSession()
          Gets the session object for this request.
 boolean isInternalRequest()
          Indicates if this request was created internally by the package to handle error conditions.
 void notifyClient()
          Notifies the registered client about the completion of an operation.
 void setOptions(int opt)
          Allows the user to configure the behavior of the request when certain errors occur, such as SnmpTooBig and optFixPduOnError.
static java.lang.String snmpErrorToString(int errcode)
          Returns the string representation of an error code.
 java.lang.String toString()
          Gives a status report of the request.
 boolean waitForCompletion(long time)
          Used in synchronous mode only.
 
Methods inherited from class com.sun.jaw.snmp.manager.Request
getAbsMaxTimeToWait, getAbsNextPollTime, getPollTimestamp, getRequestId, getRequestStatus, getRetryCount, initNewRequest, inProgress, isAborted, isResultAvailable
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

varbindList

protected SnmpVarbindList varbindList
This contains a list of SnmpVar objects for making the SNMP requests. A private copy of the user specified SnmpVarbindList is made by cloning the SnmpVarbindList to ensure that the user does not modify the SnmpVarbindList or the contents while the polling is in progress.
See Also:
SnmpVarbindList

errorStatus

protected int errorStatus
The error status associated with the response packet.

errorIndex

protected int errorIndex
The index in SnmpVarbindList that caused the exception.

thePeer

protected SnmpPeer thePeer
The peer object associated with this request.

session

protected SnmpSession session
The session object associated with this request.

callback

protected SnmpHandlerIf callback
The user implementation of the callback interface for this session.
See Also:
SnmpHandlerIf

nonRepeaters

protected int nonRepeaters
The nonRepeaters field for the bulk operation. This variable is used only for pduGetBulkRequestPdu.

maxRepetitions

protected int maxRepetitions
The maxRepetitions field for the bulk operation. This variable is used only for pduGetBulkRequestPdu.
Method Detail

getSnmpSession

public final SnmpSession getSnmpSession()
Gets the session object for this request.
Returns:
The session object for this request.

getPeer

public final SnmpPeer getPeer()
Gets the peer object for this request.
Returns:
The peer object for this request.

getParam

public final SnmpParameters getParam()
Gets the session parameter object for this request.
Returns:
The session parameter object for this request.

getCommand

public final int getCommand()
Gets the SNMP command for this request.
Returns:
The SNMP command for this request.

waitForCompletion

public final boolean waitForCompletion(long time)
                                throws SnmpStatusException
Used in synchronous mode only. Provides a hook that enables a synchronous operation on a previously sent request. Only one request can be in sync mode on a given thread. The thread that is blocked is notified when the request state reaches completion. The thread can be a session thread (when done from a callback) or a user thread. Internally the blocking mechanism happens differently. If a request is not active, the method returns immediately. The user must get the error status of the request to determine the exact status of request.
Parameters:
time - The amount of time to wait. Zero means block until complete.
Returns:
True if the request has completed, false if it is still active.
Throws:
SnmpStatusException - An error occurred while accessing a MIB node.

allowMultiplex

public final boolean allowMultiplex()
Checks to see if this request can be multiplexed with other requests. SnmpSet requests cannot be multiplexed. An already multiplexed request cannot be further multiplexed.
Returns:
True if request is allowed to be multiplexed; false otherwise.
Overrides:
allowMultiplex in class Request

toString

public java.lang.String toString()
Gives a status report of the request.
Returns:
The status report of the request.
Overrides:
toString in class Request

getErrorStatus

public final int getErrorStatus()
Gets the status associated with the SnmpVarbindList.
Returns:
The error status.

getErrorIndex

public final int getErrorIndex()
Gets the index.

NOTE: this value is equals to the errorIndex field minus 1.

Returns:
The error index.

getMaxRetry

public final int getMaxRetry()
Gets the maximum number of retries before declaring that the peer is not responding. SnmpSet operations are never retried.
Returns:
The maximum number of times a request should be retried.
Overrides:
getMaxRetry in class Request

setOptions

public final void setOptions(int opt)
Allows the user to configure the behavior of the request when certain errors occur, such as SnmpTooBig and optFixPduOnError. When carefully chosen, these can improve or degrade performance. This method can be set only when a request is inactive.
Parameters:
opt - The option as an integer.

getOptions

public final int getOptions()
Gets the options set for this request. Certain options are overridden.
Returns:
The options set for this request.

fixTooBigError

public boolean fixTooBigError()
Returns true if request should be retried for SnmpTooBig error.
Returns:
True if request should be retried for SnmpTooBig error; false otherwise.

fixPduOnError

public boolean fixPduOnError()
Returns true if the PDU should be fixed for recoverable error.
Returns:
True if pdu should be fixed for recoverable error; false otherwise.

getResponseVbList

public final SnmpVarbindList getResponseVbList()
Gets the SnmpVarbindList that is the response obtained when an agent is queried. It returns null value if the request is in progress. This ensures accidental manipulation does not occur when a request is progress. In case of any error, SnmpVarbindList is the copy of the original SnmpVarbindList at the time of making request.
Returns:
The SnmpVarbindList returned by the agent or the null value if request is in progress.

getRequestVbList

public final SnmpVarbindList getRequestVbList()
Gets the active SnmpVarbindList. The contents of it are not guaranteed to be constant when request is active. It is dangerous to modify when request is active.
Returns:
Probably the SnmpVarbindList when the request was fired.

cancelRequest

public final void cancelRequest()
Cancels the active request and removes itself from polling list. It then marks the session as inactive. This method is not synchronized.
Overrides:
cancelRequest in class Request

isInternalRequest

public boolean isInternalRequest()
Indicates if this request was created internally by the package to handle error conditions.
Returns:
True if this request was created internally; false otherwise.

notifyClient

public final void notifyClient()
Notifies the registered client about the completion of an operation. Just blindly execute notify whether someone is waiting.

finalize

public void finalize()
Sets all the references to the SnmpRequest object to null.
Overrides:
finalize in class java.lang.Object

snmpErrorToString

public static java.lang.String snmpErrorToString(int errcode)
Returns the string representation of an error code.
Parameters:
errcode - The error code as an integer.
Returns:
The error code as a string.