/*

 * Copyright (c) 1997, 2012, 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;

import java.io.Serializable;

import java.util.Enumeration;

import java.util.logging.Level;

import java.util.Vector;

import javax.management.ObjectName;

import javax.management.MBeanServer;

import javax.management.MalformedObjectNameException;

import javax.management.InstanceAlreadyExistsException;

import javax.management.MBeanRegistrationException;

import javax.management.NotCompliantMBeanException;

import static com.sun.jmx.defaults.JmxProperties.SNMP_ADAPTOR_LOGGER;

import com.sun.jmx.snmp.SnmpOid;

import com.sun.jmx.snmp.SnmpVarBind;

import com.sun.jmx.snmp.SnmpDefinitions;

import com.sun.jmx.snmp.SnmpStatusException;

/**

 * Abstract class for representing an SNMP MIB.

 * <P>

 * When compiling a SNMP MIB, among all the classes generated by

 * <CODE>mibgen</CODE>, there is one which extends <CODE>SnmpMib</CODE>

 * for representing a whole MIB.

 * <BR>The class is used by the SNMP protocol adaptor as the entry point in

 * the MIB.

 *

 * <p>This generated class can be subclassed in your code in order to

 * plug in your own specific behaviour.

 * </p>

 *

 * <p><b>This API is a Sun Microsystems internal API  and is subject

 * to change without notice.</b></p>

 */

public abstract class SnmpMib extends SnmpMibAgent implements Serializable {

    /**

     * Default constructor.

     * Initializes the OID tree.

     */

    public SnmpMib() {

        root= new SnmpMibOid();

    }

    // --------------------------------------------------------------------

    // POLYMORHIC METHODS

    // --------------------------------------------------------------------

    /**

     * <p>

     * This callback should return the OID associated to the group

     * identified by the given <code>groupName</code>.

     * </p>

     *

     * <p>

     * This method is provided as a hook to plug-in some custom

     * specific behavior. Although doing so is discouraged you might

     * want to subclass this method in order to store & provide more metadata

     * information (mapping OID <-> symbolic name) within the agent,

     * or to "change" the root of the MIB OID by prefixing the

     * defaultOid by an application dependant OID string, for instance.

     * </p>

     *

     * <p>

     * The default implementation of this method is to return the given

     * <code>defaultOid</code>

     * </p>

     *

     * @param groupName   The java-ized name of the SNMP group.

     * @param defaultOid  The OID defined in the MIB for that group

     *                    (in dot notation).

     *

     * @return The OID of the group identified by <code>groupName</code>,

     *         in dot-notation.

     */

    protected String getGroupOid(String groupName, String defaultOid) {

        return defaultOid;

    }

    /**

     * <p>

     * This callback should return the ObjectName associated to the

     * group identified by the given <code>groupName</code>.

     * </p>

     *

     * <p>

     * This method is provided as a hook to plug-in some custom

     * specific behavior. You might want to override this method

     * in order to provide a different object naming scheme than

     * that proposed by default by <code>mibgen</code>.

     * </p>

     *

     * <p>

     * This method is only meaningful if the MIB is registered

     * in the MBeanServer, otherwise, it will not be called.

     * </p>

     *

     * <p>

     * The default implementation of this method is to return an ObjectName

     * built from the given <code>defaultName</code>.

     * </p>

     *

     * @param name  The java-ized name of the SNMP group.

     * @param oid   The OID returned by getGroupOid() - in dot notation.

     * @param defaultName The name by default generated by <code>

     *                    mibgen</code>

     *

     * @return The ObjectName of the group identified by <code>name</code>

     */

    protected ObjectName getGroupObjectName(String name, String oid,

                                            String defaultName)

        throws MalformedObjectNameException {

        return new ObjectName(defaultName);

    }

    /**

     * <p>

     * Register an SNMP group and its metadata node in the MIB.

     * </p>

     *

     * <p>

     * This method is provided as a hook to plug-in some custom

     * specific behavior. You might want to override this method

     * if you want to set special links between the MBean, its metadata

     * node, its OID or ObjectName etc..

     * </p>

     *

     * <p>

     * If the MIB is not registered in the MBeanServer, the <code>

     * server</code> and <code>groupObjName</code> parameters will be

     * <code>null</code>.<br>

     * If the given group MBean is not <code>null</code>, and if the

     * <code>server</code> and <code>groupObjName</code> parameters are

     * not null, then this method will also automatically register the

     * group MBean with the given MBeanServer <code>server</code>.

     * </p>

     *

     * @param groupName  The java-ized name of the SNMP group.

     * @param groupOid   The OID as returned by getGroupOid() - in dot

     *                   notation.

     * @param groupObjName The ObjectName as returned by getGroupObjectName().

     *                   This parameter may be <code>null</code> if the

     *                   MIB is not registered in the MBeanServer.

     * @param node       The metadata node, as returned by the metadata

     *                   factory method for this group.

     * @param group      The MBean for this group, as returned by the

     *                   MBean factory method for this group.

     * @param server     The MBeanServer in which the groups are to be

     *                   registered. This parameter will be <code>null</code>

     *                   if the MIB is not registered, otherwise it is a

     *                   reference to the MBeanServer in which the MIB is

     *                   registered.

     *

     */

    protected void registerGroupNode(String groupName,   String groupOid,

                                     ObjectName groupObjName, SnmpMibNode node,

                                     Object group, MBeanServer server)

        throws NotCompliantMBeanException, MBeanRegistrationException,

        InstanceAlreadyExistsException, IllegalAccessException {

        root.registerNode(groupOid,node);

        if (server != null && groupObjName != null && group != null)

            server.registerMBean(group,groupObjName);

    }

    /**

     * <p>

     * Register an SNMP Table metadata node in the MIB.

     * </p>

     *

     * <p>

     * <b><i>

     * This method is used internally and you should never need to

     * call it directly.</i></b><br> It is used to establish the link

     * between an SNMP table metadata node and its bean-like counterpart.

     * <br>

     * The group metadata nodes will create and register their

     * underlying table metadata nodes in the MIB using this

     * method. <br>

     * The metadata nodes will be later retrieved from the MIB by the

     * bean-like table objects using the getRegisterTableMeta() method.

     * </p>

     *

     * @param name      The java-ized name of the SNMP table.

     * @param table     The SNMP table metadata node - usually this

     *                  corresponds to a <code>mibgen</code> generated

     *                  object.

     */

    public abstract void registerTableMeta(String name, SnmpMibTable table);

    /**

     * Returns a registered SNMP Table metadata node.

     *

     * <p><b><i>

     * This method is used internally and you should never need to

     * call it directly.

     * </i></b></p>

     *

     */

    public abstract SnmpMibTable getRegisteredTableMeta(String name);

    // --------------------------------------------------------------------

    // PUBLIC METHODS

    // --------------------------------------------------------------------

    /**

     * Processes a <CODE>get</CODE> operation.

     *

     **/

    // Implements the method defined in SnmpMibAgent. See SnmpMibAgent

    // for java-doc

    //

    public void get(SnmpMibRequest req) throws SnmpStatusException {

        // Builds the request tree: creation is not allowed, operation

        // is not atomic.

        final int reqType = SnmpDefinitions.pduGetRequestPdu;

        SnmpRequestTree handlers = getHandlers(req,false,false,reqType);

        SnmpRequestTree.Handler h = null;

        SnmpMibNode meta = null;

        if (SNMP_ADAPTOR_LOGGER.isLoggable(Level.FINEST)) {

            SNMP_ADAPTOR_LOGGER.logp(Level.FINEST, SnmpMib.class.getName(),

                    "get", "Processing handlers for GET... ");

        }

        // For each sub-request stored in the request-tree, invoke the

        // get() method.

            // Gets the Meta node. It can be either a Group Meta or a

            // Table Meta.

            //

            meta = handlers.getMetaNode(h);

            // Gets the depth of the Meta node in the OID tree

            final int depth = handlers.getOidDepth(h);

                 rqs.hasMoreElements();) {

                // Invoke the get() operation.

            }

        }

    }

    /**

     * Processes a <CODE>set</CODE> operation.

     *

     */

    // Implements the method defined in SnmpMibAgent. See SnmpMibAgent

    // for java-doc

    //

    public void set(SnmpMibRequest req) throws SnmpStatusException {

        SnmpRequestTree handlers = null;

        // Optimization: we're going to get the whole SnmpRequestTree

        // built in the "check" method, so that we don't have to rebuild

        // it here.

        //

        if (req instanceof SnmpMibRequestImpl)

            handlers = ((SnmpMibRequestImpl)req).getRequestTree();

        // Optimization didn't work: we have to rebuild the tree.

        //

        // Builds the request tree: creation is not allowed, operation

        // is atomic.

        //

        final int reqType = SnmpDefinitions.pduSetRequestPdu;

        if (handlers == null) handlers = getHandlers(req,false,true,reqType);

        handlers.switchCreationFlag(false);

        handlers.setPduType(reqType);

        if (SNMP_ADAPTOR_LOGGER.isLoggable(Level.FINEST)) {

            SNMP_ADAPTOR_LOGGER.logp(Level.FINEST, SnmpMib.class.getName(),

                    "set", "Processing handlers for SET... ");

        }

        // For each sub-request stored in the request-tree, invoke the

        // get() method.

            // Gets the Meta node. It can be either a Group Meta or a

            // Table Meta.

            //

            meta = handlers.getMetaNode(h);

            // Gets the depth of the Meta node in the OID tree

            final int depth = handlers.getOidDepth(h);

                 rqs.hasMoreElements();) {

                // Invoke the set() operation

            }

        }

    }

    /**

     * Checks if a <CODE>set</CODE> operation can be performed.

     * If the operation cannot be performed, the method will raise a

     * <CODE>SnmpStatusException</CODE>.

     *

     */

    // Implements the method defined in SnmpMibAgent. See SnmpMibAgent

    // for java-doc

    //

    public void check(SnmpMibRequest req) throws SnmpStatusException {

        final int reqType = SnmpDefinitions.pduWalkRequest;

        // Builds the request tree: creation is allowed, operation

        // is atomic.

        SnmpRequestTree handlers = getHandlers(req,true,true,reqType);

        if (SNMP_ADAPTOR_LOGGER.isLoggable(Level.FINEST)) {

            SNMP_ADAPTOR_LOGGER.logp(Level.FINEST, SnmpMib.class.getName(),

                    "check", "Processing handlers for CHECK... ");

        }

        // For each sub-request stored in the request-tree, invoke the

        // check() method.

            // Gets the Meta node. It can be either a Group Meta or a

            // Table Meta.

            //

            meta = handlers.getMetaNode(h);

            // Gets the depth of the Meta node in the OID tree

            final int depth = handlers.getOidDepth(h);

                 rqs.hasMoreElements();) {

                // Invoke the check() operation

            }

        }

        // Optimization: we're going to pass the whole SnmpRequestTree

        // to the "set" method, so that we don't have to rebuild it there.

        //

        if (req instanceof SnmpMibRequestImpl) {

            ((SnmpMibRequestImpl)req).setRequestTree(handlers);

        }

    }

    /**

     * Processes a <CODE>getNext</CODE> operation.

     *

     */

    // Implements the method defined in SnmpMibAgent. See SnmpMibAgent

    // for java-doc

    //

    public void getNext(SnmpMibRequest req) throws SnmpStatusException {

        // Build the request tree for the operation

        // The subrequest stored in the request tree are valid GET requests

        SnmpRequestTree handlers = getGetNextHandlers(req);

        if (SNMP_ADAPTOR_LOGGER.isLoggable(Level.FINEST)) {

            SNMP_ADAPTOR_LOGGER.logp(Level.FINEST, SnmpMib.class.getName(),

                    "getNext", "Processing handlers for GET-NEXT... ");

        }

        // Now invoke get() for each subrequest of the request tree.

            // Gets the Meta node. It can be either a Group Meta or a

            // Table Meta.

            //

            meta = handlers.getMetaNode(h);

            // Gets the depth of the Meta node in the OID tree

            int depth = handlers.getOidDepth(h);

                 rqs.hasMoreElements();) {

                // Invoke the get() operation

            }

        }

    }

    /**

     * Processes a <CODE>getBulk</CODE> operation.

     * The method implements the <CODE>getBulk</CODE> operation by calling

     * appropriately the <CODE>getNext</CODE> method.

     *

     */

    // Implements the method defined in SnmpMibAgent. See SnmpMibAgent

    // for java-doc

    //

    public void getBulk(SnmpMibRequest req, int nonRepeat, int maxRepeat)

        throws SnmpStatusException {

        getBulkWithGetNext(req, nonRepeat, maxRepeat);

    }

    /**

     * Gets the root object identifier of the MIB.

     * <P>In order to be accurate, the method should be called once the

     * MIB is fully initialized (that is, after a call to <CODE>init</CODE>

     * or <CODE>preRegister</CODE>).

     *

     * @return The root object identifier.

     */

    public long[] getRootOid() {

        if( rootOid == null) {

            // Ask the tree to do the job !

            //

            root.getRootOid(list);

            // Now format the result

            //

            rootOid= new long[list.size()];

            int i=0;

            for(Enumeration<Integer> e= list.elements(); e.hasMoreElements(); ) {

                Integer val= e.nextElement();

                rootOid[i++]= val.longValue();

            }

        }

        return rootOid;

    }

    // --------------------------------------------------------------------

    // PRIVATE METHODS

    //---------------------------------------------------------------------

    /**

     * This method builds the temporary request-tree that will be used to

     * perform the SNMP request associated with the given vector of varbinds

     * `list'.

     *

     * @param req The SnmpMibRequest object holding the varbind list

     *             concerning this MIB.

     * @param createflag Indicates whether the operation allow for creation

     *        of new instances (ie: it is a SET).

     * @param atomic Indicates whether the operation is atomic or not.

     * @param type Request type (from SnmpDefinitions).

     *

     * @return The request-tree where the original varbind list has been

     *         dispatched to the appropriate nodes.

     */

    private SnmpRequestTree getHandlers(SnmpMibRequest req,

                                        boolean createflag, boolean atomic,

                                        int type)

        throws SnmpStatusException {

        // Build an empty request tree

        SnmpRequestTree handlers =

            new SnmpRequestTree(req,createflag,type);

        int index=0;

        final int ver= req.getVersion();

        // For each varbind in the list finds its handling node.

            try {

                // Find the handling node for this varbind.

                root.findHandlingNode(var,var.oid.longValue(false),