com.helger.commons.url

Class URLHelper

java.lang.Object

com.helger.commons.url.URLHelper

@ThreadSafe
public final class URLHelper
extends Object

URL utilities.

Author:

Philip Helger

Field Summary

Fields

Modifier and Type	Field and Description
static char	AMPERSAND Separator between params: &
static String	AMPERSAND_STR
static Charset	CHARSET_URL_OBJ Default URL charset is UTF-8
static char	EQUALS Separator between param name and param value: =
static String	EQUALS_STR
static char	HASH Separator between URL path and anchor name: #
static String	HASH_STR
static String	PROTOCOL_FILE The protocol for file resources
static char	QUESTIONMARK Separator before first param: ?
static String	QUESTIONMARK_STR

Method Summary

Modifier and Type	Method and Description
static File	getAsFile(URL aURL)
static File	getAsFileOrNull(URL aURL)
static URI	getAsURI(String sURI) Get the passed String as an URI.
static URI	getAsURI(URL aURL) Get the passed URL as an URI.
static URL	getAsURL(String sURL) Get the passed String as an URL.
static URL	getAsURL(URI aURI) Get the passed URI as an URL.
static IURLData	getAsURLData(String sHref)
static IURLData	getAsURLData(String sHref, IDecoder<String,String> aParameterDecoder) Parses the passed URL into a structured form
static URL	getClassPathURL(String sPath) Get the URL for the specified path using automatic class loader handling.
static String	getCleanURLPartWithoutUmlauts(String sURLPart) Clean an URL part from nasty Umlauts.
static InputStream	getInputStream(URL aURL, int nConnectTimeoutMS, int nReadTimeoutMS, Consumer<URLConnection> aConnectionModifier, IMutableWrapper<IOException> aExceptionHolder) Get an input stream from the specified URL.
static URLParameterList	getParsedQueryParameters(String sQueryString)
static URLParameterList	getParsedQueryParameters(String sQueryString, IDecoder<String,String> aParameterDecoder)
static String	getQueryParametersAsString(List<URLParameter> aQueryParams, IEncoder<String,String> aQueryParameterEncoder) Create a parameter string.
static String	getURLString(IURLData aURL, Charset aParameterCharset)
static String	getURLString(String sPath, List<URLParameter> aQueryParams, String sAnchor, Charset aParameterCharset) Get the final representation of the URL using the specified elements.
static String	getURLString(String sPath, List<URLParameter> aQueryParams, String sAnchor, IEncoder<String,String> aQueryParameterEncoder) Get the final representation of the URL using the specified elements.
static String	getURLString(String sPath, String sQueryParams, String sAnchor) Get the final representation of the URL using the specified elements.
static boolean	isClassPathURLExisting(String sPath)
static boolean	isClassPathURLExisting(String sPath, ClassLoader aClassLoader)
static String	urlDecode(String sValue) URL-decode the passed value automatically handling charset issues.
static String	urlDecode(String sValue, Charset aCharset) URL-decode the passed value automatically handling charset issues.
static String	urlEncode(String sValue) URL-encode the passed value automatically handling charset issues.
static String	urlEncode(String sValue, Charset aCharset) URL-encode the passed value automatically handling charset issues.

Methods inherited from class java.lang.Object

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

Field Detail

CHARSET_URL_OBJ

public static final Charset CHARSET_URL_OBJ

Default URL charset is UTF-8

QUESTIONMARK

public static final char QUESTIONMARK

Separator before first param: ?

See Also:

Constant Field Values

QUESTIONMARK_STR

public static final String QUESTIONMARK_STR

AMPERSAND

public static final char AMPERSAND

Separator between params: &

See Also:

Constant Field Values

AMPERSAND_STR

public static final String AMPERSAND_STR

EQUALS

public static final char EQUALS

Separator between param name and param value: =

See Also:

Constant Field Values

EQUALS_STR

public static final String EQUALS_STR

HASH

public static final char HASH

Separator between URL path and anchor name: #

See Also:

Constant Field Values

HASH_STR

public static final String HASH_STR

PROTOCOL_FILE

public static final String PROTOCOL_FILE

The protocol for file resources

See Also:

Constant Field Values

Method Detail

urlDecode

@Nonnull
public static String urlDecode(@Nonnull
                                         String sValue)

URL-decode the passed value automatically handling charset issues. The used char set is determined by CHARSET_URL_OBJ.

Parameters:

sValue - The value to be decoded. May not be null.

Returns:

The decoded value.

urlDecode

@Nonnull
public static String urlDecode(@Nonnull
                                         String sValue,
                                         @Nonnull
                                         Charset aCharset)

URL-decode the passed value automatically handling charset issues. The implementation is ripped from URLDecoder but does not throw an UnsupportedEncodingException for nothing.

Parameters:

sValue - The value to be decoded. May not be null.

aCharset - The charset to use. May not be null.

Returns:

The decoded value.

See Also:

URLDecoder.decode(String, String)

urlEncode

@Nonnull
public static String urlEncode(@Nonnull
                                         String sValue)

URL-encode the passed value automatically handling charset issues. The used char set is determined by CHARSET_URL_OBJ.

Parameters:

sValue - The value to be encoded. May not be null.

Returns:

The encoded value.

urlEncode

@Nonnull
public static String urlEncode(@Nonnull
                                         String sValue,
                                         @Nonnull
                                         Charset aCharset)

URL-encode the passed value automatically handling charset issues. This is a ripped, optimized version of URLEncoder.encode but without the UnsupportedEncodingException.

Parameters:

sValue - The value to be encoded. May not be null.

aCharset - The charset to use. May not be null.

Returns:

The encoded value.

getCleanURLPartWithoutUmlauts

@Nullable
public static String getCleanURLPartWithoutUmlauts(@Nullable
                                                              String sURLPart)

Clean an URL part from nasty Umlauts. This mapping needs extension!

Parameters:

sURLPart - The original URL part. May be null.

Returns:

The cleaned version or null if the input was null.

getAsURLData

@Nonnull
public static IURLData getAsURLData(@Nonnull
                                              String sHref)

getAsURLData

@Nonnull
public static IURLData getAsURLData(@Nonnull
                                              String sHref,
                                              @Nullable
                                              IDecoder<String,String> aParameterDecoder)

Parses the passed URL into a structured form

Parameters:

sHref - The URL to be parsed

aParameterDecoder - The parameter decoder to use. May be null.

Returns:

the corresponding IURLData representation of the passed URL

getParsedQueryParameters

@Nonnull
 @ReturnsMutableCopy
public static URLParameterList getParsedQueryParameters(@Nullable
                                                                                        String sQueryString,
                                                                                        @Nullable
                                                                                        IDecoder<String,String> aParameterDecoder)

getParsedQueryParameters

@Nonnull
 @ReturnsMutableCopy
public static URLParameterList getParsedQueryParameters(@Nullable
                                                                                        String sQueryString)

getURLString

@Nullable
public static String getURLString(@Nullable
                                             String sPath,
                                             @Nullable
                                             String sQueryParams,
                                             @Nullable
                                             String sAnchor)

Get the final representation of the URL using the specified elements.

Parameters:

sPath - The main path. May be null.

sQueryParams - The set of all query parameters already concatenated with the correct characters (& and =). May be null.

sAnchor - An optional anchor to be added. May be null.

Returns:

May be null if path, anchor and parameters are null.

getQueryParametersAsString

@Nullable
public static String getQueryParametersAsString(@Nullable
                                                           List<URLParameter> aQueryParams,
                                                           @Nullable
                                                           IEncoder<String,String> aQueryParameterEncoder)

Create a parameter string. This is also suitable for POST body (e.g. for web form submission).

Parameters:

aQueryParams - Parameter map. May be null or empty.

aQueryParameterEncoder - The encoder to be used to encode parameter names and parameter values. May be null. This may be e.g. a URLParameterEncoder.

Returns:

null if no parameter is present.

getURLString

@Nonnull
public static String getURLString(@Nonnull
                                            IURLData aURL,
                                            @Nullable
                                            Charset aParameterCharset)

getURLString

@Nullable
public static String getURLString(@Nullable
                                             String sPath,
                                             @Nullable
                                             List<URLParameter> aQueryParams,
                                             @Nullable
                                             String sAnchor,
                                             @Nullable
                                             IEncoder<String,String> aQueryParameterEncoder)

Get the final representation of the URL using the specified elements.

Parameters:

sPath - The main path. May be null.

aQueryParams - The list of query parameters to be appended. May be null .

sAnchor - An optional anchor to be added. May be null.

aQueryParameterEncoder - The parameters encoding to be used. May be null.

Returns:

May be null if path, anchor and parameters are null.

getURLString

@Nullable
public static String getURLString(@Nullable
                                             String sPath,
                                             @Nullable
                                             List<URLParameter> aQueryParams,
                                             @Nullable
                                             String sAnchor,
                                             @Nullable
                                             Charset aParameterCharset)

Get the final representation of the URL using the specified elements.

Parameters:

sPath - The main path. May be null.

aQueryParams - The list of parameters to be appended. May be null.

sAnchor - An optional anchor to be added. May be null.

aParameterCharset - If not null the parameters are encoded using this charset.

Returns:

May be null if all parameters are null.

getAsURL

@Nullable
public static URL getAsURL(@Nullable
                                      String sURL)

Get the passed String as an URL. If the string is empty or not an URL null is returned.

Parameters:

sURL - Source URL. May be null.

Returns:

null if the passed URL is empty or invalid.

getAsURL

@Nullable
public static URL getAsURL(@Nullable
                                      URI aURI)

Get the passed URI as an URL. If the URI is null or cannot be converted to an URL null is returned.

Parameters:

aURI - Source URI. May be null.

Returns:

null if the passed URI is null or cannot be converted to an URL.

getAsURI

@Nullable
public static URI getAsURI(@Nullable
                                      String sURI)

Get the passed String as an URI. If the string is empty or not an URI null is returned.

Parameters:

sURI - Source URI. May be null.

Returns:

null if the passed URI is empty or invalid.

getAsURI

@Nullable
public static URI getAsURI(@Nullable
                                      URL aURL)

Get the passed URL as an URI. If the URL is null or not an URI null is returned.

Parameters:

aURL - Source URL. May be null.

Returns:

null if the passed URL is empty or invalid.

getInputStream

@Nullable
public static InputStream getInputStream(@Nonnull
                                                    URL aURL,
                                                    @CheckForSigned
                                                    int nConnectTimeoutMS,
                                                    @CheckForSigned
                                                    int nReadTimeoutMS,
                                                    @Nullable
                                                    Consumer<URLConnection> aConnectionModifier,
                                                    @Nullable
                                                    IMutableWrapper<IOException> aExceptionHolder)

Get an input stream from the specified URL. By default caching is disabled. This method only handles GET requests - POST requests are not possible.

Parameters:

aURL - The URL to use. May not be null.

nConnectTimeoutMS - Connect timeout milliseconds. 0 == infinite. < 0: ignored.

nReadTimeoutMS - Read timeout milliseconds. 0 == infinite. < 0: ignored.

aConnectionModifier - An optional callback object to modify the URLConnection before it is opened.

aExceptionHolder - An optional exception holder for further outside investigation.

Returns:

null if the input stream could not be opened.

getAsFile

@Nonnull
public static File getAsFile(@Nonnull
                                       URL aURL)

getAsFileOrNull

@Nullable
public static File getAsFileOrNull(@Nonnull
                                              URL aURL)

getClassPathURL

@Nullable
public static URL getClassPathURL(@Nonnull @Nonempty
                                             String sPath)

Get the URL for the specified path using automatic class loader handling. The class loaders are iterated in the following order:

1. Default class loader (usually the context class loader)
2. The class loader of this class
3. The system class loader

Parameters:

sPath - The path to be resolved. May neither be null nor empty.

Returns:

null if the path could not be resolved.

isClassPathURLExisting

public static boolean isClassPathURLExisting(@Nonnull @Nonempty
                                             String sPath)

isClassPathURLExisting

public static boolean isClassPathURLExisting(@Nonnull @Nonempty
                                             String sPath,
                                             @Nonnull
                                             ClassLoader aClassLoader)