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 String	CHARSET_URL Default URL charset is UTF-8
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

Methods

Modifier and Type	Method and Description
static String	getApplicationFormEncoded(Map<String,String> aParams, IEncoder<String> aParameterEncoder) Create a parameter string suitable for POST body (e.g. for web form submission).
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> 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 URL	getClassPathURL(String sPath, ClassLoader aClassLoader) Get the input stream of the passed resource using the specified class loader only.
static String	getCleanURLPartWithoutUmlauts(String sURLPart) Clean an URL part from nasty Umlauts.
static InputStream	getInputStream(URL aURL, int nConnectTimeoutMS, int nReadTimeoutMS, INonThrowingRunnableWithParameter<URLConnection> aConnectionModifier, IMutableWrapper<IOException> aExceptionHolder) Get an input stream from the specified URL.
static Map<String,String>	getQueryStringAsMap(String sQueryString)
static String	getURLString(IURLData aURL, Charset aParameterCharset)
static String	getURLString(String sPath, Map<String,String> aParams, String sAnchor, Charset aParameterCharset) Get the final representation of the URL using the specified elements.
static String	getURLString(String sPath, Map<String,String> aParams, String sAnchor, IEncoder<String> aParameterEncoder) Get the final representation of the URL using the specified elements.
static boolean	isClassPathURLExisting(String sPath)
static boolean	isClassPathURLExisting(String sPath, ClassLoader aClassLoader)
static InputStream	postAndGetInputStream(URL aURL, int nConnectTimeoutMS, int nReadTimeoutMS, IMimeType aContentType, byte[] aContentBytes, Map<String,String> aAdditionalHTTPHeaders, INonThrowingRunnableWithParameter<URLConnection> aConnectionModifier, IMutableWrapper<IOException> aExceptionHolder) Deprecated. Use Apache http client or the like for a much better handling
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	urlDecode(String sValue, String sCharset) 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.
static String	urlEncode(String sValue, String sCharset) 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

public static final String CHARSET_URL

Default URL charset is UTF-8

See Also:

Constant Field Values

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.

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.

Parameters:

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

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

Returns:

The decoded value.

urlDecode

@Nonnull
public static String urlDecode(@Nonnull
                       String sValue,
                       @Nonnull@Nonempty
                       String sCharset)

URL-decode the passed value automatically handling charset issues.

Parameters:

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

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

Returns:

The decoded value.

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.

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.

Parameters:

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

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

Returns:

The encoded value.

urlEncode

@Nonnull
public static String urlEncode(@Nonnull
                       String sValue,
                       @Nonnull@Nonempty
                       String sCharset)

URL-encode the passed value automatically handling charset issues.

Parameters:

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

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

getQueryStringAsMap

@Nonnull
@ReturnsMutableCopy
public static Map<String,String> getQueryStringAsMap(@Nullable
                                                                String sQueryString)

getURLString

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

getURLString

@Nullable
public static String getURLString(@Nullable
                           String sPath,
                           @Nullable
                           Map<String,String> aParams,
                           @Nullable
                           String sAnchor,
                           @Nullable
                           IEncoder<String> aParameterEncoder)

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

Parameters:

sPath - The main path. May be null.

aParams - The set of parameters to be appended. May be null.

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

aParameterEncoder - 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
                           Map<String,String> aParams,
                           @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.

aParams - The set 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
                                  INonThrowingRunnableWithParameter<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.

postAndGetInputStream

@Nullable
@Deprecated
public static InputStream postAndGetInputStream(@Nonnull
                                                    URL aURL,
                                                    int nConnectTimeoutMS,
                                                    int nReadTimeoutMS,
                                                    @Nullable
                                                    IMimeType aContentType,
                                                    @Nonnull
                                                    byte[] aContentBytes,
                                                    @Nullable
                                                    Map<String,String> aAdditionalHTTPHeaders,
                                                    @Nullable
                                                    INonThrowingRunnableWithParameter<URLConnection> aConnectionModifier,
                                                    @Nullable
                                                    IMutableWrapper<IOException> aExceptionHolder)

Deprecated. Use Apache http client or the like for a much better handling

POST something to a URL.

Parameters:

aURL - The destination URL. May not be null.

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

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

aContentType - The MIME type to be send as the Content-Type header. May be null.

aContentBytes - The main content to be send via POST. May not be null but maybe empty. The Content-Length HTTP header is automatically filled with the specified byte length.

aAdditionalHTTPHeaders - An optional map of HTTP headers to be send. This map should not contain the Content-Type and the Content-Length headers. May be null.

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.

getApplicationFormEncoded

@Nonnull
public static String getApplicationFormEncoded(@Nullable
                                       Map<String,String> aParams,
                                       @Nullable
                                       IEncoder<String> aParameterEncoder)

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

Parameters:

aParams - Parameter map. May be null or empty.

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

Returns:

A non-null string

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.

getClassPathURL

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

Get the input stream of the passed resource using the specified class loader only.

Parameters:

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

aClassLoader - The class loader to be used. May not be null.

Returns:

null if the path could not be resolved using the specified class loader.

isClassPathURLExisting

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

isClassPathURLExisting

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