1 /*

     2  * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 package com.sun.jmx.snmp.agent;

    27 

    28 // java imports

    29 //

    30 import java.io.Serializable;

    31 import java.util.Hashtable;

    32 import java.util.Vector;

    33 

    34 // jmx imports

    35 //

    36 import com.sun.jmx.snmp.SnmpVarBind;

    37 import com.sun.jmx.snmp.SnmpStatusException;

    38 

    39 

    40 /**

    41  * Represents a node in an SNMP MIB which corresponds to a group.

    42  * This class allows subnodes to be registered below a group, providing

    43  * support for nested groups. The subnodes are registered at run time

    44  * when registering the nested groups in the global MIB OID tree.

    45  * <P>

    46  * This class is used by the class generated by <CODE>mibgen</CODE>.

    47  * You should not need to use this class directly.

    48  *

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

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

    51  */

    52 @SuppressWarnings("serial") // JDK implementation class

    53 public abstract class SnmpMibGroup extends SnmpMibOid

    54     implements Serializable {

    55 

    56     // We will register the OID arcs leading to subgroups in this hashtable.

    57     // So for each arc in varList, if the arc is also in subgroups, it leads

    58     // to a subgroup, if it is not in subgroup, it leads either to a table

    59     // or to a variable.

    60     protected Hashtable<Long, Long> subgroups = null;

    61 

    62     /**

    63      * Tells whether the given arc identifies a table in this group.

    64      *

    65      * @param arc An OID arc.

    66      *

    67      * @return <CODE>true</CODE> if `arc' leads to a table.

    68      */

    69     public abstract boolean      isTable(long arc);

    70 

    71     /**

    72      * Tells whether the given arc identifies a variable (scalar object) in

    73      * this group.

    74      *

    75      * @param arc An OID arc.

    76      *

    77      * @return <CODE>true</CODE> if `arc' leads to a variable.

    78      */

    79     public abstract boolean      isVariable(long arc);

    80 

    81     /**

    82      * Tells whether the given arc identifies a readable scalar object in

    83      * this group.

    84      *

    85      * @param arc An OID arc.

    86      *

    87      * @return <CODE>true</CODE> if `arc' leads to a readable variable.

    88      */

    89     public abstract boolean      isReadable(long arc);

    90 

    91 

    92     /**

    93      * Gets the table identified by the given `arc'.

    94      *

    95      * @param arc An OID arc.

    96      *

    97      * @return The <CODE>SnmpMibTable</CODE> identified by `arc', or

    98      *    <CODE>null</CODE> if `arc' does not identify any table.

    99      */

   100     public abstract SnmpMibTable getTable(long arc);

   101 

   102     /**

   103      * Checks whether the given OID arc identifies a variable (scalar

   104      * object).

   105      *

   106      * @exception If the given `arc' does not identify any variable in this

   107      *    group, throws an SnmpStatusException.

   108      */

   109     public void validateVarId(long arc, Object userData)

   110         throws SnmpStatusException {

   111         if (isVariable(arc) == false) {

   112             throw new SnmpStatusException(SnmpStatusException.noSuchObject);

   113         }

   114     }

   115 

   116 

   117     // -------------------------------------------------------------------

   118     // We use a hashtable (subgroup) in order to determine whether an

   119     // OID arc leads to a subgroup. This implementation can be changed if

   120     // needed...

   121     // For instance, the subclass could provide a generated isNestedArc()

   122     // method in which the subgroup OID arcs would be hardcoded.

   123     // However, the generic approach was preferred because at this time

   124     // groups and subgroups are dynamically registered in the MIB.

   125     //

   126     /**

   127      * Tell whether the given OID arc identifies a sub-tree

   128      * leading to a nested SNMP sub-group. This method is used internally.

   129      * You shouldn't need to call it directly.

   130      *

   131      * @param arc An OID arc.

   132      *

   133      * @return <CODE>true</CODE> if the given OID arc identifies a subtree

   134      * leading to a nested SNMP sub-group.

   135      *

   136      */

   137     public boolean isNestedArc(long arc) {

   138         if (subgroups == null) return false;

   139         Object obj = subgroups.get(arc);

   140         // if the arc is registered in the hashtable,

   141         // it leads to a subgroup.

   142         return (obj != null);

   143     }

   144 

   145     /**

   146      * Generic handling of the <CODE>get</CODE> operation.

   147      * <p>The actual implementation of this method will be generated

   148      * by mibgen. Usually, this implementation only delegates the

   149      * job to some other provided runtime class, which knows how to

   150      * access the MBean. The current toolkit thus provides two

   151      * implementations:

   152      * <ul><li>The standard implementation will directly access the

   153      *         MBean through a java reference,</li>

   154      *     <li>The generic implementation will access the MBean through

   155      *         the MBean server.</li>

   156      * </ul>

   157      * <p>Both implementations rely upon specific - and distinct, set of

   158      * mibgen generated methods.

   159      * <p> You can override this method if you need to implement some

   160      * specific policies for minimizing the accesses made to some remote

   161      * underlying resources.

   162      * <p>

   163      *

   164      * @param req   The sub-request that must be handled by this node.

   165      *

   166      * @param depth The depth reached in the OID tree.

   167      *

   168      * @exception SnmpStatusException An error occurred while accessing

   169      *  the MIB node.

   170      */

   171     @Override

   172     abstract public void get(SnmpMibSubRequest req, int depth)

   173         throws SnmpStatusException;

   174 

   175     /**

   176      * Generic handling of the <CODE>set</CODE> operation.

   177      * <p>The actual implementation of this method will be generated

   178      * by mibgen. Usually, this implementation only delegates the

   179      * job to some other provided runtime class, which knows how to

   180      * access the MBean. The current toolkit thus provides two

   181      * implementations:

   182      * <ul><li>The standard implementation will directly access the

   183      *         MBean through a java reference,</li>

   184      *     <li>The generic implementation will access the MBean through

   185      *         the MBean server.</li>

   186      * </ul>

   187      * <p>Both implementations rely upon specific - and distinct, set of

   188      * mibgen generated methods.

   189      * <p> You can override this method if you need to implement some

   190      * specific policies for minimizing the accesses made to some remote

   191      * underlying resources.

   192      * <p>

   193      *

   194      * @param req   The sub-request that must be handled by this node.

   195      *

   196      * @param depth The depth reached in the OID tree.

   197      *

   198      * @exception SnmpStatusException An error occurred while accessing

   199      *  the MIB node.

   200      */

   201     @Override

   202     abstract public void set(SnmpMibSubRequest req, int depth)

   203         throws SnmpStatusException;

   204 

   205     /**

   206      * Generic handling of the <CODE>check</CODE> operation.

   207      *

   208      * <p>The actual implementation of this method will be generated

   209      * by mibgen. Usually, this implementation only delegates the

   210      * job to some other provided runtime class, which knows how to

   211      * access the MBean. The current toolkit thus provides two

   212      * implementations:

   213      * <ul><li>The standard implementation will directly access the

   214      *         MBean through a java reference,</li>

   215      *     <li>The generic implementation will access the MBean through

   216      *         the MBean server.</li>

   217      * </ul>

   218      * <p>Both implementations rely upon specific - and distinct, set of

   219      * mibgen generated methods.

   220      * <p> You can override this method if you need to implement some

   221      * specific policies for minimizing the accesses made to some remote

   222      * underlying resources, or if you need to implement some consistency

   223      * checks between the different values provided in the varbind list.

   224      * <p>

   225      *

   226      * @param req   The sub-request that must be handled by this node.

   227      *

   228      * @param depth The depth reached in the OID tree.

   229      *

   230      * @exception SnmpStatusException An error occurred while accessing

   231      *  the MIB node.

   232      */

   233     @Override

   234     abstract public void check(SnmpMibSubRequest req, int depth)

   235         throws SnmpStatusException;

   236 

   237     // --------------------------------------------------------------------

   238     // If we reach this node, we are below the root OID, so we just

   239     // return.

   240     // --------------------------------------------------------------------

   241     @Override

   242     public void getRootOid(Vector<Integer> result) {

   243     }

   244 

   245     // -------------------------------------------------------------------

   246     // PACKAGE METHODS

   247     // -------------------------------------------------------------------

   248 

   249     // -------------------------------------------------------------------

   250     // This method can also be overriden in a subclass to provide a

   251     // different implementation of the isNestedArc() method.

   252     // => if isNestedArc() is hardcoded, then registerSubArc() becomes

   253     //    useless and can become empty.

   254     /**

   255      * Register an OID arc that identifies a sub-tree

   256      * leading to a nested SNMP sub-group. This method is used internally.

   257      * You shouldn't ever call it directly.

   258      *

   259      * @param arc An OID arc.

   260      *

   261      */

   262     void registerNestedArc(long arc) {

   263         Long obj = arc;

   264         if (subgroups == null) subgroups = new Hashtable<>();

   265         // registers the arc in the hashtable.

   266         subgroups.put(obj,obj);

   267     }

   268 

   269     // -------------------------------------------------------------------

   270     // The SnmpMibOid algorithm relies on the fact that for every arc

   271     // registered in varList, there is a corresponding node at the same

   272     // position in children.

   273     // So the trick is to register a null node in children for each variable

   274     // in varList, so that the real subgroup nodes can be inserted at the

   275     // correct location.

   276     // registerObject() should be called for each scalar object and each

   277     // table arc by the generated subclass.

   278     /**

   279      * Register an OID arc that identifies a scalar object or a table.

   280      * This method is used internally. You shouldn't ever call it directly.

   281      *

   282      * @param arc An OID arc.

   283      *

   284      */

   285     protected void registerObject(long arc)

   286         throws IllegalAccessException {

   287 

   288         // this will register the variable in both varList and children

   289         // The node registered in children will be null, so that the parent

   290         // algorithm will behave as if no node were registered. This is a

   291         // trick that makes the parent algorithm behave as if only subgroups

   292         // were registered in varList and children.

   293         long[] oid = new long[1];

   294         oid[0] = arc;

   295         super.registerNode(oid,0,null);

   296     }

   297 

   298     // -------------------------------------------------------------------

   299     // registerNode() will be called at runtime when nested groups are

   300     // registered in the MIB. So we do know that this method will only

   301     // be called to register nested-groups.

   302     // We trap registerNode() in order to call registerSubArc()

   303     /**

   304      * Register a child node of this node in the OID tree.

   305      * This method is used internally. You shouldn't ever call it directly.

   306      *

   307      * @param oid The oid of the node being registered.

   308      * @param cursor The position reached in the oid.

   309      * @param node The node being registered.

   310      *

   311      */

   312     @Override

   313     void registerNode(long[] oid, int cursor ,SnmpMibNode node)

   314         throws IllegalAccessException {

   315         super.registerNode(oid,cursor,node);

   316         if (cursor < 0) return;

   317         if (cursor >= oid.length) return;

   318         // if we get here, then it means we are registering a subgroup.

   319         // We will thus register the sub arc in the subgroups hashtable.

   320         registerNestedArc(oid[cursor]);

   321     }

   322 

   323     // -------------------------------------------------------------------

   324     // see comments in SnmpMibNode

   325     // -------------------------------------------------------------------

   326     @Override

   327     void findHandlingNode(SnmpVarBind varbind,

   328                           long[] oid, int depth,

   329                           SnmpRequestTree handlers)

   330         throws SnmpStatusException {

   331 

   332         int length = oid.length;

   333 

   334         if (handlers == null)

   335             throw new SnmpStatusException(SnmpStatusException.snmpRspGenErr);

   336 

   337         final Object data = handlers.getUserData();

   338 

   339         if (depth >= length) {

   340             // Nothing is left... the oid is not valid

   341             throw new SnmpStatusException(SnmpStatusException.noAccess);

   342         }

   343 

   344         long arc = oid[depth];

   345 

   346         if (isNestedArc(arc)) {

   347             // This arc leads to a subgroup: delegates the search to the

   348             // method defined in SnmpMibOid

   349             super.findHandlingNode(varbind,oid,depth,handlers);

   350         } else if (isTable(arc)) {

   351             // This arc leads to a table: forward the search to the table.

   352 

   353             // Gets the table

   354             SnmpMibTable table = getTable(arc);

   355 

   356             // Forward the search to the table

   357             table.findHandlingNode(varbind,oid,depth+1,handlers);

   358 

   359         } else {

   360             // If it's not a variable, throws an exception

   361             validateVarId(arc, data);

   362 

   363             // The trailing .0 is missing in the OID

   364             if (depth+2 > length) {

   365                 throw new SnmpStatusException(SnmpStatusException.noSuchInstance);

   366             }

   367 

   368             // There are too many arcs left in the OID (there should remain

   369             // a single trailing .0)

   370             if (depth+2 < length) {

   371                 throw new SnmpStatusException(SnmpStatusException.noSuchInstance);

   372             }

   373 

   374             // The last trailing arc is not .0

   375             if (oid[depth+1] != 0L) {

   376                 throw new SnmpStatusException(SnmpStatusException.noSuchInstance);

   377             }

   378 

   379             // It's one of our variable, register this node.

   380             handlers.add(this,depth,varbind);

   381         }

   382     }

   383 

   384     // -------------------------------------------------------------------

   385     // See comments in SnmpMibNode.

   386     // -------------------------------------------------------------------

   387     @Override

   388     long[] findNextHandlingNode(SnmpVarBind varbind,

   389                                 long[] oid, int pos, int depth,

   390                                 SnmpRequestTree handlers, AcmChecker checker)

   391         throws SnmpStatusException {

   392 

   393         int length = oid.length;

   394         SnmpMibNode node = null;

   395 

   396         if (handlers == null) {

   397             // This should be considered as a genErr, but we do not want to

   398             // abort the whole request, so we're going to throw

   399             // a noSuchObject...

   400             //

   401             throw new SnmpStatusException(SnmpStatusException.noSuchObject);

   402         }

   403 

   404         final Object data = handlers.getUserData();

   405         final int pduVersion = handlers.getRequestPduVersion();

   406 

   407 

   408         // The generic case where the end of the OID has been reached is

   409         // handled in the superclass

   410         // XXX Revisit: this works but it is somewhat convoluted. Just setting

   411         //              arc to -1 would work too.

   412         if (pos >= length)

   413             return super.findNextHandlingNode(varbind,oid,pos,depth,

   414                                               handlers, checker);

   415 

   416         // Ok, we've got the arc.

   417         long arc = oid[pos];

   418 

   419         long[] result = null;

   420 

   421         // We have a recursive logic. Should we have a loop instead?

   422         try {

   423 

   424             if (isTable(arc)) {

   425                 // If the arc identifies a table, then we need to forward

   426                 // the search to the table.

   427 

   428                 // Gets the table identified by `arc'

   429                 SnmpMibTable table = getTable(arc);

   430 

   431                 // Forward to the table

   432                 checker.add(depth, arc);

   433                 try {

   434                     result = table.findNextHandlingNode(varbind,oid,pos+1,

   435                                                         depth+1,handlers,

   436                                                         checker);

   437                 }catch(SnmpStatusException ex) {

   438                     throw new SnmpStatusException(SnmpStatusException.noSuchObject);

   439                 } finally {

   440                     checker.remove(depth);

   441                 }

   442                 // Build up the leaf OID

   443                 result[depth] = arc;

   444                 return result;

   445             } else if (isReadable(arc)) {

   446                 // If the arc identifies a readable variable, then two cases:

   447 

   448                 if (pos == (length - 1)) {

   449                     // The end of the OID is reached, so we return the leaf

   450                     // corresponding to the variable identified by `arc'

   451 

   452                     // Build up the OID

   453                     // result = new SnmpOid(0);

   454                     // result.insert((int)arc);

   455                     result = new long[depth+2];

   456                     result[depth+1] = 0L;

   457                     result[depth] = arc;

   458 

   459                     checker.add(depth, result, depth, 2);

   460                     try {

   461                         checker.checkCurrentOid();

   462                     } catch(SnmpStatusException e) {

   463                         throw new SnmpStatusException(SnmpStatusException.noSuchObject);

   464                     } finally {

   465                         checker.remove(depth,2);

   466                     }

   467 

   468                     // Registers this node

   469                     handlers.add(this,depth,varbind);

   470                     return result;

   471                 }

   472 

   473                 // The end of the OID is not yet reached, so we must return

   474                 // the next leaf following the variable identified by `arc'.

   475                 // We cannot return the variable because whatever follows in

   476                 // the OID will be greater or equals to 0, and 0 identifies

   477                 // the variable itself - so we have indeed to return the

   478                 // next object.

   479                 // So we do nothing, because this case is handled at the

   480                 // end of the if ... else if ... else ... block.

   481 

   482             } else if (isNestedArc(arc)) {

   483                 // Now if the arc leads to a subgroup, we delegate the

   484                 // search to the child, just as done in SnmpMibNode.

   485                 //

   486 

   487                 // get the child ( = nested arc node).

   488                 //

   489                 final SnmpMibNode child = getChild(arc);

   490 

   491                 if (child != null) {

   492                     checker.add(depth, arc);

   493                     try {

   494                         result = child.findNextHandlingNode(varbind,oid,pos+1,

   495                                                             depth+1,handlers,

   496                                                             checker);

   497                         result[depth] = arc;

   498                         return result;

   499                     } finally {

   500                         checker.remove(depth);

   501                     }

   502                 }

   503             }

   504 

   505             // The oid is not valid, we will throw an exception in order

   506             // to try with the next valid identifier...

   507             //

   508             throw new SnmpStatusException(SnmpStatusException.noSuchObject);

   509 

   510         } catch (SnmpStatusException e) {

   511             // We didn't find anything at the given arc, so we're going

   512             // to try with the next valid arc

   513             //

   514             long[] newOid = new long[1];

   515             newOid[0] = getNextVarId(arc,data,pduVersion);

   516             return findNextHandlingNode(varbind,newOid,0,depth,

   517                                         handlers,checker);

   518         }

   519     }

   520 

   521 }