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 package com.sun.jmx.snmp.agent;
26
27 import java.util.Enumeration;
28 import java.util.Vector;
29
30 import com.sun.jmx.snmp.SnmpVarBind;
31 import com.sun.jmx.snmp.SnmpPdu;
32 import com.sun.jmx.snmp.SnmpEngine;
33
34 /**
35 * This interface models the part of a SNMP request that involves
36 * a specific MIB. One object implementing this interface will be created
37 * for every MIB involved in a SNMP request, and that object will be passed
38 * to the SnmpMibAgent in charge of handling that MIB.
39 *
40 * Objects implementing this interface will be allocated by the SNMP engine.
41 * You will never need to implement this interface. You will only use it.
42 *
43 * <p><b>This API is a Sun Microsystems internal API and is subject
44 * to change without notice.</b></p>
45 */
46 public interface SnmpMibRequest {
47 /**
48 * Returns the list of varbind to be handled by the SNMP mib node.
49 *
50 * @return The element of the enumeration are instances of
51 * {@link com.sun.jmx.snmp.SnmpVarBind}
52 */
53 public Enumeration<SnmpVarBind> getElements();
54
55 /**
56 * Returns the vector of varbind to be handled by the SNMP mib node.
57 * The caller shall not modify this vector.
58 *
59 * @return The element of the vector are instances of
60 * {@link com.sun.jmx.snmp.SnmpVarBind}
61 */
62 public Vector<SnmpVarBind> getSubList();
63
64 /**
65 * Returns the SNMP protocol version of the original request. If SNMP V1 request are received, the version is upgraded to SNMP V2.
66 *
67 * @return The SNMP protocol version of the original request.
68 */
69 public int getVersion();
70
71 /**
72 * Returns the SNMP protocol version of the original request. No translation is done on the version. The actual received request SNMP version is returned.
73 *
74 * @return The SNMP protocol version of the original request.
75 *
76 * @since 1.5
77 */
78 public int getRequestPduVersion();
79
80 /**
81 * Returns the local engine. This parameter is returned only if <CODE> SnmpV3AdaptorServer </CODE> is the adaptor receiving this request. Otherwise null is returned.
82 * @return the local engine.
83 *
84 * @since 1.5
85 */
86 public SnmpEngine getEngine();
87 /**
88 * Gets the incoming request principal. This parameter is returned only if <CODE> SnmpV3AdaptorServer </CODE> is the adaptor receiving this request. Otherwise null is returned.
89 * @return The request principal.
90 *
91 * @since 1.5
92 **/
93 public String getPrincipal();
94 /**
95 * Gets the incoming request security level. This level is defined in {@link com.sun.jmx.snmp.SnmpEngine SnmpEngine}. This parameter is returned only if <CODE> SnmpV3AdaptorServer </CODE> is the adaptor receiving this request. Otherwise -1 is returned.
96 * @return The security level.
97 *
98 * @since 1.5
99 */
100 public int getSecurityLevel();
101 /**
102 * Gets the incoming request security model. This parameter is returned only if <CODE> SnmpV3AdaptorServer </CODE> is the adaptor receiving this request. Otherwise -1 is returned.
103 * @return The security model.
104 *
105 * @since 1.5
106 */
107 public int getSecurityModel();
108 /**
109 * Gets the incoming request context name. This parameter is returned only if <CODE> SnmpV3AdaptorServer </CODE> is the adaptor receiving this request. Otherwise null is returned.
110 * @return The context name.
111 *
112 * @since 1.5
113 */
114 public byte[] getContextName();
115 /**
116 * Gets the incoming request context name used by Access Control Model in order to allow or deny the access to OIDs. This parameter is returned only if <CODE> SnmpV3AdaptorServer </CODE> is the adaptor receiving this request. Otherwise null is returned.
117 * @return The checked context name.
118 *
119 * @since 1.5
120 */
121 public byte[] getAccessContextName();
122
123 /**
124 * Returns a handle on a user allocated contextual object.
125 * This contextual object is allocated through the SnmpUserDataFactory
126 * on a per SNMP request basis, and is handed back to the user via
127 * SnmpMibRequest (and derivative) objects. It is never accessed by
128 * the system, but might be handed back in multiple threads. It is thus
129 * the user responsibility to make sure he handles this object in a
130 * thread safe manner.
131 */
132 public Object getUserData();
133
134 /**
135 * Returns the varbind index that should be embedded in an
136 * SnmpStatusException for this particular varbind.
137 * This does not necessarily correspond to the "real"
138 * index value that will be returned in the result PDU.
139 *
140 * @param varbind The varbind for which the index value is
141 * querried. Note that this varbind <b>must</b> have
142 * been obtained from the enumeration returned by
143 * <CODE>getElements()</CODE>, or from the vector
144 * returned by <CODE>getSublist()</CODE>.
145 *
146 * @return The varbind index that should be embedded in an
147 * SnmpStatusException for this particular varbind.
148 */
149 public int getVarIndex(SnmpVarBind varbind);
150
151 /**
152 * Adds a varbind to this request sublist. This method is used for
153 * internal purposes and you should never need to call it directly.
154 *
155 * @param varbind The varbind to be added in the sublist.
156 *
157 */
158 public void addVarBind(SnmpVarBind varbind);
159
160
161 /**
162 * Returns the number of elements (varbinds) in this request sublist.
163 *
164 * @return The number of elements in the sublist.
165 *
166 **/
167 public int getSize();
168 /**
169 * Returns the SNMP PDU attached to the request.
170 * @return The SNMP PDU.
171 *
172 * @since 1.5
173 **/
174 public SnmpPdu getPdu();
175 }