snmpvarbindlist.java

java1.6众多例子参考

/*
 * @(#)file      SnmpVarBindList.java
 * @(#)author    Sun Microsystems, Inc.
 * @(#)version   1.5
 * @(#)date      08/07/21
 *
 * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 */
// Copyright (c) 1995-96 by Cisco Systems, Inc.

package com.sun.jmx.snmp;


import java.util.Vector;
import java.util.Enumeration;


/**
 * Contains a list of <CODE>SnmpVarBind</CODE> objects.
 * This class helps to create an <CODE>SnmpVarBindList</CODE> from a list of MIB variable names. 
 * In addition, it contains different forms of methods which can copy or clone the list. 
 * This list is required by any SNMP entity which specifies a list of variables to query.
 * <p><b>This API is a Sun Microsystems internal API  and is subject 
 * to change without notice.</b></p>
 */

public class SnmpVarBindList extends Vector {

    /**
     * A name given to the <CODE>SnmpVarBindList</CODE>. Useful for debugging.
     * The default name is "VarBindList".
     */
    public String identity = "VarBindList " ;	// name identifying this list.

    /**
     * Timestamp when this <CODE>SnmpVarBindList</CODE> was updated.
     * Valid only for <CODE>SnmpGet</CODE> and <CODE>SnmpGetNext</CODE> operations. 
     * <CODE>SnmpTimestamp</CODE> is null by default.  
     * Also, when the list is cloned without value the timestamp is not copied.
     */
    Timestamp timestamp ;
    
    
    // CONSTRUCTORS
    //-------------

    /**
     * Prepares an empty list.
     * The initial capacity and the capacity increment are initialized to 5.
     */
    public SnmpVarBindList() {
        super(5, 5) ;
    }

    /**
     * Prepares an empty list.
     * @param initialCapacity The initial capacity of the <CODE>SnmpVarBindList</CODE>.
     */
    public SnmpVarBindList(int initialCapacity) {
        super(initialCapacity) ;
    }
    
    /**
     * Prepares an empty list with a <CODE>String</CODE> to print while debugging.
     * @param name The name of the newly created <CODE>SnmpVarBindList</CODE>.
     */
    public SnmpVarBindList(String name) {
        super(5, 5) ;
        identity = name ;
    }

    /**
     * Similar to the copy constructor. Does a shallow copy of the elements.
     * Individual elements are not cloned.
     * @param list The <CODE>SnmpVarBindList</CODE> to copy.
     */
    public SnmpVarBindList(SnmpVarBindList list) {
        super(list.size(), 5) ;
        list.copyInto(elementData) ;
        elementCount = list.size() ;
    }

    /**
     * Creates a new <CODE>SnmpVarBindList</CODE> object from a plain vector of <CODE>SnmpVarBind</CODE> objects. 
     * Objects in the specified vector can be <CODE>SnmpVarBind</CODE> objects or derivatives.
     * @param list The vector of <CODE>SnmpVarBind</CODE> objects to copy.
     */
    public SnmpVarBindList(Vector list) {
        super(list.size(), 5);
        for (Enumeration e = list.elements(); e.hasMoreElements();) {
            final SnmpVarBind varBind = (SnmpVarBind)e.nextElement();
            addElement((SnmpVarBind)varBind.clone());
        }
    }
    
    /**
     * Creates a new <CODE>SnmpVarBindList</CODE> object from a plain vector of <CODE>SnmpVarBind</CODE> objects. 
     * Objects in the specified vector can be <CODE>SnmpVarBind</CODE> objects or derivatives. 
     * @param name The name of the newly created <CODE>SnmpVarBindList</CODE>.
     * @param list The vector of <CODE>SnmpVarBind</CODE> objects to copy.
     */
    public SnmpVarBindList(String name, Vector list) {
        this(list);
        identity = name;
    }

    
    // GETTER/SETTER
    //--------------
    
    /**
     * Gets the <CODE>timestamp</CODE> associated with this <CODE>SnmpVarBindList</CODE>.
     * @return The <CODE>timestamp</CODE>.
     */
    public Timestamp getTimestamp() {
        return timestamp ;
    }

    /**
     * Records the <CODE>sysUpTime</CODE> and the actual time when this <CODE>SnmpVarBindList</CODE> 
     * was changed or created. 
     * This needs to be set explicitly.
     * @param tstamp The <CODE>SnmpTimestamp</CODE> of the device for which the values hold <CODE>true</CODE>.
     */
    public void setTimestamp(Timestamp tstamp) {
        timestamp = tstamp ;
    }

    /**
     * Gets an <CODE>SnmpVarBind</CODE> object.
     * @param pos The position in the list.
     * @return The <CODE>SnmpVarBind</CODE> object at the specified position.
     * @exception java.lang.ArrayIndexOutOfBoundsException If the specified <CODE>pos</CODE> is beyond range.
     */
    public final synchronized SnmpVarBind getVarBindAt(int pos) {
        return (SnmpVarBind)(elementAt(pos)) ;
    }

    /**
     * Gets the number of elements in this list.
     * @return The number of elements in the list.
     */
    public synchronized int getVarBindCount() {
        return size() ;
    }

    /**
     * This is a convenience function that returns an enumeration. This can be used to traverse the list. 
     * This is advantageous as it hides the implementation of the class of the list which keeps the variables.
     * @return An enumeration object of <CODE>SnmpVarBind</CODE> objects.
     */
    public synchronized Enumeration getVarBindList() {
        return elements() ;
    }

