org.snmp4j.agent.agentx.subagent

Class AgentXSharedMOTableSupport<R extends org.snmp4j.agent.mo.MOTableRow>

java.lang.Object

org.snmp4j.agent.agentx.subagent.AgentXSharedMOTableSupport<R>

All Implemented Interfaces:

EventListener, org.snmp4j.agent.mo.MOTableRowListener<R>

public class AgentXSharedMOTableSupport<R extends org.snmp4j.agent.mo.MOTableRow>
extends Object
implements org.snmp4j.agent.mo.MOTableRowListener<R>

The AgentXSharedMOTableSupport provides helper functions for shared table implementations to register rows and indexes at a master agent.

Version:

2.2

Author:

Frank Fock

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	AgentXSharedMOTableSupport.IndexStrategy

Field Summary

Fields

Modifier and Type	Field and Description
static int	INDEX_MODE_ALLOCATE
static int	INDEX_MODE_ANY_INDEX
static int	INDEX_MODE_NEW_INDEX
protected SubAgentXIndexRegistry	indexRegistry

Constructor Summary

Constructors

Constructor and Description
AgentXSharedMOTableSupport(AgentX agentX, AgentXSession session, org.snmp4j.smi.OctetString context) Creates a shared table support object for a AgentX connection, session, and context.
AgentXSharedMOTableSupport(AgentX agentX, AgentXSession session, org.snmp4j.smi.OctetString context, byte priority, byte indexAllocationMode) Creates a shared table support object for a AgentX connection, session, and context.

Method Summary

Modifier and Type	Method and Description
int	allocateIndex(org.snmp4j.smi.OctetString context, org.snmp4j.agent.mo.MOTableIndex indexDef, byte indexAllocationMode, org.snmp4j.smi.OID allocatedIndex) Allocate a new or any index at the master agent and return its value in allocateIndex.
int	deallocateIndex(org.snmp4j.smi.OctetString context, org.snmp4j.agent.mo.MOTableIndex indexDef, org.snmp4j.smi.OID allocatedIndex) Deallocate an index at the master agent.
AgentX	getAgentX()
org.snmp4j.smi.OctetString	getContext()
protected byte	getEffectiveIndexMode(org.snmp4j.agent.mo.MOTableRowEvent<R> event)
protected byte	getEffectivePriority(org.snmp4j.agent.mo.MOTableRowEvent<R> event)
byte	getIndexMode()
AgentXSharedMOTableSupport.IndexStrategy	getIndexStrategy() Gets the index strategy of this shared table support.
byte	getPriority()
AgentXSession	getSession() Gets the AgentX session used by this shared table support object.
protected int	handleIndexAllocationError(org.snmp4j.agent.mo.MOTableIndex indexDef, org.snmp4j.smi.OctetString context, org.snmp4j.smi.OID allocatedIndex, AgentXResponsePDU resp) Handle an index allocation error.
int	registerRow(org.snmp4j.agent.mo.MOTable table, R row2Register)
int	registerRow(org.snmp4j.agent.mo.MOTable table, R row2Register, byte priority) Register the necessary regions for a table row.
void	rowChanged(org.snmp4j.agent.mo.MOTableRowEvent<R> event) Process shared table row events.
void	setContext(org.snmp4j.smi.OctetString context)
void	setIndexMode(byte indexMode) Sets the index mode to be used by this shared table support object.
void	setIndexStrategy(AgentXSharedMOTableSupport.IndexStrategy indexStrategy) Sets the index strategy for this shared table support.
void	setPriority(byte priority) Sets the priority for the region registrations made by this table support.
void	setSession(AgentXSession session) Sets the AgentX session to be used for this shared table support.
int	unregisterRow(org.snmp4j.agent.mo.MOTable table, R row2Unregister)
int	unregisterRow(org.snmp4j.agent.mo.MOTable table, R row2Unregister, byte priority) Removes the region registration of a table row.

Methods inherited from class java.lang.Object

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

Field Detail

INDEX_MODE_ALLOCATE

public static final int INDEX_MODE_ALLOCATE

See Also:

Constant Field Values

INDEX_MODE_ANY_INDEX

public static final int INDEX_MODE_ANY_INDEX

See Also:

Constant Field Values

