SnmpPeer


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