com.novell.sentinel.uri
Class GenericURI

java.lang.Object
  com.novell.sentinel.uri.GenericURI

All Implemented Interfaces:

UriConstructor, UriDeconstructor

public class GenericURI
extends Object
implements UriConstructor, UriDeconstructor

A class for parsing and rendering URIs as described by RFC 3986.

In addition to the generic URI syntax described the RFC, this class supports the commonly-used query string media type "application/x-www-form-urlencoded" defined by HTML. The default is the HTML form style query.

This class is similar in concept and execution to java.net.URI and exists because java.net.URI class is not available under GWT. Note, however, that unlike java.net.URI, this class's parser does not validate the components it finds. It will not, for example, throw an exception if there is an illegal character in the scheme.

Instances of this class may be used to parse existing URI strings into constituent parts, to build new URI strings from parts, or to parse existing URI strings, modify the URI data, and then build a modified URI string from the result.

More specialized URI classes can be built on top of this class.

Nested Class Summary

static class	GenericURI.Authority A class that manages the authority component of a URI.
static class	GenericURI.FormQuery A class used to parse, store, and output information from the query component of a URI that is interpreted as of the media type "application/x-www-form-urlencoded".
static class	GenericURI.Fragment A class used to parse and output the fragment component of a URI.
static class	GenericURI.Path A class used to parse and store path segments of the path component of a URI.
static class	GenericURI.Query A class supported the generic query string specified by RFC 3986.

Constructor Summary

GenericURI()
Construct an empty URI.

GenericURI(GenericURI src)
Make a deep copy of the passed instance.

GenericURI(String uri)
Parse the passed String as a URI and make the components available in the resulting instance.

Method Summary

UriConstructor	appendPath(Collection<String> components) Append a path to any existing path.
UriConstructor	appendPath(String path) Append a path to any existing path.
UriConstructor	appendPathComponent(String pathComponent) Append a single component of the path to any existing path.
void	appendPathComponents(String... pathComponents) Append multiple path components.
protected void	ensureAuthority() If the private Authority member variable is null, allocate a new Authority instance and set it via setAuthorityImpl.
protected void	ensureFragment() If the private Fragment member variable is null, allocate a new Fragment instance and set it via setFragmentImpl.
protected void	ensurePath() If the private Path member variable is null, allocate a new Path instance and set it via setPathImpl.
protected void	ensureQuery() If the private Query member variable is null, allocate a new Query instance and set it via setQueryImpl.
protected GenericURI.Authority	getAuthorityImpl() Get the private Authority instance.
String	getDecodedQuery() Return the unparsed but percent-decoded query component from the source URI string.
String	getFragment()
protected GenericURI.Fragment	getFragmentImpl() Get the private Fragment instance.
String	getHost()
List<String>	getPathComponents()
protected GenericURI.Path	getPathImpl() Get the private Path instance.
int	getPort()
protected GenericURI.Query	getQueryImpl() Get the private Query instance.
Map<String,List<String>>	getQueryItems()
String	getRawAuthority() Return the raw, unparsed, un-decoded authority component from the source URI string.
String	getRawFragment() Return the raw, unparsed, un-decoded fragment component from the source URI string.
String	getRawPath() Return the raw, unparsed, un-decoded path component from the source URI string.
String	getRawQuery() Return the raw, unparsed, un-decoded query component from the source URI string.
String	getScheme()
String	getUserInfo()
boolean	isGenericQuery() Return true if this instance is treating the query string as a generic string (i.e., not "application/x-www-form-urlencoded").
protected void	parse(String uri) Parse a string as the basis for this instance.
protected void	parseAuthority(String rawAuthority) Parse the authority component.
protected void	parseFragment(String rawFragment) Parse the fragment component.
protected void	parsePath(String rawPath) Parse the path component.
protected void	parseQuery(String rawQuery) Parse the query component.
protected void	parseScheme(String rawScheme) Parse the scheme component.
void	set(String uri) Set this instance based on the data in the passed URI string.
protected void	setAuthorityImpl(GenericURI.Authority authority) Set the private Authority instance.
UriConstructor	setFragment(String fragment) Set the fragment portion of the URI.
protected void	setFragmentImpl(GenericURI.Fragment fragment) Set the private Fragment instance.
void	setGenericQuery(boolean genericQuery) Set the treatment of the query string.
void	setGenericQuery(String genericQuery) Set the generic query string.
UriConstructor	setHost(String host) Set the host part of the URI authority (e.g., www.novell.com).
protected void	setPathImpl(GenericURI.Path path) Set the private Path instance.
UriConstructor	setPort(int port) Set the port part of the URI authority (e.g., 8443).
protected void	setQueryImpl(GenericURI.Query query) Set the private Query instance.
UriConstructor	setQueryItem(String key, Iterable<String> values) Set a query item and optional values.
UriConstructor	setQueryItem(String key, String... values) Set a query item and optional values.
UriConstructor	setScheme(String scheme) Set the URI scheme (e.g., "https").
UriConstructor	setUserInfo(String userInfo) Set any user information for the URI.
String	toString() Return the string representation of the constructed URI.

Methods inherited from class java.lang.Object

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

Constructor Detail

GenericURI

public GenericURI()

Construct an empty URI.

GenericURI

public GenericURI(String uri)

Parse the passed String as a URI and make the components available in the resulting instance. The URI string must be in encoded, unparsed format.

Parameters:

uri - The URI string to parse.

GenericURI

public GenericURI(GenericURI src)

Make a deep copy of the passed instance.

Parameters:

src - The instance to copy.

Method Detail

isGenericQuery

public boolean isGenericQuery()

Return true if this instance is treating the query string as a generic string (i.e., not "application/x-www-form-urlencoded").

Returns:

true if the query is treated as generic.

setGenericQuery

public void setGenericQuery(boolean genericQuery)

Set the treatment of the query string. The choices are generic (as specified in RFC 3986) or "application/x-www-form-urlencoded" as specified by HTML.

If a query string is already associated with this instance, the underlying handling is switched.

Parameters:

genericQuery - true if the query is to be treated generically.

set

public void set(String uri)

Set this instance based on the data in the passed URI string.

Parameters:

uri - The URI.

getScheme

public String getScheme()

Specified by:

getScheme in interface UriDeconstructor

getUserInfo

public String getUserInfo()

Specified by:

getUserInfo in interface UriDeconstructor

getHost

public String getHost()

Specified by:

getHost in interface UriDeconstructor

getPort

public int getPort()

Specified by:

getPort in interface UriDeconstructor

getPathComponents

public List<String> getPathComponents()

Specified by:

getPathComponents in interface UriDeconstructor

getQueryItems

public Map<String,List<String>> getQueryItems()

Specified by:

getQueryItems in interface UriDeconstructor

getFragment

public String getFragment()

Specified by:

getFragment in interface UriDeconstructor

getRawAuthority

public String getRawAuthority()

Return the raw, unparsed, un-decoded authority component from the source URI string. This will return null if there was no authority component in the source URI, or if one of the following setters for authority information was used:

• setUserInfo(String)
• setHost(String)
• setPort(int)

Returns:

The raw authority component, or null.

getRawPath

public String getRawPath()

Return the raw, unparsed, un-decoded path component from the source URI string. This will return null if there was no non-empty path component in the source URI, or if one of the following setters for path segments was used:

• appendPath(String)
• appendPath(Collection)
• appendPathComponent(String)
• appendPathComponents(String...)

Returns:

The raw path component, or null.

getRawQuery

public String getRawQuery()

Return the raw, unparsed, un-decoded query component from the source URI string. This will return null if there was no query component in the source URI, or if one of the following setters for the query component was used:

• setQueryItem(String,String...)
• setQueryItem(String,Iterable)

  Returns:

  The raw query component, or null.

getDecodedQuery

public String getDecodedQuery()

Return the unparsed but percent-decoded query component from the source URI string. This will return null if there was no query component in the source URI, or if one of the following setters for the query component was used:

• setQueryItem(String,String...)
• setQueryItem(String,Iterable)

  Use this if the query string should not be interpreted as "application/x-www-form-urlencoded".

  Returns:

  The decoded query component, or null.

getRawFragment

public String getRawFragment()

Return the raw, unparsed, un-decoded fragment component from the source URI string. This will return null if there was no fragment component in the source URI, or if the following setter was used:

• setFragment(String)

Returns:

The raw fragment component, or null.

setScheme

public UriConstructor setScheme(String scheme)

Description copied from interface: UriConstructor

Set the URI scheme (e.g., "https").

Specified by:

setScheme in interface UriConstructor

Parameters:

scheme - The scheme name

Returns:

This instance.

setUserInfo

public UriConstructor setUserInfo(String userInfo)

Description copied from interface: UriConstructor

Set any user information for the URI.

Specified by:

setUserInfo in interface UriConstructor

Parameters:

userInfo - The user information string.

Returns:

This instance.

setHost

public UriConstructor setHost(String host)

Description copied from interface: UriConstructor

Set the host part of the URI authority (e.g., www.novell.com).

Specified by:

setHost in interface UriConstructor

Parameters:

host - The host string.

Returns:

This instance.

setPort

public UriConstructor setPort(int port)

Description copied from interface: UriConstructor

Set the port part of the URI authority (e.g., 8443).

Specified by:

setPort in interface UriConstructor

Parameters:

port - The port value.

Returns:

This instance.

appendPath

public UriConstructor appendPath(String path)

Description copied from interface: UriConstructor

Append a path to any existing path. Any components are separated by '/'. This means that path components with embedded '/' characters cannot be property appended with this method (@see UriConstructor.appendPathComponent(String)appendPathComponent).

Specified by:

appendPath in interface UriConstructor

Parameters:

path - The path string.

Returns:

This instance.

appendPath

public UriConstructor appendPath(Collection<String> components)

Description copied from interface: UriConstructor

Append a path to any existing path.

Specified by:

appendPath in interface UriConstructor

Parameters:

components - A collection of components. The components will be appended in the order returned by the Iterator returned by components.iterator().

Returns:

This instance.

appendPathComponent

public UriConstructor appendPathComponent(String pathComponent)

Description copied from interface: UriConstructor

Append a single component of the path to any existing path. This method handles path components with embedded '/' characters in the component value.

Specified by:

appendPathComponent in interface UriConstructor

Parameters:

pathComponent - The component value.

Returns:

This instance.

appendPathComponents

public void appendPathComponents(String... pathComponents)

Append multiple path components.

Parameters:

pathComponents - The path components.

setGenericQuery

public void setGenericQuery(String genericQuery)

Set the generic query string. If the query handling is set to support "application/x-www-form-urlencoded", then this method has no effect.

Parameters:

genericQuery - The literal query string.

setQueryItem

public UriConstructor setQueryItem(String key,
                                   String... values)

Description copied from interface: UriConstructor

Set a query item and optional values.

Specified by:

setQueryItem in interface UriConstructor

Parameters:

key - The name of the query item (e.g., "field" or "query").

values - The value(s) for the query item.

Returns:

This instance.

setQueryItem

public UriConstructor setQueryItem(String key,
                                   Iterable<String> values)

Description copied from interface: UriConstructor

Set a query item and optional values.

Specified by:

setQueryItem in interface UriConstructor

Parameters:

key - The name of the query item (e.g., "field" or "query").

values - The value(s) for the query item.

Returns:

This instance.

setFragment

public UriConstructor setFragment(String fragment)

Description copied from interface: UriConstructor

Set the fragment portion of the URI.

Specified by:

setFragment in interface UriConstructor

Parameters:

fragment - The fragment string (not including the '#').

Returns:

This instance.

toString

public String toString()

Description copied from interface: UriConstructor

Return the string representation of the constructed URI.

Specified by:

toString in interface UriConstructor

Overrides:

toString in class Object

Returns:

The URI string.

ensureAuthority

protected void ensureAuthority()

If the private Authority member variable is null, allocate a new Authority instance and set it via setAuthorityImpl.

If a derived class needs to override the base Authority implementation then the derived class must override this method.

ensurePath

protected void ensurePath()

If the private Path member variable is null, allocate a new Path instance and set it via setPathImpl.

If a derived class needs to override the base Path implementation then the derived class must override this method.

ensureQuery

protected void ensureQuery()

If the private Query member variable is null, allocate a new Query instance and set it via setQueryImpl.

If a derived class needs to override the base Query implementation then the derived class must override this method.

ensureFragment

protected void ensureFragment()

If the private Fragment member variable is null, allocate a new Fragment instance and set it via setFragmentImpl.

If a derived class needs to override the base Fragment implementation then the derived class must override this method.

getAuthorityImpl

protected GenericURI.Authority getAuthorityImpl()

Get the private Authority instance. Internal access to the Authority implementation is performed via this method, allowing derived classes to override the private member variable if necessary.

Returns:

The Authority member, or null.

setAuthorityImpl

protected void setAuthorityImpl(GenericURI.Authority authority)

Set the private Authority instance. Internal setting of the Authority implementation is performed via this method, allowing derived classes to override the private member variable if necessary.

Parameters:

authority - The Authority instance to set.

getPathImpl

protected GenericURI.Path getPathImpl()

Get the private Path instance. Internal access to the Path implementation is performed via this method, allowing derived classes to override the private member variable if necessary.

Returns:

The Path member, or null.

setPathImpl

protected void setPathImpl(GenericURI.Path path)

Set the private Path instance. Internal setting of the Path implementation is performed via this method, allowing derived classes to override the private member variable if necessary.

Parameters:

path - The Path instance to set.

getQueryImpl

protected GenericURI.Query getQueryImpl()

Get the private Query instance. Internal access to the Query implementation is performed via this method, allowing derived classes to override the private member variable if necessary.

Returns:

The Query member, or null.

setQueryImpl

protected void setQueryImpl(GenericURI.Query query)

Set the private Query instance. Internal setting of the Query implementation is performed via this method, allowing derived classes to override the private member variable if necessary.

Parameters:

query - The Query instance to set.

getFragmentImpl

protected GenericURI.Fragment getFragmentImpl()

Get the private Fragment instance. Internal access to the Fragment implementation is performed via this method, allowing derived classes to override the private member variable if necessary.

Returns:

The Fragment member, or null.

setFragmentImpl

protected void setFragmentImpl(GenericURI.Fragment fragment)

Set the private Fragment instance. Internal setting of the Fragment implementation is performed via this method, allowing derived classes to override the private member variable if necessary.

Parameters:

fragment - The Fragment instance to set.

parse

protected void parse(String uri)

Parse a string as the basis for this instance. The string is parsed into component sections and each section is parsed by the appropriate parse* method (e.g., the authority component is parsed by parseAuthority).

Parameters:

uri - The URI string.

parseScheme

protected void parseScheme(String rawScheme)

Parse the scheme component. The base implementation simply calls setScheme(String) with the passed string as the parameter.

Parameters:

rawScheme - The scheme component.

parseAuthority

protected void parseAuthority(String rawAuthority)

Parse the authority component. The base implementation constructs a new Authority instance using the Authority(String) constructor and calls setAuthorityImpl with the resulting object.

Parameters:

rawAuthority - The encoded authority component string.

parsePath

protected void parsePath(String rawPath)

Parse the path component. The base implementation constructs a new Path instance using the Path(String) constructor and calls setPathImpl with the resulting object.

Parameters:

rawPath - The encoded path component string.

parseQuery

protected void parseQuery(String rawQuery)

Parse the query component. The base implementation constructs a new Query instance using the Query(String) constructor and calls setQueryImpl with the resulting object.

Parameters:

rawQuery - The encoded query component string.

parseFragment

protected void parseFragment(String rawFragment)

Parse the fragment component. The base implementation constructs a new Fragment instance using the Fragment(String) constructor and calls setFragmentImpl with the resulting object.

Parameters:

rawFragment - The encoded fragment component string.