URL - Android SDK

Summary: Ctors | Methods | Protected Methods | Inherited Methods | [Expand All]

Added in API level 1

public final class

URL

extends Object
implements Serializable

java.lang.Object
↳	java.net.URL

Class Overview

A Uniform Resource Locator that identifies the location of an Internet resource as specified by RFC 1738.

Parts of a URL

A URL is composed of many parts. This class can both parse URL strings into parts and compose URL strings from parts. For example, consider the parts of this URL: http://username:password@host:8080/directory/file?query#ref:

Component	Example value	Also known as
`Protocol`	`http`	scheme
`Authority`	`username:password@host:8080`
`User Info`	`username:password`
`Host`	`host`
`Port`	`8080`
`File`	`/directory/file?query`
`Path`	`/directory/file`
`Query`	`query`
`Ref`	`ref`	fragment

Supported Protocols

This class may be used to construct URLs with the following protocols:

file: read files from the local filesystem.
ftp: File Transfer Protocol
http: Hypertext Transfer Protocol
https: HTTP over TLS
jar: read Jar files from the filesystem

In general, attempts to create URLs with any other protocol will fail with a MalformedURLException. Applications may install handlers for other schemes using setURLStreamHandlerFactory(URLStreamHandlerFactory) or with the java.protocol.handler.pkgs system property.

The URI class can be used to manipulate URLs of any protocol.

Summary

Public Constructors
	URL(String spec) Creates a new URL instance by parsing `spec`.
	URL(URL context, String spec) Creates a new URL by resolving `spec` relative to `context`.
	URL(URL context, String spec, URLStreamHandler handler) Creates a new URL by resolving `spec` relative to `context`.
	URL(String protocol, String host, String file) Creates a new URL of the given component parts.
	URL(String protocol, String host, int port, String file) Creates a new URL of the given component parts.
	URL(String protocol, String host, int port, String file, URLStreamHandler handler) Creates a new URL of the given component parts.

Public Methods
boolean	equals(Object o) Returns true if this URL equals `o`.
String	getAuthority() Returns the authority part of this URL, or null if this URL has no authority.
final Object	getContent(Class[] types) Equivalent to `openConnection().getContent(types)`.
final Object	getContent() Returns the content of the resource which is referred by this URL.
int	getDefaultPort() Returns the default port number of the protocol used by this URL.
String	getFile() Returns the file of this URL.
String	getHost() Returns the host name or IP address of this URL.
String	getPath() Returns the path part of this URL.
int	getPort() Returns the port number of this URL or `-1` if this URL has no explicit port.
String	getProtocol() Returns the protocol of this URL like "http" or "file".
String	getQuery() Returns the query part of this URL, or null if this URL has no query.
String	getRef() Returns the value of the reference part of this URL, or null if this URL has no reference part.
String	getUserInfo() Returns the user info of this URL, or null if this URL has no user info.
int	hashCode() Returns an integer hash code for this object.
URLConnection	openConnection(Proxy proxy) Returns a new connection to the resource referred to by this URL.
URLConnection	openConnection() Returns a new connection to the resource referred to by this URL.
final InputStream	openStream() Equivalent to `openConnection().getInputStream(types)`.
boolean	sameFile(URL otherURL) Returns true if this URL refers to the same resource as `otherURL`.
synchronized static void	setURLStreamHandlerFactory(URLStreamHandlerFactory factory) Sets the stream handler factory for this VM.
String	toExternalForm() Returns a string containing a concise, human-readable representation of this URL.
String	toString() Returns a string containing a concise, human-readable representation of this URL.
URI	toURI() Returns the URI equivalent to this URL.

Protected Methods
void	set(String protocol, String host, int port, String authority, String userInfo, String path, String query, String ref) Sets the properties of this URL using the provided arguments.
void	set(String protocol, String host, int port, String file, String ref) Sets the properties of this URL using the provided arguments.

[Expand]

Inherited Methods

From class java.lang.Object

Object	clone() Creates and returns a copy of this `Object`.
boolean	equals(Object o) Compares this instance with the specified object and indicates if they are equal.
void	finalize() Invoked when the garbage collector has detected that this instance is no longer reachable.
final Class<?>	getClass() Returns the unique instance of `Class` that represents this object's class.
int	hashCode() Returns an integer hash code for this object.
final void	notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up.
final void	notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up.
String	toString() Returns a string containing a concise, human-readable description of this object.
final void	wait() Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object.
final void	wait(long millis, int nanos) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires.
final void	wait(long millis) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires.

