SnmpEngineId


1   /*
2    * @(#)file      SnmpEngineId.java
3    * @(#)author    Sun Microsystems, Inc.
4    * @(#)version   1.30
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  package com.sun.jmx.snmp;
12  
13  import java.net.InetAddress  ;
14  import java.io.Serializable  ;
15  import java.net.UnknownHostException  ;
16  import java.util.StringTokenizer  ;
17  import java.util.Arrays  ;
18  import java.util.NoSuchElementException  ;
19  
20  import com.sun.jmx.snmp.internal.SnmpTools;
21  
22  /**
23   * This class is handling an <CODE>SnmpEngineId</CODE> data. It copes with binary as well as <CODE>String</CODE> representation of an engine Id. A string format engine is an hex string starting with 0x.
24   * <p><b>This API is a Sun Microsystems internal API  and is subject 
25   * to change without notice.</b></p>
26   * @since 1.5
27   */
28  public class SnmpEngineId implements Serializable   {
29      byte[] engineId = null;
30      String   hexString = null;
31      String   humanString = null;
32      /**
33       * New <CODE>SnmpEngineId</CODE> with an hex string value. Can handle engine Id format &lt;host&gt:&lt;port&gt.
34       * @param hexString Hexa string.
35       */
36      SnmpEngineId(String   hexString) {
37      engineId = SnmpTools.ascii2binary(hexString);
38      this.hexString = hexString.toLowerCase();
39      }
40      /**
41       * New <CODE>SnmpEngineId</CODE> with a binary value. You can use <CODE> SnmpTools </CODE> to convert from hex string to binary format.
42       * @param bin Binary value
43       */
44      SnmpEngineId(byte[] bin) {
45      engineId = bin;
46      hexString = SnmpTools.binary2ascii(bin).toLowerCase();
47      }
48  
49      /**
50       * If a string of the format &lt;address&gt;:&lt;port&gt;:&lt;IANA number&gt; has been provided at creation time, this string is returned.
51       * @return The Id as a readable string or null if not provided.
52       */
53      public String   getReadableId() {
54      return humanString;
55      }
56  
57      /**
58       * Returns a string format engine Id.
59       * @return String format value.
60       */
61      public String   toString() {
62      return hexString;
63      }
64      /**
65       * Returns a binary engine Id.
66       * @return Binary value.
67       */
68      public byte[] getBytes() { 
69      return engineId;
70      }
71      
72      /**
73       * In order to store the string used to create the engineId.
74       */
75      void setStringValue(String   val) {
76      humanString = val;
77      }
78      
79      static void validateId(String   str) throws IllegalArgumentException   {
80      byte[] arr = SnmpTools.ascii2binary(str);
81      validateId(arr);
82      }
83      
84      static void validateId(byte[] arr) throws IllegalArgumentException   {
85      
86      if(arr.length < 5) throw new IllegalArgumentException  ("Id size lower than 5 bytes.");
87      if(arr.length > 32) throw new IllegalArgumentException  ("Id size greater than 32 bytes.");
88  
89      //octet strings with very first bit = 0 and length != 12 octets
90      if( ((arr[0] & 0x80) == 0) && arr.length != 12) 
91          throw new IllegalArgumentException  ("Very first bit = 0 and length != 12 octets");
92  
93      byte[] zeroedArrays = new byte[arr.length];
94      if(Arrays.equals(zeroedArrays, arr)) throw new IllegalArgumentException  ("Zeroed Id.");
95      byte[] FFArrays = new byte[arr.length];
96      Arrays.fill(FFArrays, (byte)0xFF);
97      if(Arrays.equals(FFArrays, arr)) throw new IllegalArgumentException  ("0xFF Id.");
98  
99      }
100     
101     /**
102      * Generates an engine Id based on the passed array.
103      * @return The created engine Id or null if given arr is null or its length == 0;
104      * @exception IllegalArgumentException when:
105      * <ul>
106      *  <li>octet string lower than 5 bytes.</li>
107      *  <li>octet string greater than 32 bytes.</li>
108      *  <li>octet string = all zeros.</li>
109      *  <li>octet string = all 'ff'H.</li>
110      *  <li>octet strings with very first bit = 0 and length != 12 octets</li>
111      * </ul>
112      */
113     public static SnmpEngineId createEngineId(byte[] arr) throws IllegalArgumentException   {
114     if( (arr == null) || arr.length == 0) return null;
115     validateId(arr);
116     return new SnmpEngineId(arr);
117     }
118 
119     /**
120      * Generates an engine Id that is unique to the host the agent is running on. The engine Id unicity is system time based. The creation algorithm uses the SUN Microsystems IANA number (42).
121      * @return The generated engine Id.
122      */
123     public static SnmpEngineId createEngineId() {
124     byte[] address = null;
125     byte[] engineid = new byte[13];
126     int iana = 42;
127     long mask = 0xFF;
128     long time = System.currentTimeMillis();
129 
130     engineid[0] = (byte) ( (iana & 0xFF000000) >> 24 );
131     engineid[0] |= 0x80;
132     engineid[1] = (byte) ( (iana & 0x00FF0000) >> 16 );
133     engineid[2] = (byte) ( (iana & 0x0000FF00) >> 8 );
134     engineid[3] = (byte) (iana & 0x000000FF);
135     engineid[4] = 0x05;
136 
137     engineid[5] =  (byte) ( (time & (mask << 56)) >>> 56 );
138     engineid[6] =  (byte) ( (time & (mask << 48) ) >>> 48 );
139     engineid[7] =  (byte) ( (time & (mask << 40) ) >>> 40 );
140     engineid[8] =  (byte) ( (time & (mask << 32) ) >>> 32 );
141     engineid[9] =  (byte) ( (time & (mask << 24) ) >>> 24 );
142     engineid[10] = (byte) ( (time & (mask << 16) ) >>> 16 );
143     engineid[11] = (byte) ( (time & (mask << 8) ) >>> 8 );
144     engineid[12] = (byte) (time & mask);
145 
146     return new SnmpEngineId(engineid);
147     }
148 
149     /**
150      * Translates an engine Id in an SnmpOid format. This is useful when dealing with USM MIB indexes.
151      * The oid format is : <engine Id length>.<engine Id binary octet1>....<engine Id binary octetn - 1>.<engine Id binary octetn>
152      * Eg: "0x8000002a05819dcb6e00001f96" ==> 13.128.0.0.42.5.129.157.203.110.0.0.31.150
153      * 
154      * @return SnmpOid The oid.
155      */
156     public SnmpOid toOid() {
157     long[] oid = new long[engineId.length + 1];
158     oid[0] = engineId.length;
159     for(int i = 1; i <= engineId.length; i++)
160         oid[i] = (long) (engineId[i-1] & 0xFF);
161     return new SnmpOid(oid);
162     }
163 
164    /**
165     * <P>Generates a unique engine Id. Hexadecimal strings as well as a textual description are supported. The textual format is as follow:
166     * <BR>  &lt;address&gt;:&lt;port&gt;:&lt;IANA number&gt;</P>
167     * <P>The allowed formats :</P>
168     * <ul> 
169     * <li> &lt;address&gt;:&lt;port&gt;:&lt;IANA number&gt
170     * <BR>   All these parameters are used to generate the Id. WARNING, this method is not compliant with IPv6 address format. Use { @link com.sun.jmx.snmp.SnmpEngineId#createEngineId(java.lang.String,java.lang.String) } instead.</li>
171     * <li> &lt;address&gt;:&lt;port&gt;
172     * <BR>   The IANA number will be the SUN Microsystems one (42). </li>
173     * <li> address
174     * <BR>   The port 161 will be used to generate the Id. IANA number will be the SUN Microsystems one (42). </li>
175     * <li> :port
176     * <BR>   The host to use is localhost. IANA number will be the SUN Microsystems one (42). </li>
177     * <li> ::&lt;IANA number&gt &nbsp;&nbsp;&nbsp;
178     * <BR>   The port 161 and localhost will be used to generate the Id. </li>
179     * <li> :&lt;port&gt;:&lt;IANA number&gt;
180     * <BR>   The host to use is localhost. </li>
181     * <li> &lt;address&gt;::&lt;IANA number&gt
182     * <BR>   The port 161 will be used to generate the Id. </li>
183     * <li> :: &nbsp;&nbsp;&nbsp;
184     * <BR>   The port 161, localhost and the SUN Microsystems IANA number will be used to generate the Id. </li>
185     * </ul>
186     * @exception UnknownHostException if the host name contained in the textual format is unknown.
187     * @exception IllegalArgumentException when :
188     * <ul>
189     *  <li>octet string lower than 5 bytes.</li>
190     *  <li>octet string greater than 32 bytes.</li>
191     *  <li>octet string = all zeros.</li>
192     *  <li>octet string = all 'ff'H.</li>
193     *  <li>octet strings with very first bit = 0 and length != 12 octets</li>
194     *  <li>An IPv6 address format is used in conjonction with the ":" separator</li>
195     * </ul>
196     * @param str The string to parse.
197     * @return The generated engine Id or null if the passed string is null.
198     * 
199     */
200     public static SnmpEngineId createEngineId(String   str) 
201     throws IllegalArgumentException  , UnknownHostException   {
202     return createEngineId(str, null);
203     }
204     
205     /**
206      * Idem { @link 
207      * com.sun.jmx.snmp.SnmpEngineId#createEngineId(java.lang.String) } 
208      * with the ability to provide your own separator. This allows IPv6
209      * address format handling (eg: providing @ as separator).
210      * @param str The string to parse.
211      * @param separator the separator to use. If null is provided, the default 
212      * separator ":" is used.
213      * @return The generated engine Id or null if the passed string is null.
214      * @exception UnknownHostException if the host name contained in the 
215      * textual format is unknown.
216      * @exception IllegalArgumentException when :
217      * <ul>
218      *  <li>octet string lower than 5 bytes.</li>
219      *  <li>octet string greater than 32 bytes.</li>
220      *  <li>octet string = all zeros.</li>
221      *  <li>octet string = all 'ff'H.</li>
222      *  <li>octet strings with very first bit = 0 and length != 12 octets</li>
223      *  <li>An IPv6 address format is used in conjonction with the ":" 
224      *      separator</li>
225      * </ul>
226      * @since 1.5
227      */
228     public static SnmpEngineId createEngineId(String   str, String   separator) 
229     throws IllegalArgumentException  , UnknownHostException   {
230     if(str == null) return null;
231     
232     if(str.startsWith("0x") || str.startsWith("0X")) {
233         validateId(str);
234         return new SnmpEngineId(str);
235     }
236     separator = separator == null ? ":" : separator;
237     StringTokenizer   token = new StringTokenizer  (str, 
238                             separator, 
239                             true);
240     
241     String   address = null; 
242     String   port = null;
243     String   iana = null;
244     int objPort = 161;
245     int objIana = 42;
246     InetAddress   objAddress = null;
247     SnmpEngineId eng = null;
248     try {
249         //Deal with address
250         try {
251         address = token.nextToken();
252         }catch(NoSuchElementException   e) {
253         throw new IllegalArgumentException  ("Passed string is invalid : ["+str+"]");
254         }
255         if(!address.equals(separator)) {
256         objAddress = InetAddress.getByName(address);
257         try {
258             token.nextToken();
259         }catch(NoSuchElementException   e) {
260             //No need to go further, no port.
261             eng = SnmpEngineId.createEngineId(objAddress,
262                               objPort,
263                               objIana);
264             eng.setStringValue(str);
265             return eng;
266         }   
267         }
268         else 
269         objAddress = InetAddress.getLocalHost();
270         
271         //Deal with port
272         try {
273         port = token.nextToken();
274         }catch(NoSuchElementException   e) {
275         //No need to go further, no port.
276         eng = SnmpEngineId.createEngineId(objAddress,
277                           objPort,
278                           objIana);
279         eng.setStringValue(str);
280         return eng;
281         }
282         
283         if(!port.equals(separator)) {
284         objPort = Integer.parseInt(port);
285         try {
286             token.nextToken();
287         }catch(NoSuchElementException   e) {
288             //No need to go further, no iana.
289             eng = SnmpEngineId.createEngineId(objAddress,
290                               objPort,
291                               objIana);
292             eng.setStringValue(str);
293             return eng;
294         }   
295         }
296         
297         //Deal with iana
298         try {
299         iana = token.nextToken();
300         }catch(NoSuchElementException   e) {
301         //No need to go further, no port.
302         eng = SnmpEngineId.createEngineId(objAddress,
303                           objPort,
304                           objIana);
305         eng.setStringValue(str);
306         return eng;
307         }
308         
309         if(!iana.equals(separator))
310         objIana = Integer.parseInt(iana);
311         
312         eng = SnmpEngineId.createEngineId(objAddress,
313                           objPort,
314                           objIana);
315         eng.setStringValue(str);
316         
317         return eng;
318         
319     } catch(Exception   e) {
320         throw new IllegalArgumentException  ("Passed string is invalid : ["+str+"]. Check that the used separator ["+ separator + "] is compatible with IPv6 address format.");
321     }
322           
323     }
324 
325     /**
326      * Generates a unique engine Id. The engine Id unicity is based on 
327      * the host IP address and port. The IP address used is the 
328      * localhost one. The creation algorithm uses the SUN Microsystems IANA 
329      * number (42). 
330      * @param port The TCP/IP port the SNMPv3 Adaptor Server is listening to.
331      * @return The generated engine Id.
332      * @exception UnknownHostException if the local host name 
333      *            used to calculate the id is unknown.
334      */
335     public static SnmpEngineId createEngineId(int port) 
336     throws UnknownHostException   {
337     int suniana = 42;
338     InetAddress   address = null;
339     address = InetAddress.getLocalHost();
340     return createEngineId(address, port, suniana);
341     }
342     /**
343      * Generates a unique engine Id. The engine Id unicity is based on 
344      * the host IP address and port. The IP address used is the passed 
345      * one. The creation algorithm uses the SUN Microsystems IANA 
346      * number (42). 
347      * @param address The IP address the SNMPv3 Adaptor Server is listening to.
348      * @param port The TCP/IP port the SNMPv3 Adaptor Server is listening to.
349      * @return The generated engine Id.
350      * @exception UnknownHostException. if the provided address is null.
351      */
352     public static SnmpEngineId createEngineId(InetAddress   address, int port) 
353     throws IllegalArgumentException   {
354     int suniana = 42;
355     if(address == null) 
356         throw new IllegalArgumentException  ("InetAddress is null.");
357     return createEngineId(address, port, suniana);
358     }
359 
360     /**
361      * Generates a unique engine Id. The engine Id unicity is based on 
362      * the host IP address and port. The IP address is the localhost one. 
363      * The creation algorithm uses the passed IANA number. 
364      * @param port The TCP/IP port the SNMPv3 Adaptor Server is listening to.
365      * @param iana Your enterprise IANA number.
366      * @exception UnknownHostException if the local host name used to calculate the id is unknown.
367      * @return The generated engine Id.
368      */
369     public static SnmpEngineId createEngineId(int port, int iana) throws UnknownHostException   {
370     InetAddress   address = null;
371     address = InetAddress.getLocalHost();
372     return createEngineId(address, port, iana);
373     }
374 
375     /**
376      * Generates a unique engine Id. The engine Id unicity is based on the host IP address and port. The IP address is the passed one, it handles IPv4 and IPv6 hosts. The creation algorithm uses the passed IANA number. 
377      * @param addr The IP address the SNMPv3 Adaptor Server is listening to.
378      * @param port The TCP/IP port the SNMPv3 Adaptor Server is listening to.
379      * @param iana Your enterprise IANA number.
380      * @return The generated engine Id.
381      * @exception UnknownHostException if the provided <CODE>InetAddress </CODE> is null.
382      */
383     public static SnmpEngineId createEngineId(InetAddress   addr, 
384                           int port, 
385                           int iana) {
386     if(addr == null) throw new IllegalArgumentException  ("InetAddress is null.");
387     byte[] address = addr.getAddress();
388     byte[] engineid = new byte[9 + address.length];
389     engineid[0] = (byte) ( (iana & 0xFF000000) >> 24 );
390     engineid[0] |= 0x80;
391     engineid[1] = (byte) ( (iana & 0x00FF0000) >> 16 );
392     engineid[2] = (byte) ( (iana & 0x0000FF00) >> 8 );
393     
394 engineid[3] = (byte) (iana & 0x000000FF);
395     engineid[4] = 0x05;
396     
397     if(address.length == 4)
398         engineid[4] = 0x01;
399     
400     if(address.length == 16)
401         engineid[4] = 0x02;
402     
403     for(int i = 0; i < address.length; i++) {
404         engineid[i + 5] = address[i];
405     }
406     
407     engineid[5 + address.length] = (byte)  ( (port & 0xFF000000) >> 24 );
408     engineid[6 + address.length] = (byte) ( (port & 0x00FF0000) >> 16 );
409     engineid[7 + address.length] = (byte) ( (port & 0x0000FF00) >> 8 );
410     engineid[8 + address.length] = (byte) (  port & 0x000000FF );
411 
412     return new SnmpEngineId(engineid);
413     }
414 
415      /**
416      * Generates an engine Id based on an InetAddress. Handles IPv4 and IPv6 addresses. The creation algorithm uses the passed IANA number. 
417      * @param iana Your enterprise IANA number.
418      * @param addr The IP address the SNMPv3 Adaptor Server is listening to.
419      * @return The generated engine Id.
420      * @since 1.5
421      * @exception UnknownHostException if the provided <CODE>InetAddress </CODE> is null.
422      */
423     public static SnmpEngineId createEngineId(int iana, InetAddress   addr)
424     {
425     if(addr == null) throw new IllegalArgumentException  ("InetAddress is null.");
426     byte[] address = addr.getAddress();
427     byte[] engineid = new byte[5 + address.length];
428     engineid[0] = (byte) ( (iana & 0xFF000000) >> 24 );
429     engineid[0] |= 0x80;
430     engineid[1] = (byte) ( (iana & 0x00FF0000) >> 16 );
431     engineid[2] = (byte) ( (iana & 0x0000FF00) >> 8 );
432     
433     engineid[3] = (byte) (iana & 0x000000FF);
434     if(address.length == 4)
435         engineid[4] = 0x01;
436     
437     if(address.length == 16)
438         engineid[4] = 0x02;
439     
440     for(int i = 0; i < address.length; i++) {
441         engineid[i + 5] = address[i];
442     }
443 
444     return new SnmpEngineId(engineid);
445     }
446 
447     /**
448      * Generates an engine Id based on an InetAddress. Handles IPv4 and IPv6 
449      * addresses. The creation algorithm uses the sun IANA number (42). 
450      * @param addr The IP address the SNMPv3 Adaptor Server is listening to.
451      * @return The generated engine Id.
452      * @since 1.5
453      * @exception UnknownHostException if the provided 
454      *            <CODE>InetAddress</CODE> is null.
455      */
456     public static SnmpEngineId createEngineId(InetAddress   addr) {
457     return createEngineId(42, addr);
458     }
459 
460 
461     /**
462      * Tests <CODE>SnmpEngineId</CODE> instance equality. Two <CODE>SnmpEngineId</CODE> are equal if they have the same value.
463      * @return <CODE>true</CODE> if the two <CODE>SnmpEngineId</CODE> are equals, <CODE>false</CODE> otherwise.
464      */
465     public boolean equals(Object   a) {
466     if(!(a instanceof SnmpEngineId) ) return false;
467     return hexString.equals(((SnmpEngineId) a).toString());
468     }
469 
470     public int hashCode() {
471     return hexString.hashCode();
472     }
473 }
474
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags