SnmpMibGroup


1   /* 
2    * @(#)file      SnmpMibGroup.java 
3    * @(#)author    Sun Microsystems, Inc. 
4    * @(#)version   1.24 
5    * @(#)date      08/02/09 
6    * 
7    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
8    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
9    */ 
10  
11  package com.sun.jmx.snmp.agent;
12  
13  // java imports
14  // 
15  import java.io.Serializable  ;
16  import java.util.Hashtable  ;
17  import java.util.Enumeration  ;
18  import java.util.Vector  ;
19  
20  // jmx imports
21  //
22  import com.sun.jmx.snmp.SnmpOid;
23  import com.sun.jmx.snmp.SnmpValue;
24  import com.sun.jmx.snmp.SnmpVarBind;
25  import com.sun.jmx.snmp.SnmpStatusException;
26  
27  // SNMP Runtime imports
28  //
29  import com.sun.jmx.snmp.agent.SnmpMibOid;
30  import com.sun.jmx.snmp.agent.SnmpMibNode;
31  
32  /**
33   * Represents a node in an SNMP MIB which corresponds to a group.
34   * This class allows subnodes to be registered below a group, providing
35   * support for nested groups. The subnodes are registered at run time
36   * when registering the nested groups in the global MIB OID tree.
37   * <P>
38   * This class is used by the class generated by <CODE>mibgen</CODE>.
39   * You should not need to use this class directly.
40   *
41   * <p><b>This API is a Sun Microsystems internal API  and is subject 
42   * to change without notice.</b></p>
43   * @version     4.3     10/29/99
44   * @author      Sun Microsystems, Inc
45   */
46  
47  public abstract class SnmpMibGroup extends SnmpMibOid 
48      implements Serializable   {
49  
50      // We will register the OID arcs leading to subgroups in this hashtable.
51      // So for each arc in varList, if the arc is also in subgroups, it leads
52      // to a subgroup, if it is not in subgroup, it leads either to a table
53      // or to a variable.
54      protected Hashtable   subgroups = null;
55  
56      /**
57       * Tells whether the given arc identifies a table in this group.
58       *
59       * @param arc An OID arc.
60       *
61       * @return <CODE>true</CODE> if `arc' leads to a table.
62       */
63      public abstract boolean      isTable(long arc);
64  
65      /**
66       * Tells whether the given arc identifies a variable (scalar object) in 
67       * this group.
68       *
69       * @param arc An OID arc.
70       *
71       * @return <CODE>true</CODE> if `arc' leads to a variable.
72       */
73      public abstract boolean      isVariable(long arc);
74  
75      /**
76       * Tells whether the given arc identifies a readable scalar object in 
77       * this group.
78       *
79       * @param arc An OID arc.
80       *
81       * @return <CODE>true</CODE> if `arc' leads to a readable variable.
82       */
83      public abstract boolean      isReadable(long arc);
84  
85  
86      /**
87       * Gets the table identified by the given `arc'.
88       *
89       * @param arc An OID arc.
90       *
91       * @return The <CODE>SnmpMibTable</CODE> identified by `arc', or 
92       *    <CODE>null</CODE> if `arc' does not identify any table.
93       */
94      public abstract SnmpMibTable getTable(long arc);
95  
96      /**
97       * Checks whether the given OID arc identifies a variable (scalar 
98       * object).
99       *
100      * @exception If the given `arc' does not identify any variable in this
101      *    group, throws an SnmpStatusException.
102      */
103     public void validateVarId(long arc, Object   userData) 
104     throws SnmpStatusException {
105     if (isVariable(arc) == false) 
106         throw noSuchObjectException;
107     }
108     
109     
110     // -------------------------------------------------------------------
111     // We use a hashtable (subgroup) in order to determine whether an
112     // OID arc leads to a subgroup. This implementation can be changed if 
113     // needed...
114     // For instance, the subclass could provide a generated isNestedArc() 
115     // method in which the subgroup OID arcs would be hardcoded.
116     // However, the generic approach was prefered because at this time
117     // groups and subgroups are dynamically registered in the MIB.
118     //
119     /**
120      * Tell whether the given OID arc identifies a sub-tree
121      * leading to a nested SNMP sub-group. This method is used internally.
122      * You shouldn't need to call it directly.
123      *
124      * @param arc An OID arc.
125      *
126      * @return <CODE>true</CODE> if the given OID arc identifies a subtree
127      * leading to a nested SNMP sub-group.
128      *
129      */
130     public boolean isNestedArc(long arc) {
131     if (subgroups == null) return false;
132     Object   obj = subgroups.get(new Long  (arc));
133         // if the arc is registered in the hashtable, 
134     // it leads to a subgroup.
135     return (obj != null);
136     }
137 
138     /**
139      * Generic handling of the <CODE>get</CODE> operation.
140      * <p>The actual implementation of this method will be generated
141      * by mibgen. Usually, this implementation only delegates the
142      * job to some other provided runtime class, which knows how to
143      * access the MBean. The current toolkit thus provides two 
144      * implementations:
145      * <ul><li>The standard implementation will directly access the
146      *         MBean through a java reference,</li>
147      *     <li>The generic implementation will access the MBean through
148      *         the MBean server.</li>
149      * </ul>
150      * <p>Both implementations rely upon specific - and distinct, set of
151      * mibgen generated methods.
152      * <p> You can override this method if you need to implement some
153      * specific policies for minimizing the accesses made to some remote
154      * underlying resources.
155      * <p>
156      *
157      * @param req   The sub-request that must be handled by this node.
158      *
159      * @param depth The depth reached in the OID tree.
160      *
161      * @exception SnmpStatusException An error occurred while accessing 
162      *  the MIB node.
163      */
164     abstract public void get(SnmpMibSubRequest req, int depth) 
165     throws SnmpStatusException;
166 
167     /**
168      * Generic handling of the <CODE>set</CODE> operation.
169      * <p>The actual implementation of this method will be generated
170      * by mibgen. Usually, this implementation only delegates the
171      * job to some other provided runtime class, which knows how to
172      * access the MBean. The current toolkit thus provides two 
173      * implementations:
174      * <ul><li>The standard implementation will directly access the
175      *         MBean through a java reference,</li>
176      *     <li>The generic implementation will access the MBean through
177      *         the MBean server.</li>
178      * </ul>
179      * <p>Both implementations rely upon specific - and distinct, set of
180      * mibgen generated methods.
181      * <p> You can override this method if you need to implement some
182      * specific policies for minimizing the accesses made to some remote
183      * underlying resources.
184      * <p>
185      *
186      * @param req   The sub-request that must be handled by this node.
187      *
188      * @param depth The depth reached in the OID tree.
189      *
190      * @exception SnmpStatusException An error occurred while accessing 
191      *  the MIB node.
192      */
193     abstract public void set(SnmpMibSubRequest req, int depth) 
194     throws SnmpStatusException;
195 
196     /**
197      * Generic handling of the <CODE>check</CODE> operation.
198      *
199      * <p>The actual implementation of this method will be generated
200      * by mibgen. Usually, this implementation only delegates the
201      * job to some other provided runtime class, which knows how to
202      * access the MBean. The current toolkit thus provides two 
203      * implementations:
204      * <ul><li>The standard implementation will directly access the
205      *         MBean through a java reference,</li>
206      *     <li>The generic implementation will access the MBean through
207      *         the MBean server.</li>
208      * </ul>
209      * <p>Both implementations rely upon specific - and distinct, set of
210      * mibgen generated methods.
211      * <p> You can override this method if you need to implement some
212      * specific policies for minimizing the accesses made to some remote
213      * underlying resources, or if you need to implement some consistency
214      * checks between the different values provided in the varbind list.
215      * <p>
216      *
217      * @param req   The sub-request that must be handled by this node.
218      *
219      * @param depth The depth reached in the OID tree.
220      *
221      * @exception SnmpStatusException An error occurred while accessing 
222      *  the MIB node.
223      */
224     abstract public void check(SnmpMibSubRequest req, int depth) 
225     throws SnmpStatusException;
226 
227     // --------------------------------------------------------------------
228     // If we reach this node, we are below the root OID, so we just
229     // return.
230     // --------------------------------------------------------------------
231     public void getRootOid(Vector   result) {
232     return;
233     }
234 
235     // -------------------------------------------------------------------
236     // PACKAGE METHODS
237     // -------------------------------------------------------------------
238     
239     // -------------------------------------------------------------------
240     // This method can also be overriden in a subclass to provide a 
241     // different implementation of the isNestedArc() method.
242     // => if isNestedArc() is hardcoded, then registerSubArc() becomes
243     //    useless and can become empty.
244     /**
245      * Register an OID arc that identifies a sub-tree
246      * leading to a nested SNMP sub-group. This method is used internally.
247      * You shouldn't ever call it directly.
248      *
249      * @param arc An OID arc.
250      *
251      */
252     void registerNestedArc(long arc) {
253     Long   obj = new Long  (arc);
254     if (subgroups == null) subgroups = new Hashtable  ();
255         // registers the arc in the hashtable.
256     subgroups.put(obj,obj);
257     }
258 
259     // -------------------------------------------------------------------
260     // The SnmpMibOid algorithm relies on the fact that for every arc 
261     // registered in varList, there is a corresponding node at the same 
262     // position in children.
263     // So the trick is to register a null node in children for each variable
264     // in varList, so that the real subgroup nodes can be inserted at the 
265     // correct location. 
266     // registerObject() should be called for each scalar object and each 
267     // table arc by the generated subclass.
268     /**
269      * Register an OID arc that identifies a scalar object or a table.
270      * This method is used internally. You shouldn't ever call it directly.
271      *
272      * @param arc An OID arc.
273      *
274      */
275     protected void registerObject(long arc) 
276     throws IllegalAccessException   {
277 
278         // this will register the variable in both varList and children
279         // The node registered in children will be null, so that the parent
280         // algorithm will behave as if no node were registered. This is a
281         // trick that makes the parent algorithm behave as if only subgroups
282         // were registered in varList and children.
283     long[] oid = new long[1];
284     oid[0] = arc;
285     super.registerNode(oid,0,null);
286     }
287 
288     // -------------------------------------------------------------------
289     // registerNode() will be called at runtime when nested groups are
290     // registered in the MIB. So we do know that this method will only
291     // be called to register nested-groups.
292     // We trap registerNode() in order to call registerSubArc()
293     /**
294      * Register a child node of this node in the OID tree.
295      * This method is used internally. You shouldn't ever call it directly.
296      *
297      * @param oid The oid of the node being registered.
298      * @param cursor The position reached in the oid.
299      * @param node The node being registered.
300      *
301      */
302     void registerNode(long[] oid, int cursor ,SnmpMibNode node) 
303     throws IllegalAccessException   {
304     super.registerNode(oid,cursor,node);
305     if (cursor < 0) return;
306     if (cursor >= oid.length) return;
307         // if we get here, then it means we are registering a subgroup.
308         // We will thus register the sub arc in the subgroups hashtable.
309     registerNestedArc(oid[cursor]);
310     }
311     
312     // -------------------------------------------------------------------
313     // see comments in SnmpMibNode
314     // -------------------------------------------------------------------
315     void findHandlingNode(SnmpVarBind varbind, 
316               long[] oid, int depth, 
317               SnmpRequestTree handlers) 
318     throws SnmpStatusException {
319 
320     int length = oid.length;
321     SnmpMibNode node = null;
322     
323     if (handlers == null)
324             throw new SnmpStatusException(SnmpStatusException.snmpRspGenErr);
325 
326     final Object   data = handlers.getUserData();
327 
328     if (depth >= length) {
329         // Nothing is left... the oid is not valid
330             throw new SnmpStatusException(SnmpStatusException.noAccess);
331     }
332 
333     long arc = oid[depth];
334 
335     if (isNestedArc(arc)) {
336         // This arc leads to a subgroup: delegates the search to the
337         // method defined in SnmpMibOid
338         super.findHandlingNode(varbind,oid,depth,handlers);
339         return;
340     } else if (isTable(arc)) {
341         // This arc leads to a table: forward the search to the table.
342         
343         // Gets the table
344         SnmpMibTable table = getTable(arc);
345         
346         // Forward the search to the table
347         table.findHandlingNode(varbind,oid,depth+1,handlers);
348 
349     } else {
350         // If it's not a variable, throws an exception
351         validateVarId(arc, data);
352 
353         // The trailing .0 is missing in the OID
354         if (depth+2 > length)
355         throw noSuchInstanceException;
356 
357         // There are too many arcs left in the OID (there should remain
358         // a single trailing .0)
359         if (depth+2 < length)
360         throw noSuchInstanceException;
361 
362         // The last trailing arc is not .0
363         if (oid[depth+1] != 0L) 
364         throw noSuchInstanceException;
365 
366         // It's one of our variable, register this node.
367         handlers.add(this,depth,varbind);
368     }
369     }
370 
371     // -------------------------------------------------------------------
372     // See comments in SnmpMibNode.
373     // -------------------------------------------------------------------
374     long[] findNextHandlingNode(SnmpVarBind varbind, 
375                 long[] oid, int pos, int depth, 
376                 SnmpRequestTree handlers, AcmChecker checker) 
377     throws SnmpStatusException {
378     
379     int length = oid.length;
380     SnmpMibNode node = null;
381     
382     if (handlers == null)
383         // This should be considered as a genErr, but we do not want to
384         // abort the whole request, so we're going to throw
385         // a noSuchObject...
386         //
387             throw noSuchObjectException;
388 
389     final Object   data = handlers.getUserData();
390     final int pduVersion = handlers.getRequestPduVersion();
391 
392 
393     // The generic case where the end of the OID has been reached is
394     // handled in the superclass
395         // XXX Revisit: this works but it is somewhat convoluted. Just setting
396         //              arc to -1 would work too.
397     if (pos >= length) 
398         return super.findNextHandlingNode(varbind,oid,pos,depth,
399                           handlers, checker);
400 
401     // Ok, we've got the arc.
402     long arc = oid[pos];
403 
404     long[] result = null;
405 
406     // We have a recursive logic. Should we have a loop instead?
407     try {
408 
409         if (isTable(arc)) {
410         // If the arc identifies a table, then we need to forward
411         // the search to the table.
412 
413         // Gets the table identified by `arc'
414         SnmpMibTable table = getTable(arc);
415 
416         // Forward to the table
417         checker.add(depth, arc);
418         try {
419             result = table.findNextHandlingNode(varbind,oid,pos+1,
420                             depth+1,handlers,
421                             checker);
422         }catch(SnmpStatusException ex) {
423             throw noSuchObjectException;
424         } finally {
425             checker.remove(depth);
426         }
427         // Build up the leaf OID
428         result[depth] = arc;
429         return result;
430         } else if (isReadable(arc)) {
431         // If the arc identifies a readable variable, then two cases:
432 
433         if (pos == (length - 1)) {
434             // The end of the OID is reached, so we return the leaf
435             // corresponding to the variable identified by `arc'
436 
437             // Build up the OID
438             // result = new SnmpOid(0);
439             // result.insert((int)arc);
440             result = new long[depth+2];
441             result[depth+1] = 0L;
442             result[depth] = arc;
443 
444             checker.add(depth, result, depth, 2);
445             try {
446             checker.checkCurrentOid();
447             } catch(SnmpStatusException e) {
448             throw noSuchObjectException;
449             } finally {
450             checker.remove(depth,2);
451             }
452             
453             // Registers this node
454             handlers.add(this,depth,varbind);
455             return result;
456         } 
457 
458         // The end of the OID is not yet reached, so we must return
459         // the next leaf following the variable identified by `arc'.
460         // We cannot return the variable because whatever follows in
461         // the OID will be greater or equals to 0, and 0 identifies
462         // the variable itself - so we have indeed to return the 
463         // next object. 
464         // So we do nothing, because this case is handled at the 
465         // end of the if ... else if ... else ... block.
466 
467         } else if (isNestedArc(arc)) {
468         // Now if the arc leads to a subgroup, we delegate the 
469         // search to the child, just as done in SnmpMibNode. 
470         // 
471   
472         // get the child ( = nested arc node). 
473         // 
474         final SnmpMibNode child = getChild(arc); 
475         
476         if (child != null) { 
477             checker.add(depth, arc); 
478             try { 
479             result = child.findNextHandlingNode(varbind,oid,pos+1, 
480                                 depth+1,handlers,  
481                                 checker); 
482             result[depth] = arc; 
483             return result;
484             } finally {
485             checker.remove(depth);
486             }
487         }
488         }
489         
490         // The oid is not valid, we will throw an exception in order
491         // to try with the next valid identifier...
492         //
493         throw noSuchObjectException;
494 
495     } catch (SnmpStatusException e) {
496         // We didn't find anything at the given arc, so we're going
497         // to try with the next valid arc
498         //
499         long[] newOid = new long[1];
500         newOid[0] = getNextVarId(arc,data,pduVersion);
501         return findNextHandlingNode(varbind,newOid,0,depth,
502                     handlers,checker);
503     }
504     }
505 
506 }
507
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags