org.libj.net

Class URLs

java.lang.Object

org.libj.net.URLs

public final class URLs
extends Object

Utility functions for operations pertaining to URL.

Field Summary

Fields

Modifier and Type	Field and Description
static String	REGEX A regular expression pattern that matches URL strings.

Method Summary

Modifier and Type	Method and Description
static URL	canonicalize(URL url) Returns the canonical version of the specified URL, where redundant names such as "." and ".." are dereferenced and removed from the path.
static URL	create(String str) Creates a URL by parsing the given string.
static URL	create(String basedir, String path) Creates a URL from the specified basedir parent directory, and path child path.
static URL	create(String protocol, String host, int port, String file) Creates a URL by parsing the given protocol, host, port, and file strings.
static URL	create(String protocol, String host, int port, String file, URLStreamHandler handler) Creates a URL by parsing the given protocol, host, port, and file strings.
static URL	create(String protocol, String host, String file) Creates a URL by parsing the given protocol, host, and file strings.
static URL	create(URL context, String spec) Creates a URL by parsing the given URL and spec string.
static URL	create(URL context, String spec, URLStreamHandler handler) Creates a URL by parsing the given URL and spec string.
static String	decode(String s) Decodes a application/x-www-form-urlencoded string.
static String	decode(String s, Charset charset) Decodes an application/x-www-form-urlencoded string using a specific Charset.
static String	decode(String s, String enc) Decodes an application/x-www-form-urlencoded string using a specific encoding scheme.
static String	decodePath(String path) Returns the URL-decoded path string.
static URL	disableHttp(URL url) Returns a URL with http and https protocols disabled.
static void	disableRemote() Disables all http and https access from this JVM.
static String	encode(String s) Translates a string into application/x-www-form-urlencoded format.
static String	encode(String s, Charset charset) Translates a string into application/x-www-form-urlencoded format using a specific Charset.
static String	encode(String s, String enc) Translates a string into application/x-www-form-urlencoded format using a specific encoding scheme.
static String	encodePath(String path) Returns the URL-encoded path string.
static boolean	exists(URL url) Tests whether the specified URL references a resource that exists.
static boolean	exists(URL url, int timeout) Tests whether the specified URL references a resource that exists.
static URL	fromStringPath(String stringPath) Returns a URL created from the specified string, or null if the specified string path is null.
static URL	fromURI(URI uri) Creates a URL from the specified URI.
static URL	getCanonicalParent(URL url) Returns the canonical URL representing the parent of the specified URL, or null if url is null or does not name a parent directory (".." and "." path names are dereferenced in a canonical URL)).
static String	getJarPath(URL url) Returns the path portion of the resource referenced inside a Jar of the specified url "Jar URL" (if url is "Jar URL" resembling the "jar:<url>...!..." semantics), or null if url is not a "Jar URL".
static URL	getJarURL(URL url) Returns a URL representing the location of the Jar in url, if url is "Jar URL" resembling the "jar:<url>...!..." semantics; or null if url is not a "Jar URL".
static String	getName(URL url) Returns the name of the file or directory denoted by the specified URL.
static URL	getParent(URL url) Returns the URL representing the parent of the specified URL, or null if url is null or does not name a parent directory.
static String	getShortName(URL url) Returns the short name of the file or directory denoted by the specified URL.
static boolean	isJar(URL url) Tests whether the specified URL references a Jar resource, otherwise false.
static boolean	isLocal(URL url) Tests whether the specified URL represents a location that is either a local file with protocol "file:", or a local JAR file with protocol "jar:file:".
static boolean	isLocalFile(URL url) Tests whether the specified URL represents a file path.
static boolean	isLocalJarFile(URL url) Tests whether the specified URL represents a location that is a local JAR file with protocol "jar:file:".
static URL	toCanonicalURL(String stringPath) Returns a canonical URL created from the specified string, or null if the specified string is null (".." and "." path names are dereferenced in a canonical URL, and redundant '/' path separators are removed).
static URL	toCanonicalURL(String basedir, String path) Returns a canonical URL created from the specified basedir parent directory, and path child path (".." and "." path names are dereferenced in a canonical URL, and redundant '/' path separators are removed).
static URL[]	toURL(File... files) Converts an array of File objects into an array of URL objects.
static URL	withLiteralHost(String spec) Returns a URL for which the host is treated as a literal string (as opposed to its resolved IP address, as is dereferenced by default during the URL.equals(Object) and URL.hashCode() operations).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

REGEX

public static final String REGEX

A regular expression pattern that matches URL strings.

See Also:

Constant Field Values

Method Detail

create

public static URL create(String str)

Creates a URL by parsing the given string.

This convenience factory method works as if by invoking the URL.URL(String) constructor; any MalformedURLException thrown by the constructor is caught and wrapped in a new IllegalArgumentException object, which is then thrown.

This method is provided for use in situations where it is known that the given string is a legal URL, for example for URL constants declared within in a program, and so it would be considered a programming error for the string not to parse as such. The constructors, which throw MalformedURLException directly, should be used situations where a URL is being constructed from user input or from some other source that may be prone to errors.

Parameters:

str - The string to parse.

Returns:

The new URL.

Throws:

NullPointerException - If the given string is null.

IllegalArgumentException - If the given string declares a protocol that could not be found in a specification string, or if the string could not be parsed.

create

public static URL create(URL context,
                         String spec)

Creates a URL by parsing the given URL and spec string.

This convenience factory method works as if by invoking the URL.URL(URL,String) constructor; any MalformedURLException thrown by the constructor is caught and wrapped in a new IllegalArgumentException object, which is then thrown.

This method is provided for use in situations where it is known that the given string is a legal URL, for example for URL constants declared within in a program, and so it would be considered a programming error for the string not to parse as such. The constructors, which throw MalformedURLException directly, should be used situations where a URL is being constructed from user input or from some other source that may be prone to errors.

Parameters:

context - The context in which to parse the specification.

spec - The String to parse.

Returns:

The new URL.

Throws:

NullPointerException - If spec is null.

IllegalArgumentException - If the given string declares a protocol that could not be found in a specification string, or if the string could not be parsed.

create

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

Creates a URL by parsing the given URL and spec string.

This convenience factory method works as if by invoking the URL.URL(URL,String) constructor; any MalformedURLException thrown by the constructor is caught and wrapped in a new IllegalArgumentException object, which is then thrown.

This method is provided for use in situations where it is known that the given string is a legal URL, for example for URL constants declared within in a program, and so it would be considered a programming error for the string not to parse as such. The constructors, which throw MalformedURLException directly, should be used situations where a URL is being constructed from user input or from some other source that may be prone to errors.

Parameters:

context - The context in which to parse the specification.

spec - The String to parse.

handler - The stream handler for the URL.

Returns:

The new URL.

Throws:

NullPointerException - If spec is null.

IllegalArgumentException - If the given string declares a protocol that could not be found in a specification string, or if the string could not be parsed.

create

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

Creates a URL by parsing the given protocol, host, and file strings.

This convenience factory method works as if by invoking the URL.URL(String,String,String) constructor; any MalformedURLException thrown by the constructor is caught and wrapped in a new IllegalArgumentException object, which is then thrown.

This method is provided for use in situations where it is known that the given string is a legal URL, for example for URL constants declared within in a program, and so it would be considered a programming error for the string not to parse as such. The constructors, which throw MalformedURLException directly, should be used situations where a URL is being constructed from user input or from some other source that may be prone to errors.

Parameters:

protocol - The name of the protocol to use.

host - The name of the host.

file - The file on the host.

Returns:

The new URL.

Throws:

NullPointerException - If file is null.

IllegalArgumentException - If the given string declares a protocol that could not be found in a specification string, or if the string could not be parsed.

create

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

Creates a URL by parsing the given protocol, host, port, and file strings.

This convenience factory method works as if by invoking the URL.URL(String,String,String) constructor; any MalformedURLException thrown by the constructor is caught and wrapped in a new IllegalArgumentException object, which is then thrown.

