KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > snmp4j > mp > MessageProcessingModel


1 /*_############################################################################
2   _##
3   _## SNMP4J - MessageProcessingModel.java
4   _##
5   _## Copyright 2003-2007 Frank Fock and Jochen Katz (SNMP4J.org)
6   _##
7   _## Licensed under the Apache License, Version 2.0 (the "License");
8   _## you may not use this file except in compliance with the License.
9   _## You may obtain a copy of the License at
10   _##
11   _## http://www.apache.org/licenses/LICENSE-2.0
12   _##
13   _## Unless required by applicable law or agreed to in writing, software
14   _## distributed under the License is distributed on an "AS IS" BASIS,
15   _## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16   _## See the License for the specific language governing permissions and
17   _## limitations under the License.
18   _##
19   _##########################################################################*/
20
21 package org.snmp4j.mp;
22
23 import java.io.IOException JavaDoc;
24 import org.snmp4j.*;
25 import org.snmp4j.smi.*;
26 import org.snmp4j.asn1.BERInputStream;
27 import org.snmp4j.MutablePDU;
28 import org.snmp4j.MessageDispatcher;
29 import org.snmp4j.asn1.BEROutputStream;
30 // needed by JavaDoc:
31 import org.snmp4j.security.SecurityLevel;
32 import org.snmp4j.security.SecurityModel;
33
34 /**
35  * The <code>MessageProcessingModel</code> interface defines common methods
36  * to all SNMP message processing models.
37  * <p>Note: The read counter of the {@link BERInputStream} parameters in this
38  * interface should not be reset while those methods are executed.
39  *
40  * @author Frank Fock
41  * @version 1.0
42  */
43 public interface MessageProcessingModel {
44
45   int MPv1 = 0;
46   int MPv2c = 1;
47   int MPv2u = 2;
48   int MPv3 = 3;
49
50   /**
51    * Gets the numerical ID of the message processing model as defined by the
52    * constants in this interface or by an appropriate constant in the
53    * class implementing this interface.
54    * @return
55    * a positive integer value.
56    */
57   int getID();
58
59   /**
60    * Prepares an outgoing message as defined in RFC3412 §7.1.
61    *
62    * @param transportAddress
63    * the destination transport <code>Address</code>.
64    * @param maxMsgSize
65    * the maximum message size the transport mapping for the destination
66    * address is capable of.
67    * @param messageProcessingModel
68    * the {@link MessageProcessingModel} ID (typically, the SNMP version).
69    * @param securityModel
70    * the security model ID (see {@link SecurityModel}) to use.
71    * @param securityName
72    * the principal on behalf the message is to be sent.
73    * @param securityLevel
74    * the level of security requested (see {@link SecurityLevel}).
75    * @param pdu
76    * the <code>PDU</code> to send. For a SNMPv1 trap <code>pdu</code> has
77    * to be a {@link PDUv1} instance, for SNMPv3 messages it has to be a
78    * {@link ScopedPDU} instance.
79    * @param expectResponse
80    * indicates if a message expects a response. This has to be
81    * <code>true</code> for confirmed class PDUs and <code>false</code>
82    * otherwise.
83    * @param sendPduHandle
84    * the <code>PduHandle</code> that uniquely identifies the sent message.
85    * @param destTransportAddress
86    * returns the destination transport address (currently set always set to
87    * <code>transportAddress</code>.
88    * @param outgoingMessage
89    * returns the message to send.
90    * @throws IOException if the supplied PDU could not be encoded to the
91    * <code>outgoingMessage</code>
92    * @return
93    * the status of the message preparation. {@link SnmpConstants#SNMP_MP_OK}
94    * is returned if on success, otherwise any of the
95    * <code>SnmpConstants.SNMP_MP_*</code> values may be returned.
96    */
97   int prepareOutgoingMessage(Address transportAddress,
98                              int maxMsgSize,
99                              int messageProcessingModel,
100                              int securityModel,
101                              byte[] securityName,
102                              int securityLevel,
103                              /* the following parameters are given in ScopedPDU
104                                    byte[] contextEngineID,
105                                    byte[] contextName,
106                               */
107                              PDU pdu,
108                              boolean expectResponse,
109                              PduHandle sendPduHandle,
110                              Address destTransportAddress,
111                              BEROutputStream outgoingMessage)
112       throws IOException JavaDoc;
113
114   /**
115    * Prepares a response message as defined in RFC3412 §7.1.
116    *
117    * @param messageProcessingModel int
118    * the {@link MessageProcessingModel} ID (typically, the SNMP version).
119    * @param maxMsgSize
120    * the maximum message size the transport mapping for the destination
121    * address is capable of.
122    * @param securityModel
123    * the security model ID (see {@link SecurityModel}) to use.
124    * @param securityName
125    * the principal on behalf the message is to be sent.
126    * @param securityLevel
127    * the level of security requested (see {@link SecurityLevel}).
128    * @param pdu
129    * the <code>PDU</code> to send. For a SNMPv1 trap <code>pdu</code> has
130    * to be a {@link PDUv1} instance, for SNMPv3 messages it has to be a
131    * {@link ScopedPDU} instance.
132    * @param maxSizeResponseScopedPDU
133    * the maximum size of the scoped PDU the sender (of the request) can
134    * accept.
135    * @param stateReference
136    * reference to state information presented with the request.
137    * @param statusInformation
138    * returns success or error indication. When an error occured, the error
139    * counter OID and value are included.
140    * @param outgoingMessage
141    * returns the message to send.
142    * @throws IOException
143    * if an internal error or a resource exception occured.
144    * @return
145    * the status of the message preparation. {@link SnmpConstants#SNMP_MP_OK}
146    * is returned if on success, otherwise any of the
147    * <code>SnmpConstants.SNMP_MP_*</code> values may be returned.
148    */
149   int prepareResponseMessage(int messageProcessingModel,
150                              int maxMsgSize,
151                              int securityModel,
152                              byte[] securityName,
153                              int securityLevel,
154                              /* the following parameters are given in ScopedPDU
155                                    byte[] contextEngineID,
156                                    byte[] contextName,
157                               */
158                               PDU pdu,
159                               int maxSizeResponseScopedPDU,
160                               StateReference stateReference,
161                               StatusInformation statusInformation,
162                               BEROutputStream outgoingMessage)
163       throws IOException JavaDoc;
164
165   /**
166    * Prepare data elements from an incoming SNMP message as described in
167    * RFC3412 §7.2.
168    *
169    * @param messageDispatcher
170    * the <code>MessageDispatcher</code> instance to be used to send reports.
171    * Thus, <code>messageDispatcher</code> is typically the calling module.
172    * @param transportAddress
173    * the origin transport address.
174    * @param wholeMsg
175    * the whole message as received from the network.
176    * @param messageProcessingModel
177    * returns the message processing model (typically the SNMP version).
178    * @param securityModel
179    * returns the security model ID (see {@link SecurityModel}.
180    * @param securityName
181    * returns the principal.
182    * @param securityLevel
183    * returns the requested security level (see {@link SecurityLevel}).
184    * @param pdu
185    * returns SNMP protocol data unit (the payload of the received message).
186    * @param sendPduHandle
187    * returns the handle to match request.
188    * @param maxSizeResponseScopedPDU
189    * returns the maximum size of the scoped PDU the sender can accept.
190    * @param statusInformation
191    * returns success or error indication. When an error occured, the error
192    * counter OID and value are included.
193    * @param stateReference
194    * returns the state reference to be used for a possible response. On input
195    * the stateReference may contain information about the transport mapping
196    * of the incoming request. This allows the
197    * <code>MessageProcessingModel</code> to send reports over the same
198    * transport as it received them.
199    * @throws IOException
200    * if the decoding of the message failed.
201    * @return int
202    * the status of the message preparation. {@link SnmpConstants#SNMP_MP_OK}
203    * is returned on success, otherwise any of the
204    * <code>SnmpConstants.SNMP_MP_*</code> values may be returned.
205    */
206   int prepareDataElements(MessageDispatcher messageDispatcher,
207                           Address transportAddress,
208                           BERInputStream wholeMsg,
209                           Integer32 messageProcessingModel,
210                           Integer32 securityModel,
211                           OctetString securityName,
212                           Integer32 securityLevel,
213                           /* the following parameters are given in ScopedPDU
214                                 byte[] contextEngineID,
215                                 byte[] contextName,
216                            */
217                           MutablePDU pdu,
218                           PduHandle sendPduHandle,
219                           Integer32 maxSizeResponseScopedPDU,
220                           StatusInformation statusInformation,
221                           MutableStateReference stateReference)
222       throws IOException JavaDoc;
223
224   /**
225    * Checks whether the supplied SNMP protocol version is supported by this
226    * message processing model.
227    * @param snmpProtocolVersion
228    * the SNMP protocol version.
229    * @return
230    * <code>true</code> if the supplied SNMP protocol is supported,
231   * <code>false</code> otherwise.
232    */
233   boolean isProtocolVersionSupported(int snmpProtocolVersion);
234
235   /**
236    * Release the state reference associated with the supplied
237    * <code>PduHandle</code>.
238    * @param pduHandle
239    * a <code>PduHandle</code>.
240    */
241   void releaseStateReference(PduHandle pduHandle);
242 }
243
244
Popular Tags