de.innovationgate.utils

Class URLBuilder

java.lang.Object

de.innovationgate.utils.URLBuilder

All Implemented Interfaces:

java.lang.Cloneable

public class URLBuilder
extends java.lang.Object
implements java.lang.Cloneable

Class for building and modifying URLs including their parameters. The URLBuilder can take an existing URL or URL parts. It offers methods to modify every part of the URL separately and can then rebuild a complete URL from it. The path and query part of the URL are decoded an read if an encoding is given to the URLBuilder constructor. All setter methods are prepared to use "method chaining", as they all return the current URLBuilder instance.

Constructor Summary

Constructors

Constructor and Description
URLBuilder(javax.servlet.http.HttpServletRequest request) Builds a URL builder taking the request URL of the given request, decoding it using UTF-8
URLBuilder(javax.servlet.http.HttpServletRequest request, java.lang.String parameterEncoding) Builds a URL builder taking the request URL of the given request
URLBuilder(java.lang.String protocol, int port, java.lang.String host, java.lang.String path, java.lang.String query) Builds a URL builder for the given URL parts
URLBuilder(java.lang.String protocol, int port, java.lang.String host, java.lang.String path, java.lang.String query, java.lang.String decode) Creates a URL Builder that takes various URL parts as parameters
URLBuilder(org.apache.commons.httpclient.URI uri) Creates a URLBuilder that parses an existing URI
URLBuilder(org.apache.commons.httpclient.URI uri, java.lang.String encoding) Creates a URLBuilder that parses an existing URI
URLBuilder(java.net.URL url) Creates a URLBuilder that parses an existing URL
URLBuilder(java.net.URL url, java.lang.String encoding) Creates a URLBuilder that parses an existing URL

Method Summary

Methods

Modifier and Type	Method and Description
URLBuilder	addQueryString(java.lang.String queryString, java.lang.String decode) Adds a complete query string to the parameters of this URLBuilder
URLBuilder	appendPath(java.lang.String pathElement) Appends a new path element to the current path This method automatically ensures that a single slash is between the current path and the new path element.
java.lang.String	build() Rebuilds the URL in relative form to a string.
java.lang.String	build(boolean absolute) Rebuilds the URL to a string.
URLBuilder	clearParameters() Clears all url parameters
static java.lang.Integer	getDefaultPortForProtocol(java.lang.String protocol) Returns the default port for the given URL protocol
java.lang.String	getEncoding() Returns the encoding by which the URL will be encoded when building it using build() and variants.
java.lang.String	getHost() Returns the host part
java.lang.String	getParameter(java.lang.String param) Returns a URL parameter value
java.lang.String	getParameterEncoding() Deprecated. Use getEncoding() instead. Encoding is now also used for other URL components.
java.util.Set<java.lang.String>	getParameterNames() Returns the names of URL parameters
java.lang.String	getPath() Returns the path part
int	getPort() Returns the TCP port for this URL
java.lang.String	getProtocol() Gets the protocol
java.lang.String	getQuery() Returns the query part
boolean	hasParameter(java.lang.String param) Tests for existence of a URL parameter
static boolean	isDefaultPortForProtocol(int port, java.lang.String protocol) Tests if the given port is the default port for the given protocol.
java.net.URL	rebuild() Deprecated. Because of inconsistent return type. Use build(boolean) instead or use implicit string conversion
java.lang.String	rebuild(boolean absolute) Deprecated. Because of inconsistent return type. Use build(boolean) instead or use implicit string conversion
URLBuilder	removeParameter(java.lang.String param) Removes a parameter
URLBuilder	setEncoding(java.lang.String encoding) Sets the encoding used to encode the URL on building it using build() and variants.
URLBuilder	setHost(java.lang.String host) Sets the host
URLBuilder	setParameter(java.lang.String param, java.lang.String value) Createds/modifies a parameter
URLBuilder	setParameterEncoding(java.lang.String parameterEncoding) Deprecated. Use setEncoding(String) instead. Encoding is now also used for other URL components.
URLBuilder	setPath(java.lang.String file) Sets the path part
URLBuilder	setPort(int port) Sets the TCP port for this URL
URLBuilder	setProtocol(java.lang.String protocol) Sets the protocol
URLBuilder	setQuery(java.lang.String query) Deprecated. Modify the query via methods setParameter(String, String) and removeParameter(String)
java.lang.String	toString()

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

