UriBuilder (TrueZIP Kernel 7.1.3 API)

java.lang.Object
- de.schlichtherle.truezip.util.UriBuilder

```
@DefaultAnnotation(value=edu.umd.cs.findbugs.annotations.NonNull.class)
@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 still apply even if the method getUri() is substituted with the method toUri().
Author:

Christian Schlichtherle

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

Field Summary

Fields
Modifier and Type	Field and Description
`private String`	`authority`
`private StringBuilder`	`builder`
`private UriEncoder`	`encoder`
`private String`	`fragment`
`private String`	`path`
`private String`	`query`
`private String`	`scheme`

Constructor Summary

Constructors
Constructor and Description

UriBuilder()
Constructs a new URI builder.

UriBuilder(URI uri)
Constructs a new URI builder.

Constructors
Constructor and Description
`UriBuilder()` Constructs a new URI builder.
`UriBuilder(URI uri)` 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.
`private static URISyntaxException`	`newURISyntaxException(CharBuffer input, String reason)`
`UriBuilder`	`path(String path)` Sets the URI path component.
`UriBuilder`	`query(String query)` Sets the URI query component.
`private static String`	`quote(Object s)`
`private StringBuilder`	`resetBuilder()`
`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`	`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.
`private static void`	`validateScheme(CharBuffer input)`
`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

- Field Detail
  - encoder
```
private final UriEncoder encoder
```
  - builder
```
@CheckForNull
private StringBuilder builder
```
  - scheme
```
@CheckForNull
private String scheme
```
  - authority
```
@CheckForNull
private String authority
```
  - path
```
@CheckForNull
private String path
```
  - query
```
@CheckForNull
private String query
```
  - fragment
```
@CheckForNull
private String fragment
```
- Constructor Detail
  - UriBuilder
```
public UriBuilder()
```
    Constructs a new URI builder.
  - UriBuilder
```
public UriBuilder(URI uri)
```
    Constructs a new URI builder.
    
    Parameters:
    uri - the uri for initializing the initial state.
- Method Detail
  - 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
  - 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()
  - 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()
  - resetBuilder
```
private StringBuilder resetBuilder()
```
  - 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.
  - validateScheme
```
private static void validateScheme(CharBuffer input)
                            throws URISyntaxException
```
    Throws:
    
    URISyntaxException
  - newURISyntaxException
```
private static URISyntaxException newURISyntaxException(CharBuffer input,
                                       String reason)
```
  - quote
```
private static String quote(Object s)
```
  - 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.
  - 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.
  - 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()
  - 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()
  - setUri
```
public void setUri(URI uri)
```
    Initializes all URI components from the given URI.
    
    Parameters:
    uri - the URI.
  - uri
```
public UriBuilder uri(URI uri)
```
    Initializes all URI components from the given URI.
    
    Parameters:
    uri - the URI.
    
    Returns:
    this
  - getScheme
```
@CheckForNull
public String getScheme()
```
    Returns the URI scheme component.
    
    Returns:
    The URI scheme component.
  - setScheme
```
public void setScheme(@CheckForNull
             String scheme)
```
    Sets the URI scheme component.
    
    Parameters:
    scheme - the URI scheme component.
  - scheme
```
public UriBuilder scheme(@CheckForNull
                String scheme)
```
    Sets the URI scheme component.
    
    Parameters:
    scheme - the URI scheme 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.
  - setAuthority
```
public void setAuthority(@CheckForNull
                String authority)
```
    Sets the URI authority component.
    
    Parameters:
    authority - the URI authority component.
  - authority
```
public UriBuilder authority(@CheckForNull
                   String authority)
```
    Sets the URI authority component.
    
    Parameters:
    authority - the URI authority component.
    
    Returns:
    this
  - 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.
  - setPath
```
public void setPath(@CheckForNull
           String path)
```
    Sets the URI path component.
    
    Parameters:
    path - the URI path component.
  - path
```
public UriBuilder path(@CheckForNull
              String path)
```
    Sets the URI path component.
    
    Parameters:
    path - the URI path component.
    
    Returns:
    this
  - 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.
  - setQuery
```
public void setQuery(@CheckForNull
            String query)
```
    Sets the URI query component.
    
    Parameters:
    query - the URI query component.
  - query
```
public UriBuilder query(@CheckForNull
               String query)
```
    Sets the URI query component.
    
    Parameters:
    query - the URI query component.
    
    Returns:
    this
  - getFragment
```
@CheckForNull
public String getFragment()
```
    Returns the URI fragment component.
    
    Returns:
    The URI fragment component.
  - setFragment
```
public void setFragment(@CheckForNull
               String fragment)
```
    Sets the URI fragment component.
    
    Parameters:
    fragment - the URI fragment component.
  - fragment
```
public UriBuilder fragment(@CheckForNull
                  String fragment)
```
    Sets the URI fragment component.
    
    Parameters:
    fragment - the URI fragment component.
    
    Returns:
    this

Class UriBuilder

Identities

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

encoder

builder

scheme

authority

path

query

fragment

Constructor Detail

UriBuilder

UriBuilder

Method Detail

clear

toString

getString

resetBuilder

validateScheme

validateScheme

newURISyntaxException

quote

setString

string

toUri

getUri

setUri

uri

getScheme

setScheme

scheme

getAuthority

setAuthority

authority

getPath

setPath

path

getQuery

setQuery

query

getFragment

setFragment

fragment