All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class com.sun.jaw.snmp.manager.SnmpRequest

java.lang.Object
   |
   +----com.sun.jaw.snmp.manager.Request
           |
           +----com.sun.jaw.snmp.manager.SnmpRequest

public class SnmpRequest

extends Request

implements Serializable, SnmpDefinitions

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 instance. the protocol data units (PDU) packet size, number of SnmpVarbindLists allowed in a packet, the peer address and port, 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

SnmpRequest(SnmpSession, SnmpPeer, SnmpHandlerIf, int)

For Java DMK internal use only.

SnmpRequest(SnmpSession, SnmpPeer, SnmpHandlerIf, int, int)

For Java DMK internal use only.

allowMultiplex()

Checks to see if this request can be multiplexed with other requests.

cancelRequest()

Cancels the active request and removes itself from polling list.

finalize()

This is called only when all references to the request have been released.

fixPduOnError()

Returns true if the PDU should be fixed for recoverable error.

fixTooBigError()

Returns true if request should be retried for SnmpTooBig error.

getCommand()

Returns the SNMP command for this request.

getErrorIndex()

Returns the index.

getErrorStatus()

Returns the status associated with the SnmpVarbindList.

getMaxRetry()

Returns the maximum number of retries before declaring that the peer is not responding.

getOptions()

Returns the options set for this request.

getParam()

Returns the session parameter object for this request.

getPeer()

Returns the peer object for this request.

getRequestVbList()

Returns the active SnmpVarbindList.

getResponseVbList()

Returns the SnmpVarbindList that is the response obtained when an agent is queried.

getSnmpSession()

Returns the session object for this request.

getVarbindList()

For Java DMK internal use only.

invokeOnResponse(Object)

For Java DMK internal use only.

isInternalRequest()

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

notifyClient()

Notifies the registered client about the completion of an operation.

processResponse()

For Java DMK internal use only.

setErrorStatusAndIndex(int, int)

For Java DMK internal use only.

setInternalRequest()

Indicates the request has been created internally be the package.

setOptions(int)

Allows the user to configure the behavior of the request when certain errors occur, such as SnmpTooBig and optFixPduOnError.

setProxyObject(ReqRedirectSrvIf)

Marks this request as being created by an internal handler or it is being handled by an internal handler.

setVarbindList(SnmpVarbindList)

For Java DMK internal use only.

snmpErrorToString(int)

Returns the string representation of an error code.

start(SnmpVarbindList, boolean, long)

For Java DMK internal use only.

start(SnmpVarbindList, long)

Starts a request in asynchronous mode.

toString()

Gives a status report of the request.

waitForCompletion(long)

Used in synchronous mode only.

 public SnmpRequest(SnmpSession group,
                    SnmpPeer peer,
                    SnmpHandlerIf requestCB,
                    int cmd) throws SnmpStatusException

For Java DMK internal use only. Constructor for creating new request. This object can be created only by a session object. You must instantiate a SnmpSession object to create a request.

Parameters:

group - SnmpSession object for this request.

peer - SnmpPeer object for this request.

requestCB - Callback interface for the request.

cmd - The command type for this request.

Throws: SnmpStatusException

An error occurred while accessing a MIB node.

See Also:

SnmpPeer, SnmpSession

 public SnmpRequest(SnmpSession group,
                    SnmpPeer peer,
                    SnmpHandlerIf requestCB,
                    int nonRepeat,
                    int maxRepeat) throws SnmpStatusException

For Java DMK internal use only. Constructor for creating new bulk request. This constructor initializes the nonRepeaters and maxRepeaters with the specified values.

Parameters:

group - SnmpSession object for this request.

requestCB - Callback interface for the request.

nonRepeat - Value for nonRepeater field.

maxRepeat - Value for maxRepeater field.

Throws: SnmpStatusException

An error occurred while accessing a MIB node.

See Also:

SnmpPeer, SnmpSession

 public final SnmpSession getSnmpSession()

Returns the session object for this request.

Returns:

session object for this request.

 public final SnmpPeer getPeer()

Returns the peer object for this request.

Returns:

peer object for this request.

 public final SnmpParameters getParam()

Returns the session parameter object for this request.

Returns:

session parameter object for this request.

 public final int getCommand()

Returns the SNMP command for this request.

Returns:

SNMP command for this request.

 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.

 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.

Overrides:

allowMultiplex in class Request

 public synchronized String toString()

Gives a status report of the request.

Overrides:

toString in class Request

 public final synchronized int getErrorStatus()

Returns the status associated with the SnmpVarbindList.

 public final synchronized int getErrorIndex()

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

 public final int getMaxRetry()

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

Returns:

maximum number of times a request should be retried.

Overrides:

getMaxRetry in class Request

 public final synchronized 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.

 public final int getOptions()

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

 public synchronized void start(SnmpVarbindList vblst,
                                long when) throws SnmpStatusException

Starts a request in asynchronous mode. The callback interface is used to notify the user upon request completion.

Parameters:

vblst - The SnmpVarbindList to be used.

when - The absolute time in milliseconds when this request should start.

Throws: SnmpStatusException

An error occurred while accessing a MIB node.

 public synchronized void start(SnmpVarbindList vblst,
                                boolean copyvb,
                                long when) throws SnmpStatusException

For Java DMK internal use only. Starts a request in asynchronous mode. The callback interface is used to notify the user upon request completion. For most users this should be set to true.

Parameters:

vblst - The SnmpVarbindList to be used.

copyvb - Whether the vblst should be copied.

when - The absolute time in milliseconds when this request should start.

Throws: SnmpStatusException

An error occurred while accessing a MIB node.

 public boolean fixTooBigError()

Returns true if request should be retried for SnmpTooBig error.

Returns:

true if request should be retried for SnmpTooBig error.

 public boolean fixPduOnError()

Returns true if the PDU should be fixed for recoverable error.

Returns:

true if pdu should be fixed for recoverable error.

 public final synchronized SnmpVarbindList getResponseVbList()

Returns 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 makng request.

Returns:

vblist returned by the agent. Returns null value if request is in progress.

 public final synchronized SnmpVarbindList getRequestVbList()

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

 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

 public boolean isInternalRequest()

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

 public final synchronized void setVarbindList(SnmpVarbindList newvblst)

For Java DMK internal use only. You should specify the varBindList at SnmpRequest creation time. You cannot modify it during the life-time of the object.

 public final void processResponse() throws SnmpStatusException

For Java DMK internal use only.

Throws: SnmpStatusException

An error occurred while accessing a MIB node.

Overrides:

processResponse in class Request

 public final synchronized void setErrorStatusAndIndex(int stat,
                                                       int idx)

For Java DMK internal use only.

 public final void invokeOnResponse(Object resp)

For Java DMK internal use only.

Overrides:

invokeOnResponse in class Request

 public final synchronized SnmpVarbindList getVarbindList()

For Java DMK internal use only. To access the SnmpVarbindList associated with this request, use SnmpRequest#getRequestVbList or SnmpRequest#getResponseVbList.

See Also:

getRequestVbList, getResponseVbList

 public final synchronized void notifyClient()

Notifies the registered client about the completion of an operation. Just blindly execute notify whether someone is waiting.

 public final void setProxyObject(ReqRedirectSrvIf obj)

Marks this request as being created by an internal handler or it is being handled by an internal handler. For example, handling SnmpTooBig errors or multiplexing. Note that if the snmp callback is equal to the proxy, which means this request has been created by the internal mechanism.

 public final void setInternalRequest()

Indicates the request has been created internally be the package.

 public void finalize()

This is called only when all references to the request have been released.

Overrides:

finalize in class Object

 public static String snmpErrorToString(int errcode)

Returns the string representation of an error code.

All Packages  Class Hierarchy  This Package  Previous  Next  Index