View Javadoc
1   /*
2    * Copyright 2012 The Netty Project
3    *
4    * The Netty Project licenses this file to you under the Apache License,
5    * version 2.0 (the "License"); you may not use this file except in compliance
6    * with the License. You may obtain a copy of the License at:
7    *
8    *   http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12   * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13   * License for the specific language governing permissions and limitations
14   * under the License.
15   */
16  package io.netty.util;
17  
18  import io.netty.util.internal.PlatformDependent;
19  import io.netty.util.internal.SocketUtils;
20  import io.netty.util.internal.StringUtil;
21  import io.netty.util.internal.SystemPropertyUtil;
22  import io.netty.util.internal.logging.InternalLogger;
23  import io.netty.util.internal.logging.InternalLoggerFactory;
24  
25  import java.io.BufferedReader;
26  import java.io.File;
27  import java.io.FileReader;
28  import java.io.IOException;
29  import java.io.InputStream;
30  import java.io.InputStreamReader;
31  import java.net.Inet4Address;
32  import java.net.Inet6Address;
33  import java.net.InetAddress;
34  import java.net.InetSocketAddress;
35  import java.net.NetworkInterface;
36  import java.net.SocketException;
37  import java.net.UnknownHostException;
38  import java.security.AccessController;
39  import java.security.PrivilegedAction;
40  import java.util.ArrayList;
41  import java.util.Enumeration;
42  import java.util.List;
43  
44  /**
45   * A class that holds a number of network-related constants.
46   * <p/>
47   * This class borrowed some of its methods from a  modified fork of the
48   * <a href="http://svn.apache.org/repos/asf/harmony/enhanced/java/branches/java6/classlib/modules/luni/
49   * src/main/java/org/apache/harmony/luni/util/Inet6Util.java">Inet6Util class</a> which was part of Apache Harmony.
50   */
51  public final class NetUtil {
52  
53      /**
54       * The {@link Inet4Address} that represents the IPv4 loopback address '127.0.0.1'
55       */
56      public static final Inet4Address LOCALHOST4;
57  
58      /**
59       * The {@link Inet6Address} that represents the IPv6 loopback address '::1'
60       */
61      public static final Inet6Address LOCALHOST6;
62  
63      /**
64       * The {@link InetAddress} that represents the loopback address. If IPv6 stack is available, it will refer to
65       * {@link #LOCALHOST6}.  Otherwise, {@link #LOCALHOST4}.
66       */
67      public static final InetAddress LOCALHOST;
68  
69      /**
70       * The loopback {@link NetworkInterface} of the current machine
71       */
72      public static final NetworkInterface LOOPBACK_IF;
73  
74      /**
75       * The SOMAXCONN value of the current machine.  If failed to get the value,  {@code 200}  is used as a
76       * default value for Windows or {@code 128} for others.
77       */
78      public static final int SOMAXCONN;
79  
80      /**
81       * This defines how many words (represented as ints) are needed to represent an IPv6 address
82       */
83      private static final int IPV6_WORD_COUNT = 8;
84  
85      /**
86       * The maximum number of characters for an IPV6 string with no scope
87       */
88      private static final int IPV6_MAX_CHAR_COUNT = 39;
89  
90      /**
91       * Number of bytes needed to represent and IPV6 value
92       */
93      private static final int IPV6_BYTE_COUNT = 16;
94  
95      /**
96       * Maximum amount of value adding characters in between IPV6 separators
97       */
98      private static final int IPV6_MAX_CHAR_BETWEEN_SEPARATOR = 4;
99  
100     /**
101      * Minimum number of separators that must be present in an IPv6 string
102      */
103     private static final int IPV6_MIN_SEPARATORS = 2;
104 
105     /**
106      * Maximum number of separators that must be present in an IPv6 string
107      */
108     private static final int IPV6_MAX_SEPARATORS = 8;
109 
110     /**
111      * Maximum amount of value adding characters in between IPV4 separators
112      */
113     private static final int IPV4_MAX_CHAR_BETWEEN_SEPARATOR = 3;
114 
115     /**
116      * Number of separators that must be present in an IPv4 string
117      */
118     private static final int IPV4_SEPARATORS = 3;
119 
120     /**
121      * {@code true} if IPv4 should be used even if the system supports both IPv4 and IPv6.
122      */
123     private static final boolean IPV4_PREFERRED = SystemPropertyUtil.getBoolean("java.net.preferIPv4Stack", false);
124 
125     /**
126      * {@code true} if an IPv6 address should be preferred when a host has both an IPv4 address and an IPv6 address.
127      */
128     private static final boolean IPV6_ADDRESSES_PREFERRED =
129             SystemPropertyUtil.getBoolean("java.net.preferIPv6Addresses", false);
130 
131     /**
132      * The logger being used by this class
133      */
134     private static final InternalLogger logger = InternalLoggerFactory.getInstance(NetUtil.class);
135 
136     static {
137         logger.debug("-Djava.net.preferIPv4Stack: {}", IPV4_PREFERRED);
138         logger.debug("-Djava.net.preferIPv6Addresses: {}", IPV6_ADDRESSES_PREFERRED);
139 
140         byte[] LOCALHOST4_BYTES = {127, 0, 0, 1};
141         byte[] LOCALHOST6_BYTES = {0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1};
142 
143         // Create IPv4 loopback address.
144         Inet4Address localhost4 = null;
145         try {
146             localhost4 = (Inet4Address) InetAddress.getByAddress("localhost", LOCALHOST4_BYTES);
147         } catch (Exception e) {
148             // We should not get here as long as the length of the address is correct.
149             PlatformDependent.throwException(e);
150         }
151         LOCALHOST4 = localhost4;
152 
153         // Create IPv6 loopback address.
154         Inet6Address localhost6 = null;
155         try {
156             localhost6 = (Inet6Address) InetAddress.getByAddress("localhost", LOCALHOST6_BYTES);
157         } catch (Exception e) {
158             // We should not get here as long as the length of the address is correct.
159             PlatformDependent.throwException(e);
160         }
161         LOCALHOST6 = localhost6;
162 
163         // Retrieve the list of available network interfaces.
164         List<NetworkInterface> ifaces = new ArrayList<NetworkInterface>();
165         try {
166             Enumeration<NetworkInterface> interfaces = NetworkInterface.getNetworkInterfaces();
167             if (interfaces != null) {
168                 while (interfaces.hasMoreElements()) {
169                     NetworkInterface iface = interfaces.nextElement();
170                     // Use the interface with proper INET addresses only.
171                     if (SocketUtils.addressesFromNetworkInterface(iface).hasMoreElements()) {
172                         ifaces.add(iface);
173                     }
174                 }
175             }
176         } catch (SocketException e) {
177             logger.warn("Failed to retrieve the list of available network interfaces", e);
178         }
179 
180         // Find the first loopback interface available from its INET address (127.0.0.1 or ::1)
181         // Note that we do not use NetworkInterface.isLoopback() in the first place because it takes long time
182         // on a certain environment. (e.g. Windows with -Djava.net.preferIPv4Stack=true)
183         NetworkInterface loopbackIface = null;
184         InetAddress loopbackAddr = null;
185         loop: for (NetworkInterface iface: ifaces) {
186             for (Enumeration<InetAddress> i = SocketUtils.addressesFromNetworkInterface(iface); i.hasMoreElements();) {
187                 InetAddress addr = i.nextElement();
188                 if (addr.isLoopbackAddress()) {
189                     // Found
190                     loopbackIface = iface;
191                     loopbackAddr = addr;
192                     break loop;
193                 }
194             }
195         }
196 
197         // If failed to find the loopback interface from its INET address, fall back to isLoopback().
198         if (loopbackIface == null) {
199             try {
200                 for (NetworkInterface iface: ifaces) {
201                     if (iface.isLoopback()) {
202                         Enumeration<InetAddress> i = SocketUtils.addressesFromNetworkInterface(iface);
203                         if (i.hasMoreElements()) {
204                             // Found the one with INET address.
205                             loopbackIface = iface;
206                             loopbackAddr = i.nextElement();
207                             break;
208                         }
209                     }
210                 }
211 
212                 if (loopbackIface == null) {
213                     logger.warn("Failed to find the loopback interface");
214                 }
215             } catch (SocketException e) {
216                 logger.warn("Failed to find the loopback interface", e);
217             }
218         }
219 
220         if (loopbackIface != null) {
221             // Found the loopback interface with an INET address.
222             logger.debug(
223                     "Loopback interface: {} ({}, {})",
224                     loopbackIface.getName(), loopbackIface.getDisplayName(), loopbackAddr.getHostAddress());
225         } else {
226             // Could not find the loopback interface, but we can't leave LOCALHOST as null.
227             // Use LOCALHOST6 or LOCALHOST4, preferably the IPv6 one.
228             if (loopbackAddr == null) {
229                 try {
230                     if (NetworkInterface.getByInetAddress(LOCALHOST6) != null) {
231                         logger.debug("Using hard-coded IPv6 localhost address: {}", localhost6);
232                         loopbackAddr = localhost6;
233                     }
234                 } catch (Exception e) {
235                     // Ignore
236                 } finally {
237                     if (loopbackAddr == null) {
238                         logger.debug("Using hard-coded IPv4 localhost address: {}", localhost4);
239                         loopbackAddr = localhost4;
240                     }
241                 }
242             }
243         }
244 
245         LOOPBACK_IF = loopbackIface;
246         LOCALHOST = loopbackAddr;
247 
248         // As a SecurityManager may prevent reading the somaxconn file we wrap this in a privileged block.
249         //
250         // See https://github.com/netty/netty/issues/3680
251         SOMAXCONN = AccessController.doPrivileged(new PrivilegedAction<Integer>() {
252             @Override
253             public Integer run() {
254                 // Determine the default somaxconn (server socket backlog) value of the platform.
255                 // The known defaults:
256                 // - Windows NT Server 4.0+: 200
257                 // - Linux and Mac OS X: 128
258                 int somaxconn = PlatformDependent.isWindows() ? 200 : 128;
259                 File file = new File("/proc/sys/net/core/somaxconn");
260                 BufferedReader in = null;
261                 try {
262                     // file.exists() may throw a SecurityException if a SecurityManager is used, so execute it in the
263                     // try / catch block.
264                     // See https://github.com/netty/netty/issues/4936
265                     if (file.exists()) {
266                         in = new BufferedReader(new FileReader(file));
267                         somaxconn = Integer.parseInt(in.readLine());
268                         if (logger.isDebugEnabled()) {
269                             logger.debug("{}: {}", file, somaxconn);
270                         }
271                     } else {
272                         // Try to get from sysctl
273                         Integer tmp = null;
274                         if (SystemPropertyUtil.getBoolean("io.netty.net.somaxconn.trySysctl", false)) {
275                             tmp = sysctlGetInt("kern.ipc.somaxconn");
276                             if (tmp == null) {
277                                 tmp = sysctlGetInt("kern.ipc.soacceptqueue");
278                                 if (tmp != null) {
279                                     somaxconn = tmp;
280                                 }
281                             } else {
282                                 somaxconn = tmp;
283                             }
284                         }
285 
286                         if (tmp == null) {
287                             logger.debug("Failed to get SOMAXCONN from sysctl and file {}. Default: {}", file,
288                                          somaxconn);
289                         }
290                     }
291                 } catch (Exception e) {
292                     logger.debug("Failed to get SOMAXCONN from sysctl and file {}. Default: {}", file, somaxconn, e);
293                 } finally {
294                     if (in != null) {
295                         try {
296                             in.close();
297                         } catch (Exception e) {
298                             // Ignored.
299                         }
300                     }
301                 }
302                 return somaxconn;
303             }
304         });
305     }
306 
307     /**
308      * This will execute <a href ="https://www.freebsd.org/cgi/man.cgi?sysctl(8)">sysctl</a> with the {@code sysctlKey}
309      * which is expected to return the numeric value for for {@code sysctlKey}.
310      * @param sysctlKey The key which the return value corresponds to.
311      * @return The <a href ="https://www.freebsd.org/cgi/man.cgi?sysctl(8)">sysctl</a> value for {@code sysctlKey}.
312      */
313     private static Integer sysctlGetInt(String sysctlKey) throws IOException {
314         Process process = new ProcessBuilder("sysctl", sysctlKey).start();
315         try {
316             InputStream is = process.getInputStream();
317             InputStreamReader isr = new InputStreamReader(is);
318             BufferedReader br = new BufferedReader(isr);
319             try {
320                 String line = br.readLine();
321                 if (line.startsWith(sysctlKey)) {
322                     for (int i = line.length() - 1; i > sysctlKey.length(); --i) {
323                         if (!Character.isDigit(line.charAt(i))) {
324                             return Integer.valueOf(line.substring(i + 1, line.length()));
325                         }
326                     }
327                 }
328                 return null;
329             } finally {
330                 br.close();
331             }
332         } finally {
333             if (process != null) {
334                 process.destroy();
335             }
336         }
337     }
338 
339     /**
340      * Returns {@code true} if IPv4 should be used even if the system supports both IPv4 and IPv6. Setting this
341      * property to {@code true} will disable IPv6 support. The default value of this property is {@code false}.
342      *
343      * @see <a href="https://docs.oracle.com/javase/8/docs/api/java/net/doc-files/net-properties.html">Java SE
344      *      networking properties</a>
345      */
346     public static boolean isIpV4StackPreferred() {
347         return IPV4_PREFERRED;
348     }
349 
350     /**
351      * Returns {@code true} if an IPv6 address should be preferred when a host has both an IPv4 address and an IPv6
352      * address. The default value of this property is {@code false}.
353      *
354      * @see <a href="https://docs.oracle.com/javase/8/docs/api/java/net/doc-files/net-properties.html">Java SE
355      *      networking properties</a>
356      */
357     public static boolean isIpV6AddressesPreferred() {
358         return IPV6_ADDRESSES_PREFERRED;
359     }
360 
361     /**
362      * Creates an byte[] based on an ipAddressString. No error handling is performed here.
363      */
364     public static byte[] createByteArrayFromIpAddressString(String ipAddressString) {
365 
366         if (isValidIpV4Address(ipAddressString)) {
367             return validIpV4ToBytes(ipAddressString);
368         }
369 
370         if (isValidIpV6Address(ipAddressString)) {
371             if (ipAddressString.charAt(0) == '[') {
372                 ipAddressString = ipAddressString.substring(1, ipAddressString.length() - 1);
373             }
374 
375             int percentPos = ipAddressString.indexOf('%');
376             if (percentPos >= 0) {
377                 ipAddressString = ipAddressString.substring(0, percentPos);
378             }
379 
380             return getIPv6ByName(ipAddressString, true);
381         }
382         return null;
383     }
384 
385     private static int decimalDigit(String str, int pos) {
386         return str.charAt(pos) - '0';
387     }
388 
389     private static byte ipv4WordToByte(String ip, int from, int toExclusive) {
390         int ret = decimalDigit(ip, from);
391         from++;
392         if (from == toExclusive) {
393             return (byte) ret;
394         }
395         ret = ret * 10 + decimalDigit(ip, from);
396         from++;
397         if (from == toExclusive) {
398             return (byte) ret;
399         }
400         return (byte) (ret * 10 + decimalDigit(ip, from));
401     }
402 
403     // visible for tests
404     static byte[] validIpV4ToBytes(String ip) {
405         int i;
406         return new byte[] {
407                 ipv4WordToByte(ip, 0, i = ip.indexOf('.', 1)),
408                 ipv4WordToByte(ip, i + 1, i = ip.indexOf('.', i + 2)),
409                 ipv4WordToByte(ip, i + 1, i = ip.indexOf('.', i + 2)),
410                 ipv4WordToByte(ip, i + 1, ip.length())
411         };
412     }
413 
414     /**
415      * Converts a 32-bit integer into an IPv4 address.
416      */
417     public static String intToIpAddress(int i) {
418         StringBuilder buf = new StringBuilder(15);
419         buf.append(i >> 24 & 0xff);
420         buf.append('.');
421         buf.append(i >> 16 & 0xff);
422         buf.append('.');
423         buf.append(i >> 8 & 0xff);
424         buf.append('.');
425         buf.append(i & 0xff);
426         return buf.toString();
427     }
428 
429     /**
430      * Converts 4-byte or 16-byte data into an IPv4 or IPv6 string respectively.
431      *
432      * @throws IllegalArgumentException
433      *         if {@code length} is not {@code 4} nor {@code 16}
434      */
435     public static String bytesToIpAddress(byte[] bytes) {
436         return bytesToIpAddress(bytes, 0, bytes.length);
437     }
438 
439     /**
440      * Converts 4-byte or 16-byte data into an IPv4 or IPv6 string respectively.
441      *
442      * @throws IllegalArgumentException
443      *         if {@code length} is not {@code 4} nor {@code 16}
444      */
445     public static String bytesToIpAddress(byte[] bytes, int offset, int length) {
446         switch (length) {
447             case 4: {
448                 return new StringBuilder(15)
449                         .append(bytes[offset] & 0xff)
450                         .append('.')
451                         .append(bytes[offset + 1] & 0xff)
452                         .append('.')
453                         .append(bytes[offset + 2] & 0xff)
454                         .append('.')
455                         .append(bytes[offset + 3] & 0xff).toString();
456             }
457             case 16:
458                 return toAddressString(bytes, offset, false);
459             default:
460                 throw new IllegalArgumentException("length: " + length + " (expected: 4 or 16)");
461         }
462     }
463 
464     public static boolean isValidIpV6Address(String ip) {
465         int end = ip.length();
466         if (end < 2) {
467             return false;
468         }
469 
470         // strip "[]"
471         int start;
472         char c = ip.charAt(0);
473         if (c == '[') {
474             end--;
475             if (ip.charAt(end) != ']') {
476                 // must have a close ]
477                 return false;
478             }
479             start = 1;
480             c = ip.charAt(1);
481         } else {
482             start = 0;
483         }
484 
485         int colons;
486         int compressBegin;
487         if (c == ':') {
488             // an IPv6 address can start with "::" or with a number
489             if (ip.charAt(start + 1) != ':') {
490                 return false;
491             }
492             colons = 2;
493             compressBegin = start;
494             start += 2;
495         } else {
496             colons = 0;
497             compressBegin = -1;
498         }
499 
500         int wordLen = 0;
501         loop:
502         for (int i = start; i < end; i++) {
503             c = ip.charAt(i);
504             if (isValidHexChar(c)) {
505                 if (wordLen < 4) {
506                     wordLen++;
507                     continue;
508                 }
509                 return false;
510             }
511 
512             switch (c) {
513             case ':':
514                 if (colons > 7) {
515                     return false;
516                 }
517                 if (ip.charAt(i - 1) == ':') {
518                     if (compressBegin >= 0) {
519                         return false;
520                     }
521                     compressBegin = i - 1;
522                 } else {
523                     wordLen = 0;
524                 }
525                 colons++;
526                 break;
527             case '.':
528                 // case for the last 32-bits represented as IPv4 x:x:x:x:x:x:d.d.d.d
529 
530                 // check a normal case (6 single colons)
531                 if (compressBegin < 0 && colons != 6 ||
532                     // a special case ::1:2:3:4:5:d.d.d.d allows 7 colons with an
533                     // IPv4 ending, otherwise 7 :'s is bad
534                     (colons == 7 && compressBegin >= start || colons > 7)) {
535                     return false;
536                 }
537 
538                 // Verify this address is of the correct structure to contain an IPv4 address.
539                 // It must be IPv4-Mapped or IPv4-Compatible
540                 // (see https://tools.ietf.org/html/rfc4291#section-2.5.5).
541                 int ipv4Start = i - wordLen;
542                 int j = ipv4Start - 2; // index of character before the previous ':'.
543                 if (isValidIPv4MappedChar(ip.charAt(j))) {
544                     if (!isValidIPv4MappedChar(ip.charAt(j - 1)) ||
545                         !isValidIPv4MappedChar(ip.charAt(j - 2)) ||
546                         !isValidIPv4MappedChar(ip.charAt(j - 3))) {
547                         return false;
548                     }
549                     j -= 5;
550                 }
551 
552                 for (; j >= start; --j) {
553                     char tmpChar = ip.charAt(j);
554                     if (tmpChar != '0' && tmpChar != ':') {
555                         return false;
556                     }
557                 }
558 
559                 // 7 - is minimum IPv4 address length
560                 int ipv4End = ip.indexOf('%', ipv4Start + 7);
561                 if (ipv4End < 0) {
562                     ipv4End = end;
563                 }
564                 return isValidIpV4Address(ip, ipv4Start, ipv4End);
565             case '%':
566                 // strip the interface name/index after the percent sign
567                 end = i;
568                 break loop;
569             default:
570                 return false;
571             }
572         }
573 
574         // normal case without compression
575         if (compressBegin < 0) {
576             return colons == 7 && wordLen > 0;
577         }
578 
579         return compressBegin + 2 == end ||
580                // 8 colons is valid only if compression in start or end
581                wordLen > 0 && (colons < 8 || compressBegin <= start);
582     }
583 
584     private static boolean isValidIpV4Word(CharSequence word, int from, int toExclusive) {
585         int len = toExclusive - from;
586         char c0, c1, c2;
587         if (len < 1 || len > 3 || (c0 = word.charAt(from)) < '0') {
588             return false;
589         }
590         if (len == 3) {
591             return (c1 = word.charAt(from + 1)) >= '0' &&
592                    (c2 = word.charAt(from + 2)) >= '0' &&
593                    (c0 <= '1' && c1 <= '9' && c2 <= '9' ||
594                     c0 == '2' && c1 <= '5' && (c2 <= '5' || c1 < '5' && c2 <= '9'));
595         }
596         return c0 <= '9' && (len == 1 || isValidNumericChar(word.charAt(from + 1)));
597     }
598 
599     private static boolean isValidHexChar(char c) {
600         return c >= '0' && c <= '9' || c >= 'A' && c <= 'F' || c >= 'a' && c <= 'f';
601     }
602 
603     private static boolean isValidNumericChar(char c) {
604         return c >= '0' && c <= '9';
605     }
606 
607     private static boolean isValidIPv4MappedChar(char c) {
608         return c == 'f' || c == 'F';
609     }
610 
611     private static boolean isValidIPv4MappedSeparators(byte b0, byte b1, boolean mustBeZero) {
612         // We allow IPv4 Mapped (https://tools.ietf.org/html/rfc4291#section-2.5.5.1)
613         // and IPv4 compatible (https://tools.ietf.org/html/rfc4291#section-2.5.5.1).
614         // The IPv4 compatible is deprecated, but it allows parsing of plain IPv4 addressed into IPv6-Mapped addresses.
615         return b0 == b1 && (b0 == 0 || !mustBeZero && b1 == -1);
616     }
617 
618     private static boolean isValidIPv4Mapped(byte[] bytes, int currentIndex, int compressBegin, int compressLength) {
619         final boolean mustBeZero = compressBegin + compressLength >= 14;
620         return currentIndex <= 12 && currentIndex >= 2 && (!mustBeZero || compressBegin < 12) &&
621                 isValidIPv4MappedSeparators(bytes[currentIndex - 1], bytes[currentIndex - 2], mustBeZero) &&
622                 PlatformDependent.isZero(bytes, 0, currentIndex - 3);
623     }
624 
625     /**
626      * Takes a string and parses it to see if it is a valid IPV4 address.
627      *
628      * @return true, if the string represents an IPV4 address in dotted
629      *         notation, false otherwise
630      */
631     public static boolean isValidIpV4Address(String ip) {
632         return isValidIpV4Address(ip, 0, ip.length());
633     }
634 
635     @SuppressWarnings("DuplicateBooleanBranch")
636     private static boolean isValidIpV4Address(String ip, int from, int toExcluded) {
637         int len = toExcluded - from;
638         int i;
639         return len <= 15 && len >= 7 &&
640                (i = ip.indexOf('.', from + 1)) > 0 && isValidIpV4Word(ip, from, i) &&
641                (i = ip.indexOf('.', from = i + 2)) > 0 && isValidIpV4Word(ip, from - 1, i) &&
642                (i = ip.indexOf('.', from = i + 2)) > 0 && isValidIpV4Word(ip, from - 1, i) &&
643                isValidIpV4Word(ip, i + 1, toExcluded);
644     }
645 
646     /**
647      * Returns the {@link Inet6Address} representation of a {@link CharSequence} IP address.
648      * <p>
649      * This method will treat all IPv4 type addresses as "IPv4 mapped" (see {@link #getByName(CharSequence, boolean)})
650      * @param ip {@link CharSequence} IP address to be converted to a {@link Inet6Address}
651      * @return {@link Inet6Address} representation of the {@code ip} or {@code null} if not a valid IP address.
652      */
653     public static Inet6Address getByName(CharSequence ip) {
654         return getByName(ip, true);
655     }
656 
657     /**
658      * Returns the {@link Inet6Address} representation of a {@link CharSequence} IP address.
659      * <p>
660      * The {@code ipv4Mapped} parameter specifies how IPv4 addresses should be treated.
661      * "IPv4 mapped" format as
662      * defined in <a href="http://tools.ietf.org/html/rfc4291#section-2.5.5">rfc 4291 section 2</a> is supported.
663      * @param ip {@link CharSequence} IP address to be converted to a {@link Inet6Address}
664      * @param ipv4Mapped
665      * <ul>
666      * <li>{@code true} To allow IPv4 mapped inputs to be translated into {@link Inet6Address}</li>
667      * <li>{@code false} Consider IPv4 mapped addresses as invalid.</li>
668      * </ul>
669      * @return {@link Inet6Address} representation of the {@code ip} or {@code null} if not a valid IP address.
670      */
671     public static Inet6Address getByName(CharSequence ip, boolean ipv4Mapped) {
672         byte[] bytes = getIPv6ByName(ip, ipv4Mapped);
673         if (bytes == null) {
674             return null;
675         }
676         try {
677             return Inet6Address.getByAddress(null, bytes, -1);
678         } catch (UnknownHostException e) {
679             throw new RuntimeException(e); // Should never happen
680         }
681     }
682 
683     /**
684      * Returns the byte array representation of a {@link CharSequence} IP address.
685      * <p>
686      * The {@code ipv4Mapped} parameter specifies how IPv4 addresses should be treated.
687      * "IPv4 mapped" format as
688      * defined in <a href="http://tools.ietf.org/html/rfc4291#section-2.5.5">rfc 4291 section 2</a> is supported.
689      * @param ip {@link CharSequence} IP address to be converted to a {@link Inet6Address}
690      * @param ipv4Mapped
691      * <ul>
692      * <li>{@code true} To allow IPv4 mapped inputs to be translated into {@link Inet6Address}</li>
693      * <li>{@code false} Consider IPv4 mapped addresses as invalid.</li>
694      * </ul>
695      * @return byte array representation of the {@code ip} or {@code null} if not a valid IP address.
696      */
697     private static byte[] getIPv6ByName(CharSequence ip, boolean ipv4Mapped) {
698         final byte[] bytes = new byte[IPV6_BYTE_COUNT];
699         final int ipLength = ip.length();
700         int compressBegin = 0;
701         int compressLength = 0;
702         int currentIndex = 0;
703         int value = 0;
704         int begin = -1;
705         int i = 0;
706         int ipv6Separators = 0;
707         int ipv4Separators = 0;
708         int tmp;
709         boolean needsShift = false;
710         for (; i < ipLength; ++i) {
711             final char c = ip.charAt(i);
712             switch (c) {
713             case ':':
714                 ++ipv6Separators;
715                 if (i - begin > IPV6_MAX_CHAR_BETWEEN_SEPARATOR ||
716                         ipv4Separators > 0 || ipv6Separators > IPV6_MAX_SEPARATORS ||
717                         currentIndex + 1 >= bytes.length) {
718                     return null;
719                 }
720                 value <<= (IPV6_MAX_CHAR_BETWEEN_SEPARATOR - (i - begin)) << 2;
721 
722                 if (compressLength > 0) {
723                     compressLength -= 2;
724                 }
725 
726                 // The value integer holds at most 4 bytes from right (most significant) to left (least significant).
727                 // The following bit shifting is used to extract and re-order the individual bytes to achieve a
728                 // left (most significant) to right (least significant) ordering.
729                 bytes[currentIndex++] = (byte) (((value & 0xf) << 4) | ((value >> 4) & 0xf));
730                 bytes[currentIndex++] = (byte) ((((value >> 8) & 0xf) << 4) | ((value >> 12) & 0xf));
731                 tmp = i + 1;
732                 if (tmp < ipLength && ip.charAt(tmp) == ':') {
733                     ++tmp;
734                     if (compressBegin != 0 || (tmp < ipLength && ip.charAt(tmp) == ':')) {
735                         return null;
736                     }
737                     ++ipv6Separators;
738                     needsShift = ipv6Separators == 2 && value == 0;
739                     compressBegin = currentIndex;
740                     compressLength = bytes.length - compressBegin - 2;
741                     ++i;
742                 }
743                 value = 0;
744                 begin = -1;
745                 break;
746             case '.':
747                 ++ipv4Separators;
748                 tmp = i - begin; // tmp is the length of the current segment.
749                 if (tmp > IPV4_MAX_CHAR_BETWEEN_SEPARATOR
750                         || begin < 0
751                         || ipv4Separators > IPV4_SEPARATORS
752                         || (ipv6Separators > 0 && (currentIndex + compressLength < 12))
753                         || i + 1 >= ipLength
754                         || currentIndex >= bytes.length
755                         || ipv4Separators == 1 &&
756                             // We also parse pure IPv4 addresses as IPv4-Mapped for ease of use.
757                             ((!ipv4Mapped || currentIndex != 0 && !isValidIPv4Mapped(bytes, currentIndex,
758                                                                                      compressBegin, compressLength)) ||
759                                 (tmp == 3 && (!isValidNumericChar(ip.charAt(i - 1)) ||
760                                               !isValidNumericChar(ip.charAt(i - 2)) ||
761                                               !isValidNumericChar(ip.charAt(i - 3))) ||
762                                  tmp == 2 && (!isValidNumericChar(ip.charAt(i - 1)) ||
763                                               !isValidNumericChar(ip.charAt(i - 2))) ||
764                                  tmp == 1 && !isValidNumericChar(ip.charAt(i - 1))))) {
765                     return null;
766                 }
767                 value <<= (IPV4_MAX_CHAR_BETWEEN_SEPARATOR - tmp) << 2;
768 
769                 // The value integer holds at most 3 bytes from right (most significant) to left (least significant).
770                 // The following bit shifting is to restructure the bytes to be left (most significant) to
771                 // right (least significant) while also accounting for each IPv4 digit is base 10.
772                 begin = (value & 0xf) * 100 + ((value >> 4) & 0xf) * 10 + ((value >> 8) & 0xf);
773                 if (begin < 0 || begin > 255) {
774                     return null;
775                 }
776                 bytes[currentIndex++] = (byte) begin;
777                 value = 0;
778                 begin = -1;
779                 break;
780             default:
781                 if (!isValidHexChar(c) || (ipv4Separators > 0 && !isValidNumericChar(c))) {
782                     return null;
783                 }
784                 if (begin < 0) {
785                     begin = i;
786                 } else if (i - begin > IPV6_MAX_CHAR_BETWEEN_SEPARATOR) {
787                     return null;
788                 }
789                 // The value is treated as a sort of array of numbers because we are dealing with
790                 // at most 4 consecutive bytes we can use bit shifting to accomplish this.
791                 // The most significant byte will be encountered first, and reside in the right most
792                 // position of the following integer
793                 value += StringUtil.decodeHexNibble(c) << ((i - begin) << 2);
794                 break;
795             }
796         }
797 
798         final boolean isCompressed = compressBegin > 0;
799         // Finish up last set of data that was accumulated in the loop (or before the loop)
800         if (ipv4Separators > 0) {
801             if (begin > 0 && i - begin > IPV4_MAX_CHAR_BETWEEN_SEPARATOR ||
802                     ipv4Separators != IPV4_SEPARATORS ||
803                     currentIndex >= bytes.length) {
804                 return null;
805             }
806             if (ipv6Separators == 0) {
807                 compressLength = 12;
808             } else if (ipv6Separators >= IPV6_MIN_SEPARATORS &&
809                            (!isCompressed && (ipv6Separators == 6 && ip.charAt(0) != ':') ||
810                             isCompressed && (ipv6Separators < IPV6_MAX_SEPARATORS &&
811                                              (ip.charAt(0) != ':' || compressBegin <= 2)))) {
812                 compressLength -= 2;
813             } else {
814                 return null;
815             }
816             value <<= (IPV4_MAX_CHAR_BETWEEN_SEPARATOR - (i - begin)) << 2;
817 
818             // The value integer holds at most 3 bytes from right (most significant) to left (least significant).
819             // The following bit shifting is to restructure the bytes to be left (most significant) to
820             // right (least significant) while also accounting for each IPv4 digit is base 10.
821             begin = (value & 0xf) * 100 + ((value >> 4) & 0xf) * 10 + ((value >> 8) & 0xf);
822             if (begin < 0 || begin > 255) {
823                 return null;
824             }
825             bytes[currentIndex++] = (byte) begin;
826         } else {
827             tmp = ipLength - 1;
828             if (begin > 0 && i - begin > IPV6_MAX_CHAR_BETWEEN_SEPARATOR ||
829                     ipv6Separators < IPV6_MIN_SEPARATORS ||
830                     !isCompressed && (ipv6Separators + 1 != IPV6_MAX_SEPARATORS  ||
831                                       ip.charAt(0) == ':' || ip.charAt(tmp) == ':') ||
832                     isCompressed && (ipv6Separators > IPV6_MAX_SEPARATORS ||
833                         (ipv6Separators == IPV6_MAX_SEPARATORS &&
834                           (compressBegin <= 2 && ip.charAt(0) != ':' ||
835                            compressBegin >= 14 && ip.charAt(tmp) != ':'))) ||
836                     currentIndex + 1 >= bytes.length ||
837                     begin < 0 && ip.charAt(tmp - 1) != ':' ||
838                     compressBegin > 2 && ip.charAt(0) == ':') {
839                 return null;
840             }
841             if (begin >= 0 && i - begin <= IPV6_MAX_CHAR_BETWEEN_SEPARATOR) {
842                 value <<= (IPV6_MAX_CHAR_BETWEEN_SEPARATOR - (i - begin)) << 2;
843             }
844             // The value integer holds at most 4 bytes from right (most significant) to left (least significant).
845             // The following bit shifting is used to extract and re-order the individual bytes to achieve a
846             // left (most significant) to right (least significant) ordering.
847             bytes[currentIndex++] = (byte) (((value & 0xf) << 4) | ((value >> 4) & 0xf));
848             bytes[currentIndex++] = (byte) ((((value >> 8) & 0xf) << 4) | ((value >> 12) & 0xf));
849         }
850 
851         i = currentIndex + compressLength;
852         if (needsShift || i >= bytes.length) {
853             // Right shift array
854             if (i >= bytes.length) {
855                 ++compressBegin;
856             }
857             for (i = currentIndex; i < bytes.length; ++i) {
858                 for (begin = bytes.length - 1; begin >= compressBegin; --begin) {
859                     bytes[begin] = bytes[begin - 1];
860                 }
861                 bytes[begin] = 0;
862                 ++compressBegin;
863             }
864         } else {
865             // Selectively move elements
866             for (i = 0; i < compressLength; ++i) {
867                 begin = i + compressBegin;
868                 currentIndex = begin + compressLength;
869                 if (currentIndex < bytes.length) {
870                     bytes[currentIndex] = bytes[begin];
871                     bytes[begin] = 0;
872                 } else {
873                     break;
874                 }
875             }
876         }
877 
878         if (ipv4Separators > 0) {
879             // We only support IPv4-Mapped addresses [1] because IPv4-Compatible addresses are deprecated [2].
880             // [1] https://tools.ietf.org/html/rfc4291#section-2.5.5.2
881             // [2] https://tools.ietf.org/html/rfc4291#section-2.5.5.1
882             bytes[10] = bytes[11] = (byte) 0xff;
883         }
884 
885         return bytes;
886     }
887 
888     /**
889      * Returns the {@link String} representation of an {@link InetSocketAddress}.
890      * <p>
891      * The output does not include Scope ID.
892      * @param addr {@link InetSocketAddress} to be converted to an address string
893      * @return {@code String} containing the text-formatted IP address
894      */
895     public static String toSocketAddressString(InetSocketAddress addr) {
896         String port = String.valueOf(addr.getPort());
897         final StringBuilder sb;
898 
899         if (addr.isUnresolved()) {
900             String hostString = PlatformDependent.javaVersion() >= 7 ? addr.getHostString() : addr.getHostName();
901             sb = newSocketAddressStringBuilder(hostString, port, !isValidIpV6Address(hostString));
902         } else {
903             InetAddress address = addr.getAddress();
904             String hostString = toAddressString(address);
905             sb = newSocketAddressStringBuilder(hostString, port, address instanceof Inet4Address);
906         }
907         return sb.append(':').append(port).toString();
908     }
909 
910     /**
911      * Returns the {@link String} representation of a host port combo.
912      */
913     public static String toSocketAddressString(String host, int port) {
914         String portStr = String.valueOf(port);
915         return newSocketAddressStringBuilder(
916                 host, portStr, !isValidIpV6Address(host)).append(':').append(portStr).toString();
917     }
918 
919     private static StringBuilder newSocketAddressStringBuilder(String host, String port, boolean ipv4) {
920         int hostLen = host.length();
921         if (ipv4) {
922             // Need to include enough space for hostString:port.
923             return new StringBuilder(hostLen + 1 + port.length()).append(host);
924         }
925         // Need to include enough space for [hostString]:port.
926         StringBuilder stringBuilder = new StringBuilder(hostLen + 3 + port.length());
927         if (hostLen > 1 && host.charAt(0) == '[' && host.charAt(hostLen - 1) == ']') {
928             return stringBuilder.append(host);
929         }
930         return stringBuilder.append('[').append(host).append(']');
931     }
932 
933     /**
934      * Returns the {@link String} representation of an {@link InetAddress}.
935      * <ul>
936      * <li>Inet4Address results are identical to {@link InetAddress#getHostAddress()}</li>
937      * <li>Inet6Address results adhere to
938      * <a href="http://tools.ietf.org/html/rfc5952#section-4">rfc 5952 section 4</a></li>
939      * </ul>
940      * <p>
941      * The output does not include Scope ID.
942      * @param ip {@link InetAddress} to be converted to an address string
943      * @return {@code String} containing the text-formatted IP address
944      */
945     public static String toAddressString(InetAddress ip) {
946         return toAddressString(ip, false);
947     }
948 
949     /**
950      * Returns the {@link String} representation of an {@link InetAddress}.
951      * <ul>
952      * <li>Inet4Address results are identical to {@link InetAddress#getHostAddress()}</li>
953      * <li>Inet6Address results adhere to
954      * <a href="http://tools.ietf.org/html/rfc5952#section-4">rfc 5952 section 4</a> if
955      * {@code ipv4Mapped} is false.  If {@code ipv4Mapped} is true then "IPv4 mapped" format
956      * from <a href="http://tools.ietf.org/html/rfc4291#section-2.5.5">rfc 4291 section 2</a> will be supported.
957      * The compressed result will always obey the compression rules defined in
958      * <a href="http://tools.ietf.org/html/rfc5952#section-4">rfc 5952 section 4</a></li>
959      * </ul>
960      * <p>
961      * The output does not include Scope ID.
962      * @param ip {@link InetAddress} to be converted to an address string
963      * @param ipv4Mapped
964      * <ul>
965      * <li>{@code true} to stray from strict rfc 5952 and support the "IPv4 mapped" format
966      * defined in <a href="http://tools.ietf.org/html/rfc4291#section-2.5.5">rfc 4291 section 2</a> while still
967      * following the updated guidelines in
968      * <a href="http://tools.ietf.org/html/rfc5952#section-4">rfc 5952 section 4</a></li>
969      * <li>{@code false} to strictly follow rfc 5952</li>
970      * </ul>
971      * @return {@code String} containing the text-formatted IP address
972      */
973     public static String toAddressString(InetAddress ip, boolean ipv4Mapped) {
974         if (ip instanceof Inet4Address) {
975             return ip.getHostAddress();
976         }
977         if (!(ip instanceof Inet6Address)) {
978             throw new IllegalArgumentException("Unhandled type: " + ip);
979         }
980 
981         return toAddressString(ip.getAddress(), 0, ipv4Mapped);
982     }
983 
984     private static String toAddressString(byte[] bytes, int offset, boolean ipv4Mapped) {
985         final int[] words = new int[IPV6_WORD_COUNT];
986         int i;
987         final int end = offset + words.length;
988         for (i = offset; i < end; ++i) {
989             words[i] = ((bytes[i << 1] & 0xff) << 8) | (bytes[(i << 1) + 1] & 0xff);
990         }
991 
992         // Find longest run of 0s, tie goes to first found instance
993         int currentStart = -1;
994         int currentLength;
995         int shortestStart = -1;
996         int shortestLength = 0;
997         for (i = 0; i < words.length; ++i) {
998             if (words[i] == 0) {
999                 if (currentStart < 0) {
1000                     currentStart = i;
1001                 }
1002             } else if (currentStart >= 0) {
1003                 currentLength = i - currentStart;
1004                 if (currentLength > shortestLength) {
1005                     shortestStart = currentStart;
1006                     shortestLength = currentLength;
1007                 }
1008                 currentStart = -1;
1009             }
1010         }
1011         // If the array ends on a streak of zeros, make sure we account for it
1012         if (currentStart >= 0) {
1013             currentLength = i - currentStart;
1014             if (currentLength > shortestLength) {
1015                 shortestStart = currentStart;
1016                 shortestLength = currentLength;
1017             }
1018         }
1019         // Ignore the longest streak if it is only 1 long
1020         if (shortestLength == 1) {
1021             shortestLength = 0;
1022             shortestStart = -1;
1023         }
1024 
1025         // Translate to string taking into account longest consecutive 0s
1026         final int shortestEnd = shortestStart + shortestLength;
1027         final StringBuilder b = new StringBuilder(IPV6_MAX_CHAR_COUNT);
1028         if (shortestEnd < 0) { // Optimization when there is no compressing needed
1029             b.append(Integer.toHexString(words[0]));
1030             for (i = 1; i < words.length; ++i) {
1031                 b.append(':');
1032                 b.append(Integer.toHexString(words[i]));
1033             }
1034         } else { // General case that can handle compressing (and not compressing)
1035             // Loop unroll the first index (so we don't constantly check i==0 cases in loop)
1036             final boolean isIpv4Mapped;
1037             if (inRangeEndExclusive(0, shortestStart, shortestEnd)) {
1038                 b.append("::");
1039                 isIpv4Mapped = ipv4Mapped && (shortestEnd == 5 && words[5] == 0xffff);
1040             } else {
1041                 b.append(Integer.toHexString(words[0]));
1042                 isIpv4Mapped = false;
1043             }
1044             for (i = 1; i < words.length; ++i) {
1045                 if (!inRangeEndExclusive(i, shortestStart, shortestEnd)) {
1046                     if (!inRangeEndExclusive(i - 1, shortestStart, shortestEnd)) {
1047                         // If the last index was not part of the shortened sequence
1048                         if (!isIpv4Mapped || i == 6) {
1049                             b.append(':');
1050                         } else {
1051                             b.append('.');
1052                         }
1053                     }
1054                     if (isIpv4Mapped && i > 5) {
1055                         b.append(words[i] >> 8);
1056                         b.append('.');
1057                         b.append(words[i] & 0xff);
1058                     } else {
1059                         b.append(Integer.toHexString(words[i]));
1060                     }
1061                 } else if (!inRangeEndExclusive(i - 1, shortestStart, shortestEnd)) {
1062                     // If we are in the shortened sequence and the last index was not
1063                     b.append("::");
1064                 }
1065             }
1066         }
1067 
1068         return b.toString();
1069     }
1070 
1071     /**
1072      * Does a range check on {@code value} if is within {@code start} (inclusive) and {@code end} (exclusive).
1073      * @param value The value to checked if is within {@code start} (inclusive) and {@code end} (exclusive)
1074      * @param start The start of the range (inclusive)
1075      * @param end The end of the range (exclusive)
1076      * @return
1077      * <ul>
1078      * <li>{@code true} if {@code value} if is within {@code start} (inclusive) and {@code end} (exclusive)</li>
1079      * <li>{@code false} otherwise</li>
1080      * </ul>
1081      */
1082     private static boolean inRangeEndExclusive(int value, int start, int end) {
1083         return value >= start && value < end;
1084     }
1085 
1086     /**
1087      * A constructor to stop this class being constructed.
1088      */
1089     private NetUtil() {
1090         // Unused
1091     }
1092 }