1 /*
   2  * Copyright (c) 2000, 2012, 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 import java.util.Enumeration;
  29 import java.util.Vector;
  30 import com.sun.jmx.snmp.SnmpVarBind;
  31 import com.sun.jmx.snmp.SnmpStatusException;
  32 import com.sun.jmx.snmp.SnmpOid;
  33 // import com.sun.jmx.snmp.SnmpIndex;
  34 
  35 /**
  36  * This interface models an SNMP sub request to be performed on a specific
  37  * SNMP MIB node. The node involved can be either an SNMP group, an SNMP table,
  38  * or an SNMP table entry (conceptual row). The conceptual row may or may not
  39  * already exist. If the row did not exist at the time when the request
  40  * was received, the <CODE>isNewEntry()</CODE> method will return <CODE>
  41  * true</CODE>.
  42  * <p>
  43  * Objects implementing this interface will be allocated by the SNMP engine.
  44  * You will never need to implement this interface. You will only use it.
  45  * </p>
  46  * <p><b>This API is a Sun Microsystems internal API  and is subject
  47  * to change without notice.</b></p>
  48  */
  49 public interface SnmpMibSubRequest extends SnmpMibRequest {
  50     /**
  51      * Return the list of varbind to be handled by the SNMP MIB node.
  52      * <p>
  53      * <b>Note:</b> <ul>
  54      * <i>In case of SET operation, if this node is a table row which
  55      * contains a control variable (as identified by the table's
  56      * isRowStatus() method) the control variable will not
  57      * be included in this list: it will be obtained by calling
  58      * getRowStatusVarBind(). This will allow you to handle the control
  59      * variable specifically.</i><br>
  60      * You will never need to worry about this unless you need to
  61      * implement a non standard mechanism for handling row
  62      * creation and deletion.
  63      * </ul>
  64      * <p>
  65      * @return The elements of the enumeration are instances of
  66      *         {@link com.sun.jmx.snmp.SnmpVarBind}
  67      */
  68     @Override
  69     public Enumeration<SnmpVarBind> getElements();
  70 
  71     /**
  72      * Return the list of varbind to be handled by the SNMP MIB node.
  73      * <p>
  74      * <b>Note:</b> <ul>
  75      * <i>In case of SET operation, if this node is a table row which
  76      * contains a control variable (as identified by the table's
  77      * isRowStatus() method) the control variable will not
  78      * be included in this list: it will be obtained by calling
  79      * getRowStatusVarBind(). This will allow you to handle the control
  80      * variable specifically.</i><br>
  81      * You will never need to worry about this unless you need to
  82      * implement a non standard mechanism for handling row
  83      * creation and deletion.
  84      * </ul>
  85      * <p>
  86      * @return The elements of the vector are instances of
  87      *         {@link com.sun.jmx.snmp.SnmpVarBind}
  88      */
  89     @Override
  90     public Vector<SnmpVarBind> getSubList();
  91 
  92     /**
  93      * Return the part of the OID identifying the table entry involved.
  94      * <p>
  95      *
  96      * @return {@link com.sun.jmx.snmp.SnmpOid} or <CODE>null</CODE>
  97      *         if the request is not directed to an entry.
  98      */
  99     public SnmpOid     getEntryOid();
 100 
 101     /**
 102      * Indicate whether the entry involved is a new entry.
 103      * This method will return <CODE>true</CODE> if the entry was not
 104      * found when the request was processed. As a consequence, <CODE>
 105      * true</CODE> means that either the entry does not exist yet,
 106      * or it has been created while processing this request.
 107      * The result of this method is only significant when an entry
 108      * is involved.
 109      *
 110      * <p>
 111      * @return <CODE>true</CODE> If the entry did not exist,
 112      *  or <CODE>false</CODE> if the entry involved was found.
 113      */
 114     public boolean     isNewEntry();
 115 
 116     /**
 117      * Return the varbind that holds the RowStatus variable.
 118      * It corresponds to the varbind that was identified by
 119      * the <code>isRowStatus()</code> method generated by mibgen
 120      * on {@link com.sun.jmx.snmp.agent.SnmpMibTable} derivatives.
 121      * <ul><li>In SMIv2, it is the varbind which contains the columnar
 122      *         object implementing the RowStatus TEXTUAL-CONVENTION.</li>
 123      *      <li>In SMIv1 nothing special is generated</li>
 124      *      <ul>You may however subclass the generated table metadata
 125      *          class in order to provide your own implementation of
 126      *          isRowStatus(), getRowAction(), isRowReady() and
 127      *          setRowStatus()
 128      *          (see  {@link com.sun.jmx.snmp.agent.SnmpMibTable}).</ul>
 129      * </ul>
 130      * <p>
 131      * @return a varbind that serves to control the table modification.
 132      *         <code>null</code> means that no such varbind could be
 133      *         identified.<br>
 134      *         <b>Note:</b><i>The runtime will only try to identify
 135      *         the RowStatus varbind when processing an
 136      *         SNMP SET request. In this case, the identified
 137      *         varbind will not be included in the set of varbinds
 138      *         returned by getSubList() and getElements().
 139      *         </i>
 140      *
 141      **/
 142     public SnmpVarBind getRowStatusVarBind();
 143 
 144     /**
 145      * This method should be called when a status exception needs to
 146      * be raised for a given varbind of an SNMP GET request. This method
 147      * performs all the necessary conversions (SNMPv1 <=> SNMPv2) and
 148      * propagates the exception if needed:
 149      * If the version is SNMP v1, the exception is propagated.
 150      * If the version is SNMP v2, the exception is stored in the varbind.
 151      * This method also takes care of setting the correct value of the
 152      * index field.
 153      * <p>
 154      *
 155      * @param varbind The varbind for which the exception is
 156      *        registered. Note that this varbind <b>must</b> have
 157      *        been obtained from the enumeration returned by
 158      *        <CODE>getElements()</CODE>, or from the vector
 159      *        returned by <CODE>getSubList()</CODE>
 160      *
 161      * @param exception The exception to be registered for the given varbind.
 162      *
 163      */
 164     public void registerGetException(SnmpVarBind varbind,
 165                                      SnmpStatusException exception)
 166         throws SnmpStatusException;
 167 
 168     /**
 169      * This method should be called when a status exception needs to
 170      * be raised for a given varbind of an SNMP SET request. This method
 171      * performs all the necessary conversions (SNMPv1 <=> SNMPv2) and
 172      * propagates the exception if needed.
 173      * This method also takes care of setting the correct value of the
 174      * index field.
 175      * <p>
 176      *
 177      * @param varbind The varbind for which the exception is
 178      *        registered. Note that this varbind <b>must</b> have
 179      *        been obtained from the enumeration returned by
 180      *        <CODE>getElements()</CODE>, or from the vector
 181      *        returned by <CODE>getSubList()</CODE>
 182      *
 183      * @param exception The exception to be registered for the given varbind.
 184      *
 185      */
 186     public void registerSetException(SnmpVarBind varbind,
 187                                      SnmpStatusException exception)
 188         throws SnmpStatusException;
 189 
 190     /**
 191      * This method should be called when a status exception needs to
 192      * be raised when checking a given varbind for an SNMP SET request.
 193      * This method performs all the necessary conversions (SNMPv1 <=>
 194      * SNMPv2) and propagates the exception if needed.
 195      * This method also takes care of setting the correct value of the
 196      * index field.
 197      * <p>
 198      *
 199      * @param varbind The varbind for which the exception is
 200      *        registered. Note that this varbind <b>must</b> have
 201      *        been obtained from the enumeration returned by
 202      *        <CODE>getElements()</CODE>, or from the vector
 203      *        returned by <CODE>getSubList()</CODE>
 204      *
 205      * @param exception The exception to be registered for the given varbind.
 206      *
 207      */
 208     public void registerCheckException(SnmpVarBind varbind,
 209                                        SnmpStatusException exception)
 210         throws SnmpStatusException;
 211 }