com.sun.management.snmp.manager
Class SnmpRequest

java.lang.Object
  com.sun.management.snmp.manager.SnmpRequest

All Implemented Interfaces:

SnmpDefinitions, Serializable

public class SnmpRequest
extends Object
implements Serializable, SnmpDefinitions

Creates a request that is used to perform one or more SNMP operations such as Get, GetNext, Set, Inform and GetBulk on a specified SnmpVarBindList.

This class provides basic functions that enable you to fire requests, handle retries, 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.

An SnmpRequest can be created by the session object.

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

The session object provides resources such as 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 the SNMPv1 context.

Each request, when ready to be sent, is assigned a unique identifier which helps 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 maximum number of tries.

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 be multiplexed with an 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 this 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 requests at any time.

The requests 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, independently of the status of the 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 an event happens that moves the request into the done state, the request becomes inactive. At any time, one or more requests active in a session can be canceled.

Since:

Java DMK 5.1

See Also:

SnmpSession, SnmpPeer, Serialized Form

Field Summary

static int	stAborted Status of a request: request aborted.
static int	stInProgress Status of a request: in progress.
static int	stInternalError Status of a request: internal error occurred.
static int	stNeverUsed Status of a request: request never used.
static int	stReceivedReply Status of a request: reply received.
static int	stResultsAvailable Status of a request: result available for the request.
static int	stTimeout Status of a request: timeout.
static int	stWaitingForReply Status of a request: waiting for reply.
static int	stWaitingToSend Status of a request: waiting to be sent.

Fields inherited from interface com.sun.management.snmp.SnmpDefinitions

authMask, authNoPriv, authPriv, authPrivMask, CtxtConsFlag, noAuthNoPriv, noGroupName, noSuchContext, noSuchView, notInView, pduGetBulkRequestPdu, pduGetNextRequestPdu, pduGetRequestPdu, pduGetResponsePdu, pduInformRequestPdu, pduReportPdu, pduSetRequestPdu, pduV1TrapPdu, pduV2TrapPdu, pduWalkRequest, privMask, reportableFlag, snmpAuthNotSupported, snmpBadSecurityLevel, snmpPrivNotSupported, snmpReqAborted, snmpReqEncodingError, snmpReqHandleTooBig, snmpReqInternalError, snmpReqPacketOverflow, snmpReqRefireAfterVbFix, snmpReqSocketIOError, snmpReqTimeout, snmpReqTooBigImpossible, snmpReqUnknownError, snmpRspAuthorizationError, snmpRspBadValue, snmpRspCommitFailed, snmpRspDecodingError, snmpRspEndOfTable, snmpRspGenErr, snmpRspInconsistentName, snmpRspInconsistentValue, snmpRspNoAccess, snmpRspNoCreation, snmpRspNoError, snmpRspNoSuchName, snmpRspNotWritable, snmpRspReadOnly, snmpRspResourceUnavailable, snmpRspTooBig, snmpRspUndoFailed, snmpRspWrongEncoding, snmpRspWrongLength, snmpRspWrongType, snmpRspWrongValue, snmpUnknownPrincipal, snmpUsmBadEngineId, snmpUsmInvalidTimeliness, snmpUsmSecurityModel, snmpV1AccessControlModel, snmpV1MsgProcessingModel, snmpV1SecurityModel, snmpV2AccessControlModel, snmpV2MsgProcessingModel, snmpV2SecurityModel, snmpV3AccessControlModel, snmpV3MsgProcessingModel, snmpVersionOne, snmpVersionThree, snmpVersionTwo, snmpWrongSnmpVersion, trapAuthenticationFailure, trapColdStart, trapEgpNeighborLoss, trapEnterpriseSpecific, trapLinkDown, trapLinkUp, trapWarmStart

Method Summary

