https://openjdk.java.net/ 
/*
 * Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package com.sun.jmx.snmp.agent;



// java imports
//
import java.io.Serializable;
import java.util.Date;
import java.util.Vector;
import java.util.Enumeration;
import java.util.List;
import java.util.ArrayList;

// jmx imports
//
import javax.management.Notification;
import javax.management.ObjectName;
import javax.management.NotificationFilter;
import javax.management.NotificationListener;
import javax.management.NotificationBroadcaster;
import javax.management.MBeanNotificationInfo;
import javax.management.ListenerNotFoundException;
import com.sun.jmx.snmp.SnmpOid;
import com.sun.jmx.snmp.SnmpValue;
import com.sun.jmx.snmp.SnmpVarBind;
import com.sun.jmx.snmp.SnmpStatusException;


This class is an abstraction for an SNMP table.
It is the base class for implementing SNMP tables in the
MBean world.


Its responsibility is to synchronize the MBean view of the table
(Table of entries) with the MIB view (array of OID indexes). Each
object of this class will be bound to the Metadata object which
manages the same SNMP Table within the MIB.




For each table defined in a MIB, mibgen will generate a specific
class called TableTableName that will subclass this class, and
a corresponding TableNameMeta class extending SnmpMibTable
and corresponding to the MIB view of the same table.




Objects of this class are instantiated by MBeans representing
the SNMP Group to which the table belong.



This API is a Sun Microsystems internal API  and is subject
to change without notice.


See Also:
/**
 * This class is an abstraction for an SNMP table.
 * It is the base class for implementing SNMP tables in the
 * MBean world.
 *
 * <p>
 * Its responsibility is to synchronize the MBean view of the table
 * (Table of entries) with the MIB view (array of OID indexes). Each
 * object of this class will be bound to the Metadata object which
 * manages the same SNMP Table within the MIB.
 * </p>
 *
 * <p>
 * For each table defined in a MIB, mibgen will generate a specific
 * class called Table<i>TableName</i> that will subclass this class, and
 * a corresponding <i>TableName</i>Meta class extending SnmpMibTable
 * and corresponding to the MIB view of the same table.
 * </p>
 *
 * <p>
 * Objects of this class are instantiated by MBeans representing
 * the SNMP Group to which the table belong.
 * </p>
 *
 * <p><b>This API is a Sun Microsystems internal API  and is subject
 * to change without notice.</b></p>
 * @see com.sun.jmx.snmp.agent.SnmpTableEntryFactory
 * @see com.sun.jmx.snmp.agent.SnmpMibTable
 *
 */
public abstract class SnmpTableSupport implements SnmpTableEntryFactory,
// NPCTE fix for bugId 4499265, esc 0, MR 04 sept 2001
//  SnmpTableCallbackHandler {
    SnmpTableCallbackHandler, Serializable {
// end of NPCTE fix for bugId 4499265

    //-----------------------------------------------------------------
    //
    //  Protected Variables
    //
    //-----------------------------------------------------------------

    
The list of entries

/**
     * The list of entries
     **/
    protected List<Object> entries;

    
The associated metadata object

/**
     * The associated metadata object
     **/
    protected SnmpMibTable meta;

    
The MIB to which this table belongs

/**
     * The MIB to which this table belongs
     **/
    protected SnmpMib      theMib;

    //-----------------------------------------------------------------
    //
    //  Private Variables
    //
    //-----------------------------------------------------------------

    
This variable is initialized while binding this object to its
corresponding meta object.

/**
     * This variable is initialized while binding this object to its
     * corresponding meta object.
     **/
    private boolean registrationRequired = false;



    //-----------------------------------------------------------------
    //
    //  Constructor
    //
    //-----------------------------------------------------------------

    
Initializes the table.
The steps are these:

  •  allocate an array for storing entry object,
    • 
    
  •  retrieve the corresponding metadata object
         from the MIB,
    
  •  bind this object to the corresponding metadata object
         from the MIB.
    • 



Params:
  • mib – The MIB to which this table belong.
/**
     * Initializes the table.
     * The steps are these:
     * <ul><li> allocate an array for storing entry object,</li>
     *     <li> retrieve the corresponding metadata object
     *          from the MIB,
     *     <li> bind this object to the corresponding metadata object
     *          from the MIB.</li>
     * </ul>
     *
     * @param mib The MIB to which this table belong.
     *
     **/
    protected SnmpTableSupport(SnmpMib mib) {
        theMib  = mib;
        meta    = getRegisteredTableMeta(mib);
        bindWithTableMeta();
        entries = allocateTable();
    }


    //-----------------------------------------------------------------
    //
    //  Implementation of the SnmpTableEntryFactory interface
    //
    //-----------------------------------------------------------------

    
Creates a new entry in the table. This factory method is generated by mibgen and used internally. It is part of the SnmpTableEntryFactory interface. You may subclass this method to implement any specific behaviour your application requires. 
Throws:
/**
     * Creates a new entry in the table.
     *
     * This factory method is generated by mibgen and used internally.
     * It is part of the
     * {@link com.sun.jmx.snmp.agent.SnmpTableEntryFactory} interface.
     * You may subclass this method to implement any specific behaviour
     * your application requires.
     *
     * @exception SnmpStatusException if the entry cannot be created.
     **/
    public abstract void createNewEntry(SnmpMibSubRequest request,
                                        SnmpOid rowOid, int depth,
                                        SnmpMibTable meta)
        throws SnmpStatusException;


    //-----------------------------------------------------------------
    //
    //  Public methods
    //
    //-----------------------------------------------------------------

    
Returns the entry located at the given position in the table.

Returns:The entry located at the given position, null
        if no entry can be found at this position.
/**
     * Returns the entry located at the given position in the table.
     *
     * @return The entry located at the given position, <code>null</code>
     *         if no entry can be found at this position.
     **/
    // XXXX xxxx zzz ZZZZ => public? or protected?
    public Object getEntry(int pos) {
        if (entries == null) return null;
        return entries.get(pos);
    }

    
Returns the number of entries registered in the table.

Returns:The number of entries registered in the table.
/**
     * Returns the number of entries registered in the table.
     *
     * @return The number of entries registered in the table.
     **/
    public int getSize() {
        return meta.getSize();
    }

    
This method lets you dynamically switch the creation policy.
setCreationEnabled() will switch the policy of
     remote entry creation via SET operations, by calling
     setCreationEnabled() on the metadata object
     associated with this table.

 By default remote entry creation via SET operation is disabled.

Params:
  • remoteCreationFlag – Tells whether remote entry creation must
       be enabled or disabled.

  • 
setCreationEnabled(true) will enable remote entry
     creation via SET operations.
    • 

  • 
setCreationEnabled(false) will disable remote entry
     creation via SET operations.
    • 

     By default remote entry creation via SET operation is disabled.

See Also:
/**
     * This method lets you dynamically switch the creation policy.
     *
     * <CODE>setCreationEnabled()</CODE> will switch the policy of
     *      remote entry creation via SET operations, by calling
     *      <code>setCreationEnabled()</code> on the metadata object
     *      associated with this table.
     * <BR> By default remote entry creation via SET operation is disabled.
     *
     * @param remoteCreationFlag Tells whether remote entry creation must
     *        be enabled or disabled.
     * <li>
     * <CODE>setCreationEnabled(true)</CODE> will enable remote entry
     *      creation via SET operations.</li>
     * <li>
     * <CODE>setCreationEnabled(false)</CODE> will disable remote entry
     *      creation via SET operations.</li>
     * <p> By default remote entry creation via SET operation is disabled.
     * </p>
     *
     * @see com.sun.jmx.snmp.agent.SnmpMibTable
     *
     **/
    public void setCreationEnabled(boolean remoteCreationFlag) {
        meta.setCreationEnabled(remoteCreationFlag);
    }

    
Tells whether a new entry should be created when a SET operation
is received for an entry that does not exist yet.
This method calls isCreationEnabled() on the metadata
object associated with this table.

See Also:
Returns:true if a new entry must be created, false otherwise.

        [default: returns false]
/**
     * Tells whether a new entry should be created when a SET operation
     * is received for an entry that does not exist yet.
     * This method calls <code>isCreationEnabled()</code> on the metadata
     * object associated with this table.
     *
     * @return true if a new entry must be created, false otherwise.<br>
     *         [default: returns <CODE>false</CODE>]
     *
     * @see com.sun.jmx.snmp.agent.SnmpMibTable
     **/
    public boolean isCreationEnabled() {
        return meta.isCreationEnabled();
    }

    
Tells whether the metadata object to which this table is linked
requires entries to be registered. In this case passing an
ObjectName when registering entries will be mandatory.

Returns:true if the associated metadata requires entries
        to be registered (mibgen generated generic metadata).
/**
     * Tells whether the metadata object to which this table is linked
     * requires entries to be registered. In this case passing an
     * ObjectName when registering entries will be mandatory.
     *
     * @return <code>true</code> if the associated metadata requires entries
     *         to be registered (mibgen generated generic metadata).
     **/
    public boolean isRegistrationRequired() {
        return registrationRequired;
    }

    
Builds an entry SnmpIndex from its row OID.
This method is generated by mibgen and used internally.

Params:
  • rowOid – The SnmpOid object identifying a table entry.
Throws:
Returns:The SnmpIndex of the entry identified by rowOid.
/**
     * Builds an entry SnmpIndex from its row OID.
     *
     * This method is generated by mibgen and used internally.
     *
     * @param rowOid The SnmpOid object identifying a table entry.
     *
     * @return The SnmpIndex of the entry identified by <code>rowOid</code>.
     *
     * @exception SnmpStatusException if the index cannot be built from the
     *            given OID.
     **/
    public SnmpIndex buildSnmpIndex(SnmpOid rowOid)
        throws SnmpStatusException {
        return buildSnmpIndex(rowOid.longValue(false), 0);
    }

    
Builds an SnmpOid from an SnmpIndex object.
This method is generated by mibgen and used internally.

Params:
  • index – An SnmpIndex object identifying a table entry.
Throws:
Returns:The SnmpOid form of the given entry index.
/**
     * Builds an SnmpOid from an SnmpIndex object.
     *
     * This method is generated by mibgen and used internally.
     *
     * @param index An SnmpIndex object identifying a table entry.
     *
     * @return The SnmpOid form of the given entry index.
     *
     * @exception SnmpStatusException if the given index is not valid.
     **/
    public abstract SnmpOid buildOidFromIndex(SnmpIndex index)
        throws SnmpStatusException;

    
Builds the default ObjectName of an entry from the SnmpIndex
identifying this entry. No access is made on the entry itself.
This method is generated by mibgen and used internally.
You can subclass this method if you want to change the default
ObjectName policy. This is only meaningfull when entries
are registered MBeans.

Params:
  • index – The SnmpIndex identifying the entry from which we
             want to build the default ObjectName.
Throws:
Returns:The default ObjectName for the entry identified by
        the given index.
/**
     * Builds the default ObjectName of an entry from the SnmpIndex
     * identifying this entry. No access is made on the entry itself.
     *
     * This method is generated by mibgen and used internally.
     * You can subclass this method if you want to change the default
     * ObjectName policy. This is only meaningfull when entries
     * are registered MBeans.
     *
     * @param index The SnmpIndex identifying the entry from which we
     *              want to build the default ObjectName.
     *
     * @return The default ObjectName for the entry identified by
     *         the given index.
     *
     * @exception SnmpStatusException if the given index is not valid.
     **/
    public abstract ObjectName buildNameFromIndex(SnmpIndex index)
        throws SnmpStatusException;


    //-----------------------------------------------------------------
    //
    //  Implementation of the SnmpTableEntryFactory interface
    //
    //-----------------------------------------------------------------

    
This callback is called by  the associated metadata object
when a new table entry has been registered in the
table metadata.
This method will update the entries list.

Params:
  • pos –   The position at which the new entry was inserted
             in the table.
  • row –   The row OID of the new entry
  • name –  The ObjectName of the new entry (as specified by the
             factory)
  • entry – The new entry (as returned by the factory)
  • meta –  The table metadata object.
/**
     * This callback is called by  the associated metadata object
     * when a new table entry has been registered in the
     * table metadata.
     *
     * This method will update the <code>entries</code> list.
     *
     * @param pos   The position at which the new entry was inserted
     *              in the table.
     * @param row   The row OID of the new entry
     * @param name  The ObjectName of the new entry (as specified by the
     *              factory)
     * @param entry The new entry (as returned by the factory)
     * @param meta  The table metadata object.
     *
     **/
    public void addEntryCb(int pos, SnmpOid row, ObjectName name,
                           Object entry, SnmpMibTable meta)
        throws SnmpStatusException {
        try {
            if (entries != null) entries.add(pos,entry);
        } catch (Exception e) {
            throw new SnmpStatusException(SnmpStatusException.noSuchName);
        }
    }

    
This callback is called by  the associated metadata object
when a new table entry has been removed from the
table metadata.
This method will update the entries list.

Params:
  • pos –   The position from which the entry was deleted
  • row –   The row OID of the deleted entry
  • name –  The ObjectName of the deleted entry (may be null if
             ObjectName's were not required)
  • entry – The deleted entry (may be null if only ObjectName's
             were required)
  • meta –  The table metadata object.
/**
     * This callback is called by  the associated metadata object
     * when a new table entry has been removed from the
     * table metadata.
     *
     * This method will update the <code>entries</code> list.
     *
     * @param pos   The position from which the entry was deleted
     * @param row   The row OID of the deleted entry
     * @param name  The ObjectName of the deleted entry (may be null if
     *              ObjectName's were not required)
     * @param entry The deleted entry (may be null if only ObjectName's
     *              were required)
     * @param meta  The table metadata object.
     *
     **/
    public void removeEntryCb(int pos, SnmpOid row, ObjectName name,
                              Object entry, SnmpMibTable meta)
        throws SnmpStatusException {
        try {
            if (entries != null) entries.remove(pos);
        } catch (Exception e) {
        }
    }



    
Enables to add an SNMP entry listener to this
SnmpMibTable.

Params:
  • listener – The listener object which will handle the
   notifications emitted by the registered MBean.
  • filter – The filter object. If filter is null, no filtering
   will be performed before handling notifications.
  • handback – The context to be sent to the listener when a
   notification is emitted.
Throws:
/**
     * Enables to add an SNMP entry listener to this
     * <CODE>SnmpMibTable</CODE>.
     *
     * @param listener The listener object which will handle the
     *    notifications emitted by the registered MBean.
     *
     * @param filter The filter object. If filter is null, no filtering
     *    will be performed before handling notifications.
     *
     * @param handback The context to be sent to the listener when a
     *    notification is emitted.
     *
     * @exception IllegalArgumentException Listener parameter is null.
     */
    public void
        addNotificationListener(NotificationListener listener,
                                NotificationFilter filter, Object handback) {
        meta.addNotificationListener(listener,filter,handback);
    }

    
Enables to remove an SNMP entry listener from this
SnmpMibTable.

Params:
  • listener – The listener object which will handle the
   notifications emitted by the registered MBean.
   This method will remove all the information related to this
   listener.
Throws:
/**
     * Enables to remove an SNMP entry listener from this
     * <CODE>SnmpMibTable</CODE>.
     *
     * @param listener The listener object which will handle the
     *    notifications emitted by the registered MBean.
     *    This method will remove all the information related to this
     *    listener.
     *
     * @exception ListenerNotFoundException The listener is not registered
     *    in the MBean.
     */
    public synchronized void
        removeNotificationListener(NotificationListener listener)
        throws ListenerNotFoundException {
        meta.removeNotificationListener(listener);
    }

    
Returns a NotificationInfo object containing the
notification class and the notification type sent by the
SnmpMibTable.

/**
     * Returns a <CODE>NotificationInfo</CODE> object containing the
     * notification class and the notification type sent by the
     * <CODE>SnmpMibTable</CODE>.
     */
    public MBeanNotificationInfo[] getNotificationInfo() {
        return meta.getNotificationInfo();
    }

    //-----------------------------------------------------------------
    //
    //  Protected Abstract methods
    //
    //-----------------------------------------------------------------

    
Builds an SnmpIndex object from the index part of an OID.
This method is generated by mibgen and used internally.

Params:
  • oid – The OID from which to build the index, represented
       as an array of long.
  • start – The position where to start from in the OID array.
Throws:
Returns:The SnmpOid form of the given entry index.
/**
     * Builds an SnmpIndex object from the index part of an OID.
     *
     * This method is generated by mibgen and used internally.
     *
     * @param oid The OID from which to build the index, represented
     *        as an array of long.
     * @param start The position where to start from in the OID array.
     *
     * @return The SnmpOid form of the given entry index.
     *
     * @exception SnmpStatusException if the given index is not valid.
     **/
    protected abstract SnmpIndex buildSnmpIndex(long oid[], int start )
        throws SnmpStatusException;

    
Returns the metadata object associated with this table.
This method is generated by mibgen and used internally.

Params:
  • mib – The SnmpMib object holding the Metadata corresponding
           to this table.
Returns:The metadata object associated with this table.
        Returns null if this implementation of the
        MIB doesn't support this table.
/**
     * Returns the metadata object associated with this table.
     *
     * This method is generated by mibgen and used internally.
     *
     * @param mib The SnmpMib object holding the Metadata corresponding
     *            to this table.
     *
     * @return The metadata object associated with this table.
     *         Returns <code>null</code> if this implementation of the
     *         MIB doesn't support this table.
     **/
    protected abstract SnmpMibTable getRegisteredTableMeta(SnmpMib mib);


    //-----------------------------------------------------------------
    //
    //  Protected methods
    //
    //-----------------------------------------------------------------

    
Allocates an ArrayList for storing table entries. This method is called within the constructor at object creation. Any object implementing the List interface can be used. 
Returns:A new list in which to store entries. If null
        is returned then no entry will be stored in the list
        and getEntry() will always return null.
/**
     * Allocates an ArrayList for storing table entries.
     *
     * This method is called within the constructor at object creation.
     * Any object implementing the {@link java.util.List} interface can
     * be used.
     *
     * @return A new list in which to store entries. If <code>null</code>
     *         is returned then no entry will be stored in the list
     *         and getEntry() will always return null.
     **/
    protected List<Object> allocateTable() {
        return new ArrayList<Object>();
    }

    
Add an entry in this table.
This method registers an entry in the table and perform
synchronization with the associated table metadata object.
This method assumes that the given entry will not be registered,
or will be registered with its default ObjectName built from the
associated  SnmpIndex.

 If the entry is going to be registered, then addEntry(SnmpIndex, ObjectName, Object) should be prefered. 
 This function is mainly provided for backward compatibility.

Params:
  • index – The SnmpIndex built from the given entry.
  • entry – The entry that should be added in the table.
Throws:
/**
     * Add an entry in this table.
     *
     * This method registers an entry in the table and perform
     * synchronization with the associated table metadata object.
     *
     * This method assumes that the given entry will not be registered,
     * or will be registered with its default ObjectName built from the
     * associated  SnmpIndex.
     * <p>
     * If the entry is going to be registered, then
     * {@link com.sun.jmx.snmp.agent.SnmpTableSupport#addEntry(SnmpIndex, ObjectName, Object)} should be prefered.
     * <br> This function is mainly provided for backward compatibility.
     *
     * @param index The SnmpIndex built from the given entry.
     * @param entry The entry that should be added in the table.
     *
     * @exception SnmpStatusException if the entry cannot be registered with
     *            the given index.
     **/
    protected void addEntry(SnmpIndex index, Object entry)
        throws SnmpStatusException {
        SnmpOid oid = buildOidFromIndex(index);
        ObjectName name = null;
        if (isRegistrationRequired()) {
            name = buildNameFromIndex(index);
        }
        meta.addEntry(oid,name,entry);
    }

    
Add an entry in this table.
This method registers an entry in the table and performs
synchronization with the associated table metadata object.

Params:
  • index – The SnmpIndex built from the given entry.
  • name –  The ObjectName with which this entry will be registered.
  • entry – The entry that should be added in the table.
Throws:
/**
     * Add an entry in this table.
     *
     * This method registers an entry in the table and performs
     * synchronization with the associated table metadata object.
     *
     * @param index The SnmpIndex built from the given entry.
     * @param name  The ObjectName with which this entry will be registered.
     * @param entry The entry that should be added in the table.
     *
     * @exception SnmpStatusException if the entry cannot be registered with
     *            the given index.
     **/
    protected void addEntry(SnmpIndex index, ObjectName name, Object entry)
        throws SnmpStatusException {
        SnmpOid oid = buildOidFromIndex(index);
        meta.addEntry(oid,name,entry);
    }

    
Remove an entry from this table.
This method unregisters an entry from the table and performs
synchronization with the associated table metadata object.

Params:
  • index – The SnmpIndex identifying the entry.
  • entry – The entry that should be removed in the table. This
             parameter is optional and can be omitted if it doesn't
             need to be passed along to the
             removeEntryCb() callback defined in the SnmpTableCallbackHandler interface.
Throws:
/**
     * Remove an entry from this table.
     *
     * This method unregisters an entry from the table and performs
     * synchronization with the associated table metadata object.
     *
     * @param index The SnmpIndex identifying the entry.
     * @param entry The entry that should be removed in the table. This
     *              parameter is optional and can be omitted if it doesn't
     *              need to be passed along to the
     *              <code>removeEntryCb()</code> callback defined in the
     *              {@link com.sun.jmx.snmp.agent.SnmpTableCallbackHandler}
     *              interface.
     *
     * @exception SnmpStatusException if the entry cannot be unregistered.
     **/
    protected void removeEntry(SnmpIndex index, Object entry)
        throws SnmpStatusException {
        SnmpOid oid = buildOidFromIndex(index);
        meta.removeEntry(oid,entry);
    }

    // protected void removeEntry(ObjectName name, Object entry)
    //  throws SnmpStatusException {
    //  meta.removeEntry(name,entry);
    // }

    
Returns the entries in the table.

Returns:An Object[] array containing the entries registered in the
        table.
/**
     * Returns the entries in the table.
     *
     * @return An Object[] array containing the entries registered in the
     *         table.
     **/
    protected Object[] getBasicEntries() {
        if (entries == null) return null;
        Object[] array= new Object[entries.size()];
        entries.toArray(array);
        return array;
    }

    
Binds this table with its associated metadata, registering itself
as an SnmpTableEntryFactory.

/**
     * Binds this table with its associated metadata, registering itself
     * as an SnmpTableEntryFactory.
     **/
    protected void bindWithTableMeta() {
        if (meta == null) return;
        registrationRequired = meta.isRegistrationRequired();
        meta.registerEntryFactory(this);
    }

}