001/* 002 * Copyright (C) 2009 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 com.google.common.annotations.GwtIncompatible; 018import com.google.common.annotations.J2ktIncompatible; 019import com.google.common.base.Preconditions; 020import com.google.errorprone.annotations.CanIgnoreReturnValue; 021import java.net.InetAddress; 022import java.text.ParseException; 023import javax.annotation.CheckForNull; 024 025/** 026 * A syntactically valid host specifier, suitable for use in a URI. This may be either a numeric IP 027 * address in IPv4 or IPv6 notation, or a domain name. 028 * 029 * <p>Because this class is intended to represent host specifiers which can reasonably be used in a 030 * URI, the domain name case is further restricted to include only those domain names which end in a 031 * recognized public suffix; see {@link InternetDomainName#isPublicSuffix()} for details. 032 * 033 * <p>Note that no network lookups are performed by any {@code HostSpecifier} methods. No attempt is 034 * made to verify that a provided specifier corresponds to a real or accessible host. Only syntactic 035 * and pattern-based checks are performed. 036 * 037 * <p>If you know that a given string represents a numeric IP address, use {@link InetAddresses} to 038 * obtain and manipulate a {@link java.net.InetAddress} instance from it rather than using this 039 * class. Similarly, if you know that a given string represents a domain name, use {@link 040 * InternetDomainName} rather than this class. 041 * 042 * @author Craig Berry 043 * @since 5.0 044 */ 045@J2ktIncompatible 046@GwtIncompatible 047@ElementTypesAreNonnullByDefault 048public final class HostSpecifier { 049 050 private final String canonicalForm; 051 052 private HostSpecifier(String canonicalForm) { 053 this.canonicalForm = canonicalForm; 054 } 055 056 /** 057 * Returns a {@code HostSpecifier} built from the provided {@code specifier}, which is already 058 * known to be valid. If the {@code specifier} might be invalid, use {@link #from(String)} 059 * instead. 060 * 061 * <p>The specifier must be in one of these formats: 062 * 063 * <ul> 064 * <li>A domain name, like {@code google.com} 065 * <li>A IPv4 address string, like {@code 127.0.0.1} 066 * <li>An IPv6 address string with or without brackets, like {@code [2001:db8::1]} or {@code 067 * 2001:db8::1} 068 * </ul> 069 * 070 * @throws IllegalArgumentException if the specifier is not valid. 071 */ 072 public static HostSpecifier fromValid(String specifier) { 073 // Verify that no port was specified, and strip optional brackets from 074 // IPv6 literals. 075 HostAndPort parsedHost = HostAndPort.fromString(specifier); 076 Preconditions.checkArgument(!parsedHost.hasPort()); 077 String host = parsedHost.getHost(); 078 079 // Try to interpret the specifier as an IP address. Note we build 080 // the address rather than using the .is* methods because we want to 081 // use InetAddresses.toUriString to convert the result to a string in 082 // canonical form. 083 InetAddress addr = null; 084 try { 085 addr = InetAddresses.forString(host); 086 } catch (IllegalArgumentException e) { 087 // It is not an IPv4 or IPv6 literal 088 } 089 090 if (addr != null) { 091 return new HostSpecifier(InetAddresses.toUriString(addr)); 092 } 093 094 // It is not any kind of IP address; must be a domain name or invalid. 095 096 // TODO(user): different versions of this for different factories? 097 InternetDomainName domain = InternetDomainName.from(host); 098 099 if (domain.hasPublicSuffix()) { 100 return new HostSpecifier(domain.toString()); 101 } 102 103 throw new IllegalArgumentException( 104 "Domain name does not have a recognized public suffix: " + host); 105 } 106 107 /** 108 * Attempts to return a {@code HostSpecifier} for the given string, throwing an exception if 109 * parsing fails. Always use this method in preference to {@link #fromValid(String)} for a 110 * specifier that is not already known to be valid. 111 * 112 * @throws ParseException if the specifier is not valid. 113 */ 114 @CanIgnoreReturnValue // TODO(b/219820829): consider removing 115 public static HostSpecifier from(String specifier) throws ParseException { 116 try { 117 return fromValid(specifier); 118 } catch (IllegalArgumentException e) { 119 // Since the IAE can originate at several different points inside 120 // fromValid(), we implement this method in terms of that one rather 121 // than the reverse. 122 123 ParseException parseException = new ParseException("Invalid host specifier: " + specifier, 0); 124 parseException.initCause(e); 125 throw parseException; 126 } 127 } 128 129 /** 130 * Determines whether {@code specifier} represents a valid {@link HostSpecifier} as described in 131 * the documentation for {@link #fromValid(String)}. 132 */ 133 public static boolean isValid(String specifier) { 134 try { 135 HostSpecifier unused = fromValid(specifier); 136 return true; 137 } catch (IllegalArgumentException e) { 138 return false; 139 } 140 } 141 142 @Override 143 public boolean equals(@CheckForNull Object other) { 144 if (this == other) { 145 return true; 146 } 147 148 if (other instanceof HostSpecifier) { 149 HostSpecifier that = (HostSpecifier) other; 150 return this.canonicalForm.equals(that.canonicalForm); 151 } 152 153 return false; 154 } 155 156 @Override 157 public int hashCode() { 158 return canonicalForm.hashCode(); 159 } 160 161 /** 162 * Returns a string representation of the host specifier suitable for inclusion in a URI. If the 163 * host specifier is a domain name, the string will be normalized to all lower case. If the 164 * specifier was an IPv6 address without brackets, brackets are added so that the result will be 165 * usable in the host part of a URI. 166 */ 167 @Override 168 public String toString() { 169 return canonicalForm; 170 } 171}