KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > snmp4j > agent > MOServer


1 /*_############################################################################
2   _##
3   _## SNMP4J-Agent - MOServer.java
4   _##
5   _## Copyright (C) 2005-2007 Frank Fock (SNMP4J.org)
6   _##
7   _## Licensed under the Apache License, Version 2.0 (the "License");
8   _## you may not use this file except in compliance with the License.
9   _## You may obtain a copy of the License at
10   _##
11   _## http://www.apache.org/licenses/LICENSE-2.0
12   _##
13   _## Unless required by applicable law or agreed to in writing, software
14   _## distributed under the License is distributed on an "AS IS" BASIS,
15   _## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16   _## See the License for the specific language governing permissions and
17   _## limitations under the License.
18   _##
19   _##########################################################################*/
20
21
22 package org.snmp4j.agent;
23
24 import org.snmp4j.smi.OctetString;
25 import java.util.Iterator JavaDoc;
26 import org.snmp4j.smi.OID;
27
28 /**
29  * The managed object server interface defines the services that a repository
30  * of managed objects needs to provide for a command responder.
31  *
32  * @author Frank Fock
33  * @version 1.0
34  */
35 public interface MOServer {
36
37   /**
38    * Adds a context listener to the server. The listener will be informed about
39    * context insertion and removal.
40    * @param listener
41    * a <code>ContextListener</code> instance to be informed about context
42    * changes.
43    */
44   void addContextListener(ContextListener listener);
45
46   /**
47    * Removes a previously added context listener.
48    * @param listener
49    * a <code>ContextListener</code> instance.
50    */
51   void removeContextListener(ContextListener listener);
52
53   /**
54    * Adds the supplied context to the server. The server however may silently
55    * ignore the request if local constraints do not allow to add the context
56    * (although this should be an exception case only).
57    * @param context
58    * an <code>OctetString</code> representing the context name to add.
59    */
60   void addContext(OctetString context);
61
62   /**
63    * Removes a context from the server. Removing a context does not remove
64    * any managed objects from the server's registry.
65    * @param context
66    * n <code>OctetString</code> representing the context name to remove.
67    */
68   void removeContext(OctetString context);
69
70   /**
71    * Registers a managed object for the specified context. A managed object can
72    * be registered for more than one context.
73    * @param mo
74    * a <code>ManagedObject</code> instance.
75    * @param context
76    * the context name for which to register the <code>mo</code> or
77    * <code>null</code> if the managed oject is to be registered for all
78    * contexts (including the default context).
79    * @throws DuplicateRegistrationException
80    * if the registration conflicts (i.e. overlaps) with an already existing
81    * registration.
82    */
83   void register(ManagedObject mo, OctetString context)
84       throws DuplicateRegistrationException;
85
86   /**
87    * Removes the registration of the supplied managed object for the specified
88    * context.
89    * @param mo
90    * a <code>ManagedObject</code> instance.
91    * @param context
92    * the context name for which to unregister the <code>mo</code> or
93    * <code>null</code> if the managed oject is to be unregistered for all
94    * contexts (including the default context). In the latter case however,
95    * explicit registrations for a particular context will not be removed!
96    */
97   void unregister(ManagedObject mo, OctetString context);
98
99   /**
100    * Adds a managed object lookup listener for the supplied managed object to
101    * this managed object server. A <code>MOServerLookupListener</code> is called
102    * before the managed object is returned by {@link #lookup(MOQuery query)}.
103    *
104    * @param listener
105    * a <code>MOServerLookupListener</code> instance, for example a managed
106    * object that needs to update its state whenever it has been looked up
107    * @param mo
108    * the <code>ManagedObject</code> that triggers the
109    * {@link MOServerLookupEvent} to be fired when it has been looked up.
110    */
111   void addLookupListener(MOServerLookupListener listener,
112                          ManagedObject mo);
113
114   /**
115    * Removes a managed object lookup listener for the specified managed object.
116    * @param listener
117    * a <code>MOServerLookupListener</code> instance.
118    * @param mo
119    * the <code>ManagedObject</code> that triggered the
120    * {@link MOServerLookupEvent} to be fired when it has been looked up.
121    * @return
122    * <code>true</code> if the listener could be removed or <code>false</code>
123    * if such a listener is not registered.
124    */
125   boolean removeLookupListener(MOServerLookupListener listener,
126                                ManagedObject mo);
127
128   /**
129    * Lookups the first (lexicographically ordered) managed object that matches
130    * the supplied query.
131    * @param query
132    * a <code>MOQuery</code> instance.
133    * @return
134    * the <code>ManagedObject</code> that matches the query and
135    * <code>null</code> if no such object exists.
136    */
137   ManagedObject lookup(MOQuery query);
138
139   /**
140    * Returns an <code>Iterator</code> over the content of this server.
141    * @return
142    * the <code>Iterator</code>.
143    */
144   Iterator JavaDoc iterator();
145
146   /**
147    * Locks a ManagedObject by the supplied owner. Once a ManagedObject is
148    * locked, a lookup attempt will block until it is unlocked or a predefined
149    * timeout occurs.
150    * @param owner
151    * an Object.
152    * @param managedObject
153    * the ManagedObject to lock.
154    */
155   void lock(Object JavaDoc owner, ManagedObject managedObject);
156
157   /**
158    * Unlocks a ManagedObject that has been locked by the specified owner. If
159    * the ManagedObject is currently locked by another owner this method returns
160    * silently.
161    * <p>
162    * Note: In debug log mode a message is locked if the lock owner does not
163    * match the current lock owner.
164    * @param owner
165    * an Object.
166    * @param managedObject
167    * the ManagedObject to unlock.
168    */
169   void unlock(Object JavaDoc owner, ManagedObject managedObject);
170
171   /**
172    * Returns the contexts known by the server.
173    * @return
174    * an array of context names.
175    */
176   OctetString[] getContexts();
177
178   /**
179    * Checks whether the supplied context is supported (registered) by this
180    * server.
181    * @param context
182    * a context name.
183    * @return
184    * <code>true</code> if the context is support (thus has previously added
185    * by {@link #addContext}) and <code>false</code> otherwise.
186    */
187   boolean isContextSupported(OctetString context);
188 }
189
Popular Tags