public final class

URL

extends Object
implements Serializable
java.lang.Object
   ↳ java.net.URL

Class Overview

A URL instance specifies the location of a resource on the internet as specified by RFC 1738. Such a resource can be a simple file or a service which generates the output dynamically. A URL is divided in its parts protocol, host name, port, path, file, user-info, query, reference and authority. However, not each of this parts has to be defined.

Summary

Public Constructors
URL(String spec)
Creates a new URL instance by parsing the string spec.
URL(URL context, String spec)
Creates a new URL to the specified resource spec.
URL(URL context, String spec, URLStreamHandler handler)
Creates a new URL to the specified resource spec.
URL(String protocol, String host, String file)
Creates a new URL instance using the given arguments.
URL(String protocol, String host, int port, String file)
Creates a new URL instance using the given arguments.
URL(String protocol, String host, int port, String file, URLStreamHandler handler)
Creates a new URL instance using the given arguments.
Public Methods
boolean equals(Object o)
Compares this URL instance with the given argument o and determines if both are equal.
String getAuthority()
Gets the value of the authority part of this URL.
final Object getContent(Class[] types)
Gets the content of the resource which is referred by this URL.
final Object getContent()
Gets the content of the resource which is referred by this URL.
int getDefaultPort()
Gets the default port number of the protocol used by this URL.
String getFile()
Gets the value of the file part of this URL.
String getHost()
Gets the value of the host part of this URL.
String getPath()
Gets the value of the path part of this URL.
int getPort()
Gets the port number of this URL or -1 if the port is not set.
String getProtocol()
Gets the protocol of this URL.
String getQuery()
Gets the value of the query part of this URL.
String getRef()
Gets the value of the reference part of this URL.
String getUserInfo()
Gets the value of the user-info part of this URL.
int hashCode()
Gets the hashcode value of this URL instance.
URLConnection openConnection(Proxy proxy)
Opens a connection to the remote resource specified by this URL.
URLConnection openConnection()
Opens a connection to the remote resource specified by this URL.
final InputStream openStream()
Opens an InputStream to read the resource referred by this URL.
boolean sameFile(URL otherURL)
Returns whether this URL refers to the same resource as the given argument otherURL.
synchronized static void setURLStreamHandlerFactory(URLStreamHandlerFactory streamFactory)
Sets the URLStreamHandlerFactory which creates protocol specific stream handlers.
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()
Converts this URL instance into an equivalent URI object.
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

Public Constructors

public URL (String spec)

Since: API Level 1

Creates a new URL instance by parsing the string spec.

Parameters
spec the URL string representation which has to be parsed.
Throws
MalformedURLException if the given string spec could not be parsed as a URL.

public URL (URL context, String spec)

Since: API Level 1

Creates a new URL to the specified resource spec. This URL is relative to the given context. If the protocol of the parsed URL does not match with the protocol of the context URL, then the newly created URL is absolute and bases only on the given URL represented by spec. Otherwise the protocol is defined by the context URL.

Parameters
context the URL which is used as the context.
spec the URL string representation which has to be parsed.
Throws
MalformedURLException if the given string spec could not be parsed as a URL or an invalid protocol has been found.

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

Since: API Level 1

Creates a new URL to the specified resource spec. This URL is relative to the given context. The handler will be used to parse the URL string representation. If this argument is null the default URLStreamHandler will be used. If the protocol of the parsed URL does not match with the protocol of the context URL, then the newly created URL is absolute and bases only on the given URL represented by spec. Otherwise the protocol is defined by the context URL.

Parameters
context the URL which is used as the context.
spec the URL string representation which has to be parsed.
handler the specific stream handler to be used by this URL.
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)

Since: API Level 1

Creates a new URL instance using the given arguments. The URL uses the default port for the specified protocol.

Parameters
protocol the protocol of the new URL.
host the host name or IP address of the new URL.
file the name of the resource.
Throws
MalformedURLException if the combination of all arguments do not represent a valid URL or the protocol is invalid.

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

Since: API Level 1

Creates a new URL instance using the given arguments. The URL uses the specified port instead of the default port for the given protocol.

Parameters
protocol the protocol of the new URL.
host the host name or IP address of the new URL.
port the specific port number of the URL. -1 represents the default port of the protocol.
file the name of the resource.
Throws
MalformedURLException if the combination of all arguments do not represent a valid URL or the protocol is invalid.

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

Since: API Level 1

Creates a new URL instance using the given arguments. The URL uses the specified port instead of the default port for the given protocol.

Parameters
protocol the protocol of the new URL.
host the host name or IP address of the new URL.
port the specific port number of the URL. -1 represents the default port of the protocol.
file the name of the resource.
handler the stream handler to be used by this URL.
Throws
MalformedURLException if the combination of all arguments do not represent a valid URL or the protocol is invalid.
SecurityException if handler is non-null, and a security manager is installed that disallows user-defined protocol handlers.

Public Methods

public boolean equals (Object o)

Since: API Level 1

Compares this URL instance with the given argument o and determines if both are equal. Two URL instances are equal if all single parts are identical in their meaning. Compares the argument to the receiver, and returns true if they represent the same URL. Two URLs are equal if they have the same file, host, port, protocol, and reference components.

Parameters
o the URL this instance has to be compared with.
Returns
  • true if both instances represents the same URL, false otherwise.
See Also

public String getAuthority ()

Since: API Level 1

Gets the value of the authority part of this URL.

Returns
  • the authority part of this URL.

public final Object getContent (Class[] types)

Since: API Level 1

Gets the content of the resource which is referred by this URL. The argument types is an array of allowed or expected object types. null will be returned if the obtained object type does not match with one from this list. Otherwise the first type that matches will be used.

Parameters
types the list of allowed or expected object types.
Returns
  • the object representing the resource referred by this URL, null if the content does not match to a specified content type.
Throws
IOException if an error occurs obtaining the content.

public final Object getContent ()

Since: API Level 1

Gets the content of the resource which is referred by this URL. By default one of the following object types will be returned:

  • Image for pictures
  • AudioClip for audio sequences
  • InputStream for all other data

    • Returns
    • the content of the referred resource.
    Throws
    IOException if an error occurs obtaining the content.

    public int getDefaultPort ()

    Since: API Level 1

    Gets 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.

    Returns
    • the default port number according to the protocol of this URL.
    See Also

    public String getFile ()

    Since: API Level 1

    Gets the value of the file part of this URL.

    Returns
    • the file name this URL refers to or an empty string if the file part is not set.

    public String getHost ()

    Since: API Level 1

    Gets the value of the host part of this URL.

    Returns
    • the host name or IP address of this URL.

    public String getPath ()

    Since: API Level 1

    Gets the value of the path part of this URL.

    Returns
    • the path part of this URL.

    public int getPort ()

    Since: API Level 1

    Gets the port number of this URL or -1 if the port is not set.

    Returns
    • the port number of this URL.

    public String getProtocol ()

    Since: API Level 1

    Gets the protocol of this URL.

    Returns
    • the protocol type of this URL.

    public String getQuery ()

    Since: API Level 1

    Gets the value of the query part of this URL.

    Returns
    • the query part of this URL.

    public String getRef ()

    Since: API Level 1

    Gets the value of the reference part of this URL.

    Returns
    • the reference part of this URL.

    public String getUserInfo ()

    Since: API Level 1

    Gets the value of the user-info part of this URL.

    Returns
    • the user-info part of this URL.

    public int hashCode ()

    Since: API Level 1

    Gets the hashcode value of this URL instance.

    Returns
    • the appropriate hashcode value.

    public URLConnection openConnection (Proxy proxy)

    Since: API Level 1

    Opens a connection to the remote resource specified by this URL. The connection will be established through the given proxy and allows bidirectional data transfer.

    Parameters
    proxy the proxy through which the connection will be established.
    Returns
    • the appropriate URLConnection instance representing the connection to this URL.
    Throws
    IOException if an I/O error occurs while opening the connection.
    SecurityException if a security manager is installed and it denies to connect to the proxy.
    IllegalArgumentException if the argument proxy is null or is an invalid type.
    UnsupportedOperationException if the protocol handler does not support opening connections through proxies.

    public URLConnection openConnection ()

    Since: API Level 1

    Opens a connection to the remote resource specified by this URL. This connection allows bidirectional data transfer.

    Returns
    • the connection to this URL.
    Throws
    IOException if an error occurs while opening the connection.

    public final InputStream openStream ()

    Since: API Level 1

    Opens an InputStream to read the resource referred by this URL.

    Returns
    • the stream which allows to read the resource.
    Throws
    IOException if an error occurs while opening the InputStream.

    public boolean sameFile (URL otherURL)

    Since: API Level 1

    Returns whether this URL refers to the same resource as the given argument otherURL. All URL components except the reference field are compared.

    Parameters
    otherURL the URL to compare against.
    Returns
    • true if both instances refer to the same resource, false otherwise.

    public static synchronized void setURLStreamHandlerFactory (URLStreamHandlerFactory streamFactory)

    Since: API Level 1

    Sets the URLStreamHandlerFactory which creates protocol specific stream handlers. This method can be invoked only once during an application's lifetime. If the URLStreamHandlerFactory is already set an Error will be thrown.

    A security check is performed to verify whether the current policy allows to set the stream handler factory.

    Parameters
    streamFactory the factory to be used for creating stream protocol handlers.

    public String toExternalForm ()

    Since: API Level 1

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

    Returns
    • the string representation of this URL.

    public String toString ()

    Since: 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
    • the string representation of this URL.

    public URI toURI ()

    Since: API Level 1

    Converts this URL instance into an equivalent URI object.

    Returns
    • the URI instance that represents 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)

    Since: 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.

    Parameters
    protocol the protocol to be set.
    host the host name to be set.
    port the port number to be set.
    authority the authority to be set.
    userInfo the user-info to be set.
    path the path to be set.
    query the query to be set.
    ref the reference to be set.

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

    Since: 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.

    Parameters
    protocol the protocol to be set.
    host the host name to be set.
    port the port number to be set.
    file the file to be set.
    ref the reference to be set.