INDEX_MODE_NEW_INDEX

public static final int INDEX_MODE_NEW_INDEX

See Also:

Constant Field Values

indexRegistry

protected SubAgentXIndexRegistry indexRegistry

Constructor Detail

AgentXSharedMOTableSupport

public AgentXSharedMOTableSupport(AgentX agentX,
                                  AgentXSession session,
                                  org.snmp4j.smi.OctetString context)

Creates a shared table support object for a AgentX connection, session, and context.

Parameters:

agentX - an AgentX connection.

session - an AgentXSession session (does not need to be open at creation time).

context - a context ("" by default).

AgentXSharedMOTableSupport

public AgentXSharedMOTableSupport(AgentX agentX,
                                  AgentXSession session,
                                  org.snmp4j.smi.OctetString context,
                                  byte priority,
                                  byte indexAllocationMode)

Creates a shared table support object for a AgentX connection, session, and context.

Parameters:

agentX - an AgentX connection.

session - an AgentXSession session (does not need to be open at creation time).

context - a context ("" by default).

priority - the registration priority used for this shared table support.

indexAllocationMode - the index allocation mode to be used as default for this shared table.

Method Detail

rowChanged

public void rowChanged(org.snmp4j.agent.mo.MOTableRowEvent<R> event)

Process shared table row events. If index mode is INDEX_MODE_ALLOCATE this method will do nothing if the associated AgentX session is closed. For other index modes, the event's veto status will be set to the AgentX error AgentXProtocol.AGENTX_NOT_OPEN.

If the index OID of a created row has zero length then, depending on the current index mode, a new or any new index is allocated at the master agent.

Specified by:

rowChanged in interface org.snmp4j.agent.mo.MOTableRowListener<R extends org.snmp4j.agent.mo.MOTableRow>

Parameters:

event - a MOTableRowEvent indicating a row change in an AgentX shared table.

getEffectiveIndexMode

protected byte getEffectiveIndexMode(org.snmp4j.agent.mo.MOTableRowEvent<R> event)

getEffectivePriority

protected byte getEffectivePriority(org.snmp4j.agent.mo.MOTableRowEvent<R> event)

allocateIndex

public int allocateIndex(org.snmp4j.smi.OctetString context,
                         org.snmp4j.agent.mo.MOTableIndex indexDef,
                         byte indexAllocationMode,
                         org.snmp4j.smi.OID allocatedIndex)

Allocate a new or any index at the master agent and return its value in allocateIndex. For the index strategies AgentXSharedMOTableSupport.IndexStrategy.firstSubIndexOnly and AgentXSharedMOTableSupport.IndexStrategy.anyNonAllocatedSubIndex a local index registry maintains a reference to all allocated index values. If an allocation fails, the index value is removed from the registry.

Parameters:

context - the context for which to allocate the index. Specify an empty OctetString for the default context.

indexDef - the index definition with OID values for sub-index definitions.

indexAllocationMode - one of AgentXProtocol.FLAG_ANY_INDEX, AgentXProtocol.FLAG_NEW_INDEX, or 0 (if index value is supplied by allocateIndex).

allocatedIndex - the index value to allocate or if indexAllocationMode is not zero then an (arbitrary non-null OID) which returns the allocated new index value. If allocateIndex is an instance of AnyNewIndexOID or NewIndexOID the index value of the row will be replaced by a globally unique index value allocated by the master agent. The caller is responsible for changing the row's index in the table model of the shared table.

Returns:

AgentXProtocol.AGENTX_SUCCESS if the index could be allocated or an AgentX protocol error code if allocation failed and allocateIndex is not altered.

handleIndexAllocationError

protected int handleIndexAllocationError(org.snmp4j.agent.mo.MOTableIndex indexDef,
                                         org.snmp4j.smi.OctetString context,
                                         org.snmp4j.smi.OID allocatedIndex,
                                         AgentXResponsePDU resp)

Handle an index allocation error. By default, this method simply returns the AgentX error status from the master agent response. By overwriting this method, sub-classes may ignore such errors (for example, if using some of the "always..." index strategies.

Parameters:

indexDef - the index definition for the index whose sub-index allocation failed.

context - the context of the allocation.

allocatedIndex - the index OID of the sub-index that failed to allocate.

resp - the AgentX reponse from the master agent.

Returns:

an AgentX error status or AgentXProtocol.AGENTX_SUCCESS to ignore the error.

Since:

2.1

deallocateIndex

public int deallocateIndex(org.snmp4j.smi.OctetString context,
                           org.snmp4j.agent.mo.MOTableIndex indexDef,
                           org.snmp4j.smi.OID allocatedIndex)

Deallocate an index at the master agent.

Parameters:

context - the context for which to allocate the index. Specify an empty OctetString for the default context.

indexDef - the index definition with OID values for sub-index definitions.

allocatedIndex - the index value of the previously allocated index.

Returns:

AgentXProtocol.AGENTX_SUCCESS if the index could be deallocated or an AgentX protocol error code if deallocation failed.

registerRow

public int registerRow(org.snmp4j.agent.mo.MOTable table,
                       R row2Register)

registerRow

public int registerRow(org.snmp4j.agent.mo.MOTable table,
                       R row2Register,
                       byte priority)

Register the necessary regions for a table row.

Parameters:

table - the MOTable to register rows for.

row2Register - the row to register.

priority - the priority (default is 127). A smaller value takes precedence over larger values.

Returns:

the AgentX status of the registration.

Since:

2.1

unregisterRow

public int unregisterRow(org.snmp4j.agent.mo.MOTable table,
                         R row2Unregister)

unregisterRow

public int unregisterRow(org.snmp4j.agent.mo.MOTable table,
                         R row2Unregister,
                         byte priority)

Removes the region registration of a table row.

Parameters:

table - the MOTable to register rows for.

row2Unregister - the row to unregister.

priority - the priority (default is 127). A smaller value takes precedence over larger values.

Returns:

the AgentX status of the registration.

Since:

2.1

setPriority

public void setPriority(byte priority)

Sets the priority for the region registrations made by this table support.

Parameters:

priority - the priority (default is 127). A smaller value takes precedence over larger values.

setSession

public void setSession(AgentXSession session)

Sets the AgentX session to be used for this shared table support.

Parameters:

session - an AgentXSession instance.

setIndexMode

public void setIndexMode(byte indexMode)

Sets the index mode to be used by this shared table support object. INDEX_MODE_ALLOCATE simply allocates index values at the master agent, whereas INDEX_MODE_ANY_INDEX fetches any currently unique index value from the master agent for a new row and INDEX_MODE_NEW_INDEX fetches a new index (never used before by the master).

Parameters:

indexMode - an index mode to be used for shared tables supported by this object.

setContext

public void setContext(org.snmp4j.smi.OctetString context)

getPriority

public byte getPriority()

getSession

public AgentXSession getSession()

Gets the AgentX session used by this shared table support object.

Returns:

an AgentXSession instance or null if there is no connection/session established with the master agent.

getIndexMode

public byte getIndexMode()

getContext

public org.snmp4j.smi.OctetString getContext()

getAgentX

public AgentX getAgentX()

getIndexStrategy

public AgentXSharedMOTableSupport.IndexStrategy getIndexStrategy()

Gets the index strategy of this shared table support.

Returns:

an AgentXSharedMOTableSupport.IndexStrategy instance.

Since:

2.1

setIndexStrategy

public void setIndexStrategy(AgentXSharedMOTableSupport.IndexStrategy indexStrategy)

Sets the index strategy for this shared table support. For most use cases the AgentXSharedMOTableSupport.IndexStrategy.firstSubIndexOnly strategy is recommended. With that strategy, only the first sub-index value will be allocated at the master agent if it has not yet been allocated by this table support (for any table). Unless you need to allocated sub-indexes by a multi-sub-index table, because there does not exists a shared table for the same session with that sub-index as first sub-index value, you should always use the AgentXSharedMOTableSupport.IndexStrategy.firstSubIndexOnly or AgentXSharedMOTableSupport.IndexStrategy.anyNonAllocatedSubIndex. The AgentXSharedMOTableSupport.IndexStrategy.anyNonAllocatedSubIndex should be used for a master and dependent table combination where the dependent table(s) extend the index of the master table by additional sub-indexes.

Parameters:

indexStrategy - the new index allocation/deallocation strategy.

Since:

2.1