SnmpTableSupport


1   /* 
2    * @(#)file      SnmpTableSupport.java 
3    * @(#)author    Sun Microsystems, Inc. 
4    * @(#)version   1.17 
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  
14  
15  // java imports
16  //
17  import java.io.Serializable  ;
18  import java.util.Date  ;
19  import java.util.Vector  ;
20  import java.util.Enumeration  ;
21  import java.util.List  ;
22  import java.util.ArrayList  ;
23  
24  // jmx imports
25  //
26  import javax.management.Notification  ;
27  import javax.management.ObjectName  ;
28  import javax.management.NotificationFilter  ;
29  import javax.management.NotificationListener  ;
30  import javax.management.NotificationBroadcaster  ;
31  import javax.management.MBeanNotificationInfo  ;
32  import javax.management.ListenerNotFoundException  ;
33  import com.sun.jmx.snmp.SnmpOid;
34  import com.sun.jmx.snmp.SnmpValue;
35  import com.sun.jmx.snmp.SnmpVarBind;
36  import com.sun.jmx.snmp.SnmpStatusException;
37  
38  /**
39   * This class is an abstraction for an SNMP table.
40   * It is the base class for implementing SNMP tables in the
41   * MBean world.
42   *
43   * <p>
44   * Its responsibility is to synchronize the MBean view of the table
45   * (Table of entries) with the MIB view (array of OID indexes). Each 
46   * object of this class will be bound to the Metadata object which 
47   * manages the same SNMP Table within the MIB.
48   * </p>
49   *
50   * <p>
51   * For each table defined in a MIB, mibgen will generate a specific
52   * class called Table<i>TableName</i> that will subclass this class, and
53   * a corresponding <i>TableName</i>Meta class extending SnmpMibTable 
54   * and corresponding to the MIB view of the same table.
55   * </p>
56   *
57   * <p>
58   * Objects of this class are instantiated by MBeans representing
59   * the SNMP Group to which the table belong.
60   * </p>
61   *
62   * <p><b>This API is a Sun Microsystems internal API  and is subject 
63   * to change without notice.</b></p>
64   * @see com.sun.jmx.snmp.agent.SnmpTableEntryFactory
65   * @see com.sun.jmx.snmp.agent.SnmpMibTable
66   *
67   */
68  public abstract class SnmpTableSupport implements SnmpTableEntryFactory, 
69  // NPCTE fix for bugId 4499265, esc 0, MR 04 sept 2001
70  //  SnmpTableCallbackHandler {
71      SnmpTableCallbackHandler, Serializable   {
72  // end of NPCTE fix for bugId 4499265
73  
74      //-----------------------------------------------------------------
75      //
76      //  Protected Variables
77      //
78      //-----------------------------------------------------------------
79      
80      /**
81       * The list of entries
82       **/
83      protected List           entries;
84  
85      /**
86       * The associated metadata object
87       **/
88      protected SnmpMibTable meta;
89  
90      /**
91       * The MIB to which this table belongs
92       **/
93      protected SnmpMib      theMib;
94  
95      //-----------------------------------------------------------------
96      //
97      //  Private Variables
98      //
99      //-----------------------------------------------------------------
100     
101     /**
102      * This variable is initialized while binding this object to its 
103      * corresponding meta object.
104      **/
105     private boolean registrationRequired = false;
106 
107 
108 
109     //-----------------------------------------------------------------
110     //
111     //  Constructor
112     //
113     //-----------------------------------------------------------------
114 
115     /**
116      * Initializes the table.
117      * The steps are these:
118      * <ul><li> allocate an array for storing entry object,</li>
119      *     <li> retrieve the corresponding metadata object
120      *          from the MIB,
121      *     <li> bind this object to the corresponding metadata object
122      *          from the MIB.</li>
123      * </ul>
124      *
125      * @param mib The MIB to which this table belong. 
126      *
127      **/
128     protected SnmpTableSupport(SnmpMib mib) {
129     theMib  = mib;
130     meta    = getRegisteredTableMeta(mib);
131     bindWithTableMeta();
132     entries = allocateTable();
133     }
134 
135 
136     //-----------------------------------------------------------------
137     //
138     //  Implementation of the SnmpTableEntryFactory interface
139     //
140     //-----------------------------------------------------------------
141 
142     /**
143      * Creates a new entry in the table.
144      *
145      * This factory method is generated by mibgen and used internally.
146      * It is part of the 
147      * {@link com.sun.jmx.snmp.agent.SnmpTableEntryFactory} interface.
148      * You may subclass this method to implement any specific behaviour
149      * your application requires.
150      *
151      * @exception SnmpStatusException if the entry cannot be created.
152      **/
153     public abstract void createNewEntry(SnmpMibSubRequest request, 
154                     SnmpOid rowOid, int depth, 
155                     SnmpMibTable meta) 
156     throws SnmpStatusException;
157 
158 
159     //-----------------------------------------------------------------
160     //
161     //  Public methods
162     //
163     //-----------------------------------------------------------------
164 
165     /**
166      * Returns the entry located at the given position in the table.
167      *
168      * @return The entry located at the given position, <code>null</code>
169      *         if no entry can be found at this position.
170      **/
171     // XXXX xxxx zzz ZZZZ => public? or protected?
172     public Object   getEntry(int pos) {
173     if (entries == null) return null;
174     return entries.get(pos);
175     }
176 
177     /**
178      * Returns the number of entries registered in the table.
179      *
180      * @return The number of entries registered in the table.
181      **/
182     public int getSize() {
183     return meta.getSize();
184     }
185 
186     /**
187      * This method lets you dynamically switch the creation policy.
188      *
189      * <CODE>setCreationEnabled()</CODE> will switch the policy of 
190      *      remote entry creation via SET operations, by calling 
191      *      <code>setCreationEnabled()</code> on the metadata object 
192      *      associated with this table.
193      * <BR> By default remote entry creation via SET operation is disabled.
194      *
195      * @param remoteCreationFlag Tells whether remote entry creation must
196      *        be enabled or disabled.
197      * <li>
198      * <CODE>setCreationEnabled(true)</CODE> will enable remote entry
199      *      creation via SET operations.</li>
200      * <li>
201      * <CODE>setCreationEnabled(false)</CODE> will disable remote entry
202      *      creation via SET operations.</li>
203      * <p> By default remote entry creation via SET operation is disabled.
204      * </p>
205      *
206      * @see com.sun.jmx.snmp.agent.SnmpMibTable
207      *
208      **/
209     public void setCreationEnabled(boolean remoteCreationFlag) {
210     meta.setCreationEnabled(remoteCreationFlag);
211     }
212 
213     /**
214      * Tells whether a new entry should be created when a SET operation
215      * is received for an entry that does not exist yet.
216      * This method calls <code>isCreationEnabled()</code> on the metadata 
217      * object associated with this table.
218      *
219      * @return true if a new entry must be created, false otherwise.<br>
220      *         [default: returns <CODE>false</CODE>]
221      *
222      * @see com.sun.jmx.snmp.agent.SnmpMibTable
223      **/
224     public boolean isCreationEnabled() {
225     return meta.isCreationEnabled();
226     }
227 
228     /**
229      * Tells whether the metadata object to which this table is linked
230      * requires entries to be registered. In this case passing an 
231      * ObjectName when registering entries will be mandatory.
232      *
233      * @return <code>true</code> if the associated metadata requires entries
234      *         to be registered (mibgen generated generic metadata).
235      **/
236     public boolean isRegistrationRequired() {
237     return registrationRequired;
238     }
239 
240     /**
241      * Builds an entry SnmpIndex from its row OID.
242      *
243      * This method is generated by mibgen and used internally.
244      *
245      * @param rowOid The SnmpOid object identifying a table entry.
246      * 
247      * @return The SnmpIndex of the entry identified by <code>rowOid</code>.
248      *
249      * @exception SnmpStatusException if the index cannot be built from the 
250      *            given OID.
251      **/
252     public SnmpIndex buildSnmpIndex(SnmpOid rowOid)  
253     throws SnmpStatusException {
254     return buildSnmpIndex(rowOid.longValue(false), 0);
255     }
256 
257     /**
258      * Builds an SnmpOid from an SnmpIndex object.
259      *
260      * This method is generated by mibgen and used internally.
261      *
262      * @param index An SnmpIndex object identifying a table entry.
263      *
264      * @return The SnmpOid form of the given entry index.
265      *
266      * @exception SnmpStatusException if the given index is not valid.
267      **/
268     public abstract SnmpOid buildOidFromIndex(SnmpIndex index) 
269     throws SnmpStatusException;
270 
271     /**
272      * Builds the default ObjectName of an entry from the SnmpIndex
273      * identifying this entry. No access is made on the entry itself.
274      *
275      * This method is generated by mibgen and used internally.
276      * You can subclass this method if you want to change the default
277      * ObjectName policy. This is only meaningfull when entries
278      * are registered MBeans.
279      *
280      * @param index The SnmpIndex identifying the entry from which we
281      *              want to build the default ObjectName.
282      *        
283      * @return The default ObjectName for the entry identified by 
284      *         the given index.
285      *
286      * @exception SnmpStatusException if the given index is not valid.
287      **/
288     public abstract ObjectName   buildNameFromIndex(SnmpIndex index) 
289     throws SnmpStatusException;
290 
291 
292     //-----------------------------------------------------------------
293     //
294     //  Implementation of the SnmpTableEntryFactory interface
295     //
296     //-----------------------------------------------------------------
297 
298     /**
299      * This callback is called by  the associated metadata object
300      * when a new table entry has been registered in the 
301      * table metadata.
302      *
303      * This method will update the <code>entries</code> list.
304      *
305      * @param pos   The position at which the new entry was inserted 
306      *              in the table.
307      * @param row   The row OID of the new entry
308      * @param name  The ObjectName of the new entry (as specified by the 
309      *              factory)
310      * @param entry The new entry (as returned by the factory)
311      * @param meta  The table metadata object.
312      *
313      **/
314     public void addEntryCb(int pos, SnmpOid row, ObjectName   name, 
315                Object   entry, SnmpMibTable meta) 
316     throws SnmpStatusException {
317     try {
318         if (entries != null) entries.add(pos,entry);
319     } catch (Exception   e) {
320         throw new SnmpStatusException(SnmpStatusException.noSuchName);
321     }
322     }
323 
324     /**
325      * This callback is called by  the associated metadata object
326      * when a new table entry has been removed from the 
327      * table metadata.
328      *
329      * This method will update the <code>entries</code> list.
330      *
331      * @param pos   The position from which the entry was deleted 
332      * @param row   The row OID of the deleted entry
333      * @param name  The ObjectName of the deleted entry (may be null if
334      *              ObjectName's were not required)
335      * @param entry The deleted entry (may be null if only ObjectName's
336      *              were required)
337      * @param meta  The table metadata object.
338      *
339      **/
340     public void removeEntryCb(int pos, SnmpOid row, ObjectName   name, 
341                   Object   entry, SnmpMibTable meta)
342     throws SnmpStatusException {
343     try {
344         if (entries != null) entries.remove(pos);
345     } catch (Exception   e) {
346     }
347     }
348 
349 
350 
351     /**
352      * Enables to add an SNMP entry listener to this 
353      * <CODE>SnmpMibTable</CODE>.
354      *
355      * @param listener The listener object which will handle the 
356      *    notifications emitted by the registered MBean.
357      *
358      * @param filter The filter object. If filter is null, no filtering 
359      *    will be performed before handling notifications.
360      *
361      * @param handback The context to be sent to the listener when a 
362      *    notification is emitted.
363      *
364      * @exception IllegalArgumentException Listener parameter is null.
365      */
366     public void 
367     addNotificationListener(NotificationListener   listener, 
368                 NotificationFilter   filter, Object   handback) {
369     meta.addNotificationListener(listener,filter,handback);
370     }
371 
372     /**
373      * Enables to remove an SNMP entry listener from this 
374      * <CODE>SnmpMibTable</CODE>.
375      *
376      * @param listener The listener object which will handle the 
377      *    notifications emitted by the registered MBean.
378      *    This method will remove all the information related to this 
379      *    listener.
380      *
381      * @exception ListenerNotFoundException The listener is not registered 
382      *    in the MBean.
383      */
384     public synchronized void 
385     removeNotificationListener(NotificationListener   listener) 
386     throws ListenerNotFoundException   {
387     meta.removeNotificationListener(listener);
388     }
389     
390     /**    
391      * Returns a <CODE>NotificationInfo</CODE> object containing the 
392      * notification class and the notification type sent by the 
393      * <CODE>SnmpMibTable</CODE>.  
394      */
395     public MBeanNotificationInfo  [] getNotificationInfo() {
396     return meta.getNotificationInfo();
397     }  
398 
399     //-----------------------------------------------------------------
400     //
401     //  Protected Abstract methods
402     //
403     //-----------------------------------------------------------------
404 
405     /**
406      * Builds an SnmpIndex object from the index part of an OID.
407      *
408      * This method is generated by mibgen and used internally.
409      *
410      * @param oid The OID from which to build the index, represented
411      *        as an array of long.
412      * @param start The position where to start from in the OID array.
413      *
414      * @return The SnmpOid form of the given entry index.
415      *
416      * @exception SnmpStatusException if the given index is not valid.
417      **/
418     protected abstract SnmpIndex buildSnmpIndex(long oid[], int start ) 
419     throws SnmpStatusException;
420 
421     /**
422      * Returns the metadata object associated with this table.
423      *
424      * This method is generated by mibgen and used internally.
425      *
426      * @param mib The SnmpMib object holding the Metadata corresponding
427      *            to this table.
428      *
429      * @return The metadata object associated with this table.
430      *         Returns <code>null</code> if this implementation of the
431      *         MIB doesn't support this table.
432      **/
433     protected abstract SnmpMibTable getRegisteredTableMeta(SnmpMib mib);
434 
435 
436     //-----------------------------------------------------------------
437     //
438     //  Protected methods
439     //
440     //-----------------------------------------------------------------
441 
442     /**
443      * Allocates an ArrayList for storing table entries.
444      *
445      * This method is called within the constructor at object creation.
446      * Any object implementing the {@link java.util.List} interface can
447      * be used.
448      *
449      * @return A new list in which to store entries. If <code>null</code>
450      *         is returned then no entry will be stored in the list
451      *         and getEntry() will always return null.
452      **/
453     protected List   allocateTable() {
454     return new ArrayList  ();
455     }
456 
457     /**
458      * Add an entry in this table.
459      *
460      * This method registers an entry in the table and perform
461      * synchronization with the associated table metadata object.
462      *
463      * This method assumes that the given entry will not be registered,
464      * or will be registered with its default ObjectName built from the 
465      * associated  SnmpIndex.
466      * <p>
467      * If the entry is going to be registered, then 
468      * {@link com.sun.jmx.snmp.agent.SnmpTableSupport#addEntry(SnmpIndex, ObjectName, Object)} should be prefered.
469      * <br> This function is mainly provided for backward compatibility.
470      *
471      * @param index The SnmpIndex built from the given entry.
472      * @param entry The entry that should be added in the table.
473      *
474      * @exception SnmpStatusException if the entry cannot be registered with
475      *            the given index.
476      **/
477     protected void addEntry(SnmpIndex index, Object   entry)
478     throws SnmpStatusException {
479     SnmpOid oid = buildOidFromIndex(index);
480     ObjectName   name = null;
481     if (isRegistrationRequired()) {
482         name = buildNameFromIndex(index);
483     }
484     meta.addEntry(oid,name,entry);
485     }
486 
487     /**
488      * Add an entry in this table.
489      *
490      * This method registers an entry in the table and performs
491      * synchronization with the associated table metadata object.
492      *
493      * @param index The SnmpIndex built from the given entry.
494      * @param name  The ObjectName with which this entry will be registered.
495      * @param entry The entry that should be added in the table.
496      *
497      * @exception SnmpStatusException if the entry cannot be registered with
498      *            the given index.
499      **/
500     protected void addEntry(SnmpIndex index, ObjectName   name, Object   entry) 
501     throws SnmpStatusException {
502     SnmpOid oid = buildOidFromIndex(index);
503     meta.addEntry(oid,name,entry);
504     }
505 
506     /**
507      * Remove an entry from this table.
508      *
509      * This method unregisters an entry from the table and performs
510      * synchronization with the associated table metadata object.
511      *
512      * @param index The SnmpIndex identifying the entry.
513      * @param entry The entry that should be removed in the table. This
514      *              parameter is optional and can be omitted if it doesn't
515      *              need to be passed along to the 
516      *              <code>removeEntryCb()</code> callback defined in the
517      *              {@link com.sun.jmx.snmp.agent.SnmpTableCallbackHandler}
518      *              interface.
519      *
520      * @exception SnmpStatusException if the entry cannot be unregistered.
521      **/
522     protected void removeEntry(SnmpIndex index, Object   entry) 
523     throws SnmpStatusException {
524     SnmpOid oid = buildOidFromIndex(index);
525     meta.removeEntry(oid,entry);
526     }
527     
528     // protected void removeEntry(ObjectName name, Object entry) 
529     //  throws SnmpStatusException {
530     //  meta.removeEntry(name,entry);
531     // }
532 
533     /**
534      * Returns the entries in the table.
535      *
536      * @return An Object[] array containing the entries registered in the
537      *         table.
538      **/
539     protected Object  [] getBasicEntries() {
540     if (entries == null) return null;
541         Object  [] array= new Object  [entries.size()];
542         entries.toArray(array);
543         return array;
544     }
545 
546     /**
547      * Binds this table with its associated metadata, registering itself
548      * as an SnmpTableEntryFactory.
549      **/
550     protected void bindWithTableMeta() {
551     if (meta == null) return;
552     registrationRequired = meta.isRegistrationRequired();
553     meta.registerEntryFactory(this);
554     }
555 
556 }
557
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags