Module org.snmp4j.agent
Package org.snmp4j.agent

Interface MOServer

All Known Implementing Classes:
DefaultMOServer
public interface MOServer
The managed object server interface defines the services that a repository of managed objects needs to provide for a command responder.
Version:
3.5.0
Author:
Frank Fock

  • Method Details

    • addContextListener

      void addContextListener(ContextListener listener)
      Adds a context listener to the server. The listener will be informed about context insertion and removal.
      Parameters:
      listener - a ContextListener instance to be informed about context changes.

    • removeContextListener

      void removeContextListener(ContextListener listener)
      Removes a previously added context listener.
      Parameters:
      listener - a ContextListener instance.

    • addContext

      void addContext(org.snmp4j.smi.OctetString context)
      Adds the supplied context to the server. The server however may silently ignore the request if local constraints do not allow to add the context (although this should be an exception case only).
      Parameters:
      context - an OctetString representing the context name to add.

    • removeContext

      void removeContext(org.snmp4j.smi.OctetString context)
      Removes a context from the server. Removing a context does not remove any managed objects from the server's registry.
      Parameters:
      context - n OctetString representing the context name to remove.

    • register

      void register(ManagedObject<?> mo, org.snmp4j.smi.OctetString context) throws DuplicateRegistrationException
      Registers a managed object for the specified context. A managed object can be registered for more than one context.
      Parameters:
      mo - a ManagedObject instance.
      context - the context name for which to register the mo or null if the managed oject is to be registered for all contexts (including the default context).
      Throws:
      DuplicateRegistrationException - if the registration conflicts (i.e. overlaps) with an already existing registration.

    • registerNew

      default boolean registerNew(ManagedObject<?> mo, org.snmp4j.smi.OctetString context)
      Registers a managed object for the specified context if it has not been registered already (otherwise it does nothing but returning false. A managed object can be registered for more than one context.
      Parameters:
      mo - a ManagedObject instance.
      context - the context name for which to register the mo or null if the managed oject is to be registered for all contexts (including the default context).
      Returns:
      if the registration was successful and false if it overlaps with an already existing registration.
      Since:
      3.0.2

    • unregister

      ManagedObject<?> unregister(ManagedObject<?> mo, org.snmp4j.smi.OctetString context)
      Removes the registration of the supplied managed object for the specified context.
      Parameters:
      mo - a ManagedObject instance.
      context - the context name for which to unregister the mo or null if the managed object is to be unregistered for all contexts (including the default context). In the latter case however, explicit registrations for a particular context will not be removed!
      Returns:
      the removed ManagedObjectinstance or null if the removal failed.

    • iterator

      default Iterator<Map.Entry<MOScope,ManagedObject<?>>> iterator(Comparator<MOScope> comparator)
      Return an Iterator on the registered ManagedObjects of this server in order defined by the given comparator.
      Parameters:
      comparator - the comparator that defines the order of the managed objects to be returned.
      Returns:
      the iterator a copy of the registry.
      Since:
      3.5.0

    • iterator

      Iterator<Map.Entry<MOScope,ManagedObject<?>>> iterator(Comparator<MOScope> comparator, MOFilter moFilter)
      Return an Iterator on the registered ManagedObjects of this server in order defined by the given comparator and filtered.
      Parameters:
      comparator - the comparator that defines the order of the managed objects to be returned.
      moFilter - if not null, only those managed objects are returned by this iterator that pass the specified filter.
      Returns:
      the iterator a copy of the registry.
      Since:
      3.5.0

    • addLookupListener

      void addLookupListener(MOServerLookupListener listener, ManagedObject<?> mo)
      Adds a managed object lookup listener for the supplied managed object to this managed object server. A MOServerLookupListener is called before the managed object is returned by lookup(MOQuery query).
      Parameters:
      listener - a MOServerLookupListener instance, for example a managed object that needs to update its state whenever it has been looked up
      mo - the ManagedObject that triggers the MOServerLookupEvent to be fired when it has been looked up.

    • removeLookupListener

      boolean removeLookupListener(MOServerLookupListener listener, ManagedObject<?> mo)
      Removes a managed object lookup listener for the specified managed object.
      Parameters:
      listener - a MOServerLookupListener instance.
      mo - the ManagedObject that triggered the MOServerLookupEvent to be fired when it has been looked up.
      Returns:
      true if the listener could be removed or false if such a listener is not registered.

    • lookup

      default ManagedObject<?> lookup(MOQuery query)
      Lookup the first (lexicographically ordered) managed object that matches the supplied query. No locking will be performed, regardless of the set MOLockStrategy.
      Parameters:
      query - a MOQuery instance.
      Returns:
      the ManagedObject that matches the query and null if no such object exists.

    • lookup

      default <MO extends ManagedObject<?>> MO lookup(MOQuery query, Class<MO> managedObjectType)
      Lookup the first (lexicographically ordered) managed object that matches the supplied query. No locking will be performed, regardless of the set MOLockStrategy.
      Type Parameters:
      MO - the ManagedObject type to lookup.
      Parameters:
      query - a MOQuery instance.
      managedObjectType - the ManagedObject implementation class that is supported by the caller. Use ManagedObject by default.
      Returns:
      the ManagedObject that matches the query and null if no such object exists.
      Since:
      3.1.0

    • lookup

      @Deprecated default ManagedObject<?> lookup(MOQuery query, LockRequest lockRequest)
      Deprecated.
      Use lookup(MOQuery, LockRequest, MOServerLookupEvent, Class) instead to specify the intended use, and event source.
      Lookup the first (lexicographically ordered) managed object that matches the supplied query. Locking will be performed according to the set MOLockStrategy before the lookup listener is fired. MOServerLookupEvents fired on behalf of this method call will report the request processing phase MOServerLookupEvent.IntendedUse.undefined. To accurately report the phase use lookup(MOQuery, LockRequest, MOServerLookupEvent) instead. CAUTION: To make sure that the acquired lock is released after the using of the managed object has been finished, the unlock(Object, ManagedObject) method must be called then.
      Parameters:
      query - a MOQuery instance.
      lockRequest - the LockRequest that holds the lock owner and the timeout for acquiring a lock and returns whether a lock has been acquired or not on behalf of this lookup operation.
      Returns:
      the ManagedObject that matches the query and null if no such object exists.
      Since:
      2.4.0

    • lookup

      default ManagedObject<?> lookup(MOQuery query, LockRequest lockRequest, MOServerLookupEvent lookupEvent)
      Lookup the first (lexicographically ordered) managed object that matches the supplied query. Locking will be performed according to the set MOLockStrategy before the lookup listener is fired. CAUTION: To make sure that the acquired lock is released after the using of the managed object has been finished, the unlock(Object, ManagedObject) method must be called then.
      Parameters:
      query - a MOQuery instance.
      lockRequest - the LockRequest that holds the lock owner and the timeout for acquiring a lock and returns whether a lock has been acquired or not on behalf of this lookup operation.
      lookupEvent - provides additional information about the intended use and optionally a callback to be informed about the completion of the use, including a reference to its result.
      Returns:
      the ManagedObject that matches the query and null if no such object exists.
      Since:
      3.0

    • lookup

      <MO extends ManagedObject<?>> MO lookup(MOQuery query, LockRequest lockRequest, MOServerLookupEvent lookupEvent, Class<MO> managedObjectType)
      Lookup the first (lexicographically ordered) managed object that matches the supplied query and implements the given ManagedObject class. Locking will be performed according to the set MOLockStrategy before the lookup listener is fired. CAUTION: To make sure that the acquired lock is released after the using of the managed object has been finished, the unlock(Object, ManagedObject) method must be called then.
      Type Parameters:
      MO - the ManagedObject type to lookup.
      Parameters:
      query - a MOQuery instance.
      lockRequest - the LockRequest that holds the lock owner and the timeout for acquiring a lock and returns whether a lock has been acquired or not on behalf of this lookup operation.
      lookupEvent - provides additional information about the intended use and optionally a callback to be informed about the completion of the use, including a reference to its result.
      managedObjectType - the ManagedObject implementation class that is supported by the caller. Use ManagedObject by default.
      Returns:
      the ManagedObject that matches the query and null if no such object exists.
      Since:
      3.1

    • iterator

      Iterator<Map.Entry<MOScope,ManagedObject<?>>> iterator()
      Return a read-only Iterator over the content of this server. The iterator is thread safe and can be used while the server is being modified. The remove operation of the iterator is not supported.
      Returns:
      the Iterator on the Map.Entry instances managed by this server. Each Entry consists of an MOScope key instance and a corresponding ManagedObject value instance. If the ManagedObject has been registered for a specific context, then a MOContextScope is returned as key, otherwise the managed objects own MOScope is returned.

    • lock

      boolean lock(Object owner, ManagedObject<?> managedObject)
      Locks a ManagedObject by the supplied owner. Once a ManagedObject is locked, a lookup attempt will block until it is unlocked or a predefined timeout occurs.
      Parameters:
      owner - an Object.
      managedObject - the ManagedObject to lock.
      Returns:
      true if the lock could be acquired, false otherwise, i.e. if an InterruptedException has occurred.

    • lock

      boolean lock(Object owner, ManagedObject<?> managedObject, long timeoutMillis)
      Locks a ManagedObject by the supplied owner. Once a ManagedObject is locked, a lookup attempt from another owner will block until it is unlocked or a predefined timeout occurs. The same owner can lock again recursively but has to unlock with the same number of calls to unlock(Object, ManagedObject) to actually release the lock. To release a lock for an owner immediately without unlocking recursively, call unlockNow(Object, ManagedObject).
      Parameters:
      owner - an Object.
      managedObject - the ManagedObject to lock.
      timeoutMillis - the number of 1/1000 seconds to wait for the lock. 0 or less disables the timeout and waits forever until the lock is released by the current owner.
      Returns:
      true if the lock could be acquired, false otherwise, i.e. if an InterruptedException or timeout has occurred.
      Since:
      1.3

    • unlock

      boolean unlock(Object owner, ManagedObject<?> managedObject)
      Unlocks a ManagedObject that has been locked by the specified owner. If the ManagedObject is currently locked by another owner this method returns silently.

      Note: In debug log mode a message is locked if the lock owner does not match the current lock owner.

      Parameters:
      owner - an Object.
      managedObject - the ManagedObject to unlock. If managedObject is null then this call has no effect.
      Returns:
      true if the lock has been found and released successfully, false otherwise.

    • waitForUnlockedState

      boolean waitForUnlockedState(long waitTimeoutMillis)
      Wait until this server has not active and pending locks anymore.
      Parameters:
      waitTimeoutMillis - the maximum time in milliseconds to wait for this server to become lock free.
      Returns:
      true if server has no active and waiting locks anymore, false otherwise.
      Since:
      3.7.0

    • unlockNow

      boolean unlockNow(Object owner, ManagedObject<?> managedObject)
      Unlocks a ManagedObject that has been locked by the specified owner. If the ManagedObject is currently locked by another owner this method returns silently. If the specified owner is identical with the current lock holder for the specified managed object, then the lock is removed regardless how many recursive lock.

      Note: In debug log mode a message is locked if the lock owner does not match the current lock owner.

      Parameters:
      owner - an Object that is owner of a lock and whose locks should be removed completely now.
      managedObject - the ManagedObject to forcibly unlock. If managedObject is null then this call has no effect.
      Returns:
      true if the lock has been found and completely released successfully, false otherwise.
      Since:
      3.7.0

    • getContexts

      org.snmp4j.smi.OctetString[] getContexts()
      Returns the contexts known by the server.
      Returns:
      an array of context names.

    • isContextSupported

      boolean isContextSupported(org.snmp4j.smi.OctetString context)
      Checks whether the supplied context is supported (registered) by this server.
      Parameters:
      context - a context name.
      Returns:
      true if the context is support (thus has previously added by addContext(org.snmp4j.smi.OctetString)) and false otherwise.

    • getRegisteredContexts

      org.snmp4j.smi.OctetString[] getRegisteredContexts(ManagedObject<?> managedObject)
      Returns the contexts for which the supplied ManagedObject has been registered.
      Parameters:
      managedObject - a ManagedObject instance.
      Returns:
      an array of context strings, for which managedObject has been registered. If the managedObject has been registered for all contexts, a null element is included in the array.
      Since:
      1.4

    • getRegisteredScopes

      Map<org.snmp4j.smi.OctetString,MOScope> getRegisteredScopes(ManagedObject<?> managedObject)
      Returns the scopes MOScope or MOContextScope for which the supplied ManagedObject has been registered in a map indexed by context.
      Parameters:
      managedObject - a ManagedObject instance.
      Returns:
      a possibly empty map of context to MOScope entries. A registration to the default ("one-registration-for-all-contexts") null context is returned with a null context key value.
      Since:
      3.5.0