Public Constructors

public URL (String spec)

Added in API level 1

Creates a new URL instance by parsing spec.

Throws

MalformedURLException	if `spec` could not be parsed as a URL.

public URL (URL context, String spec)

Added in API level 1

Creates a new URL by resolving spec relative to context.

Parameters

context	the URL to which `spec` is relative, or null for no context in which case `spec` must be an absolute URL.

Throws

MalformedURLException	if `spec` could not be parsed as a URL or has an unsupported protocol.

public URL (URL context, String spec, URLStreamHandler handler)

Added in API level 1

Creates a new URL by resolving spec relative to context.

Parameters

context	the URL to which `spec` is relative, or null for no context in which case `spec` must be an absolute URL.
handler	the stream handler for this URL, or null for the protocol's default stream handler.

Throws

MalformedURLException	if the given string `spec` could not be parsed as a URL or an invalid protocol has been found.

public URL (String protocol, String host, String file)

Added in API level 1

Creates a new URL of the given component parts. The URL uses the protocol's default port.

Throws

MalformedURLException	if the combination of all arguments do not represent a valid URL or if the protocol is invalid.

public URL (String protocol, String host, int port, String file)

Added in API level 1

Creates a new URL of the given component parts. The URL uses the protocol's default port.

Parameters

host	the host name or IP address of the new URL.
port	the port, or `-1` for the protocol's default port.
file	the name of the resource.

Throws

MalformedURLException	if the combination of all arguments do not represent a valid URL or if the protocol is invalid.

public URL (String protocol, String host, int port, String file, URLStreamHandler handler)

Added in API level 1

Creates a new URL of the given component parts. The URL uses the protocol's default port.

Parameters

host	the host name or IP address of the new URL.
port	the port, or `-1` for the protocol's default port.
file	the name of the resource.
handler	the stream handler for this URL, or null for the protocol's default stream handler.

Throws

MalformedURLException	if the combination of all arguments do not represent a valid URL or if the protocol is invalid.

Public Methods

public boolean equals (Object o)

Added in API level 1

Returns true if this URL equals o. URLs are equal if they have the same protocol, host, port, file, and reference.

Network I/O Warning

Some implementations of URL.equals() resolve host names over the network. This is problematic:

The network may be slow. Many classes, including core collections like Map and Set expect that equals and hashCode will return quickly. By violating this assumption, this method posed potential performance problems.
Equal IP addresses do not imply equal content. Virtual hosting permits unrelated sites to share an IP address. This method could report two otherwise unrelated URLs to be equal because they're hosted on the same server.
The network may not be available. Two URLs could be equal when a network is available and unequal otherwise.
The network may change. The IP address for a given host name varies by network and over time. This is problematic for mobile devices. Two URLs could be equal on some networks and unequal on others.

This problem is fixed in Android 4.0 (Ice Cream Sandwich). In that release, URLs are only equal if their host names are equal (ignoring case).

Parameters

o	the object to compare this instance with.

Returns

true if the specified object is equal to this Object; false otherwise.

public String getAuthority ()

Added in API level 1

Returns the authority part of this URL, or null if this URL has no authority.

public final Object getContent (Class[] types)

Added in API level 1

Equivalent to openConnection().getContent(types).

Throws

IOException

public final Object getContent ()

Added in API level 1

Returns the content of the resource which is referred by this URL. By default this returns an InputStream, or null if the content type of the response is unknown.

Throws

IOException

public int getDefaultPort ()

Added in API level 1

Returns the default port number of the protocol used by this URL. If no default port is defined by the protocol or the URLStreamHandler, -1 will be returned.

public String getFile ()

Added in API level 1

Returns the file of this URL.

public String getHost ()

Added in API level 1

Returns the host name or IP address of this URL.

public String getPath ()

Added in API level 1

Returns the path part of this URL.

public int getPort ()

Added in API level 1

Returns the port number of this URL or -1 if this URL has no explicit port.

If this URL has no explicit port, connections opened using this URL will use its default port.

public String getProtocol ()

Added in API level 1

Returns the protocol of this URL like "http" or "file". This is also known as the scheme. The returned string is lower case.

public String getQuery ()

Added in API level 1

Returns the query part of this URL, or null if this URL has no query.

public String getRef ()

Added in API level 1

Returns the value of the reference part of this URL, or null if this URL has no reference part. This is also known as the fragment.

public String getUserInfo ()

Added in API level 1

Returns the user info of this URL, or null if this URL has no user info.

public int hashCode ()

Added in API level 1

Returns an integer hash code for this object. By contract, any two objects for which equals(Object) returns true must return the same hash code value. This means that subclasses of Object usually override both methods or neither method.

Note that hash values must not change over time unless information used in equals comparisons also changes.

See Writing a correct hashCode method if you intend implementing your own hashCode method.

Returns

this object's hash code.

public URLConnection openConnection (Proxy proxy)

Added in API level 1

Returns a new connection to the resource referred to by this URL.

Parameters

proxy	the proxy through which the connection will be established.

Throws

IOException	if an I/O error occurs while opening the connection.
IllegalArgumentException	if the argument proxy is null or of is an invalid type.
UnsupportedOperationException	if the protocol handler does not support opening connections through proxies.

public URLConnection openConnection ()

Added in API level 1

Returns a new connection to the resource referred to by this URL.

Throws

IOException	if an error occurs while opening the connection.

public final InputStream openStream ()

Added in API level 1

Equivalent to openConnection().getInputStream(types).

Throws

IOException

public boolean sameFile (URL otherURL)

Added in API level 1

Returns true if this URL refers to the same resource as otherURL. All URL components except the reference field are compared.

public static synchronized void setURLStreamHandlerFactory (URLStreamHandlerFactory factory)

Added in API level 1

Sets the stream handler factory for this VM.

Throws

Error	if a URLStreamHandlerFactory has already been installed for the current VM.

public String toExternalForm ()

Added in API level 1

Returns a string containing a concise, human-readable representation of this URL.

public String toString ()

Added in API level 1

Returns a string containing a concise, human-readable representation of this URL. The returned string is the same as the result of the method toExternalForm().

Returns

a printable representation of this object.

public URI toURI ()

Added in API level 1

Returns the URI equivalent to this URL.

Throws

URISyntaxException	if this URL cannot be converted into a URI.

Protected Methods

protected void set (String protocol, String host, int port, String authority, String userInfo, String path, String query, String ref)

Added in API level 1

Sets the properties of this URL using the provided arguments. Only a URLStreamHandler can use this method to set fields of the existing URL instance. A URL is generally constant.

protected void set (String protocol, String host, int port, String file, String ref)

Added in API level 1

Sets the properties of this URL using the provided arguments. Only a URLStreamHandler can use this method to set fields of the existing URL instance. A URL is generally constant.

Results

Interfaces

Classes

Enums

Exceptions

URL

Class Overview

Parts of a URL

Supported Protocols

Summary

Public Constructors

public URL (String spec)

Throws

public URL (URL context, String spec)

Parameters

Throws

public URL (URL context, String spec, URLStreamHandler handler)

Parameters

Throws

public URL (String protocol, String host, String file)

Throws

public URL (String protocol, String host, int port, String file)

Parameters

Throws

public URL (String protocol, String host, int port, String file, URLStreamHandler handler)

Parameters

Throws

Public Methods

public boolean equals (Object o)

Network I/O Warning

Parameters

Returns

public String getAuthority ()

public final Object getContent (Class[] types)

Throws

public final Object getContent ()

Throws

public int getDefaultPort ()

See Also

public String getFile ()

public String getHost ()

public String getPath ()

public int getPort ()

public String getProtocol ()

public String getQuery ()

public String getRef ()

public String getUserInfo ()

public int hashCode ()

Returns

public URLConnection openConnection (Proxy proxy)

Parameters

Throws

public URLConnection openConnection ()

Throws

public final InputStream openStream ()

Throws

public boolean sameFile (URL otherURL)

public static synchronized void setURLStreamHandlerFactory (URLStreamHandlerFactory factory)

Throws

public String toExternalForm ()

public String toString ()

Returns

public URI toURI ()

Throws

Protected Methods

protected void set (String protocol, String host, int port, String authority, String userInfo, String path, String query, String ref)

protected void set (String protocol, String host, int port, String file, String ref)