- java.lang.Object
-
- org.snmp4j.Snmp
-
- All Implemented Interfaces:
java.io.Closeable
,java.lang.AutoCloseable
,java.util.EventListener
,CommandResponder
,Session
public class Snmp extends java.lang.Object implements Session, CommandResponder
TheSnmp
class is the core of SNMP4J. It provides functions to send and receive SNMP PDUs. All SNMP PDU types can be send. Confirmed PDUs can be sent synchronously and asynchronously.The
Snmp
class is transport protocol independent. Support for a specificTransportMapping
instance is added by calling theaddTransportMapping(TransportMapping transportMapping)
method or creating aSnmp
instance by using the non-default constructor with the corresponding transport mapping. Transport mappings are used for incoming and outgoing messages.To setup a default SNMP session for UDP transport and with SNMPv3 support the following code snippet can be used:
Address targetAddress = GenericAddress.parse("udp:127.0.0.1/161"); TransportMapping transport = new DefaultUdpTransportMapping(); snmp = new Snmp(transport); USM usm = new USM(SecurityProtocols.getInstance(), new OctetString(MPv3.createLocalEngineID()), 0); SecurityModels.getInstance().addSecurityModel(usm); transport.listen();
How a synchronous SNMPv3 message with authentication and privacy is then sent illustrates the following code snippet:
// add user to the USM snmp.getUSM().addUser(new OctetString("MD5DES"), new UsmUser(new OctetString("MD5DES"), AuthMD5.ID, new OctetString("MD5DESUserAuthPassword"), PrivDES.ID, new OctetString("MD5DESUserPrivPassword"))); // create the target UserTarget target = new UserTarget(); target.setAddress(targetAddress); target.setRetries(1); target.setTimeout(5000); target.setVersion(SnmpConstants.version3); target.setSecurityLevel(SecurityLevel.AUTH_PRIV); target.setSecurityName(new OctetString("MD5DES")); // create the PDU PDU pdu = new ScopedPDU(); pdu.add(new VariableBinding(new OID("1.3.6"))); pdu.setType(PDU.GETNEXT); // send the PDU ResponseEvent response = snmp.send(pdu, target); // extract the response PDU (could be null if timed out) PDU responsePDU = response.getResponse(); // extract the address used by the agent to send the response: Address peerAddress = response.getPeerAddress();
An asynchronous SNMPv1 request is sent by the following code:
// setting up target CommunityTarget target = new CommunityTarget(); target.setCommunity(new OctetString("public")); target.setAddress(targetAddress); target.setRetries(2); target.setTimeout(1500); target.setVersion(SnmpConstants.version1); // creating PDU PDU pdu = new PDU(); pdu.add(new VariableBinding(new OID(new int[] {1,3,6,1,2,1,1,1}))); pdu.add(new VariableBinding(new OID(new int[] {1,3,6,1,2,1,1,2}))); pdu.setType(PDU.GETNEXT); // sending request ResponseListener listener = new ResponseListener() { public void onResponse(ResponseEvent event) { // Always cancel async request when response has been received // otherwise a memory leak is created! Not canceling a request // immediately can be useful when sending a request to a broadcast // address. ((Snmp)event.getSource()).cancel(event.getRequest(), this); System.out.println("Received response PDU is: "+event.getResponse()); } }; snmp.sendPDU(pdu, target, null, listener);
Traps (notifications) and other SNMP PDUs can be received by adding the following code to the first code snippet above:
CommandResponder trapPrinter = new CommandResponder() { public synchronized void processPdu(CommandResponderEvent e) { PDU command = e.getPDU(); if (command != null) { System.out.println(command.toString()); } } }; snmp.addCommandResponder(trapPrinter);
- Version:
- 3.4.0
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description (package private) class
Snmp.AsyncPendingRequest<A extends Address>
(package private) static class
Snmp.AsyncRequestKey
class
Snmp.NotificationDispatcher
TheNotificationDispatcher
dispatches traps, notifications, and to registered listeners.protected class
Snmp.PendingRequest<A extends Address>
static interface
Snmp.ReportHandler
Interface for handling reports.(package private) class
Snmp.ReportProcessor
(package private) static class
Snmp.SyncResponseListener<A extends Address>
-
Field Summary
Fields Modifier and Type Field Description private java.util.Map<java.lang.Object,PduHandle>
asyncRequests
TheasyncRequests
table contains pending requests accessed trough the key userObjectprivate java.util.List<CommandResponder>
commandResponderListeners
private boolean
contextEngineIdDiscoveryDisabled
private java.util.Map<Address,OctetString>
contextEngineIDs
private CounterSupport
counterSupport
private static int
DEFAULT_MAX_REQUEST_STATUS
private static int
ENGINE_ID_DISCOVERY_MAX_REQUEST_STATUS
private static LogAdapter
logger
private MessageDispatcher
messageDispatcher
private Snmp.NotificationDispatcher
notificationDispatcher
private java.util.Map<PduHandle,Snmp.PendingRequest<?>>
pendingRequests
ThependingRequests
table contains pending requests accessed trough the keyPduHandle
private Snmp.ReportHandler
reportHandler
private TimeoutModel
timeoutModel
private CommonTimer
timer
-
Constructor Summary
Constructors Constructor Description Snmp()
Creates aSnmp
instance that uses aMessageDispatcherImpl
with no message processing models and no security protols (by default).Snmp(MessageDispatcher messageDispatcher)
Creates aSnmp
instance by supplying aMessageDispatcher
.Snmp(MessageDispatcher messageDispatcher, TransportMapping<? extends Address> transportMapping)
Creates aSnmp
instance by supplying aMessageDispatcher
and aTransportMapping
.Snmp(TransportMapping<? extends Address> transportMapping)
Creates aSnmp
instance that uses aMessageDispatcherImpl
with all supported message processing models and the default security protols for dispatching.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addCommandResponder(CommandResponder listener)
Adds aCommandResponder
to this SNMP session.boolean
addNotificationListener(Address listenAddress, CommandResponder listener)
Adds a notification listener to this Snmp instance.boolean
addNotificationListener(TransportMapping<?> transportMapping, Address listenAddress, CommandResponder listener)
Adds a notification listener to this Snmp instance.void
addTransportMapping(TransportMapping<? extends Address> transportMapping)
Adds aTransportMapping
to this SNMP session.void
cancel(PDU request, ResponseListener listener)
Cancels an asynchronous request.void
close()
Closes the session and frees any allocated resources, i.e.protected void
closeTransportMapping(TransportMapping<?> tm)
UsmUserEntry
createLocalizedUsmUserEntry(byte[] engineID, OctetString securityName, OID authProtocol, OctetString authPassword, OID privProtocol, OctetString privPassword)
Create and return aUsmUserEntry
with localized authentication and privacy keys from the provided authentication and privacy passwords.protected Snmp.NotificationDispatcher
createNotificationDispatcher()
Creates the internalSnmp.NotificationDispatcher
used to dispatch notifications.private void
createPendingTimer()
<A extends Address>
byte[]discoverAuthoritativeEngineID(A address, long timeout)
Discovers the engine ID of the SNMPv3 entity denoted by the supplied address.protected void
fireProcessPdu(CommandResponderEvent<?> event)
Fires aCommandResponderEvent
event to inform listeners about a received PDU.<A extends Address>
ResponseEvent<A>get(PDU pdu, Target<A> target)
Sends a GET request to a target.<A extends Address>
voidget(PDU pdu, Target<A> target, java.lang.Object userHandle, ResponseListener listener)
Asynchronously sends a GET requestPDU
to the given target.<A extends Address>
ResponseEvent<A>getBulk(PDU pdu, Target<A> target)
Sends a GETBULK request to a target.<A extends Address>
voidgetBulk(PDU pdu, Target<A> target, java.lang.Object userHandle, ResponseListener listener)
Asynchronously sends a GETBULK requestPDU
to the given target.CounterSupport
getCounterSupport()
Gets the counter support for Snmp related counters.byte[]
getLocalEngineID()
Gets the local engine ID if the MPv3 is available, otherwise a runtime exception is thrown.MessageDispatcher
getMessageDispatcher()
Returns the message dispatcher associated with this SNMP session.MessageProcessingModel
getMessageProcessingModel(int messageProcessingModel)
Gets the message processing model for the supplied ID.private MPv3
getMPv3()
<A extends Address>
ResponseEvent<A>getNext(PDU pdu, Target<A> target)
Sends a GETNEXT request to a target.<A extends Address>
voidgetNext(PDU pdu, Target<A> target, java.lang.Object userHandle, ResponseListener listener)
Asynchronously sends a GETNEXT requestPDU
to the given target.int
getNextRequestID()
Gets the next unique request ID.TransportMapping<?>
getNotificationListenerTM(Address listenAddress)
Gets the transport mapping registered for the specified listen address.int
getPendingAsyncRequestCount()
Gets the number of currently pending asynchronous requests.int
getPendingSyncRequestCount()
Gets the number of currently pending synchronous requests.Snmp.ReportHandler
getReportHandler()
Returns the report handler which is used internally to process reports received from command responders.TimeoutModel
getTimeoutModel()
Gets the timeout model associated with this SNMP session.USM
getUSM()
Gets the User Based Security Model (USM).protected void
handleInternalResponse(PDU response, PDU pdu, Address target)
<A extends Address>
ResponseEvent<A>inform(PDU pdu, Target<A> target)
Sends an INFORM request to a target.<A extends Address>
voidinform(PDU pdu, Target<A> target, java.lang.Object userHandle, ResponseListener listener)
Asynchronously sends an INFORM requestPDU
to the given target.protected void
initMessageDispatcher()
boolean
isContextEngineIdDiscoveryDisabled()
Checks whether RFC5343 based context engine ID discovery is disabled or not.private boolean
isEmptyContextEngineID(PDU pdu)
void
listen()
Puts all associated transport mappings into listen mode.protected <A extends Address>
TransportMapping<? super A>lookupTransportMapping(Target<A> target)
void
notify(PDU pdu, Target<?> target)
Sends a SNMPv2c or SNMPv3 notification to a target.<A extends Address>
voidprocessPdu(CommandResponderEvent<A> event)
Process an incoming request or notification PDU.void
removeCommandResponder(CommandResponder listener)
Removes aCommandResponder
from this SNMP session.boolean
removeNotificationListener(Address listenAddress)
Removes (deletes) the notification listener for the specified transport endpoint.void
removeTransportMapping(TransportMapping<? extends Address> transportMapping)
Removes the specified transport mapping from this SNMP session.protected <A extends Address>
booleanresendRequest(Snmp.PendingRequest<A> request, PDU response)
<A extends Address>
ResponseEvent<A>send(PDU pdu, Target<A> target)
Sends aPDU
to the given target and returns the received responsePDU
.<A extends Address>
voidsend(PDU pdu, Target<A> target, java.lang.Object userHandle, ResponseListener listener)
Asynchronously sends aPDU
to the given target.<A extends Address>
ResponseEvent<A>send(PDU pdu, Target<A> target, TransportMapping<? super A> transport)
Sends aPDU
to the given target and if thePDU
is a confirmed request, then the received response is returned synchronously.private <A extends Address>
ResponseEvent<A>send(PDU pdu, Target<A> target, TransportMapping<? super A> transport, int maxRequestStatus)
<A extends Address>
voidsend(PDU pdu, Target<A> target, TransportMapping<? super A> transport, java.lang.Object userHandle, ResponseListener listener)
Asynchronously sends aPDU
to the given target.protected <A extends Address>
PduHandlesendMessage(PDU pdu, Target<A> target, TransportMapping<? super A> transport, PduHandleCallback<PDU> pduHandleCallback)
Actually sends a PDU to a target and returns a handle for the sent PDU.void
set(PDU pdu, Target<?> target, java.lang.Object userHandle, ResponseListener listener)
Asynchronously sends a SET requestPDU
to the given target.<A extends Address>
ResponseEvent<A>set(PDU pdu, Target<A> target)
Sends a SET request to a target.void
setContextEngineIdDiscoveryDisabled(boolean contextEngineIdDiscoveryDisabled)
Sets the RFC5343 based context engine ID discovery.void
setCounterSupport(CounterSupport counterSupport)
Sets the counter support instance to handle counter events on behalf of this Snmp instance.void
setLocalEngine(byte[] engineID, int engineBoots, int engineTime)
Sets the local engine ID for the SNMP entity represented by thisSnmp
instance.SecurityLevel
setLocalizedUserCredentials(DirectUserTarget<?> directUserTarget, UsmUserEntry localizedUserCredentials)
Sets the user's security name and authentication/privacy keys and protocols on the suppliedDirectUserTarget
and returns the maximumSecurityLevel
it can be used with.void
setMessageDispatcher(MessageDispatcher messageDispatcher)
Sets the message dispatcher associated with this SNMP session.void
setReportHandler(Snmp.ReportHandler reportHandler)
Sets the report handler and overrides the default report handler.void
setTimeoutModel(TimeoutModel timeoutModel)
Sets the timeout model for this SNMP session.void
trap(PDUv1 pdu, Target<?> target)
Sends a SNMPv1 trap to a target.
-
-
-
Field Detail
-
logger
private static final LogAdapter logger
-
DEFAULT_MAX_REQUEST_STATUS
private static final int DEFAULT_MAX_REQUEST_STATUS
- See Also:
- Constant Field Values
-
ENGINE_ID_DISCOVERY_MAX_REQUEST_STATUS
private static final int ENGINE_ID_DISCOVERY_MAX_REQUEST_STATUS
- See Also:
- Constant Field Values
-
messageDispatcher
private MessageDispatcher messageDispatcher
-
pendingRequests
private final java.util.Map<PduHandle,Snmp.PendingRequest<?>> pendingRequests
ThependingRequests
table contains pending requests accessed trough the keyPduHandle
-
asyncRequests
private final java.util.Map<java.lang.Object,PduHandle> asyncRequests
TheasyncRequests
table contains pending requests accessed trough the key userObject
-
timer
private CommonTimer timer
-
commandResponderListeners
private java.util.List<CommandResponder> commandResponderListeners
-
timeoutModel
private TimeoutModel timeoutModel
-
notificationDispatcher
private Snmp.NotificationDispatcher notificationDispatcher
-
reportHandler
private Snmp.ReportHandler reportHandler
-
contextEngineIDs
private java.util.Map<Address,OctetString> contextEngineIDs
-
contextEngineIdDiscoveryDisabled
private boolean contextEngineIdDiscoveryDisabled
-
counterSupport
private CounterSupport counterSupport
-
-
Constructor Detail
-
Snmp
public Snmp()
Creates aSnmp
instance that uses aMessageDispatcherImpl
with no message processing models and no security protols (by default). You will have to add those by calling the appropriate methods ongetMessageDispatcher()
.At least one transport mapping has to be added before
listen()
is called in order to be able to send and receive SNMP messages.To initialize a
Snmp
instance created with this constructor follow this sample code:Transport transport = ...; Snmp snmp = new Snmp(); SecurityProtocols.getInstance().addDefaultProtocols(); MessageDispatcher disp = snmp.getMessageDispatcher(); disp.addMessageProcessingModel(new MPv1()); disp.addMessageProcessingModel(new MPv2c()); snmp.addTransportMapping(transport); OctetString localEngineID = new OctetString( MPv3.createLocalEngineID()); // For command generators, you may use the following code to avoid // engine ID clashes: // MPv3.createLocalEngineID( // new OctetString("MyUniqueID"+System.currentTimeMillis()))); USM usm = new USM(SecurityProtocols.getInstance(), localEngineID, 0); disp.addMessageProcessingModel(new MPv3(usm)); snmp.listen();
-
Snmp
public Snmp(TransportMapping<? extends Address> transportMapping)
Creates aSnmp
instance that uses aMessageDispatcherImpl
with all supported message processing models and the default security protols for dispatching.To initialize a
Snmp
instance created with this constructor follow this sample code:Transport transport = ...; Snmp snmp = new Snmp(transport); OctetString localEngineID = new OctetString(snmp.getMPv3().getLocalEngineID()); USM usm = new USM(SecurityProtocols.getInstance(), localEngineID, 0); SecurityModels.getInstance().addSecurityModel(usm); snmp.listen();
- Parameters:
transportMapping
- TransportMapping the initialTransportMapping
. You can add more or remove the same later.
-
Snmp
public Snmp(MessageDispatcher messageDispatcher, TransportMapping<? extends Address> transportMapping)
Creates aSnmp
instance by supplying aMessageDispatcher
and aTransportMapping
.As of version 1.1, the supplied message dispatcher is not altered in terms of adding any message processing models to it. This has to be done now outside the Snmp class.
To initialize a
Snmp
instance created with this constructor follow this sample code:Transport transport = ...; SecurityProtocols.getInstance().addDefaultProtocols(); MessageDispatcher disp = new MessageDispatcherImpl(); disp.addMessageProcessingModel(new MPv1()); disp.addMessageProcessingModel(new MPv2c()); Snmp snmp = new Snmp(disp, transport); OctetString localEngineID = new OctetString( MPv3.createLocalEngineID()); // For command generators, you may use the following code to avoid // engine ID clashes: // MPv3.createLocalEngineID( // new OctetString("MyUniqueID"+System.currentTimeMillis()))); USM usm = new USM(SecurityProtocols.getInstance(), localEngineID, 0); disp.addMessageProcessingModel(new MPv3(usm)); snmp.listen();
- Parameters:
messageDispatcher
- aMessageDispatcher
instance that will be used to dispatch incoming and outgoing messages.transportMapping
- the initialTransportMapping
, which may benull
. You can add or remove transport mappings later usingaddTransportMapping(org.snmp4j.TransportMapping<? extends org.snmp4j.smi.Address>)
andremoveTransportMapping(org.snmp4j.TransportMapping<? extends org.snmp4j.smi.Address>)
respectively.
-
Snmp
public Snmp(MessageDispatcher messageDispatcher)
Creates aSnmp
instance by supplying aMessageDispatcher
.The supplied message dispatcher is not altered in terms of adding any message processing models to it. This has to be done now outside the Snmp class.
Do not forget to add at least one transport mapping before calling the listen method!
To initialize a
Snmp
instance created with this constructor follow this sample code:Transport transport = ...; SecurityProtocols.getInstance().addDefaultProtocols(); MessageDispatcher disp = new MessageDispatcherImpl(); disp.addMessageProcessingModel(new MPv1()); disp.addMessageProcessingModel(new MPv2c()); Snmp snmp = new Snmp(disp); snmp.addTransportMapping(transport); OctetString localEngineID = new OctetString( MPv3.createLocalEngineID()); // For command generators, you may use the following code to avoid // engine ID clashes: // MPv3.createLocalEngineID( // new OctetString("MyUniqueID"+System.currentTimeMillis()))); USM usm = new USM(SecurityProtocols.getInstance(), localEngineID, 0); disp.addMessageProcessingModel(new MPv3(usm)); snmp.listen();
- Parameters:
messageDispatcher
- aMessageDispatcher
instance that will be used to dispatch incoming and outgoing messages.- Since:
- 1.5
-
-
Method Detail
-
initMessageDispatcher
protected final void initMessageDispatcher()
-
getMessageDispatcher
public MessageDispatcher getMessageDispatcher()
Returns the message dispatcher associated with this SNMP session.- Returns:
- a
MessageDispatcher
instance. - Since:
- 1.1
-
setMessageDispatcher
public void setMessageDispatcher(MessageDispatcher messageDispatcher)
Sets the message dispatcher associated with this SNMP session. TheCommandResponder
registration is removed from the existing message dispatcher (if notnull
).- Parameters:
messageDispatcher
- a message dispatcher that processes incoming SNMPPDU
s.- Since:
- 2.5.7
-
addTransportMapping
public void addTransportMapping(TransportMapping<? extends Address> transportMapping)
Adds aTransportMapping
to this SNMP session.- Parameters:
transportMapping
- aTransportMapping
instance.
-
removeTransportMapping
public void removeTransportMapping(TransportMapping<? extends Address> transportMapping)
Removes the specified transport mapping from this SNMP session. If the transport mapping is not currently part of this SNMP session, this method will have no effect.- Parameters:
transportMapping
- a previously addedTransportMapping
.
-
addNotificationListener
public boolean addNotificationListener(TransportMapping<?> transportMapping, Address listenAddress, CommandResponder listener)
Adds a notification listener to this Snmp instance. Calling this method will create a transport mapping for the specified listening address and registers the providedCommandResponder
with the internalNotificationDispatcher
.- Parameters:
transportMapping
- the TransportMapping that is listening on the provided listenAddress. CallTransportMappings.getInstance().createTransportMapping(listenAddress);
to create such a transport mapping.listenAddress
- theAddress
denoting the transport end-point (interface and port) to listen for incoming notifications.listener
- theCommandResponder
instance that should handle the received notifications.- Returns:
true
if registration was successful andfalse
if, for example, the transport mapping for the listen address could not be created.- Since:
- 2.5.0
-
createNotificationDispatcher
protected Snmp.NotificationDispatcher createNotificationDispatcher()
Creates the internalSnmp.NotificationDispatcher
used to dispatch notifications.- Returns:
- a new notification dispatcher instance derived from the
Snmp.NotificationDispatcher
class. - Since:
- 3.4.2
-
addNotificationListener
public boolean addNotificationListener(Address listenAddress, CommandResponder listener)
Adds a notification listener to this Snmp instance. Calling this method will create a transport mapping for the specified listening address and registers the providedCommandResponder
with the internalNotificationDispatcher
.- Parameters:
listenAddress
- theAddress
denoting the transport end-point (interface and port) to listen for incoming notifications.listener
- theCommandResponder
instance that should handle the received notifications.- Returns:
true
if registration was successful andfalse
if, for example, the transport mapping for the listen address could not be created.- Since:
- 1.6
-
removeNotificationListener
public boolean removeNotificationListener(Address listenAddress)
Removes (deletes) the notification listener for the specified transport endpoint.- Parameters:
listenAddress
- the listenAddress
to be removed.- Returns:
true
if the notification listener has been removed successfully.
-
getNotificationListenerTM
public TransportMapping<?> getNotificationListenerTM(Address listenAddress)
Gets the transport mapping registered for the specified listen address.- Parameters:
listenAddress
- the listen address.- Returns:
- the
TransportMapping
for the specified listen address ornull
if there is no notification listener for that address. - Since:
- 2.5.0
-
listen
public void listen() throws java.io.IOException
Puts all associated transport mappings into listen mode.- Throws:
java.io.IOException
- if a transport mapping throws anIOException
when itsTransportMapping.listen()
method has been called.
-
getNextRequestID
public int getNextRequestID()
Gets the next unique request ID. The returned ID is unique across the last 2^31-1 IDs generated by this message dispatcher.- Returns:
- an integer value in the range 1..2^31-1. The returned ID can be used to map responses to requests send through this message dispatcher.
- Since:
- 1.1
- See Also:
MessageDispatcher.getNextRequestID()
-
close
public void close() throws java.io.IOException
Closes the session and frees any allocated resources, i.e. sockets and the internal thread for processing request timeouts. In addition,MessageDispatcher.stop()
is called to temrinate and free resources from the used message dispatcher too.If there are any pending requests, the
ResponseListener
associated with the pending requests, will be called with anull
response and aInterruptedException
in the error member of theResponseEvent
returned.After a
Session
has been closed it must not be used anymore.
-
get
public <A extends Address> ResponseEvent<A> get(PDU pdu, Target<A> target) throws java.io.IOException
Sends a GET request to a target. This method sets the PDU's type toPDU.GET
and then sends a synchronous request to the supplied target.- Type Parameters:
A
- type of the targetAddress
- Parameters:
pdu
- aPDU
instance. For SNMPv3 messages, the supplied PDU instance has to be aScopedPDU
instance.target
- the Target instance representing the target SNMP engine where to send thepdu
.- Returns:
- the received response encapsulated in a
ResponseEvent
instance. To obtain the received responsePDU
callResponseEvent.getResponse()
. If the request timed out, that method will returnnull
. - Throws:
java.io.IOException
- if the PDU cannot be sent to the target.- Since:
- 1.1
-
get
public <A extends Address> void get(PDU pdu, Target<A> target, java.lang.Object userHandle, ResponseListener listener) throws java.io.IOException
Asynchronously sends a GET requestPDU
to the given target. The response is then returned by calling the suppliedResponseListener
instance.- Type Parameters:
A
- type of the targetAddress
- Parameters:
pdu
- the PDU instance to send.target
- the Target instance representing the target SNMP engine where to send thepdu
.userHandle
- an user defined handle that is returned when the request is returned via thelistener
object.listener
- aResponseListener
instance that is called whenpdu
is a confirmed PDU and the request is either answered or timed out.- Throws:
java.io.IOException
- if the PDU cannot be sent to the target.- Since:
- 1.1
-
getNext
public <A extends Address> ResponseEvent<A> getNext(PDU pdu, Target<A> target) throws java.io.IOException
Sends a GETNEXT request to a target. This method sets the PDU's type toPDU.GETNEXT
and then sends a synchronous request to the supplied target. This method is a convenience wrapper for thesend(PDU pdu, Target target)
method.- Type Parameters:
A
- type of the targetAddress
- Parameters:
pdu
- aPDU
instance. For SNMPv3 messages, the supplied PDU instance has to be aScopedPDU
instance.target
- the Target instance representing the target SNMP engine where to send thepdu
.- Returns:
- the received response encapsulated in a
ResponseEvent
instance. To obtain the received responsePDU
callResponseEvent.getResponse()
. If the request timed out, that method will returnnull
. - Throws:
java.io.IOException
- if the PDU cannot be sent to the target.- Since:
- 1.1
-
getNext
public <A extends Address> void getNext(PDU pdu, Target<A> target, java.lang.Object userHandle, ResponseListener listener) throws java.io.IOException
Asynchronously sends a GETNEXT requestPDU
to the given target. The response is then returned by calling the suppliedResponseListener
instance.- Type Parameters:
A
- type of the targetAddress
- Parameters:
pdu
- the PDU instance to send.target
- the Target instance representing the target SNMP engine where to send thepdu
.userHandle
- an user defined handle that is returned when the request is returned via thelistener
object.listener
- aResponseListener
instance that is called whenpdu
is a confirmed PDU and the request is either answered or timed out.- Throws:
java.io.IOException
- if the PDU cannot be sent to the target.- Since:
- 1.1
-
getBulk
public <A extends Address> ResponseEvent<A> getBulk(PDU pdu, Target<A> target) throws java.io.IOException
Sends a GETBULK request to a target. This method sets the PDU's type toPDU.GETBULK
and then sends a synchronous request to the supplied target. This method is a convenience wrapper for thesend(PDU pdu, Target target)
method.- Type Parameters:
A
- type of the targetAddress
- Parameters:
pdu
- aPDU
instance. For SNMPv3 messages, the supplied PDU instance has to be aScopedPDU
instance.target
- the Target instance representing the target SNMP engine where to send thepdu
.- Returns:
- the received response encapsulated in a
ResponseEvent
instance. To obtain the received responsePDU
callResponseEvent.getResponse()
. If the request timed out, that method will returnnull
. - Throws:
java.io.IOException
- if the PDU cannot be sent to the target.- Since:
- 1.1
-
getBulk
public <A extends Address> void getBulk(PDU pdu, Target<A> target, java.lang.Object userHandle, ResponseListener listener) throws java.io.IOException
Asynchronously sends a GETBULK requestPDU
to the given target. The response is then returned by calling the suppliedResponseListener
instance.- Type Parameters:
A
- type of the targetAddress
- Parameters:
pdu
- the PDU instance to send.target
- the Target instance representing the target SNMP engine where to send thepdu
.userHandle
- an user defined handle that is returned when the request is returned via thelistener
object.listener
- aResponseListener
instance that is called whenpdu
is a confirmed PDU and the request is either answered or timed out.- Throws:
java.io.IOException
- if the PDU cannot be sent to the target.- Since:
- 1.1
-
inform
public <A extends Address> ResponseEvent<A> inform(PDU pdu, Target<A> target) throws java.io.IOException
Sends an INFORM request to a target. This method sets the PDU's type toPDU.INFORM
and then sends a synchronous request to the supplied target. This method is a convenience wrapper for thesend(PDU pdu, Target target)
method.- Type Parameters:
A
- type of the targetAddress
- Parameters:
pdu
- aPDU
instance. For SNMPv3 messages, the supplied PDU instance has to be aScopedPDU
instance.target
- the Target instance representing the target SNMP engine where to send thepdu
.- Returns:
- the received response encapsulated in a
ResponseEvent
instance. To obtain the received responsePDU
callResponseEvent.getResponse()
. If the request timed out, that method will returnnull
. - Throws:
java.io.IOException
- if the inform request could not be send to the specified target.- Since:
- 1.1
-
inform
public <A extends Address> void inform(PDU pdu, Target<A> target, java.lang.Object userHandle, ResponseListener listener) throws java.io.IOException
Asynchronously sends an INFORM requestPDU
to the given target. The response is then returned by calling the suppliedResponseListener
instance.- Type Parameters:
A
- type of the targetAddress
- Parameters:
pdu
- the PDU instance to send.target
- the Target instance representing the target SNMP engine where to send thepdu
.userHandle
- an user defined handle that is returned when the request is returned via thelistener
object.listener
- aResponseListener
instance that is called whenpdu
is a confirmed PDU and the request is either answered or timed out.- Throws:
java.io.IOException
- if the PDU cannot be sent to the target.- Since:
- 1.1
-
trap
public void trap(PDUv1 pdu, Target<?> target) throws java.io.IOException
Sends a SNMPv1 trap to a target. This method sets the PDU's type toPDU.V1TRAP
and then sends it to the supplied target. This method is a convenience wrapper for thesend(PDU pdu, Target target)
method.- Parameters:
pdu
- aPDUv1
instance.target
- the Target instance representing the target SNMP engine where to send thepdu
. The selected SNMP protocol version for the target must beSnmpConstants.version1
.- Throws:
java.io.IOException
- if the trap cannot be sent.- Since:
- 1.1
-
notify
public void notify(PDU pdu, Target<?> target) throws java.io.IOException
Sends a SNMPv2c or SNMPv3 notification to a target. This method sets the PDU's type toPDU.NOTIFICATION
and then sends it to the supplied target. This method is a convenience wrapper for thesend(PDU pdu, Target target)
method.- Parameters:
pdu
- aPDUv1
instance.target
- the Target instance representing the target SNMP engine where to send thepdu
. The selected SNMP protocol version for the target must beSnmpConstants.version2c
orSnmpConstants.version2c
.- Throws:
java.io.IOException
- if the notification cannot be sent.- Since:
- 1.1
-
set
public <A extends Address> ResponseEvent<A> set(PDU pdu, Target<A> target) throws java.io.IOException
Sends a SET request to a target. This method sets the PDU's type toPDU.SET
and then sends a synchronous request to the supplied target.- Type Parameters:
A
- type of the targetAddress
- Parameters:
pdu
- aPDU
instance. For SNMPv3 messages, the supplied PDU instance has to be aScopedPDU
instance.target
- the Target instance representing the target SNMP engine where to send thepdu
.- Returns:
- the received response encapsulated in a
ResponseEvent
instance. To obtain the received responsePDU
callResponseEvent.getResponse()
. If the request timed out, that method will returnnull
. - Throws:
java.io.IOException
- if the PDU cannot be sent to the target.- Since:
- 1.1
-
set
public void set(PDU pdu, Target<?> target, java.lang.Object userHandle, ResponseListener listener) throws java.io.IOException
Asynchronously sends a SET requestPDU
to the given target. The response is then returned by calling the suppliedResponseListener
instance.- Parameters:
pdu
- the PDU instance to send.target
- the Target instance representing the target SNMP engine where to send thepdu
.userHandle
- an user defined handle that is returned when the request is returned via thelistener
object.listener
- aResponseListener
instance that is called whenpdu
is a confirmed PDU and the request is either answered or timed out.- Throws:
java.io.IOException
- if the PDU cannot be sent to the target.- Since:
- 1.1
-
send
public <A extends Address> ResponseEvent<A> send(PDU pdu, Target<A> target) throws java.io.IOException
Description copied from interface:Session
Sends aPDU
to the given target and returns the received responsePDU
.- Specified by:
send
in interfaceSession
- Type Parameters:
A
- theAddress
type of target and response (i.e., must be the same)- Parameters:
pdu
- thePDU
to send.target
- theTarget
instance that specifies how and where to send the PDU.- Returns:
- the received response encapsulated in a
ResponseEvent
instance. To obtain the received responsePDU
callResponseEvent.getResponse()
. If the request timed out, that method will returnnull
. If the sentpdu
is an unconfirmed PDU (notification, response, or report), thennull
will be returned. - Throws:
java.io.IOException
- if the message could not be send.
-
send
public <A extends Address> ResponseEvent<A> send(PDU pdu, Target<A> target, TransportMapping<? super A> transport) throws java.io.IOException
Sends aPDU
to the given target and if thePDU
is a confirmed request, then the received response is returned synchronously.- Specified by:
send
in interfaceSession
- Type Parameters:
A
- type of the targetAddress
- Parameters:
pdu
- aPDU
instance. When sending a SNMPv1 trap PDU, the supplied PDU instance must be aPDUv1
. For all types of SNMPv3 messages, the supplied PDU instance has to be aScopedPDU
instance.target
- the Target instance representing the target SNMP engine where to send thepdu
.transport
- specifies theTransportMapping
to be used when sending the PDU. Iftransport
isnull
, the associated message dispatcher will try to determine the transport mapping by thetarget
's address.- Returns:
- the received response encapsulated in a
ResponseEvent
instance. To obtain the received responsePDU
callResponseEvent.getResponse()
. If the request timed out, that method will returnnull
. If the sentpdu
is an unconfirmed PDU (notification, response, or report), thennull
will be returned. - Throws:
java.io.IOException
- if the message could not be sent.- See Also:
PDU
,ScopedPDU
,PDUv1
-
send
private <A extends Address> ResponseEvent<A> send(PDU pdu, Target<A> target, TransportMapping<? super A> transport, int maxRequestStatus) throws java.io.IOException
- Throws:
java.io.IOException
-
createPendingTimer
private void createPendingTimer()
-
send
public <A extends Address> void send(PDU pdu, Target<A> target, java.lang.Object userHandle, ResponseListener listener) throws java.io.IOException
Description copied from interface:Session
Asynchronously sends aPDU
to the given target. The response is then returned by calling the suppliedResponseListener
instance.- Specified by:
send
in interfaceSession
- Type Parameters:
A
- theAddress
type of target and response (i.e., must be the same)- Parameters:
pdu
- the PDU instance to send.target
- the Target instance representing the target SNMP engine where to send thepdu
.userHandle
- an user defined handle that is returned when the request is returned via thelistener
object.listener
- aResponseListener
instance that is called whenpdu
is a confirmed PDU and the request is either answered or timed out.- Throws:
java.io.IOException
- if the message could not be send.
-
send
public <A extends Address> void send(PDU pdu, Target<A> target, TransportMapping<? super A> transport, java.lang.Object userHandle, ResponseListener listener) throws java.io.IOException
Description copied from interface:Session
Asynchronously sends aPDU
to the given target. The response is then returned by calling the suppliedResponseListener
instance.- Specified by:
send
in interfaceSession
- Type Parameters:
A
- the targetAddress
type.- Parameters:
pdu
- the PDU instance to send.target
- the Target instance representing the target SNMP engine where to send thepdu
.transport
- specifies theTransportMapping
to be used when sending the PDU. Iftransport
isnull
, the associated message dispatcher will try to determine the transport mapping by thetarget
's address.userHandle
- an user defined handle that is returned when the request is returned via thelistener
object.listener
- aResponseListener
instance that is called whenpdu
is a confirmed PDU and the request is either answered or timed out.- Throws:
java.io.IOException
- if the message could not be send.
-
sendMessage
protected <A extends Address> PduHandle sendMessage(PDU pdu, Target<A> target, TransportMapping<? super A> transport, PduHandleCallback<PDU> pduHandleCallback) throws java.io.IOException
Actually sends a PDU to a target and returns a handle for the sent PDU.- Type Parameters:
A
- the targetAddress
type.- Parameters:
pdu
- thePDU
instance to be sent.target
- aTarget
instance denoting the target SNMP entity.transport
- the (optional) transport mapping to be used to send the request. Iftransport
isnull
a suitable transport mapping is determined from thetarget
address.pduHandleCallback
- callback for newly created PDU handles before the request is sent out.- Returns:
- PduHandle that uniquely identifies the sent PDU for further reference.
- Throws:
java.io.IOException
- if the transport fails to send the PDU or the if the message cannot be BER encoded.
-
lookupTransportMapping
protected <A extends Address> TransportMapping<? super A> lookupTransportMapping(Target<A> target)
-
cancel
public void cancel(PDU request, ResponseListener listener)
Description copied from interface:Session
Cancels an asynchronous request. Any asynchronous request must be canceled when the supplied response listener is being called, even if theResponseEvent
indicates an error.- Specified by:
cancel
in interfaceSession
- Parameters:
request
- a request PDU as sent viaSession.send(PDU pdu, Target target, Object userHandle, ResponseListener listener)
or any .listener
- a ResponseListener instance.
-
setLocalEngine
public void setLocalEngine(byte[] engineID, int engineBoots, int engineTime)
Sets the local engine ID for the SNMP entity represented by thisSnmp
instance. This is a convenience method that sets the local engine ID in the associatedMPv3
andUSM
.- Specified by:
setLocalEngine
in interfaceSession
- Parameters:
engineID
- a byte array containing the local engine ID. The length and content has to comply with the constraints defined in the SNMP-FRAMEWORK-MIB.engineBoots
- the number of boots of this SNMP engine (zero based).engineTime
- the number of seconds since the value of engineBoots last changed.- See Also:
MPv3
,USM
-
getLocalEngineID
public byte[] getLocalEngineID()
Gets the local engine ID if the MPv3 is available, otherwise a runtime exception is thrown.- Specified by:
getLocalEngineID
in interfaceSession
- Returns:
- byte[] the local engine ID.
-
getMPv3
private MPv3 getMPv3()
-
discoverAuthoritativeEngineID
public <A extends Address> byte[] discoverAuthoritativeEngineID(A address, long timeout)
Discovers the engine ID of the SNMPv3 entity denoted by the supplied address. This method does not need to be called for normal operation, because SNMP4J automatically discovers authoritative engine IDs and also automatically synchronize engine time values. For this method to operate successfully, the discover engine IDs flag inUSM
must betrue
(which is the default).- Type Parameters:
A
- theAddress
type.- Parameters:
address
- an Address instance representing the transport address of the SNMPv3 entity for which its authoritative engine ID should be discovered.timeout
- the maximum time in milliseconds to wait for a response.- Returns:
- a byte array containing the authoritative engine ID or
null
if it could not be discovered. - See Also:
USM.setEngineDiscoveryEnabled(boolean enableEngineDiscovery)
-
getUSM
public USM getUSM()
Gets the User Based Security Model (USM). This is a convenience method that uses theMPv3.getSecurityModel(int)
method of the associated MPv3 instance to get the USM.- Returns:
- the
USM
instance associated with the MPv3 bound to thisSnmp
instance, ornull
otherwise.
-
getMessageProcessingModel
public MessageProcessingModel getMessageProcessingModel(int messageProcessingModel)
Gets the message processing model for the supplied ID.- Parameters:
messageProcessingModel
- a mesage processing model ID as defined inMessageProcessingModel
.- Returns:
- MessageProcessingModel a
MessageProcessingModel
ifmessageProcessingModel
has been registered with the message dispatcher associated with this SNMP session.
-
processPdu
public <A extends Address> void processPdu(CommandResponderEvent<A> event)
Process an incoming request or notification PDU.- Specified by:
processPdu
in interfaceCommandResponder
- Type Parameters:
A
- type of the peerAddress
.- Parameters:
event
- aCommandResponderEvent
with the decoded incoming PDU as dispatched to this method call by the associated message dispatcher.
-
isContextEngineIdDiscoveryDisabled
public boolean isContextEngineIdDiscoveryDisabled()
Checks whether RFC5343 based context engine ID discovery is disabled or not. The default value isfalse
.- Returns:
true
if context engine ID discovery is disabled.- Since:
- 2.0
-
setContextEngineIdDiscoveryDisabled
public void setContextEngineIdDiscoveryDisabled(boolean contextEngineIdDiscoveryDisabled)
Sets the RFC5343 based context engine ID discovery. The default value isfalse
.- Parameters:
contextEngineIdDiscoveryDisabled
-true
to disable context engine ID discovery,false
to enable context engine ID discovery.- Since:
- 2.0
-
resendRequest
protected <A extends Address> boolean resendRequest(Snmp.PendingRequest<A> request, PDU response)
-
handleInternalResponse
protected void handleInternalResponse(PDU response, PDU pdu, Address target)
-
removeCommandResponder
public void removeCommandResponder(CommandResponder listener)
Removes aCommandResponder
from this SNMP session.- Parameters:
listener
- a previously addedCommandResponder
instance.
-
addCommandResponder
public void addCommandResponder(CommandResponder listener)
Adds aCommandResponder
to this SNMP session. The command responder will then be informed about incoming SNMP PDUs of any kind that are not related to any outstanding requests of this SNMP session.- Parameters:
listener
- theCommandResponder
instance to be added.
-
fireProcessPdu
protected void fireProcessPdu(CommandResponderEvent<?> event)
Fires aCommandResponderEvent
event to inform listeners about a received PDU. If a listener has marked the event as processed further listeners will not be informed about the event.- Parameters:
event
- aCommandResponderEvent
.
-
getTimeoutModel
public TimeoutModel getTimeoutModel()
Gets the timeout model associated with this SNMP session.- Returns:
- a TimeoutModel instance (never
null
). - See Also:
setTimeoutModel(TimeoutModel timeoutModel)
-
getReportHandler
public Snmp.ReportHandler getReportHandler()
Returns the report handler which is used internally to process reports received from command responders.- Returns:
- the
ReportHandler
instance. - Since:
- 1.6
-
getCounterSupport
public CounterSupport getCounterSupport()
Gets the counter support for Snmp related counters. These are for example: snmp4jStatsRequestTimeouts, snmp4jStatsRequestTimeouts, snmp4jStatsRequestWaitTime- Returns:
- the counter support if available. If the
SNMP4JSettings.getSnmp4jStatistics()
value isSNMP4JSettings.Snmp4jStatistics.none
then no counter support will be created and no statistics will be collected. - Since:
- 2.4.2
-
setCounterSupport
public void setCounterSupport(CounterSupport counterSupport)
Sets the counter support instance to handle counter events on behalf of this Snmp instance.- Parameters:
counterSupport
- the counter support instance that collects the statistics events created by this Snmp instance. See alsogetCounterSupport()
.- Since:
- 2.4.2
-
setTimeoutModel
public void setTimeoutModel(TimeoutModel timeoutModel)
Sets the timeout model for this SNMP session. The default timeout model sends retries whenever the time specified by thetimeout
parameter of the target has elapsed without a response being received for the request. By specifying a different timeout model this behaviour can be changed.- Parameters:
timeoutModel
- aTimeoutModel
instance (must not benull
).
-
setReportHandler
public void setReportHandler(Snmp.ReportHandler reportHandler)
Sets the report handler and overrides the default report handler.- Parameters:
reportHandler
- aReportHandler
instance which must not benull
.- Since:
- 1.6
-
getPendingSyncRequestCount
public int getPendingSyncRequestCount()
Gets the number of currently pending synchronous requests.- Returns:
- the size of the synchronous request queue.
- Since:
- 2.4.2
-
getPendingAsyncRequestCount
public int getPendingAsyncRequestCount()
Gets the number of currently pending asynchronous requests.- Returns:
- the size of the asynchronous request queue.
- Since:
- 2.4.2
-
isEmptyContextEngineID
private boolean isEmptyContextEngineID(PDU pdu)
-
createLocalizedUsmUserEntry
public UsmUserEntry createLocalizedUsmUserEntry(byte[] engineID, OctetString securityName, OID authProtocol, OctetString authPassword, OID privProtocol, OctetString privPassword)
Create and return aUsmUserEntry
with localized authentication and privacy keys from the provided authentication and privacy passwords.- Parameters:
engineID
- the authoritative engine ID of the target for which the newUsmUserEntry
should be localized.securityName
- the (security) user name of the user.authProtocol
- the authentication protocol OID. Ifnull
is provided, no authentication key and no privacy key will be set in the returned user entry.authPassword
- the password which will be localized usingSecurityProtocols.passwordToKey(OID, OctetString, byte[])
. Ifnull
is provided, no authentication key and no privacy key will be set in the returned user entry.privProtocol
- the authentication protocol OID. Ifnull
is provided, no authentication key and no privacy key will be set in the returned user entry.privPassword
- the password which will be localized usingSecurityProtocols.passwordToKey(OID, OID, OctetString, byte[])
. Ifnull
is provided, no privacy key will be set in the returned user entry.- Returns:
- the created
UsmUserEntry
with any given passwords localized to the engine ID corresponding keys. - Since:
- 3.4.0
-
setLocalizedUserCredentials
public SecurityLevel setLocalizedUserCredentials(DirectUserTarget<?> directUserTarget, UsmUserEntry localizedUserCredentials)
Sets the user's security name and authentication/privacy keys and protocols on the suppliedDirectUserTarget
and returns the maximumSecurityLevel
it can be used with.- Parameters:
directUserTarget
- the direct user target to be modified. Security name is set always and authentication protocol and key only if provided in the givenlocalizedUserCredentials
and if the authentication protocol is available fromgetMPv3()
#getAuthenticationProtocol}. The privacy key and protocol are set only if provided the authentication could be set and if the privacy key is set inlocalizedUserCredentials
protocol is available fromgetMPv3()
#getPrivacyProtocol}localizedUserCredentials
- aUsmUserEntry
preferably created bycreateLocalizedUsmUserEntry(byte[], OctetString, OID, OctetString, OID, OctetString)
that must contain already localized keys (or no keys at all).- Returns:
- the maximum
SecurityLevel
the modifiedDirectUserTarget
directUserTarget now supports. - Since:
- 3.4.0
-
closeTransportMapping
protected void closeTransportMapping(TransportMapping<?> tm)
-
-