001/* 002 * Copyright (C) 2011 The Guava Authors 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except 005 * in compliance with the License. You may obtain a copy of the License at 006 * 007 * http://www.apache.org/licenses/LICENSE-2.0 008 * 009 * Unless required by applicable law or agreed to in writing, software distributed under the License 010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 011 * or implied. See the License for the specific language governing permissions and limitations under 012 * the License. 013 */ 014 015package com.google.common.net; 016 017import static com.google.common.base.Preconditions.checkArgument; 018import static com.google.common.base.Preconditions.checkNotNull; 019import static com.google.common.base.Preconditions.checkState; 020 021import com.google.common.annotations.Beta; 022import com.google.common.annotations.GwtCompatible; 023import com.google.common.base.Objects; 024import com.google.common.base.Strings; 025import com.google.errorprone.annotations.Immutable; 026import java.io.Serializable; 027import org.checkerframework.checker.nullness.qual.Nullable; 028 029/** 030 * An immutable representation of a host and port. 031 * 032 * <p>Example usage: 033 * 034 * <pre> 035 * HostAndPort hp = HostAndPort.fromString("[2001:db8::1]") 036 * .withDefaultPort(80) 037 * .requireBracketsForIPv6(); 038 * hp.getHost(); // returns "2001:db8::1" 039 * hp.getPort(); // returns 80 040 * hp.toString(); // returns "[2001:db8::1]:80" 041 * </pre> 042 * 043 * <p>Here are some examples of recognized formats: 044 * 045 * <ul> 046 * <li>example.com 047 * <li>example.com:80 048 * <li>192.0.2.1 049 * <li>192.0.2.1:80 050 * <li>[2001:db8::1] - {@link #getHost()} omits brackets 051 * <li>[2001:db8::1]:80 - {@link #getHost()} omits brackets 052 * <li>2001:db8::1 - Use {@link #requireBracketsForIPv6()} to prohibit this 053 * </ul> 054 * 055 * <p>Note that this is not an exhaustive list, because these methods are only concerned with 056 * brackets, colons, and port numbers. Full validation of the host field (if desired) is the 057 * caller's responsibility. 058 * 059 * @author Paul Marks 060 * @since 10.0 061 */ 062@Beta 063@Immutable 064@GwtCompatible 065public final class HostAndPort implements Serializable { 066 /** Magic value indicating the absence of a port number. */ 067 private static final int NO_PORT = -1; 068 069 /** Hostname, IPv4/IPv6 literal, or unvalidated nonsense. */ 070 private final String host; 071 072 /** Validated port number in the range [0..65535], or NO_PORT */ 073 private final int port; 074 075 /** True if the parsed host has colons, but no surrounding brackets. */ 076 private final boolean hasBracketlessColons; 077 078 private HostAndPort(String host, int port, boolean hasBracketlessColons) { 079 this.host = host; 080 this.port = port; 081 this.hasBracketlessColons = hasBracketlessColons; 082 } 083 084 /** 085 * Returns the portion of this {@code HostAndPort} instance that should represent the hostname or 086 * IPv4/IPv6 literal. 087 * 088 * <p>A successful parse does not imply any degree of sanity in this field. For additional 089 * validation, see the {@link HostSpecifier} class. 090 * 091 * @since 20.0 (since 10.0 as {@code getHostText}) 092 */ 093 public String getHost() { 094 return host; 095 } 096 097 /** Return true if this instance has a defined port. */ 098 public boolean hasPort() { 099 return port >= 0; 100 } 101 102 /** 103 * Get the current port number, failing if no port is defined. 104 * 105 * @return a validated port number, in the range [0..65535] 106 * @throws IllegalStateException if no port is defined. You can use {@link #withDefaultPort(int)} 107 * to prevent this from occurring. 108 */ 109 public int getPort() { 110 checkState(hasPort()); 111 return port; 112 } 113 114 /** Returns the current port number, with a default if no port is defined. */ 115 public int getPortOrDefault(int defaultPort) { 116 return hasPort() ? port : defaultPort; 117 } 118 119 /** 120 * Build a HostAndPort instance from separate host and port values. 121 * 122 * <p>Note: Non-bracketed IPv6 literals are allowed. Use {@link #requireBracketsForIPv6()} to 123 * prohibit these. 124 * 125 * @param host the host string to parse. Must not contain a port number. 126 * @param port a port number from [0..65535] 127 * @return if parsing was successful, a populated HostAndPort object. 128 * @throws IllegalArgumentException if {@code host} contains a port number, or {@code port} is out 129 * of range. 130 */ 131 public static HostAndPort fromParts(String host, int port) { 132 checkArgument(isValidPort(port), "Port out of range: %s", port); 133 HostAndPort parsedHost = fromString(host); 134 checkArgument(!parsedHost.hasPort(), "Host has a port: %s", host); 135 return new HostAndPort(parsedHost.host, port, parsedHost.hasBracketlessColons); 136 } 137 138 /** 139 * Build a HostAndPort instance from a host only. 140 * 141 * <p>Note: Non-bracketed IPv6 literals are allowed. Use {@link #requireBracketsForIPv6()} to 142 * prohibit these. 143 * 144 * @param host the host-only string to parse. Must not contain a port number. 145 * @return if parsing was successful, a populated HostAndPort object. 146 * @throws IllegalArgumentException if {@code host} contains a port number. 147 * @since 17.0 148 */ 149 public static HostAndPort fromHost(String host) { 150 HostAndPort parsedHost = fromString(host); 151 checkArgument(!parsedHost.hasPort(), "Host has a port: %s", host); 152 return parsedHost; 153 } 154 155 /** 156 * Split a freeform string into a host and port, without strict validation. 157 * 158 * <p>Note that the host-only formats will leave the port field undefined. You can use {@link 159 * #withDefaultPort(int)} to patch in a default value. 160 * 161 * @param hostPortString the input string to parse. 162 * @return if parsing was successful, a populated HostAndPort object. 163 * @throws IllegalArgumentException if nothing meaningful could be parsed. 164 */ 165 public static HostAndPort fromString(String hostPortString) { 166 checkNotNull(hostPortString); 167 String host; 168 String portString = null; 169 boolean hasBracketlessColons = false; 170 171 if (hostPortString.startsWith("[")) { 172 String[] hostAndPort = getHostAndPortFromBracketedHost(hostPortString); 173 host = hostAndPort[0]; 174 portString = hostAndPort[1]; 175 } else { 176 int colonPos = hostPortString.indexOf(':'); 177 if (colonPos >= 0 && hostPortString.indexOf(':', colonPos + 1) == -1) { 178 // Exactly 1 colon. Split into host:port. 179 host = hostPortString.substring(0, colonPos); 180 portString = hostPortString.substring(colonPos + 1); 181 } else { 182 // 0 or 2+ colons. Bare hostname or IPv6 literal. 183 host = hostPortString; 184 hasBracketlessColons = (colonPos >= 0); 185 } 186 } 187 188 int port = NO_PORT; 189 if (!Strings.isNullOrEmpty(portString)) { 190 // Try to parse the whole port string as a number. 191 // JDK7 accepts leading plus signs. We don't want to. 192 checkArgument(!portString.startsWith("+"), "Unparseable port number: %s", hostPortString); 193 try { 194 port = Integer.parseInt(portString); 195 } catch (NumberFormatException e) { 196 throw new IllegalArgumentException("Unparseable port number: " + hostPortString); 197 } 198 checkArgument(isValidPort(port), "Port number out of range: %s", hostPortString); 199 } 200 201 return new HostAndPort(host, port, hasBracketlessColons); 202 } 203 204 /** 205 * Parses a bracketed host-port string, throwing IllegalArgumentException if parsing fails. 206 * 207 * @param hostPortString the full bracketed host-port specification. Post might not be specified. 208 * @return an array with 2 strings: host and port, in that order. 209 * @throws IllegalArgumentException if parsing the bracketed host-port string fails. 210 */ 211 private static String[] getHostAndPortFromBracketedHost(String hostPortString) { 212 int colonIndex = 0; 213 int closeBracketIndex = 0; 214 checkArgument( 215 hostPortString.charAt(0) == '[', 216 "Bracketed host-port string must start with a bracket: %s", 217 hostPortString); 218 colonIndex = hostPortString.indexOf(':'); 219 closeBracketIndex = hostPortString.lastIndexOf(']'); 220 checkArgument( 221 colonIndex > -1 && closeBracketIndex > colonIndex, 222 "Invalid bracketed host/port: %s", 223 hostPortString); 224 225 String host = hostPortString.substring(1, closeBracketIndex); 226 if (closeBracketIndex + 1 == hostPortString.length()) { 227 return new String[] {host, ""}; 228 } else { 229 checkArgument( 230 hostPortString.charAt(closeBracketIndex + 1) == ':', 231 "Only a colon may follow a close bracket: %s", 232 hostPortString); 233 for (int i = closeBracketIndex + 2; i < hostPortString.length(); ++i) { 234 checkArgument( 235 Character.isDigit(hostPortString.charAt(i)), 236 "Port must be numeric: %s", 237 hostPortString); 238 } 239 return new String[] {host, hostPortString.substring(closeBracketIndex + 2)}; 240 } 241 } 242 243 /** 244 * Provide a default port if the parsed string contained only a host. 245 * 246 * <p>You can chain this after {@link #fromString(String)} to include a port in case the port was 247 * omitted from the input string. If a port was already provided, then this method is a no-op. 248 * 249 * @param defaultPort a port number, from [0..65535] 250 * @return a HostAndPort instance, guaranteed to have a defined port. 251 */ 252 public HostAndPort withDefaultPort(int defaultPort) { 253 checkArgument(isValidPort(defaultPort)); 254 if (hasPort()) { 255 return this; 256 } 257 return new HostAndPort(host, defaultPort, hasBracketlessColons); 258 } 259 260 /** 261 * Generate an error if the host might be a non-bracketed IPv6 literal. 262 * 263 * <p>URI formatting requires that IPv6 literals be surrounded by brackets, like "[2001:db8::1]". 264 * Chain this call after {@link #fromString(String)} to increase the strictness of the parser, and 265 * disallow IPv6 literals that don't contain these brackets. 266 * 267 * <p>Note that this parser identifies IPv6 literals solely based on the presence of a colon. To 268 * perform actual validation of IP addresses, see the {@link InetAddresses#forString(String)} 269 * method. 270 * 271 * @return {@code this}, to enable chaining of calls. 272 * @throws IllegalArgumentException if bracketless IPv6 is detected. 273 */ 274 public HostAndPort requireBracketsForIPv6() { 275 checkArgument(!hasBracketlessColons, "Possible bracketless IPv6 literal: %s", host); 276 return this; 277 } 278 279 @Override 280 public boolean equals(@Nullable Object other) { 281 if (this == other) { 282 return true; 283 } 284 if (other instanceof HostAndPort) { 285 HostAndPort that = (HostAndPort) other; 286 return Objects.equal(this.host, that.host) && this.port == that.port; 287 } 288 return false; 289 } 290 291 @Override 292 public int hashCode() { 293 return Objects.hashCode(host, port); 294 } 295 296 /** Rebuild the host:port string, including brackets if necessary. */ 297 @Override 298 public String toString() { 299 // "[]:12345" requires 8 extra bytes. 300 StringBuilder builder = new StringBuilder(host.length() + 8); 301 if (host.indexOf(':') >= 0) { 302 builder.append('[').append(host).append(']'); 303 } else { 304 builder.append(host); 305 } 306 if (hasPort()) { 307 builder.append(':').append(port); 308 } 309 return builder.toString(); 310 } 311 312 /** Return true for valid port numbers. */ 313 private static boolean isValidPort(int port) { 314 return port >= 0 && port <= 65535; 315 } 316 317 private static final long serialVersionUID = 0; 318}