URLBuilder

public URLBuilder(java.net.URL url)

Creates a URLBuilder that parses an existing URL

Parameters:

url - The URL to parse

URLBuilder

public URLBuilder(java.net.URL url,
          java.lang.String encoding)

Creates a URLBuilder that parses an existing URL

Parameters:

url - The URL to parse

encoding - The encoding of URL parameters. The URLBuilder will decode them.

URLBuilder

public URLBuilder(org.apache.commons.httpclient.URI uri)
           throws org.apache.commons.httpclient.URIException

Creates a URLBuilder that parses an existing URI

Parameters:

uri - The URI to parse

Throws:

org.apache.commons.httpclient.URIException

URLBuilder

public URLBuilder(org.apache.commons.httpclient.URI uri,
          java.lang.String encoding)
           throws org.apache.commons.httpclient.URIException

Creates a URLBuilder that parses an existing URI

Parameters:

uri - The URI to parse

encoding - The encoding of URL parameters. The URLBuilder will decode them.

Throws:

org.apache.commons.httpclient.URIException

URLBuilder

public URLBuilder(java.lang.String protocol,
          int port,
          java.lang.String host,
          java.lang.String path,
          java.lang.String query,
          java.lang.String decode)

Creates a URL Builder that takes various URL parts as parameters

Parameters:

protocol - The protocol URL part

port - The port URL part

host - The host URL part

path - The path URL part. May be left null.

query - The query string URL part. May be left null.

decode - The encoding by which the URL parts will be decoded. Specify null for no decoding.

URLBuilder

public URLBuilder(java.lang.String protocol,
          int port,
          java.lang.String host,
          java.lang.String path,
          java.lang.String query)

Builds a URL builder for the given URL parts

Parameters:

protocol -

port -

host -

path -

query -

URLBuilder

public URLBuilder(javax.servlet.http.HttpServletRequest request,
          java.lang.String parameterEncoding)
           throws java.net.MalformedURLException

Builds a URL builder taking the request URL of the given request

Parameters:

request - The request

parameterEncoding - The encoding to use in decoding the URL

Throws:

java.net.MalformedURLException

URLBuilder

public URLBuilder(javax.servlet.http.HttpServletRequest request)
           throws java.net.MalformedURLException

Builds a URL builder taking the request URL of the given request, decoding it using UTF-8

Parameters:

request - The request

Throws:

java.net.MalformedURLException

Method Detail

isDefaultPortForProtocol

public static boolean isDefaultPortForProtocol(int port,
                               java.lang.String protocol)

Tests if the given port is the default port for the given protocol. This is true if browsers implicitly assume the given port for an URL with the given protocol and do not need it explicitly in the URL.

Parameters:

port - Tested port

protocol - Tested protocol

Returns:

true if it is the default port

getDefaultPortForProtocol

public static java.lang.Integer getDefaultPortForProtocol(java.lang.String protocol)

Returns the default port for the given URL protocol

Parameters:

protocol - The URL protocol

Returns:

The default port

addQueryString

public URLBuilder addQueryString(java.lang.String queryString,
                        java.lang.String decode)

Adds a complete query string to the parameters of this URLBuilder

Parameters:

queryString - The query string

decode - The encoding by which parameters should get decoded. Use null for no decoding.

getQuery

public java.lang.String getQuery()

Returns the query part

setQuery

public URLBuilder setQuery(java.lang.String query)

