Source Home >> Java Source 1.6.0 >> java.net.InetSocketAddress V 0.09

001/*
002 * @(#)InetSocketAddress.java	1.22 05/11/17
003 *
004 * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
005 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
006 */
007package java.net;
008
009import java.io.ObjectInputStream;
010import java.io.IOException;
011import java.io.InvalidObjectException;
012
013/**
014 *
015 * This class implements an IP Socket Address (IP address + port number)
016 * It can also be a pair (hostname + port number), in which case an attempt
017 * will be made to resolve the hostname. If resolution fails then the address
018 * is said to be <I>unresolved</I> but can still be used on some circumstances
019 * like connecting through a proxy.
020 * <p>
021 * It provides an immutable object used by sockets for binding, connecting, or
022 * as returned values.
023 * <p>
024 * The <i>wildcard</i> is a special local IP address. It usually means "any"
025 * and can only be used for <code>bind</code> operations.
026 *
027 * @see	java.net.Socket
028 * @see	java.net.ServerSocket
029 * @since 1.4
030 */
031public class InetSocketAddress extends SocketAddress {
032    /* The hostname of the Socket Address
033     * @serial
034     */    
035    private String hostname = null;
036    /* The IP address of the Socket Address
037     * @serial
038     */
039    private InetAddress addr = null;
040    /* The port number of the Socket Address
041     * @serial
042     */  
043    private int port;
044
045    private static final long serialVersionUID = 5076001401234631237L;
046    
047    private InetSocketAddress() {
048    }
049
050    /**
051     * Creates a socket address where the IP address is the wildcard address
052     * and the port number a specified value.
053     * <p>
054     * A valid port value is between 0 and 65535.
055     * A port number of <code>zero</code> will let the system pick up an
056     * ephemeral port in a <code>bind</code> operation.
057     * <p>
058     * @param	port	The port number
059     * @throws IllegalArgumentException if the port parameter is outside the specified
060     * range of valid port values. 
061     */
062    public InetSocketAddress(int port) {
063	this(InetAddress.anyLocalAddress(), port);
064    }
065
066    /**
067     *
068     * Creates a socket address from an IP address and a port number.
069     * <p>
070     * A valid port value is between 0 and 65535.
071     * A port number of <code>zero</code> will let the system pick up an
072     * ephemeral port in a <code>bind</code> operation.
073     * <P>
074     * A <code>null</code> address will assign the <i>wildcard</i> address.
075     * <p>
076     * @param	addr	The IP address
077     * @param	port	The port number
078     * @throws IllegalArgumentException if the port parameter is outside the specified
079     * range of valid port values.
080     */
081    public InetSocketAddress(InetAddress addr, int port) {
082	if (port < 0 || port > 0xFFFF) {
083	    throw new IllegalArgumentException("port out of range:" + port);
084	}
085	this.port = port;
086	if (addr == null)
087	    this.addr = InetAddress.anyLocalAddress();
088	else
089	    this.addr = addr;
090    }
091
092    /**
093     *
094     * Creates a socket address from a hostname and a port number.
095     * <p>
096     * An attempt will be made to resolve the hostname into an InetAddress.
097     * If that attempt fails, the address will be flagged as <I>unresolved</I>.
098     * <p>
099     * If there is a security manager, its <code>checkConnect</code> method
100     * is called with the host name as its argument to check the permissiom
101     * to resolve it. This could result in a SecurityException.
102     * <P>
103     * A valid port value is between 0 and 65535.
104     * A port number of <code>zero</code> will let the system pick up an
105     * ephemeral port in a <code>bind</code> operation.
106     * <P>
107     * @param	hostname the Host name
108     * @param	port	The port number
109     * @throws IllegalArgumentException if the port parameter is outside the range
110     * of valid port values, or if the hostname parameter is <TT>null</TT>.
111     * @throws SecurityException if a security manager is present and
112     *				 permission to resolve the host name is
113     *				 denied.
114     * @see	#isUnresolved()
115     */
116    public InetSocketAddress(String hostname, int port) {
117	if (port < 0 || port > 0xFFFF) {
118	    throw new IllegalArgumentException("port out of range:" + port);
119	}
120	if (hostname == null) {
121	    throw new IllegalArgumentException("hostname can't be null");
122	}
123	try {
124	    addr = InetAddress.getByName(hostname);
125	} catch(UnknownHostException e) {
126	    this.hostname = hostname;
127	    addr = null;
128	}
129	this.port = port;
130    }
131
132    /**
133     *
134     * Creates an unresolved socket address from a hostname and a port number.
135     * <p>
136     * No attempt will be made to resolve the hostname into an InetAddress.
137     * The address will be flagged as <I>unresolved</I>.
138     * <p>
139     * A valid port value is between 0 and 65535.
140     * A port number of <code>zero</code> will let the system pick up an
141     * ephemeral port in a <code>bind</code> operation.
142     * <P>
143     * @param	host    the Host name
144     * @param	port	The port number
145     * @throws IllegalArgumentException if the port parameter is outside
146     *                  the range of valid port values, or if the hostname
147     *                  parameter is <TT>null</TT>.
148     * @see	#isUnresolved()
149     * @return  a <code>InetSocketAddress</code> representing the unresolved
150     *          socket address
151     * @since 1.5
152     */
153    public static InetSocketAddress createUnresolved(String host, int port) {
154	if (port < 0 || port > 0xFFFF) {
155	    throw new IllegalArgumentException("port out of range:" + port);
156	}
157	if (host == null) {
158	    throw new IllegalArgumentException("hostname can't be null");
159	}
160	InetSocketAddress s = new InetSocketAddress();
161	s.port = port;
162	s.hostname = host;
163	s.addr = null;
164	return s;
165    }
166
167    private void readObject(ObjectInputStream s) 
168 	throws IOException, ClassNotFoundException {
169 	s.defaultReadObject();
170	
171 	// Check that our invariants are satisfied
172 	if (port < 0 || port > 0xFFFF) {
173 	    throw new InvalidObjectException("port out of range:" + port);
174 	}
175 	
176 	if (hostname == null && addr == null) {
177 	    throw new InvalidObjectException("hostname and addr " + 
178 					     "can't both be null");
179 	}
180    }
181
182    /**
183     * Gets the port number.
184     *
185     * @return the port number.
186     */
187    public final int getPort() {
188	return port;
189    }
190
191    /**
192     * 
193     * Gets the <code>InetAddress</code>.
194     *
195     * @return the InetAdress or <code>null</code> if it is unresolved.
196     */
197    public final InetAddress getAddress() {
198	return addr;
199    }
200
201    /**
202     * Gets the <code>hostname</code>.
203     *
204     * @return	the hostname part of the address.
205     */
206    public final String getHostName() {
207	if (hostname != null)
208	    return hostname;
209	if (addr != null)
210	    return addr.getHostName();
211	return null;
212    }
213
214    /**
215     * Returns the hostname, or the String form of the address if it
216     * doesn't have a hostname (it was created using a litteral).
217     * This has the benefit of <b>not</b> attemptimg a reverse lookup.
218     *
219     * @return the hostname, or String representation of the address.
220     * @since 1.6
221     */
222    final String getHostString() {
223	if (hostname != null)
224	    return hostname;
225	if (addr != null) {
226	    if (addr.hostName != null)
227		return addr.hostName;
228	    else
229		return addr.getHostAddress();
230	}
231	return null;
232    }
233
234    /**
235     * Checks whether the address has been resolved or not.
236     *
237     * @return <code>true</code> if the hostname couldn't be resolved into
238     *		an <code>InetAddress</code>.
239     */
240    public final boolean isUnresolved() {
241	return addr == null;
242    }
243
244    /**
245     * Constructs a string representation of this InetSocketAddress.
246     * This String is constructed by calling toString() on the InetAddress
247     * and concatenating the port number (with a colon). If the address
248     * is unresolved then the part before the colon will only contain the hostname.
249     *
250     * @return  a string representation of this object.
251     */
252    public String toString() {
253	if (isUnresolved()) {
254	    return hostname + ":" + port;
255	} else {
256	    return addr.toString() + ":" + port;
257	}
258    }
259
260    /**
261     * Compares this object against the specified object.
262     * The result is <code>true</code> if and only if the argument is
263     * not <code>null</code> and it represents the same address as
264     * this object.
265     * <p>
266     * Two instances of <code>InetSocketAddress</code> represent the same
267     * address if both the InetAddresses (or hostnames if it is unresolved) and port
268     * numbers are equal.
269     * If both addresses are unresolved, then the hostname & the port number
270     * are compared.
271     *
272     * @param   obj   the object to compare against.
273     * @return  <code>true</code> if the objects are the same;
274     *          <code>false</code> otherwise.
275     * @see java.net.InetAddress#equals(java.lang.Object)
276     */
277    public final boolean equals(Object obj) {
278	if (obj == null || !(obj instanceof InetSocketAddress))
279	    return false;
280	InetSocketAddress sockAddr = (InetSocketAddress) obj;
281	boolean sameIP = false;
282	if (this.addr != null)
283	    sameIP = this.addr.equals(sockAddr.addr);
284	else if (this.hostname != null)
285	    sameIP = (sockAddr.addr == null) &&
286		this.hostname.equals(sockAddr.hostname);
287	else
288	    sameIP = (sockAddr.addr == null) && (sockAddr.hostname == null);
289	return sameIP && (this.port == sockAddr.port);
290    }
291
292    /**
293     * Returns a hashcode for this socket address.
294     *
295     * @return  a hash code value for this socket address.
296     */
297    public final int hashCode() {
298	if (addr != null)
299	    return addr.hashCode() + port;
300	if (hostname != null)
301	    return hostname.hashCode() + port;
302	return port;
303    }
304}