001: /*_############################################################################
002: _##
003: _## SNMP4J - MessageDispatcher.java
004: _##
005: _## Copyright (C) 2003-2008 Frank Fock and Jochen Katz (SNMP4J.org)
006: _##
007: _## Licensed under the Apache License, Version 2.0 (the "License");
008: _## you may not use this file except in compliance with the License.
009: _## You may obtain a copy of the License at
010: _##
011: _## http://www.apache.org/licenses/LICENSE-2.0
012: _##
013: _## Unless required by applicable law or agreed to in writing, software
014: _## distributed under the License is distributed on an "AS IS" BASIS,
015: _## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
016: _## See the License for the specific language governing permissions and
017: _## limitations under the License.
018: _##
019: _##########################################################################*/
020:
021: package org.snmp4j;
022:
023: import org.snmp4j.smi.Address;
024: import org.snmp4j.mp.*;
025: import java.util.Collection;
026: import org.snmp4j.asn1.BERInputStream;
027: import org.snmp4j.transport.TransportListener;
028: import java.nio.ByteBuffer;
029:
030: /**
031: * The <code>MessageDispatcher</code> interface defines common services of
032: * instances that process incoming SNMP messages and dispatch them to
033: * interested {@link CommandResponder} instances. It also provides a service
034: * to send out outgoing SNMP messages.
035: * <p>
036: * A <code>MessageDispatcher</code> needs at least one {@link TransportMapping}
037: * and at least one {@link MessageProcessingModel} in order to be able to
038: * process any messages.
039: *
040: * @author Frank Fock
041: * @version 1.6
042: */
043: public interface MessageDispatcher extends TransportListener {
044:
045: /**
046: * Gets the next unique request ID. The returned ID is unique across
047: * the last 2^31-1 IDs generated by this message dispatcher.
048: * @return
049: * an integer value in the range 1..2^31-1. The returned ID can be used
050: * to map responses to requests send through this message dispatcher.
051: * @since 1.1
052: */
053: int getNextRequestID();
054:
055: /**
056: * Adds a {@link MessageProcessingModel} to the dispatcher. In order to
057: * support a specific SNMP protocol version, the message dispatcher needs
058: * a message processing model to process messages before they can be
059: * dispatched.
060: * @param model
061: * a <code>MessageProcessingModel</code> instance.
062: */
063: void addMessageProcessingModel(MessageProcessingModel model);
064:
065: /**
066: * Removes a previously added {@link MessageProcessingModel} from
067: * the dispatcher.
068: * @param model
069: * a <code>MessageProcessingModel</code> instance.
070: */
071: void removeMessageProcessingModel(MessageProcessingModel model);
072:
073: /**
074: * Gets the <code>MessageProcessingModel</code> for the supplied message
075: * processing model ID.
076: *
077: * @param messageProcessingModel
078: * a message processing model ID
079: * (see {@link MessageProcessingModel#getID()}).
080: * @return
081: * a MessageProcessingModel instance if the ID is known, otherwise
082: * <code>null</code>
083: */
084: MessageProcessingModel getMessageProcessingModel(
085: int messageProcessingModel);
086:
087: /**
088: * Adds a {@link TransportMapping} to the dispatcher. The transport mapping
089: * is used to send and receive messages to/from the network.
090: * @param transport
091: * a <code>TransportMapping</code> instance.
092: */
093: void addTransportMapping(TransportMapping transport);
094:
095: /**
096: * Removes a previously added {@link TransportMapping} from
097: * the dispatcher.
098: * @param transport
099: * a <code>TransportMapping</code> instance.
100: * @return
101: * the <code>TransportMapping</code> instance supplied if it
102: * could be successfully removed, <code>null</code> otherwise.
103: */
104: TransportMapping removeTransportMapping(TransportMapping transport);
105:
106: /**
107: * Gets the <code>Collection</code> of transport mappings in this message
108: * dispatcher.
109: * @return
110: * a Collection with the registered transport mappings.
111: */
112: Collection getTransportMappings();
113:
114: /**
115: * Returns a transport mapping that can handle the supplied address.
116: * @param destAddress
117: * an Address instance.
118: * @return
119: * a <code>TransportMapping</code> instance that can be used to sent
120: * a SNMP message to <code>destAddress</code> or <code>null</code> if
121: * such a transport mapping does not exists.
122: * @since 1.6
123: */
124: TransportMapping getTransport(Address destAddress);
125:
126: /**
127: * Adds a {@link CommandResponder} instance to the message dispatcher.
128: * Successfully processed SNMP messages will be presented to all command
129: * responder (in the order in which they have been added) until a responder
130: * uses the {@link CommandResponderEvent#setProcessed(boolean processed)}
131: * to set the processed status of the event to <code>true</code>.
132: * @param listener
133: * a <code>CommandResponder</code> instance.
134: */
135: void addCommandResponder(CommandResponder listener);
136:
137: /**
138: * Removes a previously added {@link CommandResponder} instance from
139: * the message dispatcher.
140: * @param listener
141: * a <code>CommandResponder</code> instance.
142: */
143: void removeCommandResponder(CommandResponder listener);
144:
145: /**
146: * Sends a PDU to the supplied transport address.
147: * @param transportMapping
148: * the <code>TransportMapping</code> to be used to send the PDU. If
149: * <code>transportMapping</code> is <code>null</code> the message
150: * dispatcher will determine the appropriate transport mapping for the
151: * given transport address.
152: * @param transportAddress
153: * the target transport address.
154: * @param messageProcessingModel
155: * typically the SNMP version.
156: * @param securityModel
157: * Security Model to use.
158: * @param securityName
159: * on behalf of this principal.
160: * @param securityLevel
161: * Level of Security requested.
162: * @param pdu
163: * the SNMP Protocol Data Unit
164: * @param expectResponse
165: * <code>true</code> if a response is expected and a state reference should
166: * be saved (if needed for the supplied message processing model).
167: * @return
168: * an <code>PduHandle</code> that uniquely identifies this request.
169: * @throws MessageException
170: */
171: PduHandle sendPdu(TransportMapping transportMapping,
172: Address transportAddress, int messageProcessingModel, // typically, SNMP version
173: int securityModel, // Security Model to use
174: byte[] securityName, int securityLevel,
175: /* the following parameters are given in ScopedPDU
176: byte[] contextEngineID,
177: byte[] contextName,
178: */
179: PDU pdu, boolean expectResponse) throws MessageException;
180:
181: /**
182: * Sends a PDU to the supplied transport address and returns the
183: * <code>PduHandle</code> that uniquely identifies the request as response
184: * <em>after<em> the request has been sent and otional, if a
185: * {@link PduHandleCallback} is given, it returns also the
186: * <code>PduHandle</code> just <em>before<em> the request is sent through the
187: * the callback interface.
188: *
189: * @param transportMapping
190: * the <code>TransportMapping</code> to be used to send the PDU. If
191: * <code>transportMapping</code> is <code>null</code> the message
192: * dispatcher will determine the appropriate transport mapping for the
193: * given transport address.
194: * @param transportAddress
195: * the target transport address.
196: * @param messageProcessingModel
197: * typically the SNMP version.
198: * @param securityModel
199: * Security Model to use.
200: * @param securityName
201: * on behalf of this principal.
202: * @param securityLevel
203: * Level of Security requested.
204: * @param pdu
205: * the SNMP Protocol Data Unit
206: * @param expectResponse
207: * <code>true</code> if a response is expected and a state reference should
208: * be saved (if needed for the supplied message processing model).
209: * @param callback
210: * an optional callback instance that is informed (if not
211: * <code>null</code>) about the newly assigned PduHandle just before the
212: * message is sent out.
213: * @return
214: * an <code>PduHandle</code> that uniquely identifies this request.
215: * @throws MessageException
216: */
217: PduHandle sendPdu(TransportMapping transportMapping,
218: Address transportAddress, int messageProcessingModel, // typically, SNMP version
219: int securityModel, // Security Model to use
220: byte[] securityName, int securityLevel,
221: /* the following parameters are given in ScopedPDU
222: byte[] contextEngineID,
223: byte[] contextName,
224: */
225: PDU pdu, boolean expectResponse, PduHandleCallback callback)
226: throws MessageException;
227:
228: /**
229: * Sends a PDU to the supplied transport address. This method behaves like
230: * a call to {@link #sendPdu(TransportMapping transportMapping,
231: * Address transportAddress, int messageProcessingModel,
232: * int securityModel, byte[] securityName, int securityLevel, PDU pdu,
233: * boolean expectResponse)} with <code>transportMapping</code> set to
234: * <code>null</code>.
235: *
236: * @param transportAddress
237: * the target transport address.
238: * @param messageProcessingModel
239: * typically the SNMP version.
240: * @param securityModel
241: * Security Model to use.
242: * @param securityName
243: * on behalf of this principal.
244: * @param securityLevel
245: * Level of Security requested.
246: * @param pdu
247: * the SNMP Protocol Data Unit
248: * @param expectResponse
249: * <code>true</code> if a response is expected and a state reference should
250: * be saved (if needed for the supplied message processing model).
251: * @return
252: * an <code>PduHandle</code> that uniquely identifies this request.
253: * @throws MessageException
254: */
255: PduHandle sendPdu(Address transportAddress,
256: int messageProcessingModel, // typically, SNMP version
257: int securityModel, // Security Model to use
258: byte[] securityName, int securityLevel,
259: /* the following parameters are given in ScopedPDU
260: byte[] contextEngineID,
261: byte[] contextName,
262: */
263: PDU pdu, boolean expectResponse) throws MessageException;
264:
265: /**
266: * Returns a response PDU to the sender of the corresponding request PDU.
267: * @param messageProcessingModel int
268: * @param securityModel int
269: * @param securityName byte[]
270: * @param securityLevel int
271: * @param pdu PDU
272: * @param maxSizeResponseScopedPDU int
273: * @param stateReference StateReference
274: * @param statusInformation StatusInformation
275: * @throws MessageException
276: * @return int
277: */
278: int returnResponsePdu(int messageProcessingModel,
279: int securityModel, byte[] securityName, int securityLevel,
280: /* the following parameters are given in ScopedPDU
281: byte[] contextEngineID,
282: byte[] contextName,
283: */
284: PDU pdu, int maxSizeResponseScopedPDU,
285: StateReference stateReference,
286: StatusInformation statusInformation)
287: throws MessageException;
288:
289: /**
290: * Process an incoming SNMP message. The message is processed and dispatched
291: * according to the message's content, the message processing models, and the
292: * command responder available to the dispatcher.
293: * @param sourceTransport
294: * a <code>TransportMapping</code> instance denoting the transport that
295: * received the message and that will be used to send any responses to
296: * this message. The <code>sourceTransport</code> has to support the
297: * <code>incomingAddress</code>'s implementation class.
298: * @param incomingAddress
299: * the <code>Address</code> from which the message has been received.
300: * @param wholeMessage
301: * an <code>BERInputStream</code> containing the received SNMP message.
302: * The supplied input stream must support marks, otherwise an
303: * <code>IllegalArgumentException</code> is thrown.
304: * @deprecated
305: * Use {@link #processMessage(TransportMapping,Address,ByteBuffer)}
306: * instead.
307: */
308: void processMessage(TransportMapping sourceTransport,
309: Address incomingAddress, BERInputStream wholeMessage);
310:
311: /**
312: * Process an incoming SNMP message. The message is processed and dispatched
313: * according to the message's content, the message processing models, and the
314: * command responder available to the dispatcher.
315: * @param sourceTransport
316: * a <code>TransportMapping</code> instance denoting the transport that
317: * received the message and that will be used to send any responses to
318: * this message. The <code>sourceTransport</code> has to support the
319: * <code>incomingAddress</code>'s implementation class.
320: * @param incomingAddress
321: * the <code>Address</code> from which the message has been received.
322: * @param wholeMessage
323: * an <code>ByteBuffer</code> containing the received SNMP message.
324: */
325: void processMessage(TransportMapping sourceTransport,
326: Address incomingAddress, ByteBuffer wholeMessage);
327:
328: /**
329: * Release any state references associated with the supplied
330: * <code>PduHandle</code> in the specified message processing model.
331: * @param messageProcessingModel
332: * a message processing model ID.
333: * @param pduHandle
334: * the <code>PduHandle</code> that identifies a confirmed class message.
335: * @see MessageProcessingModel
336: */
337: void releaseStateReference(int messageProcessingModel,
338: PduHandle pduHandle);
339: }
|