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 no checking that an instance of this class produces a legal URI reference as defined by RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax. The only 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 static convenience method in this class so callers can easily encode unencoded components before setting in this URI.

TODO... We need to implement some conditions for opaque URIs like mailto, etc. to determine what to do about values of path when (path == null) => opaque and URI.getPath() would return "" for non-opaue URIs.


Field Summary
static String DEFAULT_ENCODING
          Value used to set the port as undefined.
static int UNDEFINED_PORT
          Value used to set the port as undefined.
 
Constructor Summary
MutableURI()
          Constructs a MutableURI.
MutableURI(String uriString)
          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)
          Add a parameter to the query string.
static String encode(String url, String encoding)
          Convenience method to encode unencoded components of a URI.
 boolean equals(Object object)
          Determines if the passed-in Object is equivalent to this MutableURI.
 String getDefaultParamDelimiter()
          Returns the value of the delimiter used between each query parameter in the .
 String getEncoding()
          Returns the 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<String,List<String>> getParameters()
          Returns an unmodifiable Map of all parameters.
 List<String> getParameters(String name)
          Returns the values of the given parameter.
 String getPath()
          Returns the path.
 int getPort()
          Returns the port.
 String getQuery()
          Returns the query string (encoded).
 String getQueryForXML()
          Returns the query string (encoded) to be used in an XML document.
 String getScheme()
          Returns the protocol/scheme.
 String getURIString()
          Returns a string form of this URI.
 String getURIStringForXML()
          Returns a string form of this URI suitable for an XML document.
 String getUserInfo()
          Returns the userInfo.
 int hashCode()
          Returns a hash code value for the object.
 boolean isAbsolute()
          Tells whether or not this URI is absolute.
 void removeParameter(String name)
          Removes the given parameter.
 void setAlwaysForXML(boolean alwaysForXml)
          Sets the value of the delimiter used between each query parameter in the query to be the XML "&amp;" entity, even for calls to the getQuery() and getURIString() methods.
 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 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.
 void setURI(String uriString)
          Reset 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 port as undefined.

See Also:
Constant Field Values
Constructor Detail

MutableURI

public MutableURI()
Constructs a MutableURI.


MutableURI

public MutableURI(String uriString)
           throws URISyntaxException
Constructs a MutableURI.

Parameters:
uriString - the string to be parsed into a URI
Throws:
URISyntaxException
See Also:
URI.URI(String)

MutableURI

public MutableURI(String scheme,
                  String userInfo,
                  String host,
                  int port,
                  String path,
                  String query,
                  String fragment)
Constructs a MutableURI.

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)
            throws URISyntaxException
Reset 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
Throws:
URISyntaxException
See Also:
URI.URI(String)

setEncoding

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

Parameters:
encoding -

getEncoding

public String getEncoding()
Returns the 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.

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.

Parameters:
path - path

getPath

public String getPath()
Returns the path.

Returns:
path

setAlwaysForXML

public void setAlwaysForXML(boolean alwaysForXml)
Sets the value of the delimiter used between each query parameter in the query to be the XML "&amp;" entity, even for calls to the getQuery() and getURIString() methods.

The getQueryForXML() and getURIStringForXML() methods always use the XML "&amp;" entity as the delimeter. However, the getQuery() and getURIString() methods use a default delimeter value which initially is set to be the '&' character. This method lets a client override this value such that even the getQuery() and getURIString() methods will return strings with the XML "&amp;" entity as the delimiter between the parameters in the query .

Parameters:
alwaysForXml - flag for choosing the query parameter delimiter.

getDefaultParamDelimiter

public String getDefaultParamDelimiter()
Returns the value of the delimiter used between each query parameter in the .

Returns:
query parameter delimiter.

setQuery

public void setQuery(String query)
Sets (and resets) the query string. This method assumes that the query is already encoded and the parameter delimiter is the '&' character.

Parameters:
query - Query string

getQuery

public String getQuery()
Returns the query string (encoded).

This uses a default delimiter to separate the parameters, usually the "&" character unless the instance has been set to always write the query for XML. In this case the delimiter value is the XML "&amp;" entity.

Returns:
encoded query string.

getQueryForXML

public String getQueryForXML()
Returns the query string (encoded) to be used in an XML document.

This uses the XML "&amp;" entity as the demilimeter to separate the 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)
Add a parameter to 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".

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 the parameter has several values, returns the first value.

Parameters:
name - name of the parameter
Returns:
value of the given parameter name (or just the first in the list if there are multiple values for the given name)

getParameters

public List<String> 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<String,List<String>> 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

getURIString

public String getURIString()
Returns a string form of this URI.

Returns:
the URI as a String

getURIStringForXML

public String getURIStringForXML()
Returns a string form of this URI suitable for an XML document. I.E. uses the XML "&amp;" entity as the demilimeter to separate the parameters in the query.

Returns:
the URI as a String

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

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.