MessageDispatcher


1   /*_############################################################################
2     _## 
3     _##  SNMP4J - MessageDispatcher.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;
22  
23  import org.snmp4j.smi.Address;
24  import org.snmp4j.mp.*;
25  import java.util.Collection  ;
26  import org.snmp4j.asn1.BERInputStream;
27  import org.snmp4j.transport.TransportListener;
28  import java.nio.ByteBuffer  ;
29  
30  /**
31   * The <code>MessageDispatcher</code> interface defines common services of
32   * instances that process incoming SNMP messages and dispatch them to
33   * interested {@link CommandResponder} instances. It also provides a service
34   * to send out outgoing SNMP messages.
35   * <p>
36   * A <code>MessageDispatcher</code> needs at least one {@link TransportMapping}
37   * and at least one {@link MessageProcessingModel} in order to be able to
38   * process any messages.
39   *
40   * @author Frank Fock
41   * @version 1.6
42   */
43  public interface MessageDispatcher extends TransportListener {
44  
45    /**
46     * Gets the next unique request ID. The returned ID is unique across
47     * the last 2^31-1 IDs generated by this message dispatcher.
48     * @return
49     *    an integer value in the range 1..2^31-1. The returned ID can be used
50     *    to map responses to requests send through this message dispatcher.
51     * @since 1.1
52     */
53    int getNextRequestID();
54  
55    /**
56     * Adds a {@link MessageProcessingModel} to the dispatcher. In order to
57     * support a specific SNMP protocol version, the message dispatcher needs
58     * a message processing model to process messages before they can be
59     * dispatched.
60     * @param model
61     *    a <code>MessageProcessingModel</code> instance.
62     */
63    void addMessageProcessingModel(MessageProcessingModel model);
64  
65    /**
66     * Removes a previously added {@link MessageProcessingModel} from
67     * the dispatcher.
68     * @param model
69     *    a <code>MessageProcessingModel</code> instance.
70     */
71    void removeMessageProcessingModel(MessageProcessingModel model);
72  
73    /**
74     * Gets the <code>MessageProcessingModel</code> for the supplied message
75     * processing model ID.
76     *
77     * @param messageProcessingModel
78     *    a message processing model ID
79     *    (see {@link MessageProcessingModel#getID()}).
80     * @return
81     *    a MessageProcessingModel instance if the ID is known, otherwise
82     *    <code>null</code>
83     */
84    MessageProcessingModel getMessageProcessingModel(int messageProcessingModel);
85  
86    /**
87     * Adds a {@link TransportMapping} to the dispatcher. The transport mapping
88     * is used to send and receive messages to/from the network.
89     * @param transport
90     *   a <code>TransportMapping</code> instance.
91     */
92    void addTransportMapping(TransportMapping transport);
93  
94    /**
95     * Removes a previously added {@link TransportMapping} from
96     * the dispatcher.
97     * @param transport
98     *    a <code>TransportMapping</code> instance.
99     * @return
100    *    the <code>TransportMapping</code> instance supplied if it
101    * could be successfully removed, <code>null</code> otherwise.
102    */
103   TransportMapping removeTransportMapping(TransportMapping transport);
104 
105   /**
106    * Gets the <code>Collection</code> of transport mappings in this message
107    * dispatcher.
108    * @return Collection
109    */
110   Collection   getTransportMappings();
111 
112   /**
113    * Returns a transport mapping that can handle the supplied address.
114    * @param destAddress
115    *    an Address instance.
116    * @return
117    *    a <code>TransportMapping</code> instance that can be used to sent
118    *    a SNMP message to <code>destAddress</code> or <code>null</code> if
119    *    such a transport mapping does not exists.
120    * @since 1.6
121    */
122   TransportMapping getTransport(Address destAddress);
123 
124   /**
125    * Adds a {@link CommandResponder} instance to the message dispatcher.
126    * Successfully processed SNMP messages will be presented to all command
127    * responder (in the order in which they have been added) until a responder
128    * uses the {@link CommandResponderEvent#setProcessed(boolean processed)}
129    * to set the processed status of the event to <code>true</code>.
130    * @param listener
131    *    a <code>CommandResponder</code> instance.
132    */
133   void addCommandResponder(CommandResponder listener);
134 
135   /**
136    * Removes a previously added {@link CommandResponder} instance from
137    * the message dispatcher.
138    * @param listener
139   *    a <code>CommandResponder</code> instance.
140    */
141   void removeCommandResponder(CommandResponder listener);
142 
143   /**
144    * Sends a PDU to the supplied transport address.
145    * @param transportMapping
146    *    the <code>TransportMapping</code> to be used to send the PDU. If
147    *    <code>transportMapping</code> is <code>null</code> the message
148    *    dispatcher will determine the appropriate transport mapping for the
149    *    given transport address.
150    * @param transportAddress
151    *    the target transport address.
152    * @param messageProcessingModel
153    *    typically the SNMP version.
154    * @param securityModel
155    *    Security Model to use.
156    * @param securityName
157    *    on behalf of this principal.
158    * @param securityLevel
159    *    Level of Security requested.
160    * @param pdu
161    *    the SNMP Protocol Data Unit
162    * @param expectResponse
163    *    <code>true</code> if a response is expected and a state reference should
164    *    be saved (if needed for the supplied message processing model).
165    * @return
166    *    an <code>PduHandle</code> that uniquely identifies this request.
167    * @throws MessageException
168    */
169   PduHandle sendPdu(TransportMapping transportMapping,
170                     Address transportAddress,
171                     int messageProcessingModel,    // typically, SNMP version
172                     int securityModel,             // Security Model to use
173                     byte[] securityName,
174                     int securityLevel,
175                     /* the following parameters are given in ScopedPDU
176                        byte[] contextEngineID,
177                        byte[] contextName,
178                      */
179                     PDU pdu,
180                     boolean expectResponse) throws MessageException;
181 
182   /**
183    * Sends a PDU to the supplied transport address and returns the
184    * <code>PduHandle</code> that uniquely identifies the request as response
185    * <em>after<em> the request has been sent and otional, if a
186    * {@link PduHandleCallback} is given, it returns also the
187    * <code>PduHandle</code> just <em>before<em> the request is sent through the
188    * the callback interface.
189    *
190    * @param transportMapping
191    *    the <code>TransportMapping</code> to be used to send the PDU. If
192    *    <code>transportMapping</code> is <code>null</code> the message
193    *    dispatcher will determine the appropriate transport mapping for the
194    *    given transport address.
195    * @param transportAddress
196    *    the target transport address.
197    * @param messageProcessingModel
198    *    typically the SNMP version.
199    * @param securityModel
200    *    Security Model to use.
201    * @param securityName
202    *    on behalf of this principal.
203    * @param securityLevel
204    *    Level of Security requested.
205    * @param pdu
206    *    the SNMP Protocol Data Unit
207    * @param expectResponse
208    *    <code>true</code> if a response is expected and a state reference should
209    *    be saved (if needed for the supplied message processing model).
210    * @param callback
211    *    an optional callback instance that is informed (if not
212    *    <code>null</code>) about the newly assigned PduHandle just before the
213    *    message is sent out.
214    * @return
215    *    an <code>PduHandle</code> that uniquely identifies this request.
216    * @throws MessageException
217    */
218   PduHandle sendPdu(TransportMapping transportMapping,
219                     Address transportAddress,
220                     int messageProcessingModel,    // typically, SNMP version
221                     int securityModel,             // Security Model to use
222                     byte[] securityName,
223                     int securityLevel,
224                     /* the following parameters are given in ScopedPDU
225                        byte[] contextEngineID,
226                        byte[] contextName,
227                      */
228                     PDU pdu,
229                     boolean expectResponse,
230                     PduHandleCallback callback) throws MessageException;
231 
232   /**
233    * Sends a PDU to the supplied transport address. This method behaves like
234    * a call to {@link #sendPdu(TransportMapping transportMapping,
235    * Address transportAddress, int messageProcessingModel,
236    * int securityModel, byte[] securityName, int securityLevel, PDU pdu,
237    * boolean expectResponse)} with <code>transportMapping</code> set to
238    * <code>null</code>.
239    *
240    * @param transportAddress
241    *    the target transport address.
242    * @param messageProcessingModel
243    *    typically the SNMP version.
244    * @param securityModel
245    *    Security Model to use.
246    * @param securityName
247    *    on behalf of this principal.
248    * @param securityLevel
249    *    Level of Security requested.
250    * @param pdu
251    *    the SNMP Protocol Data Unit
252    * @param expectResponse
253    *    <code>true</code> if a response is expected and a state reference should
254    *    be saved (if needed for the supplied message processing model).
255    * @return
256    *    an <code>PduHandle</code> that uniquely identifies this request.
257    * @throws MessageException
258    */
259   PduHandle sendPdu(Address transportAddress,
260                     int messageProcessingModel,    // typically, SNMP version
261                     int securityModel,             // Security Model to use
262                     byte[] securityName,
263                     int securityLevel,
264                     /* the following parameters are given in ScopedPDU
265                        byte[] contextEngineID,
266                        byte[] contextName,
267                      */
268                     PDU pdu,
269                     boolean expectResponse) throws MessageException;
270 
271   /**
272    * Returns a response PDU to the sender of the corresponding request PDU.
273    * @param messageProcessingModel int
274    * @param securityModel int
275    * @param securityName byte[]
276    * @param securityLevel int
277    * @param pdu PDU
278    * @param maxSizeResponseScopedPDU int
279    * @param stateReference StateReference
280    * @param statusInformation StatusInformation
281    * @throws MessageException
282    * @return int
283    */
284   int returnResponsePdu(int messageProcessingModel,
285                         int securityModel,
286                         byte[] securityName,
287                         int securityLevel,
288                         /* the following parameters are given in ScopedPDU
289                            byte[] contextEngineID,
290                            byte[] contextName,
291                          */
292                         PDU pdu,
293                         int maxSizeResponseScopedPDU,
294                         StateReference stateReference,
295                         StatusInformation statusInformation)
296        throws MessageException;
297 
298   /**
299    * Process an incoming SNMP message. The message is processed and dispatched
300    * according to the message's content, the message processing models, and the
301    * command responder available to the dispatcher.
302    * @param sourceTransport
303    *    a <code>TransportMapping</code> instance denoting the transport that
304    *    received the message and that will be used to send any responses to
305    *    this message. The <code>sourceTransport</code> has to support the
306    *    <code>incomingAddress</code>'s implementation class.
307    * @param incomingAddress
308    *    the <code>Address</code> from which the message has been received.
309    * @param wholeMessage
310    *    an <code>BERInputStream</code> containing the received SNMP message.
311    *    The supplied input stream must support marks, otherwise an
312    *    <code>IllegalArgumentException</code> is thrown.
313    * @deprecated
314    *    Use {@link #processMessage(TransportMapping,Address,ByteBuffer)}
315    *    instead.
316    */
317   void processMessage(TransportMapping sourceTransport,
318                       Address incomingAddress,
319                       BERInputStream wholeMessage);
320 
321   /**
322    * Process an incoming SNMP message. The message is processed and dispatched
323    * according to the message's content, the message processing models, and the
324    * command responder available to the dispatcher.
325    * @param sourceTransport
326    *    a <code>TransportMapping</code> instance denoting the transport that
327    *    received the message and that will be used to send any responses to
328    *    this message. The <code>sourceTransport</code> has to support the
329    *    <code>incomingAddress</code>'s implementation class.
330    * @param incomingAddress
331    *    the <code>Address</code> from which the message has been received.
332    * @param wholeMessage
333    *    an <code>ByteBuffer</code> containing the received SNMP message.
334    */
335   void processMessage(TransportMapping sourceTransport,
336                       Address incomingAddress,
337                       ByteBuffer   wholeMessage);
338 
339 
340   /**
341    * Release any state references associated with the supplied
342    * <code>PduHandle</code> in the specified message processing model.
343    * @param messageProcessingModel
344    *    a message processing model ID.
345    * @param pduHandle
346    *    the <code>PduHandle</code> that identifies a confirmed class message.
347    * @see MessageProcessingModel
348    */
349   void releaseStateReference(int messageProcessingModel,
350                              PduHandle pduHandle);
351 }
352 
353
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags