1. /*

  2.  * @(#)file      SnmpMibSubRequest.java

  3.  * @(#)author    Sun Microsystems, Inc.

  4.  * @(#)version   1.13

  5.  * @(#)date      04/09/15

  6.  *

  7.  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.

  8.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  9.  */

  10. 

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

  12. 

  13. import java.util.Enumeration;

  14. import java.util.Vector;

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

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

  17. import com.sun.jmx.snmp.SnmpOid;

  18. // import com.sun.jmx.snmp.SnmpIndex;

  19. 

  20. /**

  21.  * This interface models an SNMP sub request to be performed on a specific 

  22.  * SNMP MIB node. The node involved can be either an SNMP group, an SNMP table,

  23.  * or an SNMP table entry (conceptual row). The conceptual row may or may not 

  24.  * already exist. If the row did not exist at the time when the request

  25.  * was received, the <CODE>isNewEntry()</CODE> method will return <CODE>

  26.  * true</CODE>. 

  27.  * <p>

  28.  * Objects implementing this interface will be allocated by the SNMP engine. 

  29.  * You will never need to implement this interface. You will only use it. 

  30.  * </p>

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

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

  33.  */

  34. public interface SnmpMibSubRequest extends SnmpMibRequest {

  35.     /**

  36.      * Return the list of varbind to be handled by the SNMP MIB node.

  37.      * <p>

  38.      * <b>Note:</b> <ul>

  39.      * <i>In case of SET operation, if this node is a table row which 

  40.      * contains a control variable (as identified by the table's 

  41.      * isRowStatus() method) the control variable will not

  42.      * be included in this list: it will be obtained by calling

  43.      * getRowStatusVarBind(). This will allow you to handle the control

  44.      * variable specifically.</i><br>

  45.      * You will never need to worry about this unless you need to

  46.      * implement a non standard mechanism for handling row

  47.      * creation and deletion.

  48.      * </ul>

  49.      * <p>

  50.      * @return The elements of the enumeration are instances of 

  51.      *         {@link com.sun.jmx.snmp.SnmpVarBind} 

  52.      */

  53.     public Enumeration getElements();

  54. 

  55.     /**

  56.      * Return the list of varbind to be handled by the SNMP MIB node.

  57.      * <p>

  58.      * <b>Note:</b> <ul>

  59.      * <i>In case of SET operation, if this node is a table row which 

  60.      * contains a control variable (as identified by the table's 

  61.      * isRowStatus() method) the control variable will not

  62.      * be included in this list: it will be obtained by calling

  63.      * getRowStatusVarBind(). This will allow you to handle the control

  64.      * variable specifically.</i><br>

  65.      * You will never need to worry about this unless you need to

  66.      * implement a non standard mechanism for handling row

  67.      * creation and deletion.

  68.      * </ul>

  69.      * <p>

  70.      * @return The elements of the vector are instances of 

  71.      *         {@link com.sun.jmx.snmp.SnmpVarBind} 

  72.      */

  73.     public Vector getSubList();

  74. 

  75.     /**

  76.      * Return the part of the OID identifying the table entry involved.

  77.      * <p>

  78.      *

  79.      * @return {@link com.sun.jmx.snmp.SnmpOid} or <CODE>null</CODE>

  80.      *         if the request is not directed to an entry.

  81.      */

  82.     public SnmpOid     getEntryOid();

  83. 

  84.     /**

  85.      * Indicate whether the entry involved is a new entry.

  86.      * This method will return <CODE>true</CODE> if the entry was not

  87.      * found when the request was processed. As a consequence, <CODE>

  88.      * true</CODE> means that either the entry does not exist yet,

  89.      * or it has been created while processing this request.

  90.      * The result of this method is only significant when an entry

  91.      * is involved.

  92.      *

  93.      * <p>

  94.      * @return <CODE>true</CODE> If the entry did not exist, 

  95.      *  or <CODE>false</CODE> if the entry involved was found.

  96.      */

  97.     public boolean     isNewEntry();

  98. 

  99.     /**

  100.      * Return the varbind that holds the RowStatus variable.

  101.      * It corresponds to the varbind that was identified by 

  102.      * the <code>isRowStatus()</code> method generated by mibgen

  103.      * on {@link com.sun.jmx.snmp.agent.SnmpMibTable} derivatives.

  104.      * <ul><li>In SMIv2, it is the varbind which contains the columnar 

  105.      *         object implementing the RowStatus TEXTUAL-CONVENTION.</li>

  106.      *      <li>In SMIv1 nothing special is generated</li>

  107.      *      <ul>You may however subclass the generated table metadata

  108.      *          class in order to provide your own implementation of

  109.      *          isRowStatus(), getRowAction(), isRowReady() and 

  110.      *          setRowStatus()

  111.      *          (see  {@link com.sun.jmx.snmp.agent.SnmpMibTable}).</ul>

  112.      * </ul>

  113.      * <p>

  114.      * @return a varbind that serves to control the table modification.

  115.      *         <code>null</code> means that no such varbind could be

  116.      *         identified.<br>

  117.      *         <b>Note:</b><i>The runtime will only try to identify

  118.      *         the RowStatus varbind when processing an

  119.      *         SNMP SET request. In this case, the identified

  120.      *         varbind will not be included in the set of varbinds 

  121.      *         returned by getSubList() and getElements().

  122.      *         </i>

  123.      *                 

  124.      **/

  125.     public SnmpVarBind getRowStatusVarBind();

  126. 

  127.     /**

  128.      * This method should be called when a status exception needs to

  129.      * be raised for a given varbind of an SNMP GET request. This method

  130.      * performs all the necessary conversions (SNMPv1 <=> SNMPv2) and

  131.      * propagates the exception if needed:

  132.      * If the version is SNMP v1, the exception is propagated.

  133.      * If the version is SNMP v2, the exception is stored in the varbind.

  134.      * This method also takes care of setting the correct value of the

  135.      * index field.

  136.      * <p>

  137.      *

  138.      * @param varbind The varbind for which the exception is

  139.      *        registered. Note that this varbind <b>must</b> have 

  140.      *        been obtained from the enumeration returned by

  141.      *        <CODE>getElements()</CODE>, or from the vector

  142.      *        returned by <CODE>getSubList()</CODE>

  143.      *

  144.      * @param exception The exception to be registered for the given varbind.

  145.      *

  146.      */

  147.     public void registerGetException(SnmpVarBind varbind,

  148. 				     SnmpStatusException exception)

  149. 	throws SnmpStatusException;

  150. 

  151.     /**

  152.      * This method should be called when a status exception needs to

  153.      * be raised for a given varbind of an SNMP SET request. This method

  154.      * performs all the necessary conversions (SNMPv1 <=> SNMPv2) and

  155.      * propagates the exception if needed.

  156.      * This method also takes care of setting the correct value of the

  157.      * index field.

  158.      * <p>

  159.      *

  160.      * @param varbind The varbind for which the exception is

  161.      *        registered. Note that this varbind <b>must</b> have 

  162.      *        been obtained from the enumeration returned by

  163.      *        <CODE>getElements()</CODE>, or from the vector

  164.      *        returned by <CODE>getSubList()</CODE>

  165.      *

  166.      * @param exception The exception to be registered for the given varbind.

  167.      *

  168.      */

  169.     public void registerSetException(SnmpVarBind varbind,

  170. 				     SnmpStatusException exception)

  171. 	throws SnmpStatusException;

  172. 

  173.     /**

  174.      * This method should be called when a status exception needs to

  175.      * be raised when checking a given varbind for an SNMP SET request. 

  176.      * This method performs all the necessary conversions (SNMPv1 <=> 

  177.      * SNMPv2) and propagates the exception if needed.

  178.      * This method also takes care of setting the correct value of the

  179.      * index field.

  180.      * <p>

  181.      *

  182.      * @param varbind The varbind for which the exception is

  183.      *        registered. Note that this varbind <b>must</b> have 

  184.      *        been obtained from the enumeration returned by

  185.      *        <CODE>getElements()</CODE>, or from the vector

  186.      *        returned by <CODE>getSubList()</CODE>

  187.      *

  188.      * @param exception The exception to be registered for the given varbind.

  189.      *

  190.      */

  191.     public void registerCheckException(SnmpVarBind varbind,

  192. 				       SnmpStatusException exception)

  193. 	throws SnmpStatusException;

  194. }

  195. 

  196.