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 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 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 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 an 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 long	getLastModified(URL url) Returns the last modified timestamp of the resource at the specified 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 "jar: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 absolutePath) 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	toCanonicalURL(URL baseURL, String path) Returns a canonical URL created from the specified baseURL parent URL, 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	toURL(String absolutePath) Returns an URL created from the specified string, or null if the specified string is null.
static URL	toURL(String basedir, String path) Returns an URL created from the specified basedir parent directory, and path child path.
static URL	toURL(URL baseURL, String path) Returns an URL created from the specified baseURL parent URL, and path child path.

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 be parsed into a URL.

Returns:

The new URL.

Throws:

NullPointerException - If str 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.

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.

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 "jar: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 "jar:file:", or a local Jar file with protocol "jar:file:"; otherwise false.

Throws:

NullPointerException - If url is null.

toURL

public static URL toURL(String absolutePath)
                 throws MalformedURLException

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

• 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 Paths.isAbsoluteLocalWindows(String).

Parameters:

absolutePath - The string from which to create an URL.

Returns:

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

Throws:

MalformedURLException - 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:

Paths.isAbsoluteLocalWindows(String)

toCanonicalURL

public static URL toCanonicalURL(String absolutePath)
                          throws MalformedURLException

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 Paths.isAbsoluteLocalWindows(String).

Parameters:

absolutePath - The string from which to create an 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:

MalformedURLException - 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), Paths.isAbsoluteLocalWindows(String)

toURL

public static URL toURL(String basedir,
                        String path)
                 throws MalformedURLException

Returns an URL created 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:

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

Throws:

MalformedURLException - 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:

toURL(String), Paths.newPath(String,String), Paths.isAbsoluteLocalWindows(String)

toCanonicalURL

public static URL toCanonicalURL(String basedir,
                                 String path)
                          throws MalformedURLException

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:

MalformedURLException - 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:

toURL(String), canonicalize(URL), Paths.newPath(String,String), Paths.isAbsoluteLocalWindows(String)

toURL

public static URL toURL(URL baseURL,
                        String path)
                 throws MalformedURLException

Returns an URL created from the specified baseURL parent URL, and path child path.

If the specified baseURL contains a query string, this method will throw a IllegalArgumentException.

Parameters:

baseURL - The base URL of the path in the resulting URL.

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

Returns:

An URL created from the specified baseURL parent directory, and path child path.

Throws:

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

IllegalArgumentException - If the specified baseURL contains a query string.

NullPointerException - If baseURL or path is null.

toCanonicalURL

public static URL toCanonicalURL(URL baseURL,
                                 String path)
                          throws MalformedURLException

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

If the specified baseURL contains a query string, this method will throw a IllegalArgumentException.

Parameters:

baseURL - The base URL of the path in the resulting URL.

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

Returns:

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

Throws:

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

IllegalArgumentException - If the specified baseURL contains a query string.

NullPointerException - If baseURL or path is null.

canonicalize

public static URL canonicalize(URL url)
                        throws MalformedURLException

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:

MalformedURLException - 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)

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

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 an 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:

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

getLastModified

public static long getLastModified(URL url)
                            throws IOException

Returns the last modified timestamp of the resource at the specified URL. This function works for URLs that point to local files, resources in jars, and resources behind HTTP/HTTPS connections. For all other types of URLs, this function throws IllegalArgumentException.

Parameters:

url - The URL.

Returns:

The last modified timestamp of the resource at the specified URL.

Throws:

IllegalArgumentException - If url does not specify the "file", "http", or "https" protocols.

IOException - If an I/O error has occurred.

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 is null or does not name a parent directory.

See Also:

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

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