This method is provided for use in situations where it is known that the given string is a legal URL, for example for URL constants declared within in a program, and so it would be considered a programming error for the string not to parse as such. The constructors, which throw MalformedURLException directly, should be used situations where a URL is being constructed from user input or from some other source that may be prone to errors.

Parameters:

protocol - The name of the protocol to use.

host - The name of the host.

port - The port number on the host.

file - The file on the host.

Returns:

The new URL.

Throws:

NullPointerException - If file is null.

IllegalArgumentException - If the given string declares a protocol that could not be found in a specification string, or if the string could not be parsed.

create

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

Creates a URL by parsing the given protocol, host, port, and file strings.

This convenience factory method works as if by invoking the URL.URL(String,String,String) constructor; any MalformedURLException thrown by the constructor is caught and wrapped in a new IllegalArgumentException object, which is then thrown.

This method is provided for use in situations where it is known that the given string is a legal URL, for example for URL constants declared within in a program, and so it would be considered a programming error for the string not to parse as such. The constructors, which throw MalformedURLException directly, should be used situations where a URL is being constructed from user input or from some other source that may be prone to errors.

Parameters:

protocol - The name of the protocol to use.

host - The name of the host.

port - The port number on the host.

file - The file on the host.

handler - The stream handler for the URL.

Returns:

The new URL.

Throws:

NullPointerException - If file is null.

IllegalArgumentException - If the given string declares a protocol that could not be found in a specification string, or if the string could not be parsed.

create

public static URL create(String basedir,
                         String path)

Creates a URL from the specified basedir parent directory, and path child path.

Parameters:

basedir - The base directory of the path in the resulting URL.

path - The child path off of basedir in the resulting URL.

Returns:

A URL created from the specified basedir parent directory, and path child path.

Throws:

IllegalArgumentException - If a protocol is specified but is unknown, or the spec is null, or the parsed URL fails to comply with the specific syntax of the associated protocol.

NullPointerException - If basedir or path is null.

See Also:

fromStringPath(String), StringPaths.newPath(String,String), StringPaths.isAbsoluteLocalWindows(String)

fromStringPath

public static URL fromStringPath(String stringPath)

Returns a URL created from the specified string, or null if the specified string path is null.

• If the specified string path contains the string ":/", the resulting URL is created with URL.URL(String).
• Otherwise, if the specified path does not have a leading '/', then it is prepended to the path.

This method assumes the specified string path is an absolute path, and detects Windows paths using StringPaths.isAbsoluteLocalWindows(String).

Parameters:

stringPath - The string path from which to create a URL.

Returns:

A URL created from the specified string, or null if the specified string is null.

Throws:

IllegalArgumentException - If a protocol is specified but is unknown, or the spec is null, or the parsed URL fails to comply with the specific syntax of the associated protocol.

See Also:

StringPaths.isAbsoluteLocalWindows(String)

fromURI

public static URL fromURI(URI uri)

Creates a URL from the specified URI.

This convenience method works as if invoking it were equivalent to evaluating the expression new URL(uri.toString()) after first checking that this URI is absolute.

Parameters:

uri - The URI to convert to a URL.

Returns:

The new URL.

Throws:

IllegalArgumentException - If this URL is not absolute.

UncheckedIOException - If a protocol handler for the URL could not be found, or if some other error occurred while constructing the URL.

NullPointerException - If the specified uri is null.

toCanonicalURL

public static URL toCanonicalURL(String stringPath)

Returns a canonical URL created from the specified string, or null if the specified string is null (".." and "." path names are dereferenced in a canonical URL, and redundant '/' path separators are removed).

• If the specified path contains the string ":/", the resulting URL is created with URL.URL(String).
• Otherwise, if the specified path does not have a leading '/', then it is prepended to the path.

This method assumes the specified string is an absolute path, and detects Windows paths using StringPaths.isAbsoluteLocalWindows(String).

Parameters:

stringPath - The string from which to create a URL.

Returns:

A canonical URL created from the specified string, or null if the specified string is null (".." and "." path names are dereferenced in a canonical URL, and redundant '/' path separators are removed).

Throws:

IllegalArgumentException - If a protocol is specified but is unknown, or the spec is null, or the parsed URL fails to comply with the specific syntax of the associated protocol.

See Also:

canonicalize(URL), StringPaths.isAbsoluteLocalWindows(String)

toCanonicalURL

public static URL toCanonicalURL(String basedir,
                                 String path)

Returns a canonical URL created from the specified basedir parent directory, and path child path (".." and "." path names are dereferenced in a canonical URL, and redundant '/' path separators are removed).

Parameters:

basedir - The base directory of the path in the resulting URL.

path - The child path off of basedir in the resulting URL.

Returns:

A canonical URL created from the specified basedir parent directory, and path child path (".." and "." path names are dereferenced in a canonical URL, and redundant '/' path separators are removed).

Throws:

IllegalArgumentException - If a protocol is specified but is unknown, or the spec is null, or the parsed URL fails to comply with the specific syntax of the associated protocol.

NullPointerException - If basedir or path is null.

See Also:

fromStringPath(String), canonicalize(URL), StringPaths.newPath(String,String), StringPaths.isAbsoluteLocalWindows(String)

toURL

public static URL[] toURL(File... files)

Converts an array of File objects into an array of URL objects. File objects that are null will be null in the resulting URL[] array.

Parameters:

files - The array of File objects.

Returns:

An array of URL objects.

Throws:

IllegalArgumentException - If a protocol handler for the URL could not be found, or if some other error occurred while constructing the URL.

NullPointerException - If files is null.

canonicalize

public static URL canonicalize(URL url)

Returns the canonical version of the specified URL, where redundant names such as "." and ".." are dereferenced and removed from the path.

Parameters:

url - The URL.

Returns:

The canonical version of the specified URL, where redundant names such as "." and ".." are dereferenced and removed from the path.

Throws:

IllegalArgumentException - If a protocol is specified but is unknown, or the spec is null, or the parsed URL fails to comply with the specific syntax of the associated protocol.

exists

public static boolean exists(URL url,
                             int timeout)

Tests whether the specified URL references a resource that exists.

This method performs the following tests to check for the existence of the resource at the specified URL:

1. If the protocol of the specified URL is "file", this method converts the URL to a File and delegates to File.exists().
2. Otherwise, the method attempts to open a connection to the resource with the specified connection timeout. If the connection is successful, the method returns true, and otherwise false.

Parameters:

url - The URL to test.

timeout - The timeout to be used when attempting to open a connection to the url.

Returns:

true if the specified URL references a resource that exists; otherwise false.

Throws:

NullPointerException - If url is null.

IllegalArgumentException - If timeout is negative.

exists

public static boolean exists(URL url)

Tests whether the specified URL references a resource that exists.

This method performs the following tests to check for the existence of the resource at the specified URL:

1. If the protocol of the specified URL is "file", this method converts the URL to a File and delegates to File.exists().
2. Otherwise, the method attempts to open a connection to the resource with the DEFAULT_TIMEOUT. If the connection is successful, the method returns true, and otherwise false.

Parameters:

url - The URL to test.

Returns:

true if the specified URL references a resource that exists; otherwise false.

Throws:

NullPointerException - If url is null.

isLocalFile

public static boolean isLocalFile(URL url)

Tests whether the specified URL represents a file path. An URL is considered a file if its protocol is "file" (case-insensitive), and its host value is empty or equal to "localhost".

Parameters:

url - The URL.

Returns:

true if the specified URL represents a file path; otherwise false.

Throws:

NullPointerException - If url is null.

isLocalJarFile

public static boolean isLocalJarFile(URL url)

Tests whether the specified URL represents a location that is a local JAR file with protocol "jar:file:".

The compound protocol definition is unwrapped in order to determine if the root resource locator in the URL is local. This method then uses isLocalFile(URL) to check whether url is local.

Parameters:

url - The URL to test.

Returns:

true if the specified URL represents a location that is local; otherwise false.

Throws:

NullPointerException - If url is null.

isLocal

public static boolean isLocal(URL url)

Tests whether the specified URL represents a location that is either a local file with protocol "file:", or a local JAR file with protocol "jar:file:".

