Back to index...

	/*
	* Copyright (c) 2000, 2013, 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.
	*
	* <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
	**/
	protected List<Object> entries;

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

	/**
	* 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.
	**/
	private boolean registrationRequired = false;



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

	/**
	* 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
	* {@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.
	*
	* @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.
	*
	* @return The number of entries registered in the table.
	**/
	public int getSize() {
	return meta.getSize();
	}

	/**
	* 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 <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.
	*
	* @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.
	*
	* @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.
	*
	* @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.
	*
	* @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 <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 <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
	* <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
	* <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 <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.
	*
	* @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.
	*
	* @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 {@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.
	* <p>
	* If the entry is going to be registered, then
	* {@link com.sun.jmx.snmp.agent.SnmpTableSupport#addEntry(SnmpIndex, ObjectName, Object)} should be preferred.
	* <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.
	*
	* @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.
	*
	* @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.
	*
	* @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.
	**/
	protected void bindWithTableMeta() {
	if (meta == null) return;
	registrationRequired = meta.isRegistrationRequired();
	meta.registerEntryFactory(this);
	}

	}

Back to index...