com.phloc.commons.url

Class URLUtils

java.lang.Object

com.phloc.commons.url.URLUtils

@Immutable
public final class URLUtils
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 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 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 String	getCleanURLPartWithoutUmlauts(String sURLPart) Clean an URL part from nasty Umlauts.
static InputStream	getInputStream(URL aURL, int nConnectTimeoutMS, int nReadTimeoutMS, INonThrowingRunnableWithParameter<URLConnection> aConnectionModifier, IWrapper<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(IURLData aURL, String sParameterCharset) Deprecated.
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 String	getURLString(String sPath, Map<String,String> aParams, String sAnchor, String sParameterCharset) Deprecated.
static InputStream	postAndGetInputStream(URL aURL, int nConnectTimeoutMS, int nReadTimeoutMS, IMimeType aContentType, byte[] aContentBytes, Map<String,String> aAdditionalHTTPHeaders, INonThrowingRunnableWithParameter<URLConnection> aConnectionModifier, IWrapper<IOException> aExceptionHolder) POST something to a URL.
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

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,
                            @Nonnull
                            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 not 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
@Deprecated
public static String getURLString(@Nonnull
                                     IURLData aURL,
                                     @Nullable
                                     String sParameterCharset)

Deprecated.

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,
                           @Nonnull
                           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 not be null.

Returns:

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

getURLString

@Nullable
@Deprecated
public static String getURLString(@Nullable
                                      String sPath,
                                      @Nullable
                                      Map<String,String> aParams,
                                      @Nullable
                                      String sAnchor,
                                      @Nullable
                                      String sParameterCharset)

Deprecated.

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.

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

Returns:

May be null if all 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,
                                  int nConnectTimeoutMS,
                                  int nReadTimeoutMS,
                                  @Nullable
                                  INonThrowingRunnableWithParameter<URLConnection> aConnectionModifier,
                                  @Nullable
                                  IWrapper<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
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
                                         IWrapper<IOException> aExceptionHolder)

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,
                                       @Nonnull
                                       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 not be null. This may be e.g. a URLParameterEncoder.

Returns:

A non-null string