boolean	allowMultiplex() Checks to see whether this request can be multiplexed with other requests.
void	cancelRequest() Cancels the active request and removes itself from the polling list.
boolean	fixPduOnError() Returns true if the PDU should be fixed for recoverable error.
boolean	fixTooBigError() Returns true if the request should be retried for SnmpTooBig error.
long	getAbsMaxTimeToWait() Gets absolute time in milliseconds (based on epoch time) before which a response is expected from an agent.
long	getAbsNextPollTime() Gets absolute time in milliseconds (based on epoch time) when the next polling activity will begin.
int	getCommand() Gets the SNMP command for this request.
int	getErrorIndex() Gets the index.
int	getErrorStatus() Gets the status associated with the SnmpVarBindList.
int	getMaxTries() Gets the maximum number of tries before declaring that the peer is not responding.
int	getNumTries() Gets the number of tries performed for the current request.
int	getOptions() Gets the options set for this request.
SnmpParams	getParams() Gets the session parameter object for this request.
SnmpPeer	getPeer() Gets the peer object for this request.
long	getPollTimestamp() Gets the absolute time (based on epoch time) when the poll started.
SnmpVarBindList	getReportVarBindList() Gets the report SnmpVarBindList.
int	getRequestId() Gets the request id (invoke identifier) of the current request.
int	getRequestStatus() Gets the current status of the request.
SnmpVarBindList	getRequestVarBindList() Gets the active SnmpVarBindList.
SnmpSecurityParameters	getResponseSecurityParameters() Gets the response security parameters info (e.g.
SnmpVarBindList	getResponseVarBindList() Gets the SnmpVarBindList that is the response obtained when an agent is queried.
SnmpSession	getSnmpSession() Gets the session object for this request.
boolean	inProgress() Indicates whether or not the request is in progress.
boolean	isAborted() Indicates whether or not the request was aborted.
boolean	isInternalRequest() Indicates whether this request was created internally by the package to handle error conditions.
boolean	isReport() Test if the received reply is an SNMP report.
boolean	isResponse() Test if the received reply is an SNMP response.
boolean	isResultAvailable() Indicates whether or not the request result is available.
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 String	snmpErrorToString(int errcode) Returns the String representation of an error code.
static String	statusDescription(int state) Returns the string state corresponding to the specified integer state.
String	toString() Gives a status report of the request.
boolean	waitForCompletion(long time) Used in synchronous mode only.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

stInProgress

public static final int stInProgress

Status of a request: in progress.

See Also:

Constant Field Values

stWaitingToSend

public static final int stWaitingToSend

Status of a request: waiting to be sent.

See Also:

Constant Field Values

stWaitingForReply

public static final int stWaitingForReply

Status of a request: waiting for reply.

See Also:

Constant Field Values

stReceivedReply

public static final int stReceivedReply

Status of a request: reply received.

See Also:

Constant Field Values

stAborted

public static final int stAborted

Status of a request: request aborted.

See Also:

Constant Field Values

stTimeout

public static final int stTimeout

Status of a request: timeout.

See Also:

Constant Field Values

stInternalError

public static final int stInternalError

Status of a request: internal error occurred.

See Also:

Constant Field Values

stResultsAvailable

public static final int stResultsAvailable

Status of a request: result available for the request.

See Also:

Constant Field Values

stNeverUsed

public static final int stNeverUsed

Status of a request: request never used.

See Also:

Constant Field Values

Method Detail

getNumTries

public final int getNumTries()

Gets the number of tries performed for the current request.

Returns:

The number of tries performed.

getRequestId

public final int getRequestId()

Gets the request id (invoke identifier) of the current request.

Returns:

The request id.

getRequestStatus

public final int getRequestStatus()

Gets the current status of the request.

Returns:

The current status of the request.

isAborted

public final boolean isAborted()

Indicates whether or not the request was aborted.

Returns:

true if the request was aborted, false otherwise.

inProgress

public final boolean inProgress()

Indicates whether or not the request is in progress.

Returns:

true if the request is in progress, false otherwise.

isResultAvailable

public final boolean isResultAvailable()

Indicates whether or not the request result is available.

Returns:

true if the request result is available, false otherwise.

getAbsNextPollTime

public final long getAbsNextPollTime()

Gets absolute time in milliseconds (based on epoch time) when the next polling activity will begin.

Returns:

The absolute time when polling will begin.

getAbsMaxTimeToWait

public final long getAbsMaxTimeToWait()

Gets absolute time in milliseconds (based on epoch time) before which a response is expected from an agent.

Returns:

The absolute time within which a response is expected.

getPollTimestamp

public final long getPollTimestamp()

Gets the absolute time (based on epoch time) when the poll started.

Returns:

The absolute time the polling started.

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.

getParams

public final SnmpParams getParams()

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.

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 equal to the errorIndex field minus 1.

Returns:

The error index.

getMaxTries

public final int getMaxTries()

Gets the maximum number of tries before declaring that the peer is not responding. SnmpSet operations are never retried.

Returns:

The maximum number of times a request should be tried.

getOptions

public final int getOptions()

Gets the options set for this request. Certain options are overridden.

Returns:

The options set for this 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. These should be carefully chosen, as they can improve or degrade performance. This method can only be set when a request is inactive.

Parameters:

opt - The option as an integer.

getRequestVarBindList

public final SnmpVarBindList getRequestVarBindList()

Gets the active SnmpVarBindList. The contents of it are not guaranteed to be consistent when the request is active. It is dangerous to modify when the request is active.

Returns:

The SnmpVarBindList when the request was fired.

getReportVarBindList

public final SnmpVarBindList getReportVarBindList()

Gets the report SnmpVarBindList. The contents of it are not guaranteed to be consistent when the request is active. It should be called if isReport() is true.

Returns:

The SnmpVarBindList received in the report.

getResponseVarBindList

public final SnmpVarBindList getResponseVarBindList()

Gets the SnmpVarBindList that is the response obtained when an agent is queried. It returns a null value if the request is in progress. This ensures accidental manipulation does not occur when a request is in progress. In case of an error, SnmpVarBindList is the copy of the original SnmpVarBindList at the time of making the request.

Returns:

The SnmpVarBindList returned by the agent or the null value if the request is in progress.

fixTooBigError

public boolean fixTooBigError()

Returns true if the request should be retried for SnmpTooBig error.

Returns:

true if the 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.

allowMultiplex

public final boolean allowMultiplex()

Checks to see whether this request can be multiplexed with other requests. SnmpSet requests cannot be multiplexed. A request already multiplexed cannot be further multiplexed.

Returns:

true if the request is allowed to be multiplexed, false otherwise.

isInternalRequest

public boolean isInternalRequest()

Indicates whether this request was created internally by the package to handle error conditions.

Returns:

true if this request was created internally, false otherwise.

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 the 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.

cancelRequest

public final void cancelRequest()

Cancels the active request and removes itself from the polling list. It then marks the session as inactive. This method is not synchronized.

notifyClient

public final void notifyClient()

Notifies the registered client about the completion of an operation.

toString

public String toString()

Gives a status report of the request.

Overrides:

toString in class Object

Returns:

The status report of the request.

snmpErrorToString

public static 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.

isReport

public boolean isReport()

Test if the received reply is an SNMP report.

Returns:

The test result. true if a report is received, false otherwise.

isResponse

public boolean isResponse()

Test if the received reply is an SNMP response.

Returns:

The test result. true if a response is received, false otherwise.

getResponseSecurityParameters

public final SnmpSecurityParameters getResponseSecurityParameters()

Gets the response security parameters info (e.g. SnmpUsmPeer at discovery time).

Returns:

The response security parameters.

statusDescription

public static final String statusDescription(int state)

Returns the string state corresponding to the specified integer state.

Parameters:

state - The integer state.

Returns:

The string state.