Module com.aoapps.net.partialurl

Package com.aoapps.net.partialurl

Class PartialURL

java.lang.Object

com.aoapps.net.partialurl.PartialURL

Direct Known Subclasses:

MultiPartialURL, SinglePartialURL

public abstract class PartialURL
extends Object

A PartialURL matches and completes URLs. All fields are optional.

This is not a general-purpose representation of a URL. It only contains the fields specifically used for matching a request to a virtual host (TODO: Links to projects). For an instance of URL, see toURL(com.aoapps.net.partialurl.FieldSource).

All partial URLs are immutable value types.

Field Summary

Fields

Modifier and Type	Field	Description
static final SinglePartialURL	DEFAULT	A SinglePartialURL consisting of all null fields that will match all requests and can serve as a match for a default host.
static final String	HTTP	The http scheme.
static final String	HTTPS	The https scheme.
protected static final String	NULL_CONTEXT_PATH	The value used to represent null SinglePartialURL.getContextPath() or MultiPartialURL.getContextPaths().
protected static final String	NULL_PREFIX	The value used to represent null SinglePartialURL.getPrefix() or MultiPartialURL.getPrefixes().
protected static final char	WILDCARD_CHAR	The character used to represent request-value substitutions.
protected static final String	WILDCARD_STRING	The character used to represent request-value substitutions.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	PartialURL()

Method Summary

Modifier and Type	Method	Description
abstract boolean	equals(Object obj)
abstract Iterable<SinglePartialURL>	getCombinations()	Gets all combinations of single partial URLs represented by this partial URL.
abstract SinglePartialURL	getPrimary()	Gets the primary single partial URL for this partial URL.
abstract int	hashCode()
abstract boolean	isComplete()	Checks if this partial URL is complete (has no null fields other than prefix).
abstract SinglePartialURL	matches(FieldSource fieldSource)	Checks if the given FieldSource matches this partial URL.
abstract String	toString()
abstract URL	toURL(FieldSource fieldSource)	Gets the general-purpose representation of URL for this partial URL.
static SinglePartialURL	valueOf(Path prefix)	Gets a partial URL always within the current request.
static PartialURL	valueOf(Path... prefixes)	Gets a partial URL always within the current request.
static PartialURL	valueOf(Iterable<? extends Path> prefixes)	Gets a partial URL always within the current request.
static PartialURL	valueOf(Iterable<? extends String> schemes, Iterable<? extends HostAddress> hosts, Iterable<? extends Port> ports, Iterable<? extends Path> contextPaths, Iterable<? extends Path> prefixes)	Gets a partial URL supporting requests across multiple schemes/hosts/ports/...
static PartialURL	valueOf(String[] schemes, HostAddress[] hosts, Port[] ports, Path[] contextPaths, Path... prefixes)	Gets a partial URL supporting requests across multiple schemes/hosts/ports/...
static SinglePartialURL	valueOf(String scheme, HostAddress host, Port port, Path contextPath, Path prefix)	Gets a partial URL supporting requests across multiple schemes/hosts/ports/...

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Details

HTTP

public static final String HTTP

The http scheme.

See Also:

• Constant Field Values

HTTPS

public static final String HTTPS

The https scheme.

See Also:

• Constant Field Values

WILDCARD_CHAR

protected static final char WILDCARD_CHAR

The character used to represent request-value substitutions.

See Also:

• WILDCARD_STRING
• Constant Field Values

WILDCARD_STRING

protected static final String WILDCARD_STRING

The character used to represent request-value substitutions.

See Also:

• WILDCARD_CHAR

NULL_CONTEXT_PATH

protected static final String NULL_CONTEXT_PATH

The value used to represent null SinglePartialURL.getContextPath() or MultiPartialURL.getContextPaths().

NULL_PREFIX

protected static final String NULL_PREFIX

The value used to represent null SinglePartialURL.getPrefix() or MultiPartialURL.getPrefixes().

DEFAULT

public static final SinglePartialURL DEFAULT

A SinglePartialURL consisting of all null fields that will match all requests and can serve as a match for a default host.

This default host is after all others in SinglePartialURL.compareTo(com.aoapps.net.partialurl.SinglePartialURL) and PartialURLMap.get(com.aoapps.net.partialurl.FieldSource).

Constructor Details

PartialURL

protected PartialURL()

Method Details

valueOf

public static SinglePartialURL valueOf(String scheme,
 HostAddress host,
 Port port,
 Path contextPath,
 Path prefix)

Gets a partial URL supporting requests across multiple schemes/hosts/ports/...

Parameters:

scheme - (Optional) The scheme (http/https/...) to match and/or link to, converted to lower-case.

host - (Optional) The IP/host to match and/or link to

port - (Optional) The port to match and/or link to

contextPath - (Optional) The contextPath to match and/or link to

prefix - (Optional) The prefix to match against the path or null to match all. Must be either null or always ends in a slash (/).

See Also:

• SinglePartialURL(java.lang.String, com.aoapps.net.HostAddress, com.aoapps.net.Port, com.aoapps.net.Path, com.aoapps.net.Path)

valueOf

public static SinglePartialURL valueOf(Path prefix)

Gets a partial URL always within the current request.

Parameters:

prefix - (Optional) The prefix to match against the path or null to match all. Must be either null or always ends in a slash (/).

