com.ireasoning.protocol.snmp
Interface SubAgentSession

All Superinterfaces:

Serializable

public interface SubAgentSession

extends Serializable

This class represents a AgentX subagent session

See Also:

SnmpAgentX.connect(java.lang.String, int)

Method Summary

SnmpError	allocateTableIndices(SnmpVarBind[] indices) Allocates table indices, with NEW_INDEX and ANY_INDEX clear.
SnmpError	allocateTableIndices(SnmpVarBind[] indices, int mode) Allocates table indices.
void	close() Closes this subagent session
SnmpError	deallocateTableIndices(SnmpVarBind[] indices) Deallocates table indices
String	getContext() Returns context string
boolean	isActive() Returns the state of this session
boolean	pingMasterAgent() Sends PING pdu to master agent in order to monitor the master agent's ability to receive and send AgentX PDUs over AgentX session.
int	register(String subtree) Registers a subtree with master agent.
int	register(String subtree, int range_subid, long upper_bound, int timeout) Registers subtree.
boolean	sendTrap(SnmpTrap trap) Sends out trap to master agent (not to trap receiver directly).
boolean	sendTrap(SnmpVarBind[] varbinds) Sends out trap to master agent (not to trap receiver directly).
void	setContext(String context) Sets context string
void	unregister() Unregisters all previously registered subtrees
boolean	unregister(int index) Unregisters subtree, asks master agent to remove the MIB region that was previously registered on this session.
boolean	unregister(String subtree) Unregisters subtree
boolean	unregister(String subtree, int range_subid, long upper_bound) Unregisters subtree

Method Detail

register

public int register(String subtree)
             throws IOException

Registers a subtree with master agent. Uses the default priority (127) and timeout value (no timeout)

Subagent needs to register for each region of the MIB variable naming tree that it wishes to support.

The choice of what to register is implementation-specific. Standard practice however is for a subagent to register at the highest level of the naming tree that makes sense. Registration of fully-qualified instances is typically done only when a subagent can perform management operations only on particular rows of a conceptual table.

If any of the subtree is exactly the same as any subtree currently registered within the master agent, this subtree is termed "duplicate subtrees" and master agent might reject this register message.

If the subtree is overlapped by any subtree registered within the master agent, this subtree is termed "overlapping subtrees" and master agent might reject this register message.

Parameters:

subtree - An Object Identifier that names the basic subtree of a MIB region for which a subagent indicates its support. The term "subtree" is used generically here, it may represent a fully-qualified instance name, a partial instance name, a MIB table, an entire MIB, etc.

Returns:

The index of registration, which can be used later for unregister; or -1 if registration failed.

Throws:

IOException - raised if socket error occurred

See Also:

unregister(int index)

register

public int register(String subtree,
                    int range_subid,
                    long upper_bound,
                    int timeout)
             throws IOException

Registers subtree. Uses the default priority (127)

Subagent needs to register for each region of the MIB variable naming tree that it wishes to support.

The choice of what to register is implementation-specific. Standard practice however is for a subagent to register at the highest level of the naming tree that makes sense. Registration of fully-qualified instances is typically done only when a subagent can perform management operations only on particular rows of a conceptual table.

If any of the subtree is exactly the same as any subtree currently registered within the master agent, this subtree is termed "duplicate subtrees" and master agent might reject this register message.

If the subtree is overlapped by any subtree registered within the master agent, this subtree is termed "overlapping subtrees" and master agent might reject this register message.

The use of range_subid and upper_bound provide a general shorthand mechanism for specifying a MIB region. For example, if subtree is the OID 1.3.6.1.2.1.2.2.1.1.7, range_subid is 10, and upper_bound is 22, the specified MIB region can be denoted 1.3.6.1.2.1.2.2.1.[1-22].7. Registering this region is equivalent to registering the union of subtrees

         1.3.6.1.2.1.2.2.1.1.7
         1.3.6.1.2.1.2.2.1.2.7
         1.3.6.1.2.1.2.2.1.3.7
         ...
         1.3.6.1.2.1.2.2.1.22.7
 

One expected use of this mechanism is registering a conceptual row with a single PDU. In the example above, the MIB region happens to be row 7 of the RFC 1573 ifTable.

Parameters:

subtree - An Object Identifier that names the basic subtree of a MIB region for which a subagent indicates its support. The term "subtree" is used generically here, it may represent a fully-qualified instance name, a partial instance name, a MIB table, an entire MIB, etc.

range_subid - range_subid indicates the (1-based) index of this sub-identifier within the OID represented by subtree

upper_bound - The upper bound of a sub-identifier's range. This argument is effective only if range_subid is not 0.

timeout - timeout value, in seconds

Returns:

The index of registration (starting from 0), which can be used later for unregister; or -1 if registration failed.

Throws:

IOException - raised if socket error occurred

unregister

public void unregister()
                throws IOException

Unregisters all previously registered subtrees

Throws:

IOException - raised if socket error occurred

unregister

public boolean unregister(int index)
                   throws IOException

Unregisters subtree, asks master agent to remove the MIB region that was previously registered on this session.

Parameters:

index - the index of registered subtree (the return value of register methods)

Returns:

true if unregistration succeeded.

Throws:

IOException - raised if socket error occurred

See Also:

register(java.lang.String)

unregister

public boolean unregister(String subtree)
                   throws IOException

Unregisters subtree

Parameters:

subtree - An Object Identifier that names the basic subtree of a MIB region for which a subagent indicates its support. The term "subtree" is used generically here, it may represent a fully-qualified instance name, a partial instance name, a MIB table, an entire MIB, etc.

Returns:

true if unregistration succeeded.

Throws:

IOException - raised if socket error occurred

See Also:

register(java.lang.String)

unregister

public boolean unregister(String subtree,
                          int range_subid,
                          long upper_bound)
                   throws IOException

Unregisters subtree

Parameters:

subtree - An Object Identifier that names the basic subtree of a MIB region for which a subagent indicates its support. The term "subtree" is used generically here, it may represent a fully-qualified instance name, a partial instance name, a MIB table, an entire MIB, etc.

range_subid - range_subid indicates the (1-based) index of this sub-identifier within the OID represented by subtree

upper_bound - The upper bound of a sub-identifier's range. This argument is effective only if range_subid is not 0.

Returns:

true if unregistration succeeded.

Throws:

IOException - raised if socket error occurred

See Also:

register(java.lang.String)

allocateTableIndices

public SnmpError allocateTableIndices(SnmpVarBind[] indices)
                               throws IOException

Allocates table indices, with NEW_INDEX and ANY_INDEX clear. It requests master agent to allocate indices specified in passed indices.

Index allocation is a service provided by an AgentX master agent. It provides generic support for sharing MIB conceptual tables among subagents who are assumed to have no knowledge of each other. By convention, subagents use the MIB variable listed in the INDEX clause as the index object for which values must be allocated.

It is important to note that index allocation and MIB region registration are not coupled in the master agent. The current state of index allocations is not considered when processing registration requests, and the current registry is not considered when processing index allocation requests.

AgentX subagents can follow the model of "first request allocation of an index, then register the corresponding region". Then a successful index allocation request gives a subagent a good hint (but no guarantee) of what it should be able to register. The registration may fail (with `duplicateRegistration') because some other subagent session has already registered that row of the table.

Note that index allocation is necessary only when the index in question is an arbitrary value, and hence the subagent has no other reasonable way to determine which index values to use. When index values have intrinsic meaning it is not expected that subagents will allocate their index values.

For example, RFC 1514's table of running software processes (hrSWRunTable) is indexed by the system's native process identifier (pid). A subagent implementing the row of hrSWRunTable corresponding to its own process would simply register the region defining that row's object instances without allocating index values.

Parameters:

indices - indices to be allocated. Variable binding's name is the OID prefix of the MIB OBJECT-TYPE for which a value is to be allocated.

Returns:

SnmpError.NO_ERROR if allocation succeeded. Otherwise use SnmpError.getErrorStatus() and SnmpError.getErrorIndex() to get details.

Throws:

IOException - raised if socket error occurred

allocateTableIndices

public SnmpError allocateTableIndices(SnmpVarBind[] indices,
                                      int mode)
                               throws IOException

Allocates table indices.
Note: The indices need to be registered later

Parameters:

mode -
0: request indice specified in the passed indice, the same as allocateTableIndices(SnmpVarBind indice) ;
1: NEW_INDEX, request indice which are never allocated;
2: ANY_INDEX, request indice which are not currently allocated

indices - indices to be allocated. Variable binding's name is the OID prefix of the MIB OBJECT-TYPE for which a value is to be allocated. If the mode is NEW_INDEX or ANY_INDEX, this argument will be updated with the variable bindings sent from master agent.

Returns:

SnmpError.NO_ERROR if allocation succeeded. Otherwise use SnmpError.getErrorStatus() and SnmpError.getErrorIndex() to get details.

Throws:

IOException - raised if socket error occurred

See Also:

allocateTableIndices(SnmpVarBind[] indices)

deallocateTableIndices

public SnmpError deallocateTableIndices(SnmpVarBind[] indices)
                                 throws IOException

Deallocates table indices

Parameters:

indices - indices to be allocated.

Returns:

SnmpError.NO_ERROR if allocation succeeded. Otherwise use SnmpError.getErrorStatus() and SnmpError.getErrorIndex() to get details.

Throws:

IOException - raised if socket error occurred

sendTrap

public boolean sendTrap(SnmpVarBind[] varbinds)
                 throws IOException

Sends out trap to master agent (not to trap receiver directly). Even if master agent indicates that it has successfully received this trap, it's not guaranteed that master agent will forward this trap to trap receiver.

Parameters:

varbinds - variable bindings. The first one's OID has to be sysUpTime or snmpTrapOID. If the first one's OID is sysUpTime, the second one's OID has to be snmpTrapOID.

Returns:

true if the response from master agent indicates no error

Throws:

IOException - raised if trap can not be sent out

IllegalArgumentException - raise if passed varbinds is not valid

sendTrap

public boolean sendTrap(SnmpTrap trap)
                 throws IOException

Sends out trap to master agent (not to trap receiver directly). Even if master agent indicates that it has successfully received this trap, it's not guaranteed that master agent will forward this trap to trap receiver.

Parameters:

trap - trap to be sent

Returns:

true if the response from master agent indicates no error

Throws:

IOException - raised if trap can not be sent out

setContext

public void setContext(String context)

Sets context string

getContext

public String getContext()

Returns context string

pingMasterAgent

public boolean pingMasterAgent()
                        throws IOException

Sends PING pdu to master agent in order to monitor the master agent's ability to receive and send AgentX PDUs over AgentX session.

Returns:

true if no error in master agent's response

Throws:

IOException - raised if there is socket error

close

public void close()

Closes this subagent session

isActive

public boolean isActive()

Returns the state of this session