    /**
     * Replaces the current variable binding list of <CODE>SnmpVarBind</CODE> with the new specified variable binding
     * list of <CODE>SnmpVarBind</CODE> objects.
     * This method only clones the vector. It does not clone the <CODE>SnmpVarBind</CODE> objects 
     * contained in the list.
     * @param list A vector of <CODE>SnmpVarBind</CODE> objects.
     */
    public final synchronized void setVarBindList(Vector list) {
        setVarBindList(list, false) ;
    }

    /**
     * Replaces the current variable binding list of <CODE>SnmpVarBind</CODE> objects with the new variable binding 
     * list of <CODE>SnmpVarBind</CODE> objects.
     * If <CODE>copy</CODE> is <CODE>true</CODE>, it will clone each <CODE>SnmpVarBind</CODE> object 
     * contained in the list.
     * @param list A vector of <CODE>SnmpVarBind</CODE> objects.
     * @param copy The flag indicating whether each object in the list should be cloned.
     */
    public final synchronized void setVarBindList(Vector list, boolean copy) {
        synchronized (list) {
            final int max = list.size();
            setSize(max) ;
            list.copyInto(this.elementData) ;
            if (copy) { 	// do deepcopy of all vars.
                for (int i = 0; i < max ; i++) {
                    SnmpVarBind avar = (SnmpVarBind)elementData[i] ;
                    elementData[i] = avar.clone() ;
                }
            }
        }
    }
    
    
    // PUBLIC METHODS
    //---------------
    
    /**
     * Appends an <CODE>SnmpVarBindList</CODE> at the end of the current <CODE>SnmpVarBindList</CODE> object.
     * @param list The <CODE>SnmpVarBindList</CODE> to append.
     */
    public synchronized void addVarBindList(SnmpVarBindList list) {
        ensureCapacity(list.size() + size()) ;
        for (int i = 0; i < list.size(); i++) {
            addElement(list.getVarBindAt(i)) ;
        }
    }

    /**
     * Removes all the <CODE>SnmpVarBind</CODE> objects of the given <CODE>SnmpVarBindList</CODE> from the existing 
     * <CODE>SnmpVarBindList</CODE>.
     * @param list The <CODE>SnmpVarBindList</CODE> to be removed.
     * @return <CODE>true</CODE> if all the <CODE>SnmpVarBind</CODE> objects were components of this 
     * <CODE>SnmpVarBindList</CODE>, <CODE>false</CODE> otherwise.
     */
    public synchronized boolean removeVarBindList(SnmpVarBindList list) {
        boolean result = true;
        for (int i = 0; i < list.size(); i++) {
            result = removeElement(list.getVarBindAt(i)) ;
        }
        return result;
    }

    /**
     * Replaces an element at a specified location with the new element.
     * @param var The replacement variable.
     * @param pos The location in the <CODE>SnmpVarBindList</CODE>.
     * @exception java.lang.ArrayIndexOutOfBoundsException If the specified <CODE>pos</CODE> is beyond range.
     */
    public final synchronized void replaceVarBind(SnmpVarBind var, int pos) {
        setElementAt(var, pos) ;
    }

    /**
     * Prepares a vector of <CODE>SnmpVarBindList</CODE> from an array of SNMP MIB variables and instances.
     * @param list An array of <CODE>String</CODE> containing MIB variable names.
     * @param inst A common instance for each of the MIB variables in <CODE>vlist</CODE>.
     * @exception SnmpStatusException An error occurred while accessing a MIB node.
     */
    public final synchronized void addVarBind(String list[], String inst) throws SnmpStatusException {
        for (int i = 0; i < list.length; i++) {
            SnmpVarBind avar = new SnmpVarBind(list[i]) ;
            avar.addInstance(inst) ;
            addElement(avar) ;
        }
    }

    /**
     * Removes the array of SNMP MIB variables and instances from the existing <CODE>SnmpVarBindList</CODE>.
     * @param list An array of <CODE>String</CODE> containing MIB variable names.
     * @param inst A common instance for each of the MIB variables in <CODE>vlist</CODE>.
     * @return <CODE>true</CODE> if all the SNMP MIB variables were components of this <CODE>SnmpVarBindList</CODE>,
     * <CODE>false</CODE> otherwise.
     * @exception SnmpStatusException An error occurred while accessing a MIB node.
     */
    public synchronized boolean removeVarBind(String list[], String inst) throws SnmpStatusException {
        boolean result = true;
        for (int i = 0; i < list.length; i++) {
            SnmpVarBind avar = new SnmpVarBind(list[i]) ;
            avar.addInstance(inst) ;
            int indexOid = indexOfOid(avar) ;
            try {
                removeElementAt(indexOid) ;
            } catch (ArrayIndexOutOfBoundsException e) {
                result = false ;
            }
        }
        return result ;
    }

    /**
     * Adds an array of MIB variable names to the list. For example:
     * <P>
     * <CODE>
     * String mylist[] = {"sysUpTime.0", "ifInOctets.0"}
     * <BR>
     * vb.addVarBind(mylist) ;
     * </BR>
     * </CODE>
     * @param list The array of MIB variable names.
     * @exception SnmpStatusException An error occurred while accessing a MIB node.
     */