UriBuilder (TrueCommons Shed 2.3.4 API)

java.lang.Object
- net.java.truecommons.shed.UriBuilder

```
@NotThreadSafe
public final class UriBuilder
extends Object
```
A mutable JavaBean for composing URIs according to RFC 2396 and its updates in RFC 2732 for IPv6 addresses.
This class complements the immutable URI class by enabling its clients to compose a URI from its components which can get read or written as independent properties. Each URI is composed of the five components scheme, authority, path, query and fragment. When done with setting the properties for the URI components, the resulting URI can be composed by calling any of the methods getUri(), toUri(), getString() or toString().
This class quotes illegal characters wherever required for the respective URI component. As a deviation from RFC 2396, non-US-ASCII characters get preserved when encoding.
Note that using this class is superior to the five argument URI constructor new URI(scheme, authority, path, query, fragment) because the URI constructor does not quote all paths correctly. For example, new URI(null, null, "foo:bar", null, null) does not quote the colon before parsing so the resulting URI will have a scheme component foo and a path component bar instead of just a path component foo:bar.
Identities
For any URI u it is generally true that
```
new UriBuilder(u).toUri().equals(u);
```
and
```
new UriBuilder().uri(u).toUri().equals(u);
```
and
```
new UriBuilder()
     .scheme(u.getScheme())
     .authority(u.getAuthority())
     .path(u.isOpaque() ? u.getSchemeSpecificPart() : u.getPath())
     .query(u.getQuery())
     .fragment(u.getFragment())
     .toUri()
     .equals(u);
 
```
These identity productions apply for the method toUri() as well as the method getUri().
Author:

Christian Schlichtherle

See Also:
RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax, RFC 2732: Format for Literal IPv6 Addresses in URL's

Constructor Summary

Constructors
Constructor and Description
`UriBuilder()` Constructs a new URI builder.
`UriBuilder(boolean raw)` Constructs a new URI builder.
`UriBuilder(URI uri)` Constructs a new URI builder.
`UriBuilder(URI uri, boolean raw)` Constructs a new URI builder.

Method Summary

Methods
Modifier and Type	Method and Description
`UriBuilder`	`authority(String authority)` Sets the URI authority component.
`UriBuilder`	`clear()` Clears the state of this URI builder.
`UriBuilder`	`fragment(String fragment)` Sets the URI fragment component.
`String`	`getAuthority()` Returns the URI authority component.
`String`	`getFragment()` Returns the URI fragment component.
`String`	`getPath()` Returns the URI path component.
`String`	`getQuery()` Returns the URI query component.
`String`	`getScheme()` Returns the URI scheme component.
`String`	`getString()` Returns a new URI string which conforms to the syntax constraints defined in RFC 2396 and its updates in RFC 2732 for IPv6 addresses.
`URI`	`getUri()` Returns a new URI which conforms to the syntax constraints defined in RFC 2396 and its updates in RFC 2732 for IPv6 addresses.
`UriBuilder`	`path(String path)` Sets the URI path component.
`UriBuilder`	`pathQuery(String pathQuery)` Sets the URI path an query components by splitting the given string at the first occurence of the query separator `'?'`.
`UriBuilder`	`query(String query)` Sets the URI query component.
`UriBuilder`	`scheme(String scheme)` Sets the URI scheme component.
`void`	`setAuthority(String authority)` Sets the URI authority component.
`void`	`setFragment(String fragment)` Sets the URI fragment component.
`void`	`setPath(String path)` Sets the URI path component.
`void`	`setPathQuery(String pathQuery)` Sets the URI path an query components by splitting the given string at the first occurence of the query separator `'?'`.
`void`	`setQuery(String query)` Sets the URI query component.
`void`	`setScheme(String scheme)` Sets the URI scheme component.
`void`	`setString(String uri)` Initializes all URI components from the given URI string.
`void`	`setUri(URI uri)` Initializes all URI components from the given URI.
`UriBuilder`	`string(String uri)` Initializes all URI components from the given URI string.
`String`	`toString()` Returns a new URI string which conforms to the syntax constraints defined in RFC 2396 and its updates in RFC 2732 for IPv6 addresses.
`URI`	`toUri()` Returns a new URI which conforms to the syntax constraints defined in RFC 2396 and its updates in RFC 2732 for IPv6 addresses.
`UriBuilder`	`uri(URI uri)` Initializes all URI components from the given URI.
`static void`	`validateScheme(String scheme)` Checks the given string to conform to the syntax constraints for URI schemes in RFC 2396

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - UriBuilder
```
public UriBuilder()
```
    Constructs a new URI builder. Equivalent to UriBuilder(false).
  - UriBuilder
```
public UriBuilder(boolean raw)
```
    Constructs a new URI builder.
    
    Parameters:
    raw - If true, then the '%' character doesn't get quoted.
  - UriBuilder
```
public UriBuilder(URI uri)
```
    Constructs a new URI builder. Equivalent to UriBuilder(uri, false).
    
    Parameters:
    uri - the uri for initializing the initial state.
  - UriBuilder
```
public UriBuilder(URI uri,
          boolean raw)
```
    Constructs a new URI builder.
    
    Parameters:
    uri - the uri for initializing the initial state.
    raw - If true, then the '%' character doesn't get quoted.
- Method Detail
  - authority
```
public UriBuilder authority(@CheckForNull
                   String authority)
```
    Sets the URI authority component.
    
    Parameters:
    authority - the URI authority component.
    
    Returns:
    this
  - clear
```
public UriBuilder clear()
```
    Clears the state of this URI builder. Calling this method is effectively the same as setting all URI component properties to null.
    
    Returns:
    this
  - fragment
```
public UriBuilder fragment(@CheckForNull
                  String fragment)
```
    Sets the URI fragment component.
    
    Parameters:
    fragment - the URI fragment component.
    
    Returns:
    this
  - getAuthority
```
@CheckForNull
public String getAuthority()
```
    Returns the URI authority component. If this URI builder has been initialized from an opaque URI, then this property is null.
    
    Returns:
    The URI authority component.
  - getFragment
```
@CheckForNull
public String getFragment()
```
    Returns the URI fragment component.
    
    Returns:
    The URI fragment component.
  - getPath
```
@CheckForNull
public String getPath()
```
    Returns the URI path component. If this URI builder has been initialized from an opaque URI, then this property contains the scheme specific part of the URI.
    
    Returns:
    The URI path component.
  - getQuery
```
@CheckForNull
public String getQuery()
```
    Returns the URI query component. If this URI builder has been initialized from an opaque URI, then this property is null.
    
    Returns:
    The URI query component.
  - getScheme
```
@CheckForNull
public String getScheme()
```
    Returns the URI scheme component.
    
    Returns:
    The URI scheme component.
  - getString
```
public String getString()
                 throws URISyntaxException
```
    Returns a new URI string which conforms to the syntax constraints defined in RFC 2396 and its updates in RFC 2732 for IPv6 addresses.
    
    Returns:
    A valid URI string which is composed from the properties of this URI builder.
    
    Throws:
    
    URISyntaxException - if composing a valid URI is not possible due to an invalid scheme.
    See Also:
    toString()
  - getUri
```
public URI getUri()
           throws URISyntaxException
```
    Returns a new URI which conforms to the syntax constraints defined in RFC 2396 and its updates in RFC 2732 for IPv6 addresses.
    
    Returns:
    A valid URI which is composed from the properties of this URI builder.
    
    Throws:
    
    URISyntaxException - if composing a valid URI is not possible.
    See Also:
    toUri()
  - path
```
public UriBuilder path(@CheckForNull
              String path)
```
    Sets the URI path component.
    
    Parameters:
    path - the URI path component.
    
    Returns:
    this
  - pathQuery
