com.sun.jaw.snmp.manager
Class SnmpSession

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

public final class SnmpSession
extends java.lang.Object
implements SnmpManagerSrvIf, SnmpDefinitions, java.lang.Runnable, java.io.Serializable

An SnmpSession object essentially creates, controls, and manages one or more request. A session can be bound to a peer so that all requests created (without specifying a peer) will use this as the default. Alternately, there can be a mixture of peers, that is two requests can talk to two different peers.

Each SnmpSession has a dispatcher that is a thread used to service all the requests it creates. It also uses a socket which defaults to a default SnmpSocket. If desired, the session can be configured to exclusively use a seperate socket. By default, all sessions use the same default socket unless explicitly configured. See SnmpSocket for additional information.

This class implements SNMP commands interface which provides a variety of convenience methods that are used to create requests. Each of the requests perform specific SNMP operation. These methods are simple to use and automatically start the request. The session maintains the list of all active request and responses.

Users can explicitly create and start the requests. This is usually not required for most applications.

Each such method provides specific SNMP operation like SnmpGet, SnmpGetNext, and SnmpSet. The SnmpGet and SnmpGetNext operations can be either poll or non-poll. In addition there is a convenience method which automatically walks through a set of instances starting at any arbitrary place in the MIB hierarchy and terminates when a specified condition becomes true.

The requests are retried when the peer does not respond within a specified time. There is a maximum retry limit. Certain options of sessions can be configured using the SnmpOptions object. This allow enabling and disabling features like fixing protocol data units (PDU) on error, handling SnmpTooBig errors and multiplexing requests.

Once a session is created the user can perform one or more SNMP operation in a one-at-a-time sequence. Usually such a sequence is a set of logical operations which together form a complete operation. For example, a SnmpSet operation, which involves a initial query to the agent for obtaining a valid index. This is followed by one or more SnmpSet commands to complete the set operation.

At any time, one or more requests active in a session can be cancelled.

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

Field Summary
 java.lang.String sessionName
          The name identifying this session.
 SnmpOptions snmpOptions
          Set of options used to configure all SnmpRequests created in this session.
 
Constructor Summary
SnmpSession(java.lang.String name)
          Constructor for creating a new session.
SnmpSession(java.lang.String name, SnmpAuthHandlerIf auth)
          Constructor for creating new session.
SnmpSession(java.lang.String name, SnmpPeer apeer, SnmpAuthHandlerIf auth)
          Constructor for creating new session.
 
Method Summary
protected  void addResponse(Request reqc)
          Adds the request object which received a response to a request generated by the session.
 boolean anyPendingResponses()
          Indicates whether there are any responses available for processing.
 void cancelAllRequests()
          Cancels all pending requests with this session.
 boolean checkResponseFor(Request req)
          Indicates whether a response was received for this request.
protected  void deleteRequest(SnmpRequest snmpreq)
          Deletes a request.
 void destroySession()
          Destroys any pending requests and then stops the session.
 void finalize()
          Removes all the requests for this session, closes the socket and sets all the references to the SnmpSession object to null.
 java.util.Vector getAllRequestsForPeer(SnmpPeer apeer)
          Gets a list of requests which have the specified destination.
 SnmpPeer getDefaultPeer()
          Gets a default peer (if any) bound to this session.
