org.snmp4j.agent.MOServer Maven / Gradle / Ivy
/*_############################################################################
_##
_## SNMP4J-Agent 2 - MOServer.java
_##
_## Copyright (C) 2005-2014 Frank Fock (SNMP4J.org)
_##
_## Licensed under the Apache License, Version 2.0 (the "License");
_## you may not use this file except in compliance with the License.
_## You may obtain a copy of the License at
_##
_## http://www.apache.org/licenses/LICENSE-2.0
_##
_## Unless required by applicable law or agreed to in writing, software
_## distributed under the License is distributed on an "AS IS" BASIS,
_## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
_## See the License for the specific language governing permissions and
_## limitations under the License.
_##
_##########################################################################*/
package org.snmp4j.agent;
import org.snmp4j.agent.mo.lock.LockRequest;
import org.snmp4j.smi.OctetString;
import java.util.Iterator;
import java.util.Map;
import org.snmp4j.smi.OID;
/**
* The managed object server interface defines the services that a repository
* of managed objects needs to provide for a command responder.
*
* @author Frank Fock
* @version 2.1
*/
public interface MOServer {
/**
* Adds a context listener to the server. The listener will be informed about
* context insertion and removal.
* @param listener
* a ContextListener instance to be informed about context
* changes.
*/
void addContextListener(ContextListener listener);
/**
* Removes a previously added context listener.
* @param listener
* a ContextListener instance.
*/
void removeContextListener(ContextListener listener);
/**
* 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).
* @param context
* an OctetString representing the context name to add.
*/
void addContext(OctetString context);
/**
* Removes a context from the server. Removing a context does not remove
* any managed objects from the server's registry.
* @param context
* n OctetString representing the context name to remove.
*/
void removeContext(OctetString context);
/**
* Registers a managed object for the specified context. A managed object can
* be registered for more than one context.
* @param mo
* a ManagedObject instance.
* @param 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.
*/
void register(ManagedObject mo, OctetString context)
throws DuplicateRegistrationException;
/**
* Removes the registration of the supplied managed object for the specified
* context.
* @param mo
* a ManagedObject instance.
* @param 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!
* @return
* the removed {@link ManagedObject}instance or null if
* the removal failed.
*/
ManagedObject unregister(ManagedObject mo, OctetString context);
/**
* 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 {@link #lookup(MOQuery query)}.
*
* @param listener
* a MOServerLookupListener instance, for example a managed
* object that needs to update its state whenever it has been looked up
* @param mo
* the ManagedObject that triggers the
* {@link MOServerLookupEvent} to be fired when it has been looked up.
*/
void addLookupListener(MOServerLookupListener listener,
ManagedObject mo);
/**
* Removes a managed object lookup listener for the specified managed object.
* @param listener
* a MOServerLookupListener instance.
* @param mo
* the ManagedObject that triggered the
* {@link MOServerLookupEvent} to be fired when it has been looked up.
* @return
* true if the listener could be removed or false
* if such a listener is not registered.
*/
boolean removeLookupListener(MOServerLookupListener listener,
ManagedObject mo);
/**
* Lookup the first (lexicographically ordered) managed object that matches
* the supplied query. No locking will be performed, regardless of the
* set {@link org.snmp4j.agent.mo.lock.MOLockStrategy}.
* @param query
* a MOQuery instance.
* @return
* the ManagedObject that matches the query and
* null if no such object exists.
*/
ManagedObject lookup(MOQuery query);
/**
* Lookup the first (lexicographically ordered) managed object that matches
* the supplied query. Locking will be performed according to the
* set {@link org.snmp4j.agent.mo.lock.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 {@link #unlock(Object, ManagedObject)}
* method must be called then.
* @param query
* a MOQuery instance.
* @param lockRequest
* the {@link 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.
* @return
* the ManagedObject that matches the query and
* null if no such object exists.
* @since 2.4.0
*/
ManagedObject lookup(MOQuery query, LockRequest lockRequest);
/**
* 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.
* @return
* the Iterator on the Map.Entry instances managed by
* this server. Each Entry consists of an {@link MOScope}
* key instance and a corresponding {@link ManagedObject} value instance.
* If the ManagedObject has been registered for a specific
* context, then a {@link MOContextScope} is returned as key, otherwise
* the managed objects own MOScope is returned.
*/
Iterator> iterator();
/**
* 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.
* @param owner
* an Object.
* @param managedObject
* the ManagedObject to lock.
* @return
* true if the lock could be acquired, false
* otherwise, i.e. if an InterruptedException has occurred.
*/
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.
* @param owner
* an Object.
* @param managedObject
* the ManagedObject to lock.
* @param 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.
* @return
* true if the lock could be acquired, false
* otherwise, i.e. if an InterruptedException or timeout has occurred.
* @since 1.3
*/
boolean lock(Object owner, ManagedObject managedObject, long timeoutMillis);
/**
* 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.
* @param owner
* an Object.
* @param managedObject
* the ManagedObject to unlock. If managedObject is null
* then this call has no effect.
* @return
* true if the lock has been found and released successfully,
* false otherwise.
*/
boolean unlock(Object owner, ManagedObject managedObject);
/**
* Returns the contexts known by the server.
* @return
* an array of context names.
*/
OctetString[] getContexts();
/**
* Checks whether the supplied context is supported (registered) by this
* server.
* @param context
* a context name.
* @return
* true if the context is support (thus has previously added
* by {@link #addContext}) and false otherwise.
*/
boolean isContextSupported(OctetString context);
/**
* Returns the contexts for which the supplied {@link ManagedObject} has been
* registered.
* @param managedObject
* a {@link ManagedObject} instance.
* @return
* 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
*/
OctetString[] getRegisteredContexts(ManagedObject managedObject);
}