KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > sun > jmx > snmp > SnmpVarBindList


1 /*
2  * @(#)file SnmpVarBindList.java
3  * @(#)author Sun Microsystems, Inc.
4  * @(#)version 1.4
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 // Copyright (c) 1995-96 by Cisco Systems, Inc.
12
13 package com.sun.jmx.snmp;
14
15
16 import java.util.Vector JavaDoc;
17 import java.util.Enumeration JavaDoc;
18
19
20 /**
21  * Contains a list of <CODE>SnmpVarBind</CODE> objects.
22  * This class helps to create an <CODE>SnmpVarBindList</CODE> from a list of MIB variable names.
23  * In addition, it contains different forms of methods which can copy or clone the list.
24  * This list is required by any SNMP entity which specifies a list of variables to query.
25  * <p><b>This API is a Sun Microsystems internal API and is subject
26  * to change without notice.</b></p>
27  */
28
29 public class SnmpVarBindList extends Vector JavaDoc {
30
31     /**
32      * A name given to the <CODE>SnmpVarBindList</CODE>. Useful for debugging.
33      * The default name is "VarBindList".
34      */
35     public String JavaDoc identity = "VarBindList " ; // name identifying this list.
36
37     /**
38      * Timestamp when this <CODE>SnmpVarBindList</CODE> was updated.
39      * Valid only for <CODE>SnmpGet</CODE> and <CODE>SnmpGetNext</CODE> operations.
40      * <CODE>SnmpTimestamp</CODE> is null by default.
41      * Also, when the list is cloned without value the timestamp is not copied.
42      */
43     Timestamp timestamp ;
44     
45     
46     // CONSTRUCTORS
47 //-------------
48
49     /**
50      * Prepares an empty list.
51      * The initial capacity and the capacity increment are initialized to 5.
52      */
53     public SnmpVarBindList() {
54         super(5, 5) ;
55     }
56
57     /**
58      * Prepares an empty list.
59      * @param initialCapacity The initial capacity of the <CODE>SnmpVarBindList</CODE>.
60      */
61     public SnmpVarBindList(int initialCapacity) {
62         super(initialCapacity) ;
63     }
64     
65     /**
66      * Prepares an empty list with a <CODE>String</CODE> to print while debugging.
67      * @param name The name of the newly created <CODE>SnmpVarBindList</CODE>.
68      */
69     public SnmpVarBindList(String JavaDoc name) {
70         super(5, 5) ;
71         identity = name ;
72     }
73
74     /**
75      * Similar to the copy constructor. Does a shallow copy of the elements.
76      * Individual elements are not cloned.
77      * @param list The <CODE>SnmpVarBindList</CODE> to copy.
78      */
79     public SnmpVarBindList(SnmpVarBindList list) {
80         super(list.size(), 5) ;
81         list.copyInto(elementData) ;
82         elementCount = list.size() ;
83     }
84
85     /**
86      * Creates a new <CODE>SnmpVarBindList</CODE> object from a plain vector of <CODE>SnmpVarBind</CODE> objects.
87      * Objects in the specified vector can be <CODE>SnmpVarBind</CODE> objects or derivatives.
88      * @param list The vector of <CODE>SnmpVarBind</CODE> objects to copy.
89      */
90     public SnmpVarBindList(Vector JavaDoc list) {
91         super(list.size(), 5);
92         for (Enumeration JavaDoc e = list.elements(); e.hasMoreElements();) {
93             final SnmpVarBind varBind = (SnmpVarBind)e.nextElement();
94             addElement((SnmpVarBind)varBind.clone());
95         }
96     }
97     
98     /**
99      * Creates a new <CODE>SnmpVarBindList</CODE> object from a plain vector of <CODE>SnmpVarBind</CODE> objects.
100      * Objects in the specified vector can be <CODE>SnmpVarBind</CODE> objects or derivatives.
101      * @param name The name of the newly created <CODE>SnmpVarBindList</CODE>.
102      * @param list The vector of <CODE>SnmpVarBind</CODE> objects to copy.
103      */
104     public SnmpVarBindList(String JavaDoc name, Vector JavaDoc list) {
105         this(list);
106         identity = name;
107     }
108
109     
110     // GETTER/SETTER
111 //--------------
112
113     /**
114      * Gets the <CODE>timestamp</CODE> associated with this <CODE>SnmpVarBindList</CODE>.
115      * @return The <CODE>timestamp</CODE>.
116      */
117     public Timestamp getTimestamp() {
118         return timestamp ;
119     }
120
121     /**
122      * Records the <CODE>sysUpTime</CODE> and the actual time when this <CODE>SnmpVarBindList</CODE>
123      * was changed or created.
124      * This needs to be set explicitly.
125      * @param tstamp The <CODE>SnmpTimestamp</CODE> of the device for which the values hold <CODE>true</CODE>.
126      */
127     public void setTimestamp(Timestamp tstamp) {
128         timestamp = tstamp ;
129     }
130
131     /**
132      * Gets an <CODE>SnmpVarBind</CODE> object.
133      * @param pos The position in the list.
134      * @return The <CODE>SnmpVarBind</CODE> object at the specified position.
135      * @exception java.lang.ArrayIndexOutOfBoundsException If the specified <CODE>pos</CODE> is beyond range.
136      */
137     public final synchronized SnmpVarBind getVarBindAt(int pos) {
138         return (SnmpVarBind)(elementAt(pos)) ;
139     }
140
141     /**
142      * Gets the number of elements in this list.
143      * @return The number of elements in the list.
144      */
145     public synchronized int getVarBindCount() {
146         return size() ;
147     }
148
149     /**
150      * This is a convenience function that returns an enumeration. This can be used to traverse the list.
151      * This is advantageous as it hides the implementation of the class of the list which keeps the variables.
152      * @return An enumeration object of <CODE>SnmpVarBind</CODE> objects.
153      */
154     public synchronized Enumeration JavaDoc getVarBindList() {
155         return elements() ;
156     }
157
158     /**
159      * Replaces the current variable binding list of <CODE>SnmpVarBind</CODE> with the new specified variable binding
160      * list of <CODE>SnmpVarBind</CODE> objects.
161      * This method only clones the vector. It does not clone the <CODE>SnmpVarBind</CODE> objects
162      * contained in the list.
163      * @param list A vector of <CODE>SnmpVarBind</CODE> objects.
164      */
165     public final synchronized void setVarBindList(Vector JavaDoc list) {
166         setVarBindList(list, false) ;
167     }
168
169     /**
170      * Replaces the current variable binding list of <CODE>SnmpVarBind</CODE> objects with the new variable binding
171      * list of <CODE>SnmpVarBind</CODE> objects.
172      * If <CODE>copy</CODE> is <CODE>true</CODE>, it will clone each <CODE>SnmpVarBind</CODE> object
173      * contained in the list.
174      * @param list A vector of <CODE>SnmpVarBind</CODE> objects.
175      * @param copy The flag indicating whether each object in the list should be cloned.
176      */
177     public final synchronized void setVarBindList(Vector JavaDoc list, boolean copy) {
178         synchronized (list) {
179             final int max = list.size();
180             setSize(max) ;
181             list.copyInto(this.elementData) ;
182             if (copy) { // do deepcopy of all vars.
183 for (int i = 0; i < max ; i++) {
184                     SnmpVarBind avar = (SnmpVarBind)elementData[i] ;
185                     elementData[i] = avar.clone() ;
186                 }
187             }
188         }
189     }
190     
191     
192     // PUBLIC METHODS
193 //---------------
194
195     /**
196      * Appends an <CODE>SnmpVarBindList</CODE> at the end of the current <CODE>SnmpVarBindList</CODE> object.
197      * @param list The <CODE>SnmpVarBindList</CODE> to append.
198      */
199     public synchronized void addVarBindList(SnmpVarBindList list) {
200         ensureCapacity(list.size() + size()) ;
201         for (int i = 0; i < list.size(); i++) {
202             addElement(list.getVarBindAt(i)) ;
203         }
204     }
205
206     /**
207      * Removes all the <CODE>SnmpVarBind</CODE> objects of the given <CODE>SnmpVarBindList</CODE> from the existing
208      * <CODE>SnmpVarBindList</CODE>.
209      * @param list The <CODE>SnmpVarBindList</CODE> to be removed.
210      * @return <CODE>true</CODE> if all the <CODE>SnmpVarBind</CODE> objects were components of this
211      * <CODE>SnmpVarBindList</CODE>, <CODE>false</CODE> otherwise.
212      */
213     public synchronized boolean removeVarBindList(SnmpVarBindList list) {
214         boolean result = true;
215         for (int i = 0; i < list.size(); i++) {
216             result = removeElement(list.getVarBindAt(i)) ;
217         }
218         return result;
219     }
220
221     /**
222      * Replaces an element at a specified location with the new element.
223      * @param var The replacement variable.
224      * @param pos The location in the <CODE>SnmpVarBindList</CODE>.
225      * @exception java.lang.ArrayIndexOutOfBoundsException If the specified <CODE>pos</CODE> is beyond range.
226      */
227     public final synchronized void replaceVarBind(SnmpVarBind var, int pos) {
228         setElementAt(var, pos) ;
229     }
230
231     /**
232      * Prepares a vector of <CODE>SnmpVarBindList</CODE> from an array of SNMP MIB variables and instances.
233      * @param list An array of <CODE>String</CODE> containing MIB variable names.
234      * @param inst A common instance for each of the MIB variables in <CODE>vlist</CODE>.
235      * @exception SnmpStatusException An error occurred while accessing a MIB node.
236      */
237     public final synchronized void addVarBind(String JavaDoc list[], String JavaDoc inst) throws SnmpStatusException {
238         for (int i = 0; i < list.length; i++) {
239             SnmpVarBind avar = new SnmpVarBind(list[i]) ;
240             avar.addInstance(inst) ;
241             addElement(avar) ;
242         }
243     }
244
245     /**
246      * Removes the array of SNMP MIB variables and instances from the existing <CODE>SnmpVarBindList</CODE>.
247      * @param list An array of <CODE>String</CODE> containing MIB variable names.
248      * @param inst A common instance for each of the MIB variables in <CODE>vlist</CODE>.
249      * @return <CODE>true</CODE> if all the SNMP MIB variables were components of this <CODE>SnmpVarBindList</CODE>,
250      * <CODE>false</CODE> otherwise.
251      * @exception SnmpStatusException An error occurred while accessing a MIB node.
252      */
253     public synchronized boolean removeVarBind(String JavaDoc list[], String JavaDoc inst) throws SnmpStatusException {
254         boolean result = true;
255         for (int i = 0; i < list.length; i++) {
256             SnmpVarBind avar = new SnmpVarBind(list[i]) ;
257             avar.addInstance(inst) ;
258             int indexOid = indexOfOid(avar) ;
259             try {
260                 removeElementAt(indexOid) ;
261             } catch (ArrayIndexOutOfBoundsException JavaDoc e) {
262                 result = false ;
263             }
264         }
265         return result ;
266     }
267
268     /**
269      * Adds an array of MIB variable names to the list. For example:
270      * <P>
271      * <CODE>
272      * String mylist[] = {"sysUpTime.0", "ifInOctets.0"}
273      * <BR>
274      * vb.addVarBind(mylist) ;
275      * </BR>
276      * </CODE>
277      * @param list The array of MIB variable names.
278      * @exception SnmpStatusException An error occurred while accessing a MIB node.
279      */
280     public synchronized void addVarBind(String JavaDoc list[]) throws SnmpStatusException {
281         addVarBind(list, null) ;
282     }
283
284     /**
285      * Removes the array of SNMP MIB variables from the existing <CODE>SnmpVarBindList</CODE>.
286      * @param list Array of strings containing MIB variable names.
287      * @return <CODE>true</CODE> if all the SNMP MIB variables were components of this <CODE>SnmpVarBindList</CODE>,
288      * <CODE>false</CODE> otherwise.
289      * @exception SnmpStatusException An error occurred while accessing a MIB node.
290      */
291     public synchronized boolean removeVarBind(String JavaDoc list[]) throws SnmpStatusException {
292         return removeVarBind(list, null) ;
293     }
294
295     /**
296      * Creates an <CODE>SnmpVarBind</CODE> object from the given MIB variable and appends it to the existing
297      * <CODE>SnmpVarBindList</CODE>.
298      * It creates a new <CODE>SnmpVarBindList</CODE> if one did not exist.
299      * @param name A MIB variable name.
300      * @exception SnmpStatusException An error occurred while accessing a MIB node.
301      */
302     public synchronized void addVarBind(String JavaDoc name) throws SnmpStatusException {
303         SnmpVarBind avar ;
304         avar = new SnmpVarBind(name) ;
305         addVarBind(avar) ;
306     }
307
308     /**
309      * Removes the <CODE>SnmpVarBind</CODE> object corresponding to the given MIB variable from the existing
310      * <CODE>SnmpVarBindList</CODE>.
311      * @param name A MIB variable name.
312      * @return <CODE>true</CODE> if the SNMP MIB variable was a component of this <CODE>SnmpVarBindList</CODE>,
313      * <CODE>false</CODE> otherwise.
314      * @exception SnmpStatusException An error occurred while accessing a MIB node.
315      */
316     public synchronized boolean removeVarBind(String JavaDoc name) throws SnmpStatusException {
317         SnmpVarBind avar ;
318         int indexOid ;
319         avar = new SnmpVarBind(name) ;
320         indexOid = indexOfOid(avar) ;
321         try {
322             removeElementAt(indexOid) ;
323             return true ;
324         } catch (ArrayIndexOutOfBoundsException JavaDoc e) {
325             return false ;
326         }
327     }
328
329     /**
330      * Appends the given <CODE>SnmpVarBind</CODE> object to the existing <CODE>SnmpVarBindList</CODE>.
331      * It creates a new <CODE>SnmpVarBindList</CODE> if one did not exist.
332      * @param var The <CODE>SnmpVarBind</CODE> object to be appended.
333      */
334     public synchronized void addVarBind(SnmpVarBind var) {
335         addElement(var) ;
336     }
337
338     /**
339      * Removes the given <CODE>SnmpVarBind</CODE> object from the existing <CODE>SnmpVarBindList</CODE>.
340      * @param var The <CODE>SnmpVarBind</CODE> object to be removed.
341      * @return <CODE>true</CODE> if the <CODE>SnmpVarBind</CODE> object was a component of this
342      * <CODE>SnmpVarBindList</CODE>, <CODE>false</CODE> otherwise.
343      */
344     public synchronized boolean removeVarBind(SnmpVarBind var) {
345         return removeElement(var) ;
346     }
347
348     /**
349      * Adds the string as an instance part to all OIDs in this list.
350      * This method should be used with caution because it affects all OIDs in the list.
351      * @param inst The <CODE>String</CODE> to add as an instance part.
352      * @exception SnmpStatusException An error occurred while accessing a MIB node.
353      */
354     public synchronized void addInstance(String JavaDoc inst) throws SnmpStatusException {
355         int max= size();
356         for (int i = 0; i < max; i++) {
357             ((SnmpVarBind)elementData[i]).addInstance(inst) ;
358         }
359     }
360
361     /**
362      * Adds elements in the specified <CODE>SnmpVarBindList</CODE> to this list.
363      * The elements are not cloned.
364      * @param list A vector of <CODE>SnmpVarBind</CODE>.
365      */
366     final public synchronized void concat(Vector JavaDoc list) {
367         ensureCapacity(size() + list.size()) ;
368         for (Enumeration JavaDoc e = list.elements() ; e.hasMoreElements() ; ) {
369             addElement(e.nextElement()) ;
370         }
371     }
372
373     /**
374      * Returns <CODE>false</CODE> if any of the variables does not contain a valid value.
375      * Typically used for <CODE>SnmpSet</CODE> operations.
376      * @return <CODE>false</CODE> if any of the variables does not contain a valid value, <CODE>true</CODE> otherwise.
377      */
378     public synchronized boolean checkForValidValues() {
379         int max= this.size();
380         for (int i = 0; i < max ; i++) {
381             SnmpVarBind avar = (SnmpVarBind)elementData[i] ;
382             if (avar.isValidValue() == false)
383                 return false ;
384         }
385         return true ;
386     }
387
388     /**
389      * Returns <CODE>true</CODE> if there is a value that is not specified.
390      * @return <CODE>true</CODE> if there is a value that is not specified, <CODE>false</CODE> otherwise.
391      */
392     public synchronized boolean checkForUnspecifiedValue() {
393         int max= this.size();
394         for (int i = 0; i < max ; i++) {
395             SnmpVarBind avar = (SnmpVarBind)elementData[i] ;
396             if (avar.isUnspecifiedValue())
397                 return true ;
398         }
399         return false ;
400     }
401
402     /**
403      * Splits the <CODE>SnmpVarBindList</CODE>.
404      * @param pos The position at which to split the <CODE>SnmpVarBindList</CODE>
405      * @return The <CODE>SnmpVarBindList</CODE> list from the beginning up to the split position.
406      */
407     public synchronized SnmpVarBindList splitAt(int pos) {
408         SnmpVarBindList splitVb = null ;
409         if (pos > elementCount)
410             return splitVb ;
411         splitVb = new SnmpVarBindList() ; // size() - atPosition) ;
412 int max= size();
413         for (int i = pos; i < max ; i++)
414             splitVb.addElement(elementData[i]) ;
415         elementCount = pos ;
416         trimToSize() ;
417         return splitVb ;
418     }
419
420     /**
421      * Gives the index of an OID in the <CODE>SnmpVarBindList</CODE>.
422      * The index returned must be greater than or equal to the <CODE>start</CODE> parameter
423      * and smaller than the <CODE>end</CODE> parameter. Otherwise the method returns -1.
424      * @param var The <CODE>SnmpVarBind</CODE> object with the requested OID.
425      * @param min The min index in <CODE>SnmpVarBindList</CODE>.
426      * @param max The max index in <CODE>SnmpVarBindList</CODE>.
427      * @return The index of the OID in <CODE>SnmpVarBindList</CODE>.
428      */
429     public synchronized int indexOfOid(SnmpVarBind var, int min, int max) {
430         SnmpOid oidarg = var.getOid() ;
431         for (int i = min; i < max ; i++) {
432             SnmpVarBind avar = (SnmpVarBind)elementData[i] ;
433             if (oidarg.equals(avar.getOid()))
434                 return i ;
435         }
436         return -1 ;
437     }
438
439     /**
440      * Gives the index of an OID in the <CODE>SnmpVarBindList</CODE>.
441      * @param var The <CODE>SnmpVarBind</CODE> object with the requested OID.
442      * @return The index of the OID in <CODE>SnmpVarBindList</CODE>.
443      */
444     public synchronized int indexOfOid(SnmpVarBind var) {
445         return indexOfOid(var, 0, size()) ;
446     }
447
448     /**
449      * Gives the index of an OID in the <CODE>SnmpVarBindList</CODE>.
450      * @param oid The <CODE>SnmpOid</CODE> object with the requested OID.
451      * @return The index of the OID in <CODE>SnmpVarBindList</CODE>.
452      */
453     public synchronized int indexOfOid(SnmpOid oid) {
454         int max = size();
455         for (int i = 0; i < max ; i++) {
456             SnmpVarBind avar = (SnmpVarBind)elementData[i] ;
457             if (oid.equals(avar.getOid()))
458                 return i ;
459         }
460         return -1 ;
461     }
462
463     /**
464      * Clones the <CODE>SnmpVarBindList</CODE>. A new copy of the <CODE>SnmpVarBindList</CODE> is created.
465      * It is a real deep copy.
466      * @return The <CODE>SnmpVarBindList</CODE> clone.
467      */
468     public synchronized SnmpVarBindList cloneWithValue() {
469         SnmpVarBindList newvb = new SnmpVarBindList() ;
470         newvb.setTimestamp(this.getTimestamp()) ;
471         newvb.ensureCapacity(this.size()) ;
472         for (int i = 0; i < this.size() ; i++) {
473             SnmpVarBind avar = (SnmpVarBind)elementData[i] ;
474             newvb.addElement(avar.clone()) ;
475         }
476         return newvb ;
477     }
478
479     /**
480      * Clones the <CODE>SnmpVarBindList</CODE>. It does not clone the value part of the variable.
481      * It is a deep copy (except for the value portion).
482      * @return The <CODE>SnmpVarBindList</CODE> clone.
483      */
484     public synchronized SnmpVarBindList cloneWithoutValue() {
485         SnmpVarBindList newvb = new SnmpVarBindList() ;
486         int max = this.size();
487         newvb.ensureCapacity(max) ;
488         for (int i = 0; i < max ; i++) {
489             SnmpVarBind avar = (SnmpVarBind)elementData[i] ;
490             newvb.addElement(avar.cloneWithoutValue()) ;
491         }
492         return newvb ;
493     }
494
495     /**
496      * Clones the <CODE>SnmpVarBindList</CODE>. A new copy of the <CODE>SnmpVarBindList</CODE> is created.
497      * It is a real deep copy.
498      * @return The object clone.
499      */
500     public synchronized Object JavaDoc clone() {
501         return cloneWithValue() ;
502     }
503
504     /**
505      * Copies the <CODE>SnmpVarBindList</CODE> into a plain vector of <CODE>SnmpVarBind</CODE> objects.
506      * If the <code>copy</code> flag is false, does a shallow copy of the list. Otherwise,
507      * individual elements will be cloned.
508      * @param copy The flag indicating whether each object in the list should be cloned.
509      * @return A new vector of <CODE>SnmpVarBind</CODE> objects.
510      */
511     public synchronized Vector JavaDoc toVector(boolean copy) {
512         final int count = elementCount;
513         if (copy == false) return (Vector JavaDoc) super.clone();
514         Vector JavaDoc result = new Vector JavaDoc(count,5);
515         for (int i = 0; i < count ; i++) {
516             SnmpVarBind avar = (SnmpVarBind)elementData[i] ;
517             result.addElement(avar.clone()) ;
518         }
519         return result;
520     }
521
522     /**
523      * Returns a <CODE>String</CODE> containing the ASCII representation of all OIDs in the list.
524      * @return An ASCII list of all OIDs in this list.
525      */
526     public String JavaDoc oidListToString() {
527         StringBuffer JavaDoc s = new StringBuffer JavaDoc(300) ;
528         for (int i = 0 ; i < elementCount ; i++) {
529             SnmpVarBind avar = (SnmpVarBind)elementData[i] ;
530             s.append(avar.getOid().toString() + "\n") ;
531         }
532         return s.toString() ;
533     }
534
535     /**
536      * Constructs a <CODE>String</CODE> containing details of each <CODE>SnmpVarBindList</CODE> (oid+value).
537      * This is typically used in debugging.
538      * @return A detailed <CODE>String</CODE> of all in the <CODE>SnmpVarBindList</CODE>.
539      */
540     public synchronized String JavaDoc varBindListToString() {
541         StringBuffer JavaDoc s = new StringBuffer JavaDoc(300) ;
542         for (int i = 0; i < elementCount ; i++) {
543             s.append(elementData[i].toString() + "\n") ;
544         }
545         return s.toString() ;
546     }
547     
548     /**
549      * Finalizer of the <CODE>SnmpVarBindList</CODE> objects.
550      * This method is called by the garbage collector on an object
551      * when garbage collection determines that there are no more references to the object.
552      * <P>Removes all the elements from this <CODE>SnmpVarBindList</CODE> object.
553      */
554     public void finalize() {
555         removeAllElements() ;
556     }
557 }
558
Popular Tags