protected  java.lang.Thread getDispatcher()
          Gets the dispatcher thread associated with the session.
 java.lang.String getName()
          Gets the session name (often used in identification).
 SnmpSocket getSocket()
          Gets the SnmpSocket which will be used by requests created in this session.
 boolean isEquivalent(SnmpSession arg)
          Two sessions are equivalent if they share the same socket.
 boolean isSessionActive()
          Indicates if the thread for this session is active.
 void run()
          Dispatcher method for this session thread.
 void setDefaultPeer(SnmpPeer apeer)
          Sets peer as default.
 void setName(java.lang.String name)
          Sets the session name (often used in identification).
 SnmpRequest snmpGet(SnmpHandlerIf cb, SnmpVarbindList vblst)
          Performs a single SNMP get request on the varbind list.
 SnmpRequest snmpGet(SnmpPeer peer, SnmpHandlerIf cb, SnmpVarbindList vblst)
          Performs a single SNMP get request on the varbind list.
 SnmpRequest snmpGetBulk(SnmpHandlerIf cb, SnmpVarbindList vblst, int nonRepeat, int maxRepeat)
          Performs a single SNMP getbulk request on the varbind list.
 SnmpRequest snmpGetBulk(SnmpPeer peer, SnmpHandlerIf cb, SnmpVarbindList vblst, int nonRepeat, int maxRepeat)
          Performs a single SNMP getbulk request on the varbind list.
 SnmpRequest snmpGetNext(SnmpHandlerIf cb, SnmpVarbindList vblst)
          Performs a single SNMP getnext request on the varbind list.
 SnmpRequest snmpGetNext(SnmpPeer peer, SnmpHandlerIf cb, SnmpVarbindList vblst)
          Performs a single SNMP getnext request on the varbind list.
 SnmpRequest snmpGetNextPoll(SnmpHandlerIf cb, SnmpVarbindList vblst, int intrvl)
          Starts polling the peer at the specified intervals, for the MIB variables in the varbind list.
 SnmpRequest snmpGetNextPoll(SnmpPeer peer, SnmpHandlerIf cb, SnmpVarbindList vblst, int intrvl)
          Starts polling the peer at the specified intervals, for the MIB variables in the varbind list.
 SnmpRequest snmpGetPoll(SnmpHandlerIf cb, SnmpVarbindList vblst, int intrvl)
          Starts polling the peer at the specified intervals, for the MIB variables in the varbind list.
 SnmpRequest snmpGetPoll(SnmpPeer peer, SnmpHandlerIf cb, SnmpVarbindList vblst, int intrvl)
          Starts polling the peer at the specified intervals, for the MIB variables in the varbind list.
 SnmpRequest snmpSet(SnmpHandlerIf cb, SnmpVarbindList vblst)
          Performs a single SNMP set request on the peer for the specified varbind list.
 SnmpRequest snmpSet(SnmpPeer peer, SnmpHandlerIf cb, SnmpVarbindList vblst)
          Performs a single SNMP set request on the peer for the specified varbind list.
 SnmpRequest snmpWalkUntil(SnmpHandlerIf cb, SnmpVarbindList vblst, SnmpOid key)
          Walks through the lexicographic ordering of the agent MIB.
 SnmpRequest snmpWalkUntil(SnmpPeer peer, SnmpHandlerIf cb, SnmpVarbindList vblst, SnmpOid key)
          Walks through the lexicographic ordering of the agent MIB.
 boolean syncInProgress()
          Indicates whether this session is performing synchronous operation for a request.
 boolean thisSessionContext()
          Returns true if the current executing thread is this sessions dispatcher.
 java.lang.String toString()
          Gets a string representation of the session.
 void useExclusiveSocket()
          Creates a new socket which it will use exclusively for sending and receiving SNMP requests and responses of this session.
 void useExclusiveSocket(SnmpSocket sock)
          Uses the specified socket to perform an I/O.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

sessionName

public java.lang.String sessionName
The name identifying this session. Useful in debugging a session.

snmpOptions

public SnmpOptions snmpOptions
Set of options used to configure all SnmpRequests created in this session. The user can directly manipulate the options. Note that this variable is public.
Constructor Detail

SnmpSession

public SnmpSession(java.lang.String name,
                   SnmpPeer apeer,
                   SnmpAuthHandlerIf auth)
Constructor for creating new session.
Parameters:
name - The session name.
apeer - The default peer to send requests to.
auth - Unused.

SnmpSession

public SnmpSession(java.lang.String name,
                   SnmpAuthHandlerIf auth)
Constructor for creating new session.
Parameters:
name - The session name.
auth - Unused.

SnmpSession

public SnmpSession(java.lang.String name)
Constructor for creating a new session. Responses to the request for this session will not be authenticated.
Parameters:
name - The session name.
Method Detail

getName

public final java.lang.String getName()
Gets the session name (often used in identification).
Returns:
The session name.

setName

public final void setName(java.lang.String name)
Sets the session name (often used in identification).
Parameters:
name - The session name.

setDefaultPeer

public final void setDefaultPeer(SnmpPeer apeer)
Sets peer as default. This peer is used when a SNMP command is issued without specifying the destination.
Parameters:
apeer - The default destination.

getDefaultPeer

public final SnmpPeer getDefaultPeer()
Gets a default peer (if any) bound to this session.
Returns:
The default peer object.

toString

public final java.lang.String toString()
Gets a string representation of the session.
Returns:
A string representation of the session.
Overrides:
toString in class java.lang.Object

getSocket

public final SnmpSocket getSocket()
Gets the SnmpSocket which will be used by requests created in this session.
Returns:
The socket which will be used in this session.

useExclusiveSocket

public final void useExclusiveSocket(SnmpSocket sock)
Uses the specified socket to perform an I/O. Note that this socket could be shared with other sessions as well.
Parameters:
sock - The user supplied specific socket to use.

useExclusiveSocket

public final void useExclusiveSocket()
                              throws java.net.SocketException
Creates a new socket which it will use exclusively for sending and receiving SNMP requests and responses of this session.
Throws:
java.net.SocketException - Unable to create an exclusive socket.

isEquivalent

public final boolean isEquivalent(SnmpSession arg)
Two sessions are equivalent if they share the same socket.
Parameters:
arg - The session to compare this with.
Returns:
True if they use same socket; false otherwise.

isSessionActive

public final boolean isSessionActive()
Indicates if the thread for this session is active.
Returns:
True if active; false otherwise.

syncInProgress

public boolean syncInProgress()
Indicates whether this session is performing synchronous operation for a request.
Returns:
True the session is performing synchronous operation; false otherwise.

destroySession

public final void destroySession()
Destroys any pending requests and then stops the session. The session will not be usable after this method returns.

getAllRequestsForPeer

public java.util.Vector getAllRequestsForPeer(SnmpPeer apeer)
Gets a list of requests which have the specified destination.
Parameters:
apeer - The SnmpPeer.
Returns:
Vector of requests to the specified peer.

cancelAllRequests

public final void cancelAllRequests()
Cancels all pending requests with this session.

checkResponseFor

public boolean checkResponseFor(Request req)
Indicates whether a response was received for this request. The status of response is maintained in the request object.
Parameters:
req - The request.
Returns:
True if request has a pending response; false otherwise.

thisSessionContext

public boolean thisSessionContext()
Returns true if the current executing thread is this sessions dispatcher. Typically used to detect if the user is doing a sync operation from this dispatcher context. For instance, a user gives a sync command from within a request callback using its associated session.
Returns:
True if current thread is this session's dispatcher; false otherwise.

snmpGet

public final SnmpRequest snmpGet(SnmpPeer peer,
                                 SnmpHandlerIf cb,
                                 SnmpVarbindList vblst)
                          throws SnmpStatusException
Performs a single SNMP get request on the varbind list. When the command completes, the appropriate callback method is invoked.
Specified by:
snmpGet in interface SnmpManagerSrvIf
Parameters:
peer - The SNMP peer object.
cb - The callback that gets invoked when request is complete.
vblst - A list of SNMP varbinds.
Throws:
SnmpStatusException - You may never get this by using these convenience ftns.
See Also:
How to get response data.

snmpGet

public final SnmpRequest snmpGet(SnmpHandlerIf cb,
                                 SnmpVarbindList vblst)
                          throws SnmpStatusException
Performs a single SNMP get request on the varbind list. Uses the default peer.
Specified by:
snmpGet in interface SnmpManagerSrvIf
Parameters:
cb - The callback that gets invoked when request is complete.
vblst - A list of SNMP varbinds.
Throws:
SnmpStatusException - You may never get this by using these convenience ftns.
See Also:
How to get response data.

snmpGetNext

public final SnmpRequest snmpGetNext(SnmpPeer peer,
                                     SnmpHandlerIf cb,
                                     SnmpVarbindList vblst)
                              throws SnmpStatusException
Performs a single SNMP getnext request on the varbind list. When the command completes, the appropriate callback method is invoked.
Specified by:
snmpGetNext in interface SnmpManagerSrvIf
Parameters:
peer - The SNMP peer object.
cb - The callback that is invoked when a request is complete.
vblst - A list of SNMP varbinds.
Throws:
SnmpStatusException - You may never get this by using these convenience ftns.
See Also:
How to get response data.

snmpGetNext

public final SnmpRequest snmpGetNext(SnmpHandlerIf cb,
                                     SnmpVarbindList vblst)
                              throws SnmpStatusException
Performs a single SNMP getnext request on the varbind list. Uses the default peer.
Specified by:
snmpGetNext in interface SnmpManagerSrvIf
Parameters:
cb - The callback that is invoked when a request is complete.
vblst - A list of SNMP varbinds.
Throws:
SnmpStatusException - You may never get this by using these convenience ftns.
See Also:
How to get response data.

snmpGetBulk

public final SnmpRequest snmpGetBulk(SnmpPeer peer,
                                     SnmpHandlerIf cb,
                                     SnmpVarbindList vblst,
                                     int nonRepeat,
                                     int maxRepeat)
                              throws SnmpStatusException
Performs a single SNMP getbulk request on the varbind list. When the command completes, the appropriate callback method is invoked.
Specified by:
snmpGetBulk in interface SnmpManagerSrvIf
Parameters:
peer - The SNMP peer object.
cb - The callback that is invoked when a request is complete.
vblst - A list of SNMP varbinds.
nonRepeat - Number of varbind to get one time.
maxRepeat - Number of repetition for varbind to get multiple time.
Throws:
SnmpStatusException - You may never get this by using these convenience ftns.
See Also:
How to get response data.

snmpGetBulk

public final SnmpRequest snmpGetBulk(SnmpHandlerIf cb,
                                     SnmpVarbindList vblst,
                                     int nonRepeat,
                                     int maxRepeat)
                              throws SnmpStatusException
Performs a single SNMP getbulk request on the varbind list. Uses the default peer.
Specified by:
snmpGetBulk in interface SnmpManagerSrvIf
Parameters:
cb - The callback that is invoked when a request is complete.
vblst - A list of SNMP varbinds.
nonRepeat - Number of varbind to get one time.
maxRepeat - Number of repetition for varbind to get multiple time.
Throws:
SnmpStatusException - You may never get this by using these convenience ftns.
See Also:
How to get response data.

snmpSet

public final SnmpRequest snmpSet(SnmpPeer peer,
                                 SnmpHandlerIf cb,
                                 SnmpVarbindList vblst)
                          throws SnmpStatusException
Performs a single SNMP set request on the peer for the specified varbind list. Because retries on set operations are not performed, the user needs to specify the timeout value within which a response is requested.
Specified by:
snmpSet in interface SnmpManagerSrvIf
Parameters:
peer - The SNMP peer object.
cb - The callback that is invoked when request is complete.
vblst - A list of SNMP varbinds.
Throws:
SnmpStatusException - You may never get this by using these convenience ftns.
See Also:
How to get response data.

snmpSet

public final SnmpRequest snmpSet(SnmpHandlerIf cb,
                                 SnmpVarbindList vblst)
                          throws SnmpStatusException
Performs a single SNMP set request on the peer for the specified varbind list. Uses the default peer.
Specified by:
snmpSet in interface SnmpManagerSrvIf
Parameters:
cb - The callback that is invoked when request is complete.
vblst - A list of SNMP varbinds.
Throws:
SnmpStatusException - You may never get this by using these convenience ftns.
See Also:
How to get response data.

snmpGetPoll

public final SnmpRequest snmpGetPoll(SnmpPeer peer,
                                     SnmpHandlerIf cb,
                                     SnmpVarbindList vblst,
                                     int intrvl)
                              throws SnmpStatusException
Starts polling the peer at the specified intervals, for the MIB variables in the varbind list. It does a SNMP get request on the varbind list. After each poll, the appropriate callback method is invoked.
Specified by:
snmpGetPoll in interface SnmpManagerSrvIf
Parameters:
peer - The SNMP peer object.
cb - The callback that is invoked when request is complete.
vblst - A list of SNMP varbinds.
intrvl - The frequency of polling.
Throws:
SnmpStatusException - You may never get this by using these convenience ftns.
See Also:
How to get response data.

snmpGetPoll

public final SnmpRequest snmpGetPoll(SnmpHandlerIf cb,
                                     SnmpVarbindList vblst,
                                     int intrvl)
                              throws SnmpStatusException
Starts polling the peer at the specified intervals, for the MIB variables in the varbind list. Uses the default peer.
Specified by:
snmpGetPoll in interface SnmpManagerSrvIf
Parameters:
cb - The callback that is invoked when request is complete.
vblst - A list of SNMP varbinds.
intrvl - The frequency of polling.
Throws:
SnmpStatusException - You may never get this by using these convenience ftns.
See Also:
How to get response data.

snmpGetNextPoll

public final SnmpRequest snmpGetNextPoll(SnmpPeer peer,
                                         SnmpHandlerIf cb,
                                         SnmpVarbindList vblst,
                                         int intrvl)
                                  throws SnmpStatusException
Starts polling the peer at the specified intervals, for the MIB variables in the varbind list. It saves the original varbind list that is used during each poll. It performs an SNMP getnext request on the saved original varbind list and provides the response to the user via the callback mechanism. This method is similar to snmpGetPoll except that it uses getnext on the original varbind list instead of get.
Specified by:
snmpGetNextPoll in interface SnmpManagerSrvIf
Parameters:
peer - The SNMP peer object.
cb - The callback that is invoked when request is complete.
vblst - A list of SNMP varbinds.
intrvl - The frequency of polling.
Throws:
SnmpStatusException - You may never get this by using these convenience ftns.
See Also:
How to get response data.

snmpGetNextPoll

public final SnmpRequest snmpGetNextPoll(SnmpHandlerIf cb,
                                         SnmpVarbindList vblst,
                                         int intrvl)
                                  throws SnmpStatusException
Starts polling the peer at the specified intervals, for the MIB variables in the varbind list. Uses the default peer.
Specified by:
snmpGetNextPoll in interface SnmpManagerSrvIf
Parameters:
cb - The callback that is invoked when request is complete.
vblst - A list of SNMP varbinds.
intrvl - The frequency of polling.
Throws:
SnmpStatusException - You may never get this by using these convenience ftns.
See Also:
How to get response data.

snmpWalkUntil

public final SnmpRequest snmpWalkUntil(SnmpPeer peer,
                                       SnmpHandlerIf cb,
                                       SnmpVarbindList vblst,
                                       SnmpOid key)
                                throws SnmpStatusException
Walks through the lexicographic ordering of the agent MIB. It starts at the specified varbind list and continues until the OID key specified as a parameter is "smaller" than the first variable in the response varbind list or an error occurred. Typically, this feature is used to walk an arbitrary table and obtain all rows satisfying a specific condition. The condition may be a specific instance combination for a MIB variable or a MIB variable OID entry object.
 String var[] = {"sysDescr"} ;
 SnmpVarbindList vblst = new SnmpVarbindList() ;
 vblst.addVariable(var) ;
 SnmpRequest request = session.snmpWalkUntil(null, vblst, new SnmpOid("sysServices")) ;
 
This example walks through the system group and get all the variables in this group.
 SnmpRequest request = session.snmpWalkUntil(null, vblst, new SnmpOid("1.4")) ;
 
This example walks through the entire agent MIB starting at sysDescr.
 String var[] = {"sysDescr.0"} ;
 SnmpVarbindList vblst = new SnmpVarbindList() ;
 vblst.addVariable(var) ;
 SnmpRequest request = session.snmpWalkUntil(null, vblst, new SnmpOid("sysServices.0")) ;
 
This example walks through the system group beginning after the sysDescr variable (not included) and ending with the sysServices variable (included).

If there is more than one variable in the specified varbind list, the request will start at the first variable of the list.

Specified by:
snmpWalkUntil in interface SnmpManagerSrvIf
Parameters:
peer - The peer object to talk to.
cb - The callback that is invoked when the request completes.
vblst - The list from SnmpVarbindList.
key - Condition key that must be a subset of the first variable in the response SnmpVarbindList. Walk terminates if this condition is false.
Throws:
SnmpStatusException - You may never get this by using these convenience ftns.
See Also:
SnmpManagerSrvIf

snmpWalkUntil

public final SnmpRequest snmpWalkUntil(SnmpHandlerIf cb,
                                       SnmpVarbindList vblst,
                                       SnmpOid key)
                                throws SnmpStatusException
Walks through the lexicographic ordering of the agent MIB. Uses the default peer.
Specified by:
snmpWalkUntil in interface SnmpManagerSrvIf
Parameters:
cb - The callback that is invoked when the request completes.
vblst - The list from SnmpVarbindList.
key - Condition key that must be a subset of the first variable in the response SnmpVarbindList. Walk terminates if this condition is false.
Throws:
SnmpStatusException - You may never get this by using these convenience ftns.
See Also:
SnmpManagerSrvIf

deleteRequest

protected final void deleteRequest(SnmpRequest snmpreq)
Deletes a request.
Parameters:
snmpreq - The request to delete.

anyPendingResponses

public boolean anyPendingResponses()
Indicates whether there are any responses available for processing. These responses belong to the requests made using this session.
Returns:
True if response is available; false otherwise.

run

public void run()
Dispatcher method for this session thread. This is the dispatcher method which goes in an endless-loop and waits for servicing requests which got a reply from the agent.
Specified by:
run in interface java.lang.Runnable

finalize

public void finalize()
Removes all the requests for this session, closes the socket and sets all the references to the SnmpSession object to null.
Overrides:
finalize in class java.lang.Object

addResponse

protected void addResponse(Request reqc)
Adds the request object which received a response to a request generated by the session. This is added to a private store, which will be eventually picked up by the dispatcher for processing.
Parameters:
reqc - The request that received the response from the agent.

getDispatcher

protected final java.lang.Thread getDispatcher()
Gets the dispatcher thread associated with the session. Used to check whether the sync request was done from within the dispatcher. You should prevent this from happening.
Returns:
The dispatcher thread associated with the session.