1. /*
  2. * @(#)file SnmpPeer.java
  3. * @(#)author Sun Microsystems, Inc.
  4. * @(#)version 3.42
  5. * @(#)date 04/09/15
  6. *
  7. * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
  8. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  9. *
  10. */
  11. // Copyright (c) 1995-96 by Cisco Systems, Inc.
  12. package com.sun.jmx.snmp ;
  13. // java imports
  14. //
  15. import java.net.InetAddress;
  16. import java.net.UnknownHostException;
  17. import java.io.Serializable;
  18. // JMX imports
  19. //
  20. import com.sun.jmx.snmp.SnmpPduFactory ;
  21. // SNMP Runtime imports
  22. //
  23. import com.sun.jmx.snmp.SnmpPduFactoryBER ;
  24. /**
  25. * Holds information about an SNMP agent. This information is used to communicate with the agent.
  26. * These are the IP address, port number, SNMP parameters, and peer channel parameters
  27. * (such as the maximum request packet size, maximum number of variable bindings in a packet, retries, and timeouts).
  28. * Changing these would affect all active requests.
  29. * <P>
  30. * The class contains the following properties:
  31. * <UL>
  32. * <LI><B>destPort</B>: port number of the destination host.
  33. * <BR>The default port is <B>161</B>.
  34. *
  35. * <LI><B>maxVarBindLimit</B>: maximum number of OIDs which can be encoded in a single request packet.
  36. * This is set by the user.
  37. * <BR>A request which contains more than this limit will be automatically split into multiple requests.
  38. * Typically used when multiplexing requests.
  39. * <BR>The default value is 25.
  40. *
  41. * <LI><B>maxSnmpPacketSize</B>: maximum packet size of the request PDU.
  42. * This can be set by the user.
  43. * <BR> If the request crosses this limit while encoding, the request is automatically split into
  44. * multiple small requests. Each of these requests will again be within this limit.
  45. * <BR>The default value is (2 * 1024).
  46. *
  47. * <LI><B>maxTries</B>: number of times to try before giving up.
  48. * <BR>The default number is <B>3</B>.
  49. *
  50. * <LI><B>timeout</B>: amount of time to wait for a response from the
  51. * peer. If this amount of time passes without a response, and if the
  52. * <B>maxTries</B> value has not been exceeded, the request will be
  53. * resent. <BR>The default amount of time is <B>3000
  54. * milliseconds</B>.
  55. *
  56. * <LI><B>snmpParameters</B>: SNMP parameters to be used when communicating with the agent.
  57. * The parameters contain the protocol version and security information (the parameters can be shared amongst several peers).
  58. *
  59. *</UL>
  60. * JavaBean compliant getters and setters allow the properties listed above to be modified.
  61. *
  62. * <p><b>This API is a Sun Microsystems internal API and is subject
  63. * to change without notice.</b></p>
  64. * @see com.sun.jmx.snmp.SnmpParameters
  65. */
  66. public class SnmpPeer implements Serializable {
  67. // PUBLIC VARIABLES
  68. //-----------------
  69. /**
  70. * The default SNMP packet size of an SNMP request (2 * 1024).
  71. * <BR>The maximum size is initially set to Ethernet maximum transfer unit (MTU).
  72. */
  73. public static int defaultSnmpRequestPktSize = 2 * 1024 ;
  74. /**
  75. * The default SNMP packet size of an SNMP response (8 * 1024).
  76. * <BR>This will be the default size that the session socket uses when receiving a packet.
  77. */
  78. public static int defaultSnmpResponsePktSize = 8 * 1024 ;
  79. // PRIVATE VARIABLES
  80. //------------------
  81. /**
  82. * The maximum number of variable bindings that can be packed into a request.
  83. * The default value is 25.
  84. */
  85. private int maxVarBindLimit = 25 ;
  86. /**
  87. * Port number of the destination host.
  88. * The default port is 161.
  89. */
  90. private int portNum = 161 ;
  91. /**
  92. * Number of times to try before giving up.
  93. * The default number is 3.
  94. */
  95. private int maxTries = 3 ;
  96. /**
  97. * The amount of time to wait for a response from the peer.
  98. * The default amount of time is 3000 millisec.
  99. */
  100. private int timeout = 3000;
  101. /**
  102. * The PDU factory. The default factory is an instance of <CODE>SnmpPduFactoryBER</CODE>.
  103. */
  104. private SnmpPduFactory pduFactory = new SnmpPduFactoryBER() ;
  105. /**
  106. * The maximum round trip time for a packet with the peer.
  107. */
  108. private long _maxrtt ;
  109. /**
  110. * The minimum round trip time for a packet with the peer.
  111. */
  112. private long _minrtt ;
  113. /**
  114. * The average round trip time for a packet with the peer.
  115. */
  116. private long _avgrtt ;
  117. /**
  118. * SNMP parameters for this peer are valid for all requests using this peer.
  119. * @see com.sun.jmx.snmp.SnmpParameters
  120. */
  121. private SnmpParams _snmpParameter = new SnmpParameters() ;
  122. /**
  123. * Internet address of the peer to be used when communicating with the peer.
  124. */
  125. private InetAddress _devAddr = null ;
  126. /**
  127. * Maximum packet size of the request PDU. This can be set by the user.
  128. * If the request crosses this limit while encoding, the request is automatically split
  129. * into multiple small request. Each of these requests will again be within this limit.
  130. * The default value is (2 * 1024).
  131. */
  132. private int maxSnmpPacketSize = defaultSnmpRequestPktSize ;
  133. /**
  134. * List of alternate addresses.
  135. */
  136. InetAddress _devAddrList[] = null ;
  137. /**
  138. * The index of address currently being used.
  139. */
  140. int _addrIndex = 0 ;
  141. private boolean customPduFactory = false;
  142. // CONSTRUCTORS
  143. //-------------
  144. /**
  145. * Creates an SNMP peer object for a device. The default port is 161.
  146. * @param host The peer name.
  147. * @exception UnknownHostException If the host name cannot be resolved.
  148. */
  149. public SnmpPeer(String host) throws UnknownHostException {
  150. this(host, (int)161) ;
  151. }
  152. /**
  153. * Creates an SNMP peer object for a device. The default port is 161.
  154. * @param netaddr The peer <CODE>InetAddress</CODE>.
  155. * @param port The port number.
  156. */
  157. public SnmpPeer(InetAddress netaddr, int port) {
  158. _devAddr = netaddr ;
  159. portNum = port;
  160. }
  161. /**
  162. * Creates an SNMP peer object for a device. The default port is 161.
  163. * @param netaddr The peer <CODE>InetAddress</CODE>.
  164. */
  165. public SnmpPeer(InetAddress netaddr) {
  166. _devAddr = netaddr ;
  167. }
  168. /**
  169. * Creates an SNMP peer object for a device with the specified port.
  170. * @param host The peer name.
  171. * @param port The port number.
  172. * @exception UnknownHostException If the host name cannot be resolved.
  173. */
  174. public SnmpPeer(String host, int port) throws UnknownHostException {
  175. useIPAddress(host) ;
  176. portNum = port;
  177. }
  178. // PUBLIC METHODS
  179. //---------------
  180. /**
  181. * Sets a specific IP address to which the peer will communicate.
  182. * Typically used to set an alternate IP address or a specific address which is known to respond to requests.
  183. * The IP address <CODE>String</CODE> can either be a machine name, such as <CODE>ibiza</CODE>,
  184. * or a <CODE>String</CODE> representing its IP address, such as "206.26.48.100".
  185. * @param ipaddr Dot formatted IP address or logical host name.
  186. * @exception UnknownHostException If the host name cannot be resolved.
  187. */
  188. final public synchronized void useIPAddress(String ipaddr) throws UnknownHostException {
  189. _devAddr = InetAddress.getByName(ipaddr) ;
  190. }
  191. /**
  192. * Returns the dot-formatted IP address string (for example 171.69.220.224).
  193. * Useful when you want to know which IP address is used
  194. * when the address was resolved using a DNS name.
  195. * @return The dot-formatted IP address being used.
  196. */
  197. final public synchronized String ipAddressInUse() {
  198. byte [] adr = _devAddr.getAddress() ;
  199. return
  200. (adr[0]&0xFF) + "." + (adr[1]&0xFF) + "." +
  201. (adr[2]&0xFF) + "." + (adr[3]&0xFF);
  202. }
  203. /**
  204. * Specifies the list of addresses to be used. When a host is not responding
  205. * the user can switch to the next address by calling <CODE>useNextAddress</CODE>.
  206. * @param adrList The list of <CODE>InetAddresses</CODE>.
  207. */
  208. final public synchronized void useAddressList(InetAddress adrList[]) {
  209. _devAddrList = adrList ;
  210. _addrIndex = 0 ;
  211. useNextAddress() ;
  212. }
  213. /**
  214. * Causes all subsequent requests to go to the new address
  215. * obtained from the specified list of alternate addresses.
  216. * If it reaches the end of list, it starts again at the first address.
  217. */
  218. final public synchronized void useNextAddress() {
  219. if (_devAddrList == null)
  220. return ;
  221. /* NPCTE fix for bug 4486059, esc 0 MR 03-August-2001 */
  222. /* if (_addrIndex > _devAddrList.length) */
  223. if (_addrIndex > _devAddrList.length-1)
  224. /* end of NPCTE fix for bugid 4486059 */
  225. _addrIndex = 0 ;
  226. _devAddr = _devAddrList[_addrIndex++] ;
  227. }
  228. /**
  229. * Determines whether an SNMP <CODE>set</CODE> operation is allowed with this
  230. * peer object. For now it just makes sure a parameter is configured for a write operation.
  231. * @return <CODE>true</CODE> if SNMP <CODE>set</CODE> is allowed and the parameter is configured,
  232. * <CODE>false</CODE> otherwise.
  233. */
  234. public boolean allowSnmpSets() {
  235. return _snmpParameter.allowSnmpSets() ;
  236. }
  237. /**
  238. * Compares the two peer objects to determine whether they are the same. This is used
  239. * to determine whether requests can be multiplexed.
  240. * @param obj The object to compare <CODE>this</CODE> with.
  241. * @return <CODE>true</CODE> if they are referring to same peer and using same address;
  242. * <CODE>false</CODE> otherwise.
  243. */
  244. public boolean equals(Object obj) {
  245. if (this == obj)
  246. return true ;
  247. /*
  248. if (obj instanceof SnmpPeer) {
  249. SnmpPeer peer = (SnmpPeer) obj ;
  250. if (_devAddr.equals(peer.getDestAddr()) &&
  251. portNum == peer.getDestPort())
  252. return true ;
  253. }
  254. */
  255. return false ;
  256. }
  257. /**
  258. * Gets the list of alternate <CODE>InetAddress</CODE> configured for this peer.
  259. * @return The <CODE>InetAddress</CODE> of the peer.
  260. */
  261. final public InetAddress[] getDestAddrList() {
  262. return _devAddrList;
  263. }
  264. /**
  265. * Gets the <CODE>InetAddress</CODE> object for this peer.
  266. * @return The <CODE>InetAddress</CODE> of the peer.
  267. */
  268. final public InetAddress getDestAddr() {
  269. return _devAddr ;
  270. }
  271. /**
  272. * Gets the destination port number of the peer to which SNMP requests are to be sent.
  273. * @return The destination port number.
  274. */
  275. final public int getDestPort() {
  276. return portNum ;
  277. }
  278. /**
  279. * Changes the port address of the destination for the request.
  280. * @param newPort The destination port.
  281. */
  282. final public synchronized void setDestPort(int newPort) {
  283. portNum = newPort ;
  284. }
  285. /**
  286. * Gets the timeout to wait for a response from the peer.
  287. * @return The value of the timeout property.
  288. */
  289. final public int getTimeout() {
  290. return timeout;
  291. }
  292. /**
  293. * Changes the timeout to wait for a response from the peer.
  294. * @param newTimeout The timeout (in milliseconds).
  295. */
  296. final public synchronized void setTimeout(int newTimeout) {
  297. if (newTimeout < 0)
  298. throw new IllegalArgumentException();
  299. timeout= newTimeout;
  300. }
  301. /**
  302. * Gets the number of times to try before giving up.
  303. * @return The maximun number of tries.
  304. */
  305. final public int getMaxTries() {
  306. return maxTries;
  307. }
  308. /**
  309. * Changes the maximun number of times to try before giving up.
  310. * @param newMaxTries The maximun number of tries.
  311. */
  312. final public synchronized void setMaxTries(int newMaxTries) {
  313. if (newMaxTries < 0)
  314. throw new IllegalArgumentException();
  315. maxTries= newMaxTries;
  316. }
  317. /**
  318. * Gets the name specified in the constructor while creating this object.
  319. * @return The name of the host as specified while creating this object.
  320. */
  321. final public String getDevName() {
  322. return getDestAddr().getHostName() ;
  323. }
  324. /**
  325. * Returns the <CODE>String</CODE> representation for this <CODE>SnmpPeer</CODE>.
  326. * @return The <CODE>String</CODE> representation.
  327. */
  328. public String toString() {
  329. return "Peer/Port : " + getDevName() + "/" + getDestPort() ;
  330. }
  331. /**
  332. * Gets the maximum number of variable bindings that can be sent to a peer.
  333. * @return The maximum variable bindings that can be encoded into a request packet.
  334. */
  335. final public synchronized int getVarBindLimit() {
  336. return maxVarBindLimit ;
  337. }
  338. /**
  339. * Configures the maximum number of variable bindings that can be sent to a peer.
  340. * @param limit The desired limit.
  341. */
  342. final public synchronized void setVarBindLimit(int limit) {
  343. maxVarBindLimit = limit ;
  344. }
  345. /**
  346. * Sets the <CODE>SnmpParams</CODE> object associated with the peer.
  347. * @param params The desired parameters.
  348. */
  349. public void setParams(SnmpParams params) {
  350. _snmpParameter = params;
  351. }
  352. /**
  353. * Gets the <CODE>SnmpParams</CODE> object associated with the peer.
  354. * @return The associated parameters.
  355. */
  356. public SnmpParams getParams() {
  357. return _snmpParameter;
  358. }
  359. /**
  360. * Gets the maximum request packet size that is currently used.
  361. * @return The maximum request packet size.
  362. */
  363. final public int getMaxSnmpPktSize() {
  364. return maxSnmpPacketSize ;
  365. }
  366. /**
  367. * Configures the maximum packet size that can be used when generating an SNMP request.
  368. * @param newsize The desired packet size.
  369. */
  370. final public synchronized void setMaxSnmpPktSize(int newsize) {
  371. maxSnmpPacketSize = newsize ;
  372. }
  373. boolean isCustomPduFactory() {
  374. return customPduFactory;
  375. }
  376. /**
  377. * Finalizer of the <CODE>SnmpPeer</CODE> objects.
  378. * This method is called by the garbage collector on an object
  379. * when garbage collection determines that there are no more references to the object.
  380. * <P>Sets all the references to this SNMP peer object to <CODE>null</CODE>.
  381. */
  382. public void finalize() {
  383. _devAddr = null ;
  384. _devAddrList = null ;
  385. _snmpParameter = null ;
  386. }
  387. /**
  388. * Gets the minimum round trip time for a packet with the peer.
  389. * @return The minimum round trip time for a packet with the peer.
  390. */
  391. public long getMinRtt() {
  392. return _minrtt ;
  393. }
  394. /**
  395. * Gets the maximum round trip time for a packet with the peer.
  396. * @return The maximum round trip time for a packet with the peer.
  397. */
  398. public long getMaxRtt() {
  399. return _maxrtt ;
  400. }
  401. /**
  402. * Gets the average round trip time for a packet with the peer.
  403. * @return The average round trip time for a packet with the peer.
  404. */
  405. public long getAvgRtt() {
  406. return _avgrtt ;
  407. }
  408. // PRIVATE METHODS
  409. //----------------
  410. private void updateRttStats(long tm) {
  411. if (_minrtt > tm)
  412. _minrtt = tm ;
  413. else if (_maxrtt < tm)
  414. _maxrtt = tm ;
  415. else
  416. _avgrtt = tm ; // to do later.
  417. }
  418. }