org.apache.beehive.netui.core.urls
Class MutableURI

Object
  extended by MutableURI
Direct Known Subclasses:
FreezableMutableURI

public class MutableURI
extends Object

Mutable class for creating URIs.

There is little checking that an instance of this class produces a legal URI reference as defined by RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax. The minimal checking for syntax is on constructors that take a String representation or the URI, a URI, or a URL. To avoid the cost of continually checking the syntax, it is up to the user to ensure that the components are set correctly.

The setters of this class also assume that the data components are already encoded correctly for the given encoding of this URI, unless noted otherwise as in the methods to add unecoded parameters to the query. Then this class will handle the encoding. See addParameter( String name, String value, boolean encoded ) and addParameters( Map newParams, boolean encoded )

There is a static convenience method in this class so callers can easily encode unencoded components before setting it in this object.


Field Summary
static String DEFAULT_ENCODING
          Value used to set the encoding as undefined.
static int UNDEFINED_PORT
          Value used to set the port as undefined.
 
Constructor Summary
MutableURI()
          Constructs a MutableURI.
MutableURI(String uriString, boolean encoded)
          Constructs a MutableURI.
MutableURI(String scheme, String userInfo, String host, int port, String path, String query, String fragment)
          Constructs a MutableURI.
MutableURI(URI uri)
          Constructs a MutableURI.
MutableURI(URL url)
          Constructs a MutableURI.
 
Method Summary
 void addParameter(String name, String value, boolean encoded)
          Add a parameter for the query string.
 void addParameters(Map newParams, boolean encoded)
           Adds all the parameters in a Map to a URI's query string.
 String encode(String url)
          Convenience method to encode unencoded components of a URI.
static String encode(String url, String encoding)
          Convenience method to encode unencoded components of a URI.
protected static URI encodeURI(String original)
          Parse a URI reference, as a String, into its components and use URI to encode the components correctly.
 boolean equals(Object object)
          Determines if the passed-in Object is equivalent to this MutableURI.
static URIContext getDefaultContext()
          Returns a default URIContext.
 String getEncoding()
          Returns the character encoding that is used when adding unencoded parameters.
 String getFragment()
          Returns the fragment.
 String getHost()
          Returns the host.
 String getParameter(String name)
          Returns the value of the parameter.
 Map getParameters()
          Returns an unmodifiable Map of all parameters.
 List getParameters(String name)
          Returns the values of the given parameter.
 String getPath()
          Returns the path.
 int getPort()
          Returns the port.
 String getQuery(URIContext uriContext)
          Returns the query string (encoded/escaped).
 String getScheme()
          Returns the protocol/scheme.
 String getSchemeSpecificPart()
          Returns the scheme-specific part of this URI if it is opaque.
 String getURIString(URIContext uriContext)
          Returns a string form of this URI.
 String getUserInfo()
          Returns the userInfo.
 int hashCode()
          Returns a hash code value for the object.
protected static int indexFirstOf(String s, String delims, int offset)
          Get the earliest index, searching for the first occurrance of any one of the given delimiters.
 boolean isAbsolute()
          Tells whether or not this URI is absolute.
 boolean isOpaque()
          Tells whether or not this URI is opaque.
 void removeParameter(String name)
          Removes the given parameter.
 void setEncoding(String encoding)
          Set the encoding used when adding unencoded parameters.
 void setFragment(String fragment)
          Sets the fragment.
 void setHost(String host)
          Sets the host.
 void setOpaque(String scheme, String schemeSpecificPart)
          Sets the URI to be opaque using the given scheme and schemeSpecificPart.
 void setPath(String path)
          Sets the path.
 void setPort(int port)
          Sets the port.
 void setQuery(String query)
          Sets (and resets) the query string.
 void setScheme(String scheme)
          Sets the protocol/scheme.
protected  void setSchemeSpecificPart(String schemeSpecificPart)
          Set the scheme-specific part of this (opaque) URI
 void setURI(String uriString, boolean encoded)
          Set the value of the MutableURI.
 void setURI(URI uri)
          Set the value of the MutableURI.
 void setUserInfo(String userInfo)
          Sets the userInfo.
 
Methods inherited from class Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

UNDEFINED_PORT

public static final int UNDEFINED_PORT
Value used to set the port as undefined.

See Also:
Constant Field Values

DEFAULT_ENCODING

public static final String DEFAULT_ENCODING
Value used to set the encoding as undefined.

See Also:
Constant Field Values
Constructor Detail

MutableURI

public MutableURI()
Constructs a MutableURI.


MutableURI

public MutableURI(String uriString,
                  boolean encoded)
           throws URISyntaxException
Constructs a MutableURI.

Parameters:
uriString - the string to be parsed into a URI
encoded - Flag indicating whether the string is already encoded.
Throws:
URISyntaxException

MutableURI

public MutableURI(String scheme,
                  String userInfo,
                  String host,
                  int port,
                  String path,
                  String query,
                  String fragment)
Constructs a MutableURI. Assumes the individual components are already encoded and escaped.

Parameters:
scheme - the name of the protocol to use
userInfo - the username and password
host - the name of the host
port - the port number on the host
path - the file on the host
query - the query part of this URI
fragment - the fragment part of this URI (internal reference in the URL)

MutableURI

public MutableURI(URI uri)
Constructs a MutableURI.

Parameters:
uri - the initial value for this mutable URI

MutableURI

public MutableURI(URL url)
           throws URISyntaxException
Constructs a MutableURI.

This is just a convenience constructor that functions the same as MutableURI(URI) constructor with URL.toURI() as the argument.

Note, any URL instance that complies with RFC 2396 can be converted to a URI. However, some URLs that are not strictly in compliance can not be converted to a URI. See URL

Parameters:
url - the initial value for this mutable URI
Throws:
URISyntaxException - if this URL is not formatted strictly to RFC2396 and cannot be converted to a URI.
See Also:
URL.toURI()
Method Detail

setURI

public void setURI(String uriString,
                   boolean encoded)
            throws URISyntaxException
Set the value of the MutableURI.

This method can also be used to clear the MutableURI.

Parameters:
uriString - the string to be parsed into a URI
encoded - Flag indicating whether the string is already encoded.
Throws:
URISyntaxException

setURI

public void setURI(URI uri)
Set the value of the MutableURI.

This method can also be used to clear the MutableURI.

Parameters:
uri - the URI

setEncoding

public void setEncoding(String encoding)
Set the encoding used when adding unencoded parameters.

Parameters:
encoding -

getEncoding

public String getEncoding()
Returns the character encoding that is used when adding unencoded parameters.

Returns:
encoding

setScheme

public void setScheme(String scheme)
Sets the protocol/scheme.

Parameters:
scheme - protocol/scheme

getScheme

public String getScheme()
Returns the protocol/scheme. If no protocol was previously set, returns null.

Returns:
protocol/scheme

setUserInfo

public void setUserInfo(String userInfo)
Sets the userInfo. Assumes this component is already escaped.

Parameters:
userInfo - userInfo

getUserInfo

public String getUserInfo()
Returns the userInfo. If no host was previously set, returns null.

Returns:
userInfo

setHost

public void setHost(String host)
Sets the host.

Parameters:
host - host

getHost

public String getHost()
Returns the host. If no host was previously set, returns null.

Returns:
host

setPort

public void setPort(int port)
Sets the port.

Parameters:
port - port

getPort

public int getPort()
Returns the port. If no port was previously set, returns null.

Returns:
port

setPath

public void setPath(String path)
Sets the path. Assumes this component is already escaped.

Parameters:
path - path

getPath

public String getPath()
Returns the path.

Returns:
path

setQuery

public void setQuery(String query)
Sets (and resets) the query string. This method assumes that the query is already encoded and escaped.

Parameters:
query - Query string

getQuery

public String getQuery(URIContext uriContext)
Returns the query string (encoded/escaped).

The context states whether or not to use the default delimiter, usually the "&" entity, to separate the parameters. Otherwise, the "&" character is used.

Parameters:
uriContext - has property indicating if we use the HTML Amp entity to separate the query parameters.
Returns:
encoded query string.

addParameter

public void addParameter(String name,
                         String value,
                         boolean encoded)
Add a parameter for the query string.

If the encoded flag is true then this method assumes that the name and value do not need encoding or are already encoded correctly. Otherwise, it translates the name and value with the character encoding of this URI and adds them to the set of parameters for the query. If the encoding for this URI has not been set, then the default encoding used is "UTF-8".

Multiple values for the same parameter can be set by calling this method multiple times with the same name.

Parameters:
name - name
value - value
encoded - Flag indicating whether the names and values are already encoded.

addParameters

public void addParameters(Map newParams,
                          boolean encoded)

Adds all the parameters in a Map to a URI's query string.

If the encoded flag is true then this method assumes that the name and value do not need encoding or are already encoded correctly. Otherwise, it translates the name and value with the character encoding of this URI and adds them to the set of parameters for the query. If the encoding for this URI has not been set, then the default encoding used is "UTF-8".

The query parameters are added in the order the keys of the Map.

Parameters:
newParams - the map of new parameters to add to the URI
encoded - Flag indicating whether the names and values are already encoded.

getParameter

public String getParameter(String name)
Returns the value of the parameter. If several values are associated with the given parameter name, the first value is returned.

Parameters:
name - a name of the parameter
Returns:
value associated with the given parameter name

getParameters

public List getParameters(String name)
Returns the values of the given parameter.

Parameters:
name - name of the parameter
Returns:
an unmodifable List of values for the given parameter name

getParameters

public Map getParameters()
Returns an unmodifiable Map of all parameters.

Returns:
an unmodifiable Map of names and values for all parameters

removeParameter

public void removeParameter(String name)
Removes the given parameter.

Parameters:
name - name

setFragment

public void setFragment(String fragment)
Sets the fragment.

Parameters:
fragment - fragment

getFragment

public String getFragment()
Returns the fragment.

Returns:
fragment

isAbsolute

public boolean isAbsolute()
Tells whether or not this URI is absolute.

A URI is absolute if, and only if, it has a scheme component.

Returns:
true if, and only if, this URI is absolute

isOpaque

public boolean isOpaque()
Tells whether or not this URI is opaque.

Returns:
true if this URI was explicitly set as opaque

setOpaque

public void setOpaque(String scheme,
                      String schemeSpecificPart)
Sets the URI to be opaque using the given scheme and schemeSpecificPart.

From URI: "A URI is opaque if, and only if, it is absolute and its scheme-specific part does not begin with a slash character ('/'). An opaque URI has a scheme, a scheme-specific part, and possibly a fragment; all other components are undefined."

Parameters:
scheme - the scheme component of this URI
schemeSpecificPart - the scheme-specific part of this URI

getSchemeSpecificPart

public String getSchemeSpecificPart()
Returns the scheme-specific part of this URI if it is opaque. Otherwise, this method returns null.

Returns:
the scheme-specific part of this URI if this URI was explicitly set as opaque. Otherwise, return null.

setSchemeSpecificPart

protected void setSchemeSpecificPart(String schemeSpecificPart)
Set the scheme-specific part of this (opaque) URI

Parameters:
schemeSpecificPart - the scheme-specific part of this URI

getURIString

public String getURIString(URIContext uriContext)
Returns a string form of this URI. The URIContext encapsulates the data needed to write out the string form.

E.g. Defines if the "&" entity or the '&' character should be used to separate quary parameters.

Parameters:
uriContext - data required to write out the string form.
Returns:
the URI as a String

getDefaultContext

public static URIContext getDefaultContext()
Returns a default URIContext.

Returns:
the URIContext with default data.

encode

public static String encode(String url,
                            String encoding)
Convenience method to encode unencoded components of a URI.

Parameters:
url - the string to be encoded by URLCodec
encoding - the character encoding to use
Returns:
the encoded string

encode

public String encode(String url)
Convenience method to encode unencoded components of a URI. This implementation uses the value of the character encoding field of this instance.

Parameters:
url - the string to be encoded by URLCodec
Returns:
the encoded string

equals

public boolean equals(Object object)
Determines if the passed-in Object is equivalent to this MutableURI.

Overrides:
equals in class Object
Parameters:
object - the Object to test for equality.
Returns:
true if object is a MutableURI with all values equal to this MutableURI, false otherwise

hashCode

public int hashCode()
Returns a hash code value for the object.

Implemented in conjunction with equals() override.

This is a mutable class implying that we're basing the hash code on the member data that can change. Therefor it's important not to use this class as a key in a hashtable as it would still appear with an enumeration but not when calling contains. I.E. The object could get lost in the hashtable. A call for the hashcode would return a different value than when it was first placed in the hashtable.

With this in mind, we simply return the same value to support the rules of equality.

Overrides:
hashCode in class Object
Returns:
a hash code value for this object.

encodeURI

protected static URI encodeURI(String original)
                        throws URISyntaxException
Parse a URI reference, as a String, into its components and use URI to encode the components correctly. This comes from the parsing algorithm of the Apache Commons HttpClient code for its URI class.

Parameters:
original - the original character sequence
Throws:
URISyntaxException - If an error occurs.

indexFirstOf

protected static int indexFirstOf(String s,
                                  String delims,
                                  int offset)
Get the earliest index, searching for the first occurrance of any one of the given delimiters.

Parameters:
s - the string to be indexed
delims - the delimiters used to index
offset - the from index
Returns:
the earlier index if there are delimiters