UriBuilder (TrueZIP Kernel 7.4.1 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 boolean`	`raw`
`private String`	`scheme`

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.
`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 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
  - authority
```
@CheckForNull
private String authority
```
  - builder
```
@CheckForNull
private StringBuilder builder
```
  - encoder
```
private final UriEncoder encoder
```
  - fragment
```
@CheckForNull
private String fragment
```
  - path
```
@CheckForNull
private String path
```
  - query
```
@CheckForNull
private String query
```
  - raw
```
private final boolean raw
```
  - scheme
```
@CheckForNull
private String scheme
```
- 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).
  - 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()
  - newURISyntaxException
```
private static URISyntaxException newURISyntaxException(CharBuffer input,
                                       String reason)
```
  - path
```
public UriBuilder path(@CheckForNull
              String path)
```
    Sets the URI path component.
    
    Parameters:
    path - the URI path component.
    
    Returns:
    this
  - query
```
public UriBuilder query(@CheckForNull
               String query)
```
    Sets the URI query component.
    
    Parameters:
    query - the URI query component.
    
    Returns:
    this
  - resetBuilder
```
private StringBuilder resetBuilder()
```
  - 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.
  - 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
```
private static void validateScheme(CharBuffer input)
                            throws URISyntaxException
```
    Throws:
    
    URISyntaxException
  - 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

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

authority

builder

encoder

fragment

path

query

raw

scheme

Constructor Detail

UriBuilder

UriBuilder

UriBuilder

UriBuilder

Method Detail

authority

clear

fragment

getAuthority

getFragment

getPath

getQuery

getScheme

getString

getUri

newURISyntaxException

path

query

resetBuilder

scheme

setAuthority

setFragment

setPath

setQuery

setScheme

setString

setUri

string

toString

toUri

uri

validateScheme

validateScheme