Module org.refcodes.web

Package org.refcodes.web

Class Url

java.lang.Object

org.refcodes.web.Url

All Implemented Interfaces:

org.refcodes.mixin.CredentialsAccessor, org.refcodes.mixin.Dumpable, org.refcodes.mixin.IdentityAccessor, org.refcodes.mixin.PathAccessor, org.refcodes.mixin.PortAccessor, org.refcodes.mixin.SecretAccessor, org.refcodes.net.IpAddressAccessor, FragmentAccessor, HostAccessor, QueryFieldsAccessor, SchemeAccessor

Direct Known Subclasses:

UrlBuilder

public class Url
extends Object
implements org.refcodes.mixin.Dumpable, SchemeAccessor, HostAccessor, org.refcodes.net.IpAddressAccessor, org.refcodes.mixin.PortAccessor, org.refcodes.mixin.PathAccessor, QueryFieldsAccessor, FragmentAccessor, org.refcodes.mixin.CredentialsAccessor

The Url class represents an immutable URL: An URL looks something like this: "scheme://[identity[:secret]@]host[:port][/path][?query][#fragment] In contrast to the java.net URL, this URL also supports "relative" locators with neither a scheme nor a host declaration. If the relative locator starts with a "/" slash, then we assume not having a host being provided: "/path?query#fragment" When it does *not* start with a "/" slash, then we assume that the first element being the host: "[identity[:secret]@]host[:port]/path[?query][#fragment]"

Nested Class Summary

Nested classes/interfaces inherited from interface org.refcodes.mixin.CredentialsAccessor

org.refcodes.mixin.CredentialsAccessor.CredentialsBuilder<B extends org.refcodes.mixin.CredentialsAccessor.CredentialsBuilder<B>>, org.refcodes.mixin.CredentialsAccessor.CredentialsMutator, org.refcodes.mixin.CredentialsAccessor.CredentialsProperty

Nested classes/interfaces inherited from interface org.refcodes.web.FragmentAccessor

FragmentAccessor.FragmentBuilder<B extends FragmentAccessor.FragmentBuilder<?>>, FragmentAccessor.FragmentMutator, FragmentAccessor.FragmentProperty

Nested classes/interfaces inherited from interface org.refcodes.web.HostAccessor

HostAccessor.HostBuilder<B extends HostAccessor.HostBuilder<?>>, HostAccessor.HostMutator, HostAccessor.HostProperty

Nested classes/interfaces inherited from interface org.refcodes.mixin.IdentityAccessor

org.refcodes.mixin.IdentityAccessor.IdentityBuilder<B extends org.refcodes.mixin.IdentityAccessor.IdentityBuilder<B>>, org.refcodes.mixin.IdentityAccessor.IdentityMutator, org.refcodes.mixin.IdentityAccessor.IdentityProperty

Nested classes/interfaces inherited from interface org.refcodes.net.IpAddressAccessor

org.refcodes.net.IpAddressAccessor.IpAddressBuilder<B extends org.refcodes.net.IpAddressAccessor.IpAddressBuilder<B>>, org.refcodes.net.IpAddressAccessor.IpAddressMutator, org.refcodes.net.IpAddressAccessor.IpAddressProperty

Nested classes/interfaces inherited from interface org.refcodes.mixin.PathAccessor

org.refcodes.mixin.PathAccessor.PathBuilder<B extends org.refcodes.mixin.PathAccessor.PathBuilder<?>>, org.refcodes.mixin.PathAccessor.PathMutator, org.refcodes.mixin.PathAccessor.PathProperty

Nested classes/interfaces inherited from interface org.refcodes.mixin.PortAccessor

org.refcodes.mixin.PortAccessor.PortBuilder<B extends org.refcodes.mixin.PortAccessor.PortBuilder<B>>, org.refcodes.mixin.PortAccessor.PortMutator, org.refcodes.mixin.PortAccessor.PortProperty

Nested classes/interfaces inherited from interface org.refcodes.web.QueryFieldsAccessor

QueryFieldsAccessor.QueryFieldsBuilder<B extends QueryFieldsAccessor.QueryFieldsBuilder<?>>, QueryFieldsAccessor.QueryFieldsMutator, QueryFieldsAccessor.QueryFieldsProperty

Nested classes/interfaces inherited from interface org.refcodes.web.SchemeAccessor

SchemeAccessor.SchemeBuilder<B extends SchemeAccessor.SchemeBuilder<B>>, SchemeAccessor.SchemeMutator, SchemeAccessor.SchemeProperty

Nested classes/interfaces inherited from interface org.refcodes.mixin.SecretAccessor

org.refcodes.mixin.SecretAccessor.SecretBuilder<B extends org.refcodes.mixin.SecretAccessor.SecretBuilder<B>>, org.refcodes.mixin.SecretAccessor.SecretMutator, org.refcodes.mixin.SecretAccessor.SecretProperty

Field Summary

Fields

Modifier and Type	Field	Description
protected String	_fragment
protected String	_host
protected String	_identity
protected int[]	_ipAddress
protected String	_path
protected int	_port
protected String	_protocol
protected FormFields	_queryFields
protected org.refcodes.data.Scheme	_scheme
protected String	_secret

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	Url()	Default constructor.
	Url(String aUrl)	Constructs an Url from the provided URL String.
	Url(String aProtocol, String aHost)	Constructs an Url with the common attributes.
	Url(String aProtocol, String aHost, int aPort)	Constructs an Url with the common attributes.
	Url(String aProtocol, String aHost, int aPort, String aPath)	Constructs an Url with the common attributes.
	Url(String aProtocol, String aHost, int aPort, String aPath, FormFields aQueryFields)	Constructs an Url with the common attributes.
	Url(String aProtocol, String aHost, int aPort, String aPath, FormFields aQueryFields, String aFragment)	Constructs an Url with the common attributes.
	Url(String aProtocol, String aHost, String aPath)	Constructs an Url with the common attributes.
	Url(String aProtocol, String aHost, String aPath, FormFields aQueryFields)	Constructs an Url with the common attributes.
	Url(String aProtocol, String aHost, String aPath, FormFields aQueryFields, String aFragment)	Constructs an Url with the common attributes.
	Url(String aUrl, FormFields aQueryFields)	Constructs an Url from the provided URL String.
	Url(String aUrl, FormFields aQueryFields, String aFragment)	Constructs an Url from the provided URL String.
	Url(URL aURL)	Constructs an Url from the provided URL instance.
	Url(org.refcodes.data.Scheme aScheme, String aHost)	Constructs an Url with the common attributes.
	Url(org.refcodes.data.Scheme aScheme, String aHost, int aPort)	Constructs an Url with the common attributes.
	Url(org.refcodes.data.Scheme aScheme, String aHost, int aPort, String aPath)	Constructs an Url with the common attributes.
	Url(org.refcodes.data.Scheme aScheme, String aHost, int aPort, String aPath, FormFields aQueryFields)	Constructs an Url with the common attributes.
	Url(org.refcodes.data.Scheme aScheme, String aHost, int aPort, String aPath, FormFields aQueryFields, String aFragment)	Constructs an Url with the common attributes.
	Url(org.refcodes.data.Scheme aScheme, String aHost, String aPath)	Constructs an Url with the common attributes.
	Url(org.refcodes.data.Scheme aScheme, String aHost, String aPath, FormFields aQueryFields)	Constructs an Url with the common attributes.
	Url(org.refcodes.data.Scheme aScheme, String aHost, String aPath, FormFields aQueryFields, String aFragment)	Constructs an Url with the common attributes.
	Url(Url aUrl)	Creates an Url from the provided Url.
	Url(Url aUrl, String... aPaths)	Some Url algebra: Adds the provided path to the given Url by prepending it to the Url's path.
	Url(Url aUrl, Url aOtherUrl)	Constructs a new Url from the given Url instances by adding the other Url's data to the first Url's data.

Method Summary

Modifier and Type	Method	Description
protected void	fromUrl(String aUrl)	Uses the given String to set the Url's state.
protected void	fromURL(URL aUrl)
String	getFragment()	Retrieves the fragment from the fragment property.
String	getHost()	Retrieves the host from the host property.
String	getIdentity()
int[]	getIpAddress()
String	getPath()
int	getPort()
FormFields	getQueryFields()	Retrieves the request Query-Fields from the request Query-Fields property.
org.refcodes.data.Scheme	getScheme()	Retrieves the UrlScheme from the URL scheme.
String	getSecret()
protected void	setHost(String aHost)
protected void	setIpAddress(int[] aIpAddress)
protected void	setPath(String aPath)
protected void	setPort(int aPort)
protected void	setProtocol(String aProtocol)
protected void	setScheme(org.refcodes.data.Scheme aScheme)
String	toHost()	Returns the "host" depending on whether an IP-Address has been provided or a host name.
String	toHttpUrl()	Creates the complete "HTTP" URL String from the Url instance's state.
String	toLocator()	Creates the locator part from the Url instance's state, excluding the fragment or the query fields.
String	toProtocol()	Retrieves the protocol representation from the Scheme.
String	toString()
protected static String	toTruncatePath(String aPath)	Removes any leading and trailing path delimiters (as of Delimiter.PATH).
protected static String	toTruncatePathPrefix(String aPath)	Removes any leading path delimiters (as of Delimiter.PATH).
protected static String	toTruncatePathSuffix(String aPath)	Removes any trailing path delimiters (as of Delimiter.PATH).
URL	toURL()	Constructs an URL instance from your Url's state.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.refcodes.mixin.Dumpable

toDump, toDump

Methods inherited from interface org.refcodes.net.IpAddressAccessor

toCidrNotation

Field Details

_scheme

protected org.refcodes.data.Scheme _scheme

_protocol

protected String _protocol

_host

protected String _host

_ipAddress

protected int[] _ipAddress

_path

protected String _path

_port

protected int _port

_queryFields

protected FormFields _queryFields

_identity

protected String _identity

_secret

protected String _secret

_fragment

protected String _fragment

Constructor Details

Url

protected Url()

Default constructor. Make sure to set required attributes for a valid URL.

Url

public Url(Url aUrl)

Creates an Url from the provided Url.

Parameters:

aUrl - The Url from which to construct this instance.

Url

public Url(String aUrl)
    throws MalformedURLException

Constructs an Url from the provided URL String.

Parameters:

aUrl - The URL String to be parsed. The URL consists of the scheme (protocol), the identify and the secret (optional), the host as well as an optional port and the (optional) path.

Throws:

MalformedURLException - in case the provided URL is considered being malformed.

Url

public Url(String aUrl,
 FormFields aQueryFields)
    throws MalformedURLException

Constructs an Url from the provided URL String.

Parameters:

aUrl - The URL String to be parsed. The URL consists of the scheme (protocol), the identify and the secret (optional), the host as well as an optional port and the (optional) path.

aQueryFields - The Query-Fields to be used for the HTTP Query-String.

Throws:

MalformedURLException - in case the provided URL is considered being malformed.

Url

public Url(String aUrl,
 FormFields aQueryFields,
 String aFragment)
    throws MalformedURLException

Constructs an Url from the provided URL String.

Parameters:

aUrl - The URL String to be parsed. The URL consists of the scheme (protocol), the identify and the secret (optional), the host as well as an optional port and the (optional) path.

aQueryFields - The Query-Fields to be used for the HTTP Query-String.

aFragment - The fragment to be set.

Throws:

MalformedURLException - in case the provided URL is considered being malformed.

Url

public Url(URL aURL)

Constructs an Url from the provided URL instance.

Parameters:

aURL - The URL to be used.

Url

public Url(org.refcodes.data.Scheme aScheme,
 String aHost)

Constructs an Url with the common attributes.

Parameters:

aScheme - The Scheme (e.g. HTTP or HTTPS) to be used for the destination URL.

aHost - The host to which the destination URL is to point to.

Url

public Url(org.refcodes.data.Scheme aScheme,
 String aHost,
 int aPort)

Constructs an Url with the common attributes.

Parameters:

aScheme - The Scheme (e.g. HTTP or HTTPS) to be used for the destination URL.

aHost - The host to which the destination URL is to point to.

aPort - The port to be used when connecting to the host.

Url

public Url(org.refcodes.data.Scheme aScheme,
 String aHost,
 int aPort,
 String aPath)

Constructs an Url with the common attributes.

Parameters:

aScheme - The Scheme (e.g. HTTP or HTTPS) to be used for the destination URL.

aHost - The host to which the destination URL is to point to.

aPort - The port to be used when connecting to the host.

aPath - The path on the host to which the base destination URL is to point to.

Url

public Url(org.refcodes.data.Scheme aScheme,
 String aHost,
 int aPort,
 String aPath,
 FormFields aQueryFields)

Constructs an Url with the common attributes.

Parameters:

aScheme - The Scheme (e.g. HTTP or HTTPS) to be used for the destination URL.

aHost - The host to which the destination URL is to point to.

aPort - The port to be used when connecting to the host.

aPath - The path on the host to which the base destination URL is to point to.

aQueryFields - The Query-Fields to be used for the HTTP Query-String.

Url

public Url(org.refcodes.data.Scheme aScheme,
 String aHost,
 int aPort,
 String aPath,
 FormFields aQueryFields,
 String aFragment)

Constructs an Url with the common attributes.

Parameters:

aScheme - The Scheme (e.g. HTTP or HTTPS) to be used for the destination URL.

aHost - The host to which the destination URL is to point to.

aPort - The port to be used when connecting to the host.

aPath - The path on the host to which the base destination URL is to point to.

aQueryFields - The Query-Fields to be used for the HTTP Query-String.

aFragment - The fragment to be set.

Url

public Url(String aProtocol,
 String aHost)

Constructs an Url with the common attributes.

Parameters:

aProtocol - The protocol String (e.g. "http://" or "https://") to be used for the destination URL.

aHost - The host to which the destination URL is to point to.

Url

public Url(String aProtocol,
 String aHost,
 int aPort)

Constructs an Url with the common attributes.

Parameters:

aProtocol - The protocol String (e.g. "http://" or "https://") to be used for the destination URL.

aHost - The host to which the destination URL is to point to.

aPort - The port to be used when connecting to the host.

Url

public Url(String aProtocol,
 String aHost,
 int aPort,
 String aPath)

Constructs an Url with the common attributes.

Parameters:

aProtocol - The protocol String (e.g. "http://" or "https://") to be used for the destination URL.

aHost - The host to which the destination URL is to point to.

aPort - The port to be used when connecting to the host.

aPath - The path on the host to which the base destination URL is to point to.

Url

public Url(String aProtocol,
 String aHost,
 int aPort,
 String aPath,
 FormFields aQueryFields)

Constructs an Url with the common attributes.

Parameters:

aProtocol - The protocol String (e.g. "http://" or "https://") to be used for the destination URL.

aHost - The host to which the destination URL is to point to.

aPort - The port to be used when connecting to the host.

aPath - The path on the host to which the base destination URL is to point to.

aQueryFields - The Query-Fields to be used for the HTTP Query-String.

Url

public Url(String aProtocol,
 String aHost,
 int aPort,
 String aPath,
 FormFields aQueryFields,
 String aFragment)

Constructs an Url with the common attributes.

Parameters:

aProtocol - The protocol String (e.g. "http://" or "https://") to be used for the destination URL.

aHost - The host to which the destination URL is to point to.

aPort - The port to be used when connecting to the host.

aPath - The path on the host to which the base destination URL is to point to.

aQueryFields - The Query-Fields to be used for the HTTP Query-String.

aFragment - The fragment to be set.

Url

public Url(org.refcodes.data.Scheme aScheme,
 String aHost,
 String aPath)

Constructs an Url with the common attributes.

Parameters:

aScheme - The Scheme (e.g. HTTP or HTTPS) to be used for the destination URL.

aHost - The host to which the destination URL is to point to.

aPath - The path on the host to which the base destination URL is to point to.

Url

public Url(org.refcodes.data.Scheme aScheme,
 String aHost,
 String aPath,
 FormFields aQueryFields)

Constructs an Url with the common attributes.

Parameters:

aScheme - The Scheme (e.g. HTTP or HTTPS) to be used for the destination URL.

aHost - The host to which the destination URL is to point to.

aPath - The path on the host to which the base destination URL is to point to.

aQueryFields - The Query-Fields to be used for the HTTP Query-String.

Url

public Url(org.refcodes.data.Scheme aScheme,
 String aHost,
 String aPath,
 FormFields aQueryFields,
 String aFragment)

Constructs an Url with the common attributes.

Parameters:

aScheme - The Scheme (e.g. HTTP or HTTPS) to be used for the destination URL.

aHost - The host to which the destination URL is to point to.

aPath - The path on the host to which the base destination URL is to point to.

aQueryFields - The Query-Fields to be used for the HTTP Query-String.

aFragment - The fragment to be set.

Url

public Url(String aProtocol,
 String aHost,
 String aPath)

Constructs an Url with the common attributes.

Parameters:

aProtocol - The protocol String (e.g. "http://" or "https://") to be used for the destination URL.

aHost - The host to which the destination URL is to point to.

aPath - The path on the host to which the base destination URL is to point to.

Url

public Url(String aProtocol,
 String aHost,
 String aPath,
 FormFields aQueryFields)

Constructs an Url with the common attributes.

Parameters:

aProtocol - The protocol String (e.g. "http://" or "https://") to be used for the destination URL.

aHost - The host to which the destination URL is to point to.

aPath - The path on the host to which the base destination URL is to point to.

aQueryFields - The Query-Fields to be used for the HTTP Query-String.

Url

public Url(Url aUrl,
 Url aOtherUrl)

Constructs a new Url from the given Url instances by adding the other Url's data to the first Url's data. E.g. a path from the other Url is append to the first Url's path, the query parameters are added or overwritten accordingly and so on.

Parameters:

aUrl - The Url which is to be enriched.

aOtherUrl - The Url enriching the given Url.

Url

public Url(String aProtocol,
 String aHost,
 String aPath,
 FormFields aQueryFields,
 String aFragment)

Constructs an Url with the common attributes.

Parameters:

aProtocol - The protocol String (e.g. "http://" or "https://") to be used for the destination URL.

aHost - The host to which the destination URL is to point to.

aPath - The path on the host to which the base destination URL is to point to.

aQueryFields - The Query-Fields to be used for the HTTP Query-String.

aFragment - The fragment to be set.

Url

public Url(Url aUrl,
 String... aPaths)

Some Url algebra: Adds the provided path to the given Url by prepending it to the Url's path.

Parameters:

aUrl - The Url to which to add the path.

aPaths - The paths to be added to the given Url.

Method Details

getFragment

public String getFragment()

Retrieves the fragment from the fragment property.

Specified by:

getFragment in interface FragmentAccessor

Returns:

The fragment stored by the fragment property.

getHost

public String getHost()

Retrieves the host from the host property.

Specified by:

getHost in interface HostAccessor

Returns:

The host stored by the host property.

getIdentity

public String getIdentity()

Specified by:

getIdentity in interface org.refcodes.mixin.IdentityAccessor

getIpAddress

public int[] getIpAddress()

Specified by:

getIpAddress in interface org.refcodes.net.IpAddressAccessor

getPath

public String getPath()

Specified by:

getPath in interface org.refcodes.mixin.PathAccessor

getPort

public int getPort()

Specified by:

getPort in interface org.refcodes.mixin.PortAccessor

getQueryFields

public FormFields getQueryFields()

Retrieves the request Query-Fields from the request Query-Fields property.

Specified by:

getQueryFields in interface QueryFieldsAccessor

Returns:

The request Query-Fields stored by the request Query-Fields property.

getScheme

public org.refcodes.data.Scheme getScheme()

Retrieves the UrlScheme from the URL scheme.

Specified by:

getScheme in interface SchemeAccessor

Returns:

The UrlScheme stored by the URL scheme.

getSecret

public String getSecret()

Specified by:

getSecret in interface org.refcodes.mixin.SecretAccessor

toProtocol

public String toProtocol()

Retrieves the protocol representation from the Scheme. In case of a scheme unknown by the Scheme enumeration, then SchemeAccessor.getScheme() might return null whilst SchemeAccessor.toProtocol() still retrieves the unknown scheme's protocol representation (as of SchemeAccessor.SchemeMutator.setProtocol(String)).

Specified by:

toProtocol in interface SchemeAccessor

Returns:

The protocol representation for the URL.

toHost

public String toHost()

Returns the "host" depending on whether an IP-Address has been provided or a host name.

Returns:

The determined host.

toHttpUrl

public String toHttpUrl()

Creates the complete "HTTP" URL String from the Url instance's state.

Returns:

The URL String for the given Url.

toLocator

public String toLocator()

Creates the locator part from the Url instance's state, excluding the fragment or the query fields.

Returns:

The locator for the given Url.

toURL

public URL toURL()
          throws MalformedURLException

Constructs an URL instance from your Url's state.

Returns:

The according URL instance.

Throws:

MalformedURLException - thrown in case the state of your Url instance cannot be used to construct a valid URL, you may be missing some properties.

toString

public String toString()

Overrides:

toString in class Object

fromUrl

protected void fromUrl(String aUrl)
                throws MalformedURLException

Uses the given String to set the Url's state.

Parameters:

aUrl - The URL from which to determine the state.

Throws:

MalformedURLException - in case the provided URL is considered being malformed.

fromURL

protected void fromURL(URL aUrl)

setScheme

protected void setScheme(org.refcodes.data.Scheme aScheme)

setProtocol

protected void setProtocol(String aProtocol)

setHost

protected void setHost(String aHost)

setIpAddress

protected void setIpAddress(int[] aIpAddress)

setPort

protected void setPort(int aPort)

setPath

protected void setPath(String aPath)

toTruncatePathPrefix

protected static String toTruncatePathPrefix(String aPath)

Removes any leading path delimiters (as of Delimiter.PATH).

Parameters:

aPath - The path to be processed.

Returns:

The path without any leading path delimiters.

toTruncatePathSuffix

protected static String toTruncatePathSuffix(String aPath)

Removes any trailing path delimiters (as of Delimiter.PATH).

Parameters:

aPath - The path to be processed.

Returns:

The path without any trailing path delimiters.

toTruncatePath

protected static String toTruncatePath(String aPath)

Removes any leading and trailing path delimiters (as of Delimiter.PATH).

Parameters:

aPath - The path to be processed.

Returns:

The path with neither any leading nor any trailing path delimiters.