Class SubagentXConfigManager

java.lang.Object
org.snmp4j.agent.agentx.subagent.SubagentXConfigManager
All Implemented Interfaces:
Runnable, org.snmp4j.agent.mo.util.VariableProvider
public abstract class SubagentXConfigManager extends Object implements Runnable, org.snmp4j.agent.mo.util.VariableProvider
The SubagentXConfigManager is the main component of a SNMP4J AgentX Subagent. It puts together agent configuration and agent components like command processor, message dispatcher, managed objects and server.
Since:
3.0.0
Version:
3.0.0
Author:
Frank Fock

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    class 
    SubagentXConfigManager.AgentState
    The AgentState maintains the current run state of this agent and the list of errors that occurred since the agent was launched.
    static class 
    SubagentXConfigManager.ErrorDescriptor
    The ErrorDescriptor describes an error that occurred during an agent state transition, including the causing exception and the source and target states involved.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected AgentXCommandListener
    agent
    The AgentX command listener that handles incoming AgentX packages and manages the associated AgentX sessions.
    protected List<org.snmp4j.agent.AgentStateListener<SubagentXConfigManager>>
    agentStateListeners
    The list of listeners that are notified about agent state changes.
    protected org.snmp4j.agent.io.MOInputFactory
    configuration
    The factory that provides the MOInput stream with the serialized agent configuration, or null if no configuration is loaded.
    protected org.snmp4j.smi.OctetString
    defaultContext
    The default SNMPv3 context of this agent.
    protected AgentXMessageDispatcher
    dispatcher
    The AgentX message dispatcher used to send and receive AgentX messages.
    protected org.snmp4j.agent.mo.MOFactory
    moFactory
    The factory used to create the managed objects of this agent.
    protected org.snmp4j.agent.NotificationOriginator
    notificationOriginator
    The notification originator used to emit notifications, or null if notifications are not supported.
    protected int
    persistenceImportMode
    The import mode used when restoring persistent managed objects.
    protected org.snmp4j.agent.io.MOPersistenceProvider
    persistenceProvider
    The primary persistence provider used to load and store persistent managed objects.
    protected org.snmp4j.agent.mo.MOPriorityProvider
    priorityProvider
    The provider that defines the order in which managed objects are persisted.
    protected SubagentXConfigManager.AgentState
    runState
    The current run state of this agent.
    protected org.snmp4j.agent.MOServer[]
    servers
    The managed object server(s) that serve the managed objects available to this agent.
    protected org.snmp4j.agent.mo.util.MOTableSizeLimit<org.snmp4j.agent.mo.MOTableRow>
    tableSizeLimit
    An optional table size limit that restricts the maximum number of rows of managed object tables, or null if unlimited.
    protected org.snmp4j.util.WorkerPool
    workerPool
    The worker pool used to process incoming requests concurrently.

  • Constructor Summary

    Constructors
    Constructor
    Description
    SubagentXConfigManager(AgentXCommandListener agentXCommandListener, AgentXMessageDispatcher messageDispatcher, org.snmp4j.agent.MOServer[] moServers, org.snmp4j.util.WorkerPool workerPool, org.snmp4j.agent.io.MOInputFactory configurationFactory, org.snmp4j.agent.io.MOPersistenceProvider persistenceProvider, org.snmp4j.agent.mo.MOFactory moFactory)
    Creates a SNMP agent configuration which can be run by calling run() later.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addAgentStateListener(org.snmp4j.agent.AgentStateListener<SubagentXConfigManager> agentStateListener)
    Adds a listener that is notified whenever the state of this agent changes.
    void
    configure()
    Configures components and managed objects.
    boolean
    continueProcessing()
    Continues processing of SNMP requests by coupling message dispatcher and agent.
    protected void
    fireAgentStateChange()
    Notifies all registered AgentStateListeners about the current state of this agent.
    protected void
    fireLaunchNotifications()
    Fire notifications after agent start, i.e. sending a coldStart trap.
    protected org.snmp4j.smi.OctetString
    getContext(org.snmp4j.agent.MOGroup mibGroup, org.snmp4j.smi.OctetString defaultContext)
    This method can be overwritten by a subagent to specify the contexts each MIB module (group) will be registered to.
    org.snmp4j.smi.OctetString
    getDefaultContext()
    Returns the default context - which is the context that is used by the base agent to register its MIB objects.
    int
    getPersistenceImportMode()
    Returns the currently active import mode for the MOPersistenceProvider.
    org.snmp4j.agent.mo.MOPriorityProvider
    getPriorityProvider()
    Gets the priority provider defining the order of storing and restoring persistent data.
    org.snmp4j.agent.MOServer
    getServer(org.snmp4j.smi.OctetString context)
    Get the MOServer associated with the given context.
    org.snmp4j.agent.MOServer[]
    getServers()
    Gets the managed object servers of this agent.
    org.snmp4j.agent.AgentState
    getState()
    Returns the state of the agent.
    org.snmp4j.smi.Variable
    getVariable(String name)
     
    org.snmp4j.util.WorkerPool
    getWorkerPool()
    Gets the worker pool of this agent.
    void
    initialize()
    Initialize the agent by registering all MIB modules.
    protected void
    launch()
    Launch the agent by registering and launching (i.e., set to listen mode) transport mappings.
    abstract void
    launchAgentXSessions()
    Establish AgentX connection to one or more AgentX master agents by implementing this method.
    protected void
    launchTransportMappings()
    Launch the transport mappings.
    protected static void
    launchTransportMappings(Collection<? extends org.snmp4j.TransportMapping<?>> transportMappings)
    Puts a list of transport mappings into listen mode.
    protected void
    linkCounterListener()
    Hook method for overriding in sub-classes that is called by initialize() before registerMIBs(OctetString).
    protected void
    registerMIBs(org.snmp4j.smi.OctetString context)
    Register the initialized MIB modules in the specified context of the agent.
    void
    registerShutdownHook()
    Registers a shutdown hook Thread at the Runtime instance.
    boolean
    removeAgentStateListener(org.snmp4j.agent.AgentStateListener<SubagentXConfigManager> agentStateListener)
    Removes a previously added agent state change listener.
    boolean
    restoreState()
    Restore a previously persistently saved state - if available.
    void
    run()
    Initializes, configures, restores agent state, and then launches the SNMP agent depending on its current run state.
    boolean
    saveState()
    Save the state of the agent persistently - if necessary persistent storage is available.
    void
    setPersistenceImportMode(int importMode)
    Sets the import mode for the MOPersistenceProvider.
    void
    setPriorityProvider(org.snmp4j.agent.mo.MOPriorityProvider priorityProvider)
    Sets the MOPriorityProvider that defines in which order ManagedObjects of this sub-agent are stored and restored.
    void
    setTableSizeLimit(int sizeLimit)
    Sets the table size limit for the tables in this agent.
    void
    setTableSizeLimits(Properties sizeLimits)
    Sets the table size limits for the tables in this agent.
    void
    shutdown()
    Shutdown the agent by closing the internal SNMP session - including the transport mappings provided through the configured MessageDispatcher and then store the agent state to persistent storage (if available).
    protected static void
    stopTransportMappings(Collection<? extends org.snmp4j.TransportMapping<?>> transportMappings)
    Closes a list of transport mappings.
    void
    suspendProcessing()
    Suspends processing of SNMP requests.
    protected void
    unregisterMIBs(org.snmp4j.smi.OctetString context)
    Unregister the initialized MIB modules from the default context of the agent.

    Methods inherited from class Object

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

  • Field Details

    • agent

      protected AgentXCommandListener agent
      The AgentX command listener that handles incoming AgentX packages and manages the associated AgentX sessions.

    • workerPool

      protected org.snmp4j.util.WorkerPool workerPool
      The worker pool used to process incoming requests concurrently.

    • servers

      protected org.snmp4j.agent.MOServer[] servers
      The managed object server(s) that serve the managed objects available to this agent.

    • dispatcher

      protected AgentXMessageDispatcher dispatcher
      The AgentX message dispatcher used to send and receive AgentX messages.

    • notificationOriginator

      protected org.snmp4j.agent.NotificationOriginator notificationOriginator
      The notification originator used to emit notifications, or null if notifications are not supported.

    • configuration

      protected org.snmp4j.agent.io.MOInputFactory configuration
      The factory that provides the MOInput stream with the serialized agent configuration, or null if no configuration is loaded.

    • persistenceProvider

      protected org.snmp4j.agent.io.MOPersistenceProvider persistenceProvider
      The primary persistence provider used to load and store persistent managed objects.

    • persistenceImportMode

      protected int persistenceImportMode
      The import mode used when restoring persistent managed objects.

    • priorityProvider

      protected org.snmp4j.agent.mo.MOPriorityProvider priorityProvider
      The provider that defines the order in which managed objects are persisted.

    • moFactory

      protected org.snmp4j.agent.mo.MOFactory moFactory
      The factory used to create the managed objects of this agent.

    • defaultContext

      protected org.snmp4j.smi.OctetString defaultContext
      The default SNMPv3 context of this agent.

    • runState

      protected SubagentXConfigManager.AgentState runState
      The current run state of this agent.

    • tableSizeLimit

      protected org.snmp4j.agent.mo.util.MOTableSizeLimit<org.snmp4j.agent.mo.MOTableRow> tableSizeLimit
      An optional table size limit that restricts the maximum number of rows of managed object tables, or null if unlimited.

    • agentStateListeners

      protected List<org.snmp4j.agent.AgentStateListener<SubagentXConfigManager>> agentStateListeners
      The list of listeners that are notified about agent state changes.

  • Constructor Details

    • SubagentXConfigManager

      public SubagentXConfigManager(AgentXCommandListener agentXCommandListener, AgentXMessageDispatcher messageDispatcher, org.snmp4j.agent.MOServer[] moServers, org.snmp4j.util.WorkerPool workerPool, org.snmp4j.agent.io.MOInputFactory configurationFactory, org.snmp4j.agent.io.MOPersistenceProvider persistenceProvider, org.snmp4j.agent.mo.MOFactory moFactory)
      Creates a SNMP agent configuration which can be run by calling run() later.
      Parameters:
      agentXCommandListener - the AgentXCommandListener that handles the AgentX packages and that is able to close all AgentXSessions.
      messageDispatcher - the MessageDispatcher to use. The message dispatcher must be configured outside, i.e. transport mappings have to be added before this constructor is being called.
      moServers - the managed object server(s) that serve the managed objects available to this agent.
      workerPool - the WorkerPool to be used to process incoming request.
      configurationFactory - a MOInputFactory that creates a MOInput stream with containing serialized ManagedObject information with the agent's configuration or null otherwise.
      persistenceProvider - the primary MOPersistenceProvider to be used to load and store persistent MOs.
      moFactory - the MOFactory to be used to create ManagedObjects created by this config manager. If null the DefaultMOFactory will be used.

  • Method Details

    • getWorkerPool

      public org.snmp4j.util.WorkerPool getWorkerPool()
      Gets the worker pool of this agent.
      Returns:
      the internal worker pool.

    • run

      public void run()
      Initializes, configures, restores agent state, and then launches the SNMP agent depending on its current run state. For example, if initialize() has not yet been called it will be called before the agent is being configured in the next step.

      See also initialize(), configure(), restoreState(), and launch().

      Specified by:
      run in interface Runnable

    • addAgentStateListener

      public void addAgentStateListener(org.snmp4j.agent.AgentStateListener<SubagentXConfigManager> agentStateListener)
      Adds a listener that is notified whenever the state of this agent changes.
      Parameters:
      agentStateListener - the listener to add.

    • removeAgentStateListener

      public boolean removeAgentStateListener(org.snmp4j.agent.AgentStateListener<SubagentXConfigManager> agentStateListener)
      Removes a previously added agent state change listener.
      Parameters:
      agentStateListener - the listener to remove.
      Returns:
      true if the listener was registered and has been removed, false otherwise.

    • fireAgentStateChange

      protected void fireAgentStateChange()
      Notifies all registered AgentStateListeners about the current state of this agent.

    • getServer

      public org.snmp4j.agent.MOServer getServer(org.snmp4j.smi.OctetString context)
      Get the MOServer associated with the given context.
      Parameters:
      context - a SNMPv3 context or null (or empty OctetString) for the default context.
      Returns:
      the associated MOServer for the context that acutally also supports the context or null otherwise.

    • getServers

      public org.snmp4j.agent.MOServer[] getServers()
      Gets the managed object servers of this agent.
      Returns:
      the array of MOServer instances that serve the managed objects of this agent.

    • getState

      public org.snmp4j.agent.AgentState getState()
      Returns the state of the agent.
      Returns:
      a AgentState instance.

    • launch

      protected void launch()
      Launch the agent by registering and launching (i.e., set to listen mode) transport mappings.

    • launchAgentXSessions

      public abstract void launchAgentXSessions() throws IOException
      Establish AgentX connection to one or more AgentX master agents by implementing this method.
      Throws:
      IOException - if the session(s) cannot be established due to IO error and the agent should not advance to the state AgentState.STATE_RUNNING.

    • fireLaunchNotifications

      protected void fireLaunchNotifications()
      Fire notifications after agent start, i.e. sending a coldStart trap.

    • continueProcessing

      public boolean continueProcessing()
      Continues processing of SNMP requests by coupling message dispatcher and agent. To succeed, the current state of the agent must be AgentState.STATE_SUSPENDED.
      Returns:
      true if the running state could be restored, false otherwise.

    • suspendProcessing

      public void suspendProcessing()
      Suspends processing of SNMP requests. This call decouples message dispatcher and agent. All transport mappings remain unchanged and thus all ports remain opened.

    • shutdown

      public void shutdown()
      Shutdown the agent by closing the internal SNMP session - including the transport mappings provided through the configured MessageDispatcher and then store the agent state to persistent storage (if available).

    • registerShutdownHook

      public void registerShutdownHook()
      Registers a shutdown hook Thread at the Runtime instance.

    • launchTransportMappings

      protected void launchTransportMappings() throws IOException
      Launch the transport mappings. By default launchTransportMappings(Collection) is called with the transport mappings of the dispatcher.
      Throws:
      IOException - if a transport mapping throws an IOException of TransportMapping.listen().

    • launchTransportMappings

      protected static void launchTransportMappings(Collection<? extends org.snmp4j.TransportMapping<?>> transportMappings) throws IOException
      Puts a list of transport mappings into listen mode.
      Parameters:
      transportMappings - a list of TransportMapping instances.
      Throws:
      IOException - if a transport cannot listen to incoming messages.

    • stopTransportMappings

      protected static void stopTransportMappings(Collection<? extends org.snmp4j.TransportMapping<?>> transportMappings) throws IOException
      Closes a list of transport mappings.
      Parameters:
      transportMappings - a list of TransportMapping instances.
      Throws:
      IOException - if a transport cannot be closed.

    • saveState

      public boolean saveState()
      Save the state of the agent persistently - if necessary persistent storage is available.
      Returns:
      true if state has been saved successfully, false is returned if an error occurred or no persistenceProvider is set. The error details can be found in the runState object.

    • restoreState

      public boolean restoreState()
      Restore a previously persistently saved state - if available.
      Returns:
      true if the agent state could be restored successfully, false otherwise.

    • configure

      public void configure()
      Configures components and managed objects.

    • linkCounterListener

      protected void linkCounterListener()
      Hook method for overriding in sub-classes that is called by initialize() before registerMIBs(OctetString). This method does nothing by default.

    • initialize

      public void initialize()
      Initialize the agent by registering all MIB modules.

    • setTableSizeLimits

      public void setTableSizeLimits(Properties sizeLimits)
      Sets the table size limits for the tables in this agent. If this method is called while the agent's registration is being changed, a ConcurrentModificationException might be thrown.
      Parameters:
      sizeLimits - a set of properties as defined by MOTableSizeLimit.
      Since:
      1.4

    • setTableSizeLimit

      public void setTableSizeLimit(int sizeLimit)
      Sets the table size limit for the tables in this agent. If this method is called while the agent's registration is being changed, a ConcurrentModificationException might be thrown.
      Parameters:
      sizeLimit - the maximum size (numer of rows) of tables allowed for this agent.
      Since:
      1.4

    • getDefaultContext

      public org.snmp4j.smi.OctetString getDefaultContext()
      Returns the default context - which is the context that is used by the base agent to register its MIB objects. By default it is null which causes the objects to be registered virtually for all contexts. In that case, subagents for example my not register their own objects under the same subtree(s) in any context. To allow subagents to register their own instances of those MIB modules, an empty OctetString should be used as default context instead.
      Returns:
      null or an OctetString (normally the empty string) denoting the context used for registering default MIBs.

    • getContext

      protected org.snmp4j.smi.OctetString getContext(org.snmp4j.agent.MOGroup mibGroup, org.snmp4j.smi.OctetString defaultContext)
      This method can be overwritten by a subagent to specify the contexts each MIB module (group) will be registered to.
      Parameters:
      mibGroup - a group of ManagedObjects (i.e., a MIB module).
      defaultContext - the context to be used by default (i.e., the null context)
      Returns:
      the context for which the module should be registered.

    • registerMIBs

      protected void registerMIBs(org.snmp4j.smi.OctetString context) throws org.snmp4j.agent.DuplicateRegistrationException
      Register the initialized MIB modules in the specified context of the agent.
      Parameters:
      context - the context to register the internal MIB modules. This should be null by default.
      Throws:
      org.snmp4j.agent.DuplicateRegistrationException - if some of the MIB modules registration regions conflict with already registered regions.

    • unregisterMIBs

      protected void unregisterMIBs(org.snmp4j.smi.OctetString context)
      Unregister the initialized MIB modules from the default context of the agent.
      Parameters:
      context - the context where the MIB modules have been previously registered.

    • getPriorityProvider

      public org.snmp4j.agent.mo.MOPriorityProvider getPriorityProvider()
      Gets the priority provider defining the order of storing and restoring persistent data.
      Returns:
      a MOPriorityProvider instance.

    • setPriorityProvider

      public void setPriorityProvider(org.snmp4j.agent.mo.MOPriorityProvider priorityProvider)
      Sets the MOPriorityProvider that defines in which order ManagedObjects of this sub-agent are stored and restored. A defined order can be important for initializing dependent objects and to avoid security issues during restore operations.
      Parameters:
      priorityProvider - a MOPriorityProvider or null if the default lexicographic order by OID should be applied.
      Since:
      3.5.0

    • setPersistenceImportMode

      public void setPersistenceImportMode(int importMode)
      Sets the import mode for the MOPersistenceProvider.
      Parameters:
      importMode - one of the import modes defined by ImportMode.

    • getPersistenceImportMode

      public int getPersistenceImportMode()
      Returns the currently active import mode for the MOPersistenceProvider.
      Returns:
      one of the import modes defined by ImportMode.

    • getVariable

      public org.snmp4j.smi.Variable getVariable(String name)
      Specified by:
      getVariable in interface org.snmp4j.agent.mo.util.VariableProvider