See Also:

• valueOf(java.lang.String, com.aoapps.net.HostAddress, com.aoapps.net.Port, com.aoapps.net.Path, com.aoapps.net.Path)

valueOf

public static PartialURL valueOf(Iterable<? extends String> schemes,
 Iterable<? extends HostAddress> hosts,
 Iterable<? extends Port> ports,
 Iterable<? extends Path> contextPaths,
 Iterable<? extends Path> prefixes)

Gets a partial URL supporting requests across multiple schemes/hosts/ports/...

Parameters:

schemes - (Optional) The scheme (http/https/...) to match and/or link to, converted to lower-case. null elements are skipped.

hosts - (Optional) The IP/host to match and/or link to null elements are skipped.

ports - (Optional) The port to match and/or link to null elements are skipped.

contextPaths - (Optional) The contextPath to match and/or link to null elements are skipped.

prefixes - (Optional) The prefix to match against the path or null to match all. Must be either null or always ends in a slash (/). null elements are skipped.

See Also:

• MultiPartialURL(java.util.Set, java.util.Map, java.util.Set, java.util.Set, java.util.Set)

valueOf

public static PartialURL valueOf(String[] schemes,
 HostAddress[] hosts,
 Port[] ports,
 Path[] contextPaths,
 Path... prefixes)

Gets a partial URL supporting requests across multiple schemes/hosts/ports/...

Parameters:

schemes - (Optional) The scheme (http/https/...) to match and/or link to, converted to lower-case. null elements are skipped.

hosts - (Optional) The IP/host to match and/or link to null elements are skipped.

ports - (Optional) The port to match and/or link to null elements are skipped.

contextPaths - (Optional) The contextPath to match and/or link to null elements are skipped.

prefixes - (Optional) The prefix to match against the path or null to match all. Must be either null or always ends in a slash (/). null elements are skipped.

See Also:

• valueOf(java.lang.Iterable, java.lang.Iterable, java.lang.Iterable, java.lang.Iterable, java.lang.Iterable)

valueOf

public static PartialURL valueOf(Iterable<? extends Path> prefixes)

Gets a partial URL always within the current request.

Parameters:

prefixes - (Optional) The prefix to match against the path or null to match all. Must be either null or always ends in a slash (/).

See Also:

• valueOf(java.lang.Iterable, java.lang.Iterable, java.lang.Iterable, java.lang.Iterable, java.lang.Iterable)

valueOf

public static PartialURL valueOf(Path... prefixes)

Gets a partial URL always within the current request.

Parameters:

prefixes - (Optional) The prefix to match against the path or null to match all. Must be either null or always ends in a slash (/).

See Also:

• valueOf(java.lang.Iterable)

toString

public abstract String toString()

Overrides:

toString in class Object

equals

public abstract boolean equals(Object obj)

Overrides:

equals in class Object

hashCode

public abstract int hashCode()

Overrides:

hashCode in class Object

matches

public abstract SinglePartialURL matches(FieldSource fieldSource)
                                  throws MalformedURLException

Checks if the given FieldSource matches this partial URL.

The SinglePartialURL returned, if any, is also in the set of partial URLs provided by getCombinations(). Specifically, the match must be equivalent to the first match found by iterative calls to the results of getCombinations(), using SinglePartialURL.matches(com.aoapps.net.partialurl.FieldSource) on each single partial. The implementation, however, does not need to be iterative.

Ordering is consistent with:

• getCombinations()
• SinglePartialURL.compareTo(com.aoapps.net.partialurl.SinglePartialURL)
• PartialURLMap.get(com.aoapps.net.partialurl.FieldSource)

Parameters:

fieldSource - When all fields are null (this is DEFAULT), this is not used and may be null.

Returns:

The SinglePartialURL with non-null fields selected to match the field source, or null when does not match. When the match is equals the primary, returns the same object as getPrimary().

Throws:

MalformedURLException

isComplete

public abstract boolean isComplete()

Checks if this partial URL is complete (has no null fields other than prefix). A complete URL may be converted to a URL without any field source provided.

See Also:

• toURL(com.aoapps.net.partialurl.FieldSource)

getPrimary

public abstract SinglePartialURL getPrimary()

Gets the primary single partial URL for this partial URL.

This will always be found in getCombinations().

See Also:

• getCombinations()

getCombinations

public abstract Iterable<SinglePartialURL> getCombinations()

Gets all combinations of single partial URLs represented by this partial URL.

Ordering is consistent with:

• matches(com.aoapps.net.partialurl.FieldSource)
• SinglePartialURL.compareTo(com.aoapps.net.partialurl.SinglePartialURL)
• PartialURLMap.get(com.aoapps.net.partialurl.FieldSource)

When one of the results is equal to the primary, returns the same object instance as getPrimary().

See Also:

• getPrimary()
• SinglePartialURL.compareTo(com.aoapps.net.partialurl.SinglePartialURL)

toURL

public abstract URL toURL(FieldSource fieldSource)
                   throws MalformedURLException

Gets the general-purpose representation of URL for this partial URL.

Parameters:

fieldSource - Only used when at least one field is null and uses the value from the source. May be null when this PartialURL is known to have all fields specified.

Throws:

NullPointerException - when fieldSource not provided and at least one field is null.

MalformedURLException

See Also:

• isComplete()