```
public UriBuilder pathQuery(@CheckForNull
                   String pathQuery)
```
    Sets the URI path an query components by splitting the given string at the first occurence of the query separator '?'.
    
    Parameters:
    pathQuery - the combined URI path and query components.
    
    Returns:
    this
  - query
```
public UriBuilder query(@CheckForNull
               String query)
```
    Sets the URI query component.
    
    Parameters:
    query - the URI query component.
    
    Returns:
    this
  - scheme
```
public UriBuilder scheme(@CheckForNull
                String scheme)
```
    Sets the URI scheme component.
    
    Parameters:
    scheme - the URI scheme component.
    
    Returns:
    this
  - setAuthority
```
public void setAuthority(@CheckForNull
                String authority)
```
    Sets the URI authority component.
    
    Parameters:
    authority - the URI authority component.
  - setFragment
```
public void setFragment(@CheckForNull
               String fragment)
```
    Sets the URI fragment component.
    
    Parameters:
    fragment - the URI fragment component.
  - setPath
```
public void setPath(@CheckForNull
           String path)
```
    Sets the URI path component.
    
    Parameters:
    path - the URI path component.
  - setPathQuery
```
public void setPathQuery(@CheckForNull
                String pathQuery)
```
    Sets the URI path an query components by splitting the given string at the first occurence of the query separator '?'.
    
    Parameters:
    pathQuery - the combined URI path and query components.
  - setQuery
```
public void setQuery(@CheckForNull
            String query)
```
    Sets the URI query component.
    
    Parameters:
    query - the URI query component.
  - setScheme
```
public void setScheme(@CheckForNull
             String scheme)
```
    Sets the URI scheme component.
    
    Parameters:
    scheme - the URI scheme component.
  - setString
```
public void setString(String uri)
```
    Initializes all URI components from the given URI string.
    
    Parameters:
    uri - the URI string.
    
    Throws:
    
    IllegalArgumentException - if uri does not conform to the syntax constraints of the URI class.
  - setUri
```
public void setUri(URI uri)
```
    Initializes all URI components from the given URI.
    
    Parameters:
    uri - the URI.
  - string
```
public UriBuilder string(String uri)
```
    Initializes all URI components from the given URI string.
    
    Parameters:
    uri - the URI string.
    
    Returns:
    this
    
    Throws:
    
    IllegalArgumentException - if uri does not conform to the syntax constraints of the URI class.
  - toString
```
public String toString()
```
    Returns a new URI string which conforms to the syntax constraints defined in RFC 2396 and its updates in RFC 2732 for IPv6 addresses.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    A valid URI string which is composed from the properties of this URI builder.
    
    Throws:
    
    IllegalStateException - if composing a valid URI is not possible.
    See Also:
    getString()
  - toUri
```
public URI toUri()
```
    Returns a new URI which conforms to the syntax constraints defined in RFC 2396 and its updates in RFC 2732 for IPv6 addresses.
    
    Returns:
    A valid URI which is composed from the properties of this URI builder.
    
    Throws:
    
    IllegalStateException - if composing a valid URI is not possible.
    See Also:
    getUri()
  - uri
```
public UriBuilder uri(URI uri)
```
    Initializes all URI components from the given URI.
    
    Parameters:
    uri - the URI.
    
    Returns:
    this
  - validateScheme
```
public static void validateScheme(String scheme)
                           throws URISyntaxException
```
    Checks the given string to conform to the syntax constraints for URI schemes in RFC 2396
    
    Parameters:
    scheme - the string to validate.
    
    Throws:
    
    URISyntaxException - if scheme does not conform to the syntax constraints for URI schemes in RFC 2396.

Class UriBuilder

Identities

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

UriBuilder

UriBuilder

UriBuilder

UriBuilder

Method Detail

authority

clear

fragment

getAuthority

getFragment

getPath

getQuery

getScheme

getString

getUri

path

pathQuery

query

scheme

setAuthority

setFragment

setPath

setPathQuery

setQuery

setScheme

setString

setUri

string

toString

toUri

uri

validateScheme