URLs with compound protocol definitions, such as "jar:file:" are first unwrapped in order to digest the root resource locator in the URL. This method then uses isLocalFile(URL) to check whether url is local.

Parameters:

url - The URL to test.

Returns:

true if the specified URL represents a location that is either a local file with protocol "file:", or a local JAR file with protocol "jar:file:"; otherwise false.

Throws:

NullPointerException - If url is null.

isJar

public static boolean isJar(URL url)

Tests whether the specified URL references a Jar resource, otherwise false.

Parameters:

url - The URL to test.

Returns:

true if the specified URL references a Jar resource; otherwise false.

Throws:

NullPointerException - If url is null.

getJarURL

public static URL getJarURL(URL url)

Returns a URL representing the location of the Jar in url, if url is "Jar URL" resembling the "jar:<url>...!..." semantics; or null if url is not a "Jar URL".

Parameters:

url - The URL.

Returns:

A URL representing the location of the Jar in url, if url is "Jar URL" resembling the "jar:<url>...!..." semantics; or null if url is not a "Jar URL".

Throws:

NullPointerException - If url is null.

getJarPath

public static String getJarPath(URL url)

Returns the path portion of the resource referenced inside a Jar of the specified url "Jar URL" (if url is "Jar URL" resembling the "jar:<url>...!..." semantics), or null if url is not a "Jar URL".

Parameters:

url - The URL.

Returns:

The path portion of the resource referenced inside a Jar of the specified url "Jar URL" (if url is "Jar URL" resembling the "jar:<url>...!..." semantics), or null if url is not a "Jar URL".

Throws:

NullPointerException - If url is null.

getName

public static String getName(URL url)

Returns the name of the file or directory denoted by the specified URL. This is just the last name in the name sequence of url. If the name sequence of url is empty, then the empty string is returned.

Parameters:

url - The URL.

Returns:

The name of the file or directory denoted by the specified URL, or the empty string if the name sequence of url is empty.

Throws:

NullPointerException - If url is null.

getShortName

public static String getShortName(URL url)

Returns the short name of the file or directory denoted by the specified URL. This is just the last name in the name sequence of url, with its dot-extension removed if present. If the name sequence of url is empty, then the empty string is returned.

Parameters:

url - The URL.

Returns:

The short name of the file or directory denoted by the specified URL, or the empty string if the name sequence of url is empty.

Throws:

NullPointerException - If url is null.

getParent

public static URL getParent(URL url)

Returns the URL representing the parent of the specified URL, or null if url is null or does not name a parent directory.

Parameters:

url - The URL.

Returns:

The URL representing the parent of the specified URL, or null if url does not name a parent directory.

Throws:

NullPointerException - If url is null.

See Also:

StringPaths.getParent(String)

getCanonicalParent

public static URL getCanonicalParent(URL url)

Returns the canonical URL representing the parent of the specified URL, or null if url is null or does not name a parent directory (".." and "." path names are dereferenced in a canonical URL)).

Parameters:

url - The URL.

Returns:

The URL representing the parent of the specified URL, or null if url is null or does not name a parent directory (".." and "." path names are dereferenced in a canonical URL, and redundant '/' path separators are removed).

See Also:

StringPaths.getParent(String)

encode

public static String encode(String s)

Translates a string into application/x-www-form-urlencoded format. This method uses UTF-8 as the character encoding.

Parameters:

s - String to be translated.

Returns:

The translated String.

encode

public static String encode(String s,
                            String enc)

Translates a string into application/x-www-form-urlencoded format using a specific encoding scheme.

This method behaves the same as URLEncoder.encode(String,String) except that, instead of throwing a UnsupportedEncodingException if the named encoding is not supported, this method will instead will instead throw a UnsupportedOperationException.

This method is intended purely to remove the need to catch the UnsupportedEncodingException if using URLEncoder.encode(String,String) directly.

Parameters:

s - String to be translated.

enc - The name of a supported character encoding.

Returns:

The translated String.

Throws:

UnsupportedOperationException - If the named encoding is not supported.

NullPointerException - If s or enc is null.

See Also:

decode(String,String)

encode

public static String encode(String s,
                            Charset charset)

Translates a string into application/x-www-form-urlencoded format using a specific Charset. This method uses the supplied charset to obtain the bytes for unsafe characters.

Note: The World Wide Web Consortium Recommendation states that UTF-8 should be used. Not doing so may introduce incompatibilities.

This method is intended purely to remove the need to catch the UnsupportedEncodingException if using URLEncoder.encode(String,String) directly.

Parameters:

s - String to be translated.

charset - The given Charset.

Returns:

The translated String.

Throws:

UnsupportedOperationException - If the named encoding is not supported.

NullPointerException - If s or charset is null.

See Also:

decode(String,Charset)

decode

public static String decode(String s)

Decodes a application/x-www-form-urlencoded string. This method uses UTF-8 as the character encoding.

Parameters:

s - The String to decode.

Returns:

The decoded String.

Throws:

IllegalArgumentException - If the implementation encounters illegal path separators.

NullPointerException - If s is null.

decode

public static String decode(String s,
                            Charset charset)

Decodes an application/x-www-form-urlencoded string using a specific Charset. The supplied charset is used to determine what characters are represented by any consecutive sequences of the form "%xy".

Note: The World Wide Web Consortium Recommendation states that UTF-8 should be used. Not doing so may introduce incompatibilities.

Parameters:

s - The String to decode.

charset - The given Charset.

Returns:

The decoded String.

Throws:

NullPointerException - If s or charset is null.

IllegalArgumentException - If the implementation encounters illegal characters.

See Also:

encode(String,Charset)

decode

public static String decode(String s,
                            String enc)

Decodes an application/x-www-form-urlencoded string using a specific encoding scheme.

This method behaves the same as decode(String,Charset) except that it will look up the charset using the given encoding name.

Parameters:

s - The String to decode.

enc - The name of a supported encoding.

Returns:

The decoded String.

Throws:

NullPointerException - If s or charset is null.

IllegalArgumentException - If the implementation encounters illegal characters, or if the given charset name is null.

IllegalCharsetNameException - If the given charset name is illegal.

UnsupportedCharsetException - If no support for the named charset is available in this instance of the Java virtual machine.

See Also:

encode(String,String)

encodePath

public static String encodePath(String path)

Returns the URL-encoded path string.

URL path segments may contain '+' symbols which should not be decoded into ' '. This method delegates to URLEncoder, then replaces '+' with "%20".

Parameters:

path - The path to decode.

Returns:

The URL-decoded path string.

decodePath

public static String decodePath(String path)

Returns the URL-decoded path string.

URL path segments may contain '+' symbols which should not be decoded into ' '. This method replaces '+' with "%2B" and delegates to URLDecoder.

Parameters:

path - The path to decode.

Returns:

The URL-decoded path string.

disableHttp

public static URL disableHttp(URL url)

Returns a URL with http and https protocols disabled.

If the specified URL is of a protocol that is http or https, a new URL is returned with the URL.openConnection() and URL.openConnection(Proxy) methods disabled (i.e. they will throw FileNotFoundException when the InputStream.read() or OutputStream.write(int) methods are invoked); otherwise the specified URL is returned unmodified.

Parameters:

url - The URL for which http and https protocols are to be disabled.

Returns:

A URL with http and https protocols disabled.

Throws:

NullPointerException - If the specified url is null.

disableRemote

public static void disableRemote()

Disables all http and https access from this JVM.

Note: Once called, this cannot be undone.

withLiteralHost

public static URL withLiteralHost(String spec)

Returns a URL for which the host is treated as a literal string (as opposed to its resolved IP address, as is dereferenced by default during the URL.equals(Object) and URL.hashCode() operations).

Parameters:

spec - The String to parse as a URL.

Returns:

A URL for which the host is treated as a literal string.

Throws:

IllegalArgumentException - If no protocol is specified, or an unknown protocol is found, or spec is null, or the parsed URL fails to comply with the specific syntax of the associated protocol.

SecurityException - If a security manager exists and its checkPermission method doesn't allow specifying a stream handler.