Deprecated. Modify the query via methods setParameter(String, String) and removeParameter(String)

Sets the query part. You should not use this since the query is rebuilt from its parsed parameters. Manipulating the query here will not be reflected when rebuilding the URL.

Parameters:

query - The query to set

getPath

public java.lang.String getPath()

Returns the path part

setPath

public URLBuilder setPath(java.lang.String file)

Sets the path part

Parameters:

file - The file to set

Throws:

org.apache.commons.httpclient.URIException

appendPath

public URLBuilder appendPath(java.lang.String pathElement)

Appends a new path element to the current path This method automatically ensures that a single slash is between the current path and the new path element.

Parameters:

pathElement -

getHost

public java.lang.String getHost()

Returns the host part

setHost

public URLBuilder setHost(java.lang.String host)

Sets the host

Parameters:

host - The host to set

getProtocol

public java.lang.String getProtocol()

Gets the protocol

setProtocol

public URLBuilder setProtocol(java.lang.String protocol)

Sets the protocol

Parameters:

protocol - The protocol to set

rebuild

public java.lang.String rebuild(boolean absolute)

Deprecated. Because of inconsistent return type. Use build(boolean) instead or use implicit string conversion

Rebuilds the URL to a string.

Parameters:

absolute - Specify true for an absolute URL. false will rebuild it only from the path part on, omitting protocol, port and hos.

Returns:

The rebuilt URL as string

build

public java.lang.String build(boolean absolute)

Rebuilds the URL to a string.

Parameters:

absolute - Specify true for an absolute URL. false will rebuild it only from the path part on, omitting protocol, port and host.

Returns:

The rebuilt URL as string

build

public java.lang.String build()

Rebuilds the URL in relative form to a string.

Returns:

The rebuilt URL as string

rebuild

public java.net.URL rebuild()
                     throws java.net.MalformedURLException

Deprecated. Because of inconsistent return type. Use build(boolean) instead or use implicit string conversion

Rebuilds the absolute URL to an URL object,

Throws:

java.net.MalformedURLException

getParameter

public java.lang.String getParameter(java.lang.String param)

Returns a URL parameter value

Parameters:

param - The parameter name

Returns:

The parameter value

hasParameter

public boolean hasParameter(java.lang.String param)

Tests for existence of a URL parameter

Parameters:

param - The parameter name

Returns:

true, if the parameter is defined

removeParameter

public URLBuilder removeParameter(java.lang.String param)

Removes a parameter

Parameters:

param - The parameter name

setParameter

public URLBuilder setParameter(java.lang.String param,
                      java.lang.String value)

Createds/modifies a parameter

Parameters:

param - The parameter name

value - The parameter value

getParameterEncoding

public java.lang.String getParameterEncoding()

Deprecated. Use getEncoding() instead. Encoding is now also used for other URL components.

Returns the encoding used to encode URL parameters. null (default) means no encoding.

setParameterEncoding

public URLBuilder setParameterEncoding(java.lang.String parameterEncoding)

Deprecated. Use setEncoding(String) instead. Encoding is now also used for other URL components.

Sets the encoding used to encode URL parameters. The default is null = no encoding

Parameters:

parameterEncoding - The parameterEncoding to set.

clearParameters

public URLBuilder clearParameters()

Clears all url parameters

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

getPort

public int getPort()

Returns the TCP port for this URL

setPort

public URLBuilder setPort(int port)

Sets the TCP port for this URL

getParameterNames

public java.util.Set<java.lang.String> getParameterNames()

Returns the names of URL parameters

getEncoding

public java.lang.String getEncoding()

Returns the encoding by which the URL will be encoded when building it using build() and variants. Is initialized with the encoding by which the given URL was decoded, if one was given to the URLBuilder constructor that was used.

setEncoding

public URLBuilder setEncoding(java.lang.String encoding)

Sets the encoding used to encode the URL on building it using build() and variants.

Parameters:

